Bulk API

Attention: SAP Field Service Management documentation is now available at the SAP Help Portal. On 31 December 2020, docs.coresystems will no longer be available. Until that time, documentation will NOT be updated in docs.coresystems.

1.1 Overview

The Bulk API is an extension of the Data API v4 used to create/update and delete resources in bulk.


1.1.1 Supported Endpoints

  Note Section
1.1.1.1 PUT request to create objects in bulk using externalId. The externalId must be present in the request body. 1.2
1.1.1.2 PATCH request to update objects in bulk using externalId. The externalId must be present in the request body. 1.3
1.1.1.3 DELETE request to delete objects in bulk using externalId. The externalId must be present in the request body. 1.4
1.1.1.4 PUT request to create objects in bulk using Id. The Id must be present in the request body. 1.5
1.1.1.5 PATCH request to opdate objects in bulk using Id. The id must be present in the request body. 1.6
1.1.1.6 DELETE request to opdate objects in bulk using Id. The id must be present in the request body. 1.7

1.1.2 Supported Query Parameters

The following query paramters are supported by the Bulk API:

Query Parameter Type Required Description
forceUpdate(For Patch and Put requests) Boolean FALSE Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.
forceDelete(For delete Requests) Boolean FALSE Set to false by default. If set to true, the optimistic locking mechanism provided by lastChanged property is ignored. Such a call overrides any possible changes made to the resource since the last retrieval.
dtoVersions( Only for Patch and Put requests) String TRUE resourceName.dtoVersion for example Address.20

1.1.3 URL Paramaters

Example https://{cluster}.coresuite.com/api/data/v4/Address/externalId/bulk?dtos=Address.14
Parameter Example Description Required
{resourceName} Address Here you will reference the supported data object which you wish to create or update in bulk. Required
{resourceName.dtoVersion} Address.14 Here you will reference the data transfer object again along with the specific version. Required

1.2 Create Bulk Request by externalId

Create objects in bulk using externalId.

  Note
1.2.0.1 If the resource does not exist, this server will create it under the given URI.

Please note that this is valid also for PATCH, but you need to send all required fields in order to create a valid object.
1.2.0.2 In order to create/update an object using a PUT request, the whole object needs to be provided in request body.

1.2.1 Request

In order to create an object, a PUT request must be made to following url:

Method URL
PUT https://{cluster}.coresuite.com/api/data/v4/{resourceName}/externalId/bulk?dtos={resourceName.dtoVersion}

1.2.2 Request Body

The following is an example of the request body contained in a Bulk API PUT request.

Note: PUT requests must reference the externalId of the objects in the request body.

[{
        "externalId": "C6765B13EF1E2462868E5F",
        "inactive": false,
        "lastChanged": 0,
        "city": "test City 1",
        "country": "test Country 1",
        "defaultAddress": false,
        "name": "Test address 1",
        "object": {
            "objectId": "A506E7AD87374F209CDC43E589029445",
            "objectType": "BUSINESSPARTNER"
        },
        "street": "test street 1",
        "zipCode": "4444"
    },
    {
        "externalId": "EB6EDED4929E4246BAB1969285F",
        "inactive": false,
        "lastChanged": 0,
        "city": "test City 2",
        "country": "test Country 2",
        "defaultAddress": false,
        "name": "Test address 2",
        "object": {
            "objectId": "ABC6E7AD87374F209CDC43E589029123",
            "objectType": "BUSINESSPARTNER"
        },
        "street": "test street 2",
        "zipCode": "5555"
    }
  ]

1.2.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.2.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for each individual resource in the response body.
201 Created/Updated. Returned for individual resource in the response body.

Note: The response body contains the list of updated (created) resources with a status for each individual resource.


1.2.4 Example Response

The following is an example of a response returned from a PUT request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 201,
        "location": "http://localhost:9080/dc/api/data/v4/Address/externalId/C6765B13EF1E2462868E5F",
        "address": {
            "country": "test country 1",
            "zipCode": "4444",
            "city": "test city 1",
            "county": null,
            "owners": null,
            "type": null,
            "building": null,
            "syncObjectKPIs": null,
            "postOfficeBox": null,
            "inactive": false,
            "street": "not sure",
            "block": null,
            "state": null,
            "id": "6CF10C216829433C958D3B3AE5510A91",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1550566130211,
            "createPerson": "AFC0F59CD7C54474A3FA788E037C71B6",
            "externalId": "C6765B13EF1E2462868E5F",
            "groups": null,
            "branches": null,
            "room": null,
            "createDateTime": "2019-02-19T14:18:48+05:30",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 1",
            "location": null,
            "udfValues": null,
            "name2": null,
            "lastChangedBy": "AFC0F59CD7C54474A3FA788E037C71B6",
            "remarks": null,
            "syncStatus": "BLOCKED",
            "defaultAddress": false,
            "object": {
                "objectId": "A506E7AD87374F209CDC43E589029445",
                "objectType": "BUSINESSPARTNER"
            }
        }
    },
    {
        "status": 201,
        "location": "http://localhost:9080/dc/api/data/v4/Address/externalId/EB6EDED4929E4246BAB1969285F",
        "address": {
            "country": "test country 2",
            "zipCode": "5555",
            "city": "test city 2",
            "county": null,
            "owners": null,
            "type": null,
            "building": null,
            "syncObjectKPIs": null,
            "postOfficeBox": null,
            "inactive": false,
            "street": "test street 2",
            "block": null,
            "state": null,
            "id": "390CB7C5322346C39BDB8E1DF0DE6CD2",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1550566131486,
            "createPerson": "AFC0F59CD7C54474A3FA788E037C71B6",
            "externalId": "EB6EDED4929E4246BAB1969285F",
            "groups": null,
            "branches": null,
            "room": null,
            "createDateTime": "2019-02-19T14:18:51+05:30",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 2",
            "location": null,
            "udfValues": null,
            "name2": null,
            "lastChangedBy": "AFC0F59CD7C54474A3FA788E037C71B6",
            "remarks": null,
            "syncStatus": "BLOCKED",
            "defaultAddress": false,
            "object": {
                "objectId": "ABC6E7AD87374F209CDC43E589029123",
                "objectType": "BUSINESSPARTNER"
            }
        }
    }
] 

1.2.5 Failure Response

The following is an example of the message returned when the request has failed:

Code Response
207 HTTP_MULTI_STATUS
 
[
    {
        "status": 422,
        "externalId": "C6765B13EF1E2462868E5F",
        "ex": {
            "error": "CA-41",
            "message": "CA-41: Cannot create resource [Address:6CF10C216829433C958D3B3AE5510A91] as it already exists.",
            "values": [
                "Address",
                "6CF10C216829433C958D3B3AE5510A91"
            ],
            "id": "df60161198284830b739dbf1e150ecd1"
        }
    },
    {
        "status": 422,
        "externalId": "EB6EDED4929E4246BAB1969285F",
        "ex": {
            "error": "CA-41",
            "message": "CA-41: Cannot create resource [Address:390CB7C5322346C39BDB8E1DF0DE6CD2] as it already exists.",
            "values": [
                "Address",
                "390CB7C5322346C39BDB8E1DF0DE6CD2"
            ],
            "id": "a25de2053bd04a9786a2a46fe899008c"
        }
    }
]

1.3 Update Bulk Request by externalId

Update objects in bulk by externalId.

Please note the following:

  Note
1.3.0.1 Request should contain in the body the fields that you want to update.
1.3.0.2 If the resource does not exist, this server will create it under the given URI.

Please note that this is valid also for PATCH, but you need to send all required fields in order to create a valid object.

1.3.1 Request

To update objects in bulk, a PATCH request must be made as in the following example:

Method URL
PATCH https://{cluster}.coresuite.com/api/data/v4/Address/externalId/bulk?dtos=Address.14

Note: PATCH requests made to this endpoint must reference the externalId of the objects in the request body.


1.3.2 Request Body

The following is an example request body for a bulk update PATCH request:

[
    {
        "id": "B4656EC748AF4F1CBD384A75EFC0E113",
        "externalId": "addressExIdChange1"
    },
    {
        "id": "B93062E044D341558A9314E7E9690412",
        "externalId": "addressExIdChange2"
    }
]

1.3.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.3.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for each individual resource in the response body.
201 Created/Updated. Returned for individual resource in the response body.

Note: The response body contains the list of updated (created) resources with a status for each individual resource.


1.3.4 Example Response

The following is an example of a response returned from a PATCH request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B4656EC748AF4F1CBD384A75EFC0E113",
        "address": {
            "country": "IN",
            "zipCode": "4444",
            "city": "Warsaw",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street1",
            "block": null,
            "state": null,
            "id": "B4656EC748AF4F1CBD384A75EFC0E113",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184515614,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "addressExIdChange1",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 9",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "058BAE32613E4EA6B6AF6539A601DA9A",
                    "externalId": "C0001"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    },
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B93062E044D341558A9314E7E9690412",
        "address": {
            "country": "JP",
            "zipCode": "5555",
            "city": "Nagasaki",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street2",
            "block": null,
            "state": null,
            "id": "B93062E044D341558A9314E7E9690412",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184515951,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "addressExIdChange2",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 10",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "35C2996591244F7C9180DD7DDBF15C52",
                    "externalId": "C0003"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    }
]

1.4 DELETE Bulk Request by externalId

Delete objects in bulk using externalId.


1.4.1 Request

Method URL
DELETE https://{cluster}.coresuite.com/api/data/v4/{resourceName}/externalId/bulk

1.4.2 Request Body

Note: DELETE requests must reference the externalId of the object in the request body.

 
[{
     
    "externalId":"ABAD",
    "lastChanged": 1550571215725 (lastChanged is not needed if forceDelete=true is passed as query parameter )
},{
     
    "externalId":"ACDA",
    "lastChanged": 1550571215725
}]

1.4.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.4.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for individual resource in the response body.

1.4.4 Example Response

The following is an example of a response returned from a DELETE request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 200,
        "externalId": "ABAD"
    },
    {
        "status": 200,
        "externalId": "ACDA"
    }
]

1.5 Create Objects in Bulk by Id

Create objects in bulk using the object Id.

1.5.1 Request

Method URL
PUT https://{cluster}.coresuite.com/api/data/v4/{resourceName}/bulk

1.5.2 Request Body

The following is an example of a PUT request made to the Bulk API using the object Id:

[{
        "externalId": "ADD001",
        "inactive": false,
        "city": "Warsaw",
        "country": "IN",
        "defaultAddress": false,
        "name": "Test address 9",
        "object": { 
            "objectId":{
                "externalId" : "C0001"
            },
            "objectType": "BUSINESSPARTNER"
             
        } ,
        "street": "Street1",
        "zipCode": "4444"
    },
    {
        "externalId": "ADD002",
        "inactive": false,
        "city": "Nagasaki",
        "country": "JP",
        "defaultAddress": false,
        "name": "Test address 10",
        "object": { 
            "objectId":{
                "externalId" : "C0003"
            },
            "objectType": "BUSINESSPARTNER"
             
        } ,
        "street": "Street2",
        "zipCode": "5555"
    }
  ]

1.5.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.5.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for individual resource in the response body.

1.5.4 Example Response

The following is an example of a response returned from a DELETE request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B4656EC748AF4F1CBD384A75EFC0E113",
        "address": {
            "country": "IN",
            "zipCode": "4444",
            "city": "Warsaw",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street1",
            "block": null,
            "state": null,
            "id": "B4656EC748AF4F1CBD384A75EFC0E113",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184215359,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "ADD001",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 9",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "058BAE32613E4EA6B6AF6539A601DA9A",
                    "externalId": "C0001"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    },
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B93062E044D341558A9314E7E9690412",
        "address": {
            "country": "JP",
            "zipCode": "5555",
            "city": "Nagasaki",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street2",
            "block": null,
            "state": null,
            "id": "B93062E044D341558A9314E7E9690412",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184215633,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "ADD002",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 10",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "35C2996591244F7C9180DD7DDBF15C52",
                    "externalId": "C0003"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    }
] 

1.6 Update Objects in Bulk by Id

Update objects in bulk using Id.

1.6.1 Request

Method URL
PATCH https://{cluster}.coresuite.com/api/data/v4/Address/bulk?dtos=Address.14

1.6.2 Request Body

The following is an example request body for a PATCH call made to the Bulk API using Id to reference records:

[
    {
        "id": "B4656EC748AF4F1CBD384A75EFC0E113",
        "externalId": "addressExIdChange1"
    },
    {
        "id": "B93062E044D341558A9314E7E9690412",
        "externalId": "addressExIdChange2"
    }
]

1.6.3 Response

Code Response
207 HTTP_MULTI_STATUS

1.6.3.1 Response for Individual Resources

The following status codes are communicated in the response body:

Code Response
200 OK. Returned for individual resource in the response body.

1.6.4 Example Response

[
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B4656EC748AF4F1CBD384A75EFC0E113",
        "address": {
            "country": "IN",
            "zipCode": "4444",
            "city": "Warsaw",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street1",
            "block": null,
            "state": null,
            "id": "B4656EC748AF4F1CBD384A75EFC0E113",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184515614,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "addressExIdChange1",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 9",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "058BAE32613E4EA6B6AF6539A601DA9A",
                    "externalId": "C0001"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    },
    {
        "status": 201,
        "location": "http://et.dev.coresuite.com/dc/api/data/v4/Address/B93062E044D341558A9314E7E9690412",
        "address": {
            "country": "JP",
            "zipCode": "5555",
            "city": "Nagasaki",
            "county": null,
            "owners": [],
            "type": null,
            "building": null,
            "syncObjectKPIs": [],
            "postOfficeBox": null,
            "inactive": false,
            "street": "Street2",
            "block": null,
            "state": null,
            "id": "B93062E044D341558A9314E7E9690412",
            "floor": null,
            "streetNo": null,
            "lastChanged": 1577184515951,
            "createPerson": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "externalId": "addressExIdChange2",
            "groups": [],
            "branches": [],
            "room": null,
            "createDateTime": "2019-12-24T10:43:35Z",
            "name3": null,
            "udfMetaGroups": null,
            "name": "Test address 10",
            "location": null,
            "udfValues": [],
            "name2": null,
            "lastChangedBy": {
                "id": "14523B3D57424338858CB56BBF120696",
                "externalId": "admin"
            },
            "remarks": null,
            "syncStatus": "IN_CLOUD",
            "defaultAddress": false,
            "object": {
                "objectId": {
                    "id": "35C2996591244F7C9180DD7DDBF15C52",
                    "externalId": "C0003"
                },
                "objectType": "BUSINESSPARTNER"
            }
        }
    }
]

1.7 Delete Objects in Bulk by Id

Delete objects in bulk using Id as reference.

1.7.1 Request

Method URL
DELETE https://{cluster}.coresuite.com/api/data/v4/Address/bulk?dtos=Address.14

1.7.2 Request Body

The following is an example of the request body of a DELETE bulk request made referencing the object Id:

[
    {
        "id": "B4656EC748AF4F1CBD384A75EFC0E113"
    },
    {
        "id": "B93062E044D341558A9314E7E9690412"
    }
  ]

1.7.3 Response

The following is an example of a response returned from a DELETE request made to the Bulk API.

Please note that an individual response code is present for each impacted resource. This response code is communicated in status.

[
    {
        "status": 200,
        "externalId": "B4656EC748AF4F1CBD384A75EFC0E113"
    },
    {
        "status": 200,
        "externalId": "B93062E044D341558A9314E7E9690412"
    }
]

1.7.4 Error Response

The following is an example of an error response returned from the Bulk API in a failed DELETE request:

[
    {
        "status": 404,
        "id": "5B8497C654374422898A4A39DA57C754",
        "externalId": null,
        "ex": {
            "error": "CA-26",
            "message": "CA-26: Resource [Address] with id [5B8497C654374422898A4A39DA57C754] is not found.",
            "values": [
                "Address",
                "5B8497C654374422898A4A39DA57C754"
            ],
            "id": "d51695442f1648fd81f4e18c6f753dfd"
        }
    },
    {
        "status": 404,
        "id": "EA5CC4E047574805B37FFFCCDEEE665B",
        "externalId": null,
        "ex": {
            "error": "CA-26",
            "message": "CA-26: Resource [Address] with id [EA5CC4E047574805B37FFFCCDEEE665B] is not found.",
            "values": [
                "Address",
                "EA5CC4E047574805B37FFFCCDEEE665B"
            ],
            "id": "203a2491b3094b51abb77e5471eb4508"
        }
    }
]