Set up the SAP writeback service

Step 1: Set up the SAP server destination

To send requests to your SAP S/4HANA instance, set up the SAP host destination.

An SAP instance is a configuration for an external SAP S/4HANA destination system. The instance resource contains all the information this API service needs to connect to the SAP S/4HANA destination.

Send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/instances to create an SAP instance destination. See API documentation for more information.

Step 2: Set up your schema mapping (Optional)

The SAP writeback service provides schema mapping functionality to map a Cognite Data Fusion (CDF) resource data schema to an SAP entity schema. The mapping must be defined using the Cognite extractor mapping language. If you set a mapping, the SAP writeback service will apply the mapping expression before sending the request to the SAP destination.

The example below contains an expression mapping the Cognite InField observation schema to the SAP maintenance notification schema:

{
    "NotificationText": substring(input.description,0,40), 
    "MaintPriority": case(input.priority,"Very High","1","Medium","2","Low","3"), 
    "NotificationType": input.type, 
    "MaintNotifLongTextForEdit":concat(input.description,input.troubleshooting), 
}

info

Write the mapping expressions to fulfill your business needs regarding field or value mapping between Cognite Data Fusion and SAP entities.

To save your mapping, send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/mappings. See API documentation for more information.

Step 3: Set up the SAP endpoint destination

In the SAP writeback service, an SAP endpoint is a configuration to an SAP S/4HANA OData endpoint (and its related OData entity). The API will send writeback requests to this endpoint. It defines which SAP instance destination and schema mapping should be used when processing a writeback request. Use the SAP endpoint as a reference to send requests to your SAP destination.

To set the SAP endpoint, send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/endpoints. See API documentation for more information.

Step 4: Connectivity check (Optional)

The SAP writeback service provides an endpoint that checks if the connectivity between CDF and the configured SAP endpoint destination is successful.

Send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/endpoints/verify. See API documentation for more information.

For a successful connection, the response from the SAP writeback /verify endpoint looks like:

{
    "status": "success"
}

Step 5: Send a request

Once you're done with the setup, send requests to your SAP destination.

The SAP writeback service sends all requests to SAP asynchronously. Once you send a request through the service, you'll get a requestId. You can use the requestId to track the status of the request once it is completed.

Send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/requests with the payload to be sent to SAP. See API documentation for more information.

The example below shows a successful writeback request to SAP.

{
    "items": [
        {
            "endpointId": "test-notification",
            "request": [
                {
                    "payload": {
                        "MaintNotifLongTextForEdit": "test description",
                        "MaintPriority": "3",
                        "NotificationText": "Test",
                        "NotificationType": "M2"
                    }
                }
            ]
        }
    ]
}

Response:

{
    "items": [
        {
            "createdTime": 1724416805132,
            "lastUpdatedTime": 1724416805132,
            "requestId": "0a0a0-1b1b-2c2c-3d3d-4e4e4e",
            "status": "pending",
            "request": [
                {
                    "payload": {
                        "MaintPriority": "3",
                        "NotificationText": "Test",
                        "NotificationType": "M2",
                        "MaintNotifLongTextForEdit": "test description"
                    }
                }
            ]
        }
    ]
}

To check the request status, send a POST request to https://{cluster}.cognitedata.com/api/v1/projects/{project}/writeback/sap/requests/byids with the related requestId. See API documentation for more information.

Request:

{
    "items":[
        {
            "requestId":"0a0a0-1b1b-2c2c-3d3d-4e4e4e"
        }
    ]
}

Response:

{
    "items": [
        {
            "createdTime": 1724416805132,
            "lastUpdatedTime": 1724416806161,
            "requestId": "0a0a0-1b1b-2c2c-3d3d-4e4e4e",
            "status": "done",
            "request": [
                {
                    "sapObjectId": "10129745",
                    "payload": {
                        "MaintPriority": "3",
                        "NotificationText": "Test",
                        "NotificationType": "M2",
                        "MaintNotifLongTextForEdit": "test description"
                    }
                }
            ]
        }
    ]
}

The writeback request is completed when the request status is set to done. The response parameter sapObjectId contains the object ID of the record created in the SAP destination.

Sign in to your SAP server and go to transaction code IW23 to check the maintenance notification created by the writeback request.

Input the sapObjectId value available in the writeback response.