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),
}
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.