Data Import

Poll Import JobWSDL

Allows to poll the status of an Import Job.

SecurityapiKey
Request
path Parameters
jobId
required
string (JobId)

Unique identifier of a Job.

Example: 35f23c03-1c22-45fe-9484-3ffe769325de
query Parameters
skippedStartAfter
string

Next page of items will be retrieved. When skippedNextStartAfter provided in the response, should be used.

Example: skippedStartAfter=5712566172571652
Responses
200

OK

get/jobs/importjobs/{jobId}
Request samples
Response samples
application/json
{
  • "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  • "name": "Process vendor data.",
  • "description": "I started this job to improve quality of our data.",
  • "domain": "BusinessPartner",
  • "createdBy": "76248934691294444",
  • "createdAt": "2024-06-20T07:02:28Z",
  • "modifiedAt": "2024-06-20T07:02:28Z",
  • "progress": "77",
  • "status": "RUNNING",
  • "statusMessage": "The job failed because storage is empty.",
  • "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  • "dataSource": "648824a691d8d2503d65103e",
  • "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  • "externalIdColumn": "BP_EXTERNAL_ID",
  • "featureOn": [
    ],
  • "result": {
    }
}

Start Import JobWSDL

To start importing a file into a storage, use the following request.

POST https://api.corporate-data-league.ch/data-exchange/rest/jobs/importjobs
  ?file=@{YOUR FILE}
  ?storageId={YOUR STORAGE ID}
  ?dataSource={YOUR DATASOURCE ID}

Fields (cells) in a file, that contain a special character (comma, semicolon, CR, LF, or double quote), must be "escaped" by enclosing them in double quotes. Header names can not contain any dot.

In order to successfully perform file upload use file upload for files up to 10MB or Upload via Upload Request approach for files larger than 10MB. file and url are not allowed to be present together.

Use one of the below instructions for your case:

  1. File size < 10MB : File Upload
  2. File size > 10MB : Request Upload

Including this sample CSV file in the default configuration.

Customer Number;City
123;St. Gallen

Supported columns (matched by ignoring letter case) with their mappings are the following:

Column Name Target Path in the latest Business Partner Model Wiki Page of Attribute in CDQ Data Model
CUSTOMER NUMBER $.externalId Business Partner External ID
VENDOR NUMBER $.externalId when CUSTOMER NUMBER is not available Business Partner External ID
NAME $.names[0].value, $.names[0].type.technicalKey = LOCAL Business Partner Name Value
TAX NUMBER 1 $.identifiers[identifierId].value in identifierId of TAX NUMBER 1 TYPE if exists, otherwise, new identifier of STCD1 type mapping, applied for COUNTRY Identifier Value
TAX NUMBER 1 TYPE $.identifiers[identifierId].type Identifier Type
TAX NUMBER 2 $.identifiers[identifierId].value in identifierId of TAX NUMBER 2 TYPE if exists, otherwise, new identifier of STCD2 type mapping, applied for COUNTRY Identifier Value
TAX NUMBER 2 TYPE $.identifiers[identifierId].type Identifier Type
TAX NUMBER 3 $.identifiers[identifierId].value in identifierId of TAX NUMBER 3 TYPE if exists, otherwise, new identifier of STCD3 type mapping, applied for COUNTRY Identifier Value
TAX NUMBER 3 TYPE $.identifiers[identifierId].type Identifier Type
TAX NUMBER 4 $.identifiers[identifierId].value in identifierId of TAX NUMBER 4 TYPE if exists, otherwise, new identifier of STCD4 type mapping, applied for COUNTRY Identifier Value
TAX NUMBER 4 TYPE $.identifiers[identifierId].type Identifier Type
TAX NUMBER 5 $.identifiers[identifierId].value in identifierId of TAX NUMBER 5 TYPE if exists, otherwise, new identifier of STCD5 type mapping, applied for COUNTRY Identifier Value
TAX NUMBER 5 TYPE $.identifiers[identifierId].type Identifier Type
VAT NUMBER $.identifiers[identifierId].value in identifierId of VAT NUMBER TYPE if exists, otherwise, new identifier of STCEG type mapping, applied for COUNTRY Identifier Value
VAT NUMBER TYPE $.identifiers[identifierId].type Identifier Type
COUNTRY address.country.(value, shortName) in $.addresses[0] (+ in $.addresses[1] when PO BOX exists for non-France) Country
REGION address.administrativeAreas[0].value in $.addresses[0] (+ in $.addresses[1] when PO BOX exists for non-France) Administrative Area Value
POSTAL CODE address.postCodes[0].value in $.addresses[0] (+ in $.addresses[1] when PO BOX exists for non-France) Post Code Value
CITY address.localities[0].value in $.addresses[0] (+ in $.addresses[1] when PO BOX exists for non-France) Locality Value
STREET address.thoroughfares[0].value Thoroughfare Value
HOUSE NUMBER address.thoroughfares[0].number Thoroughfare Number
PO BOX address.postalDeliveryPoints[0].value, address.postalDeliveryPoints[0].type.technicalKey = POST_OFFICE_BOX in $.addresses[0] in France, in $.addresses[1] for non-France https://meta.cdq.com/Business_partner/external_id

Alternatively, CUSTOM_DATA_MAPPER feature can be used to enable record transformation based on the Data Mapper Definition provided either via a dataMapperDefinitionId field or fetched from the configuration of provided data source.

Input file could contain customized columns naming effectively mapped to the Business Partner model via data mapper, shown in this sample CSV.

MyId;Country;City;Name
123;CH;St. Gallen;
124;CH;;Quote "Example"
"125";"CH";"";"""Quote """"Example""""  """

Input file for CUSTOM_DATA_MAPPER feature can also contain only one Record column with a stringified JSON representation of a record. Based on the Data Mapper Definition, data is transformed to the Business Partner model. In case UPSERT_BY_EXTERNAL_ID feature is used, external ID value needs to be included:

  • in a column which name is provided via a extenalIdColumn request property
  • in the JSON representation in the attribute mapped to externalId via data mapper

Below is the sample CSV file for Record-based configuration containing external ID column named MyId.

MyId,Record
123,"{""MyId"": ""123"", ""Country"": ""CH"", ""City"": ""St. Gallen""}"
124,"{""MyId"": ""124"", ""Country"": ""CH"", ""Name"": ""Quote \""Example\""""}"
125,"{""MyId"": ""125"", ""Country"": ""CH"", ""Name"": ""\""Quote \""\""Example\""\""  \""""}"

The maximum number of columns is 512

The response is shown below. Use the returned id to poll the import job status.

{
    "id" : "{YOUR IMPORT JOB ID}"
    ...
}

These imports, in default import samples, lead to the following Business Partners in the storage. The imported rows are represented as stringified JSONs.

{
   "id" : "{AUTO GENERATED}",
   "externalId" : "123",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"123\", \"Country\" : \"CH\", \"City\" : \"St. Gallen\" }",
   "addresses": [{
      "country": {
         "shortName": "CH"
      },
      "localities": [{
         "value": "St. Gallen"
      }]
   }],
   ...
},
{
   "id" : "{AUTO GENERATED}",
   "externalId" : "124",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"124\", \"Country\" : \"CH\", \"Name\" : \"Quote \\\"Example\\\"\" }",
   "names": [{
      "value": "Quote \"Example\""
      ...
   }],
   "addresses": [{
      "country": {
         "shortName": "CH"
      }
   }],
   ...
},
{
   "id" : "{AUTO GENERATED}",
   "externalId" : "125",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"125\", \"Country\" : \"CH\", \"Name\" : \"\\\"Quote \\\"\\\"Example\\\"\\\"  \\\"\" }",
   "names": [{
      "value": "\"Quote \"\"Example\"\"  \""
      ...
   }],
   "addresses": [{
      "country": {
         "shortName": "CH"
      }
   }],
   ...
}

Input file which first 100 data lines except header are corrupted is canceled without further processing.

SecurityapiKey
Request
Request Body schema: multipart/form-data
dataMapperDefinitionId
string

The ID of data mapper to be used to transform the data before importing it. This or a data source is required if feature CUSTOM_DATA_MAPPER is activated. Disabled when CUSTOM_DATA_MAPPER feature is not provided in a request.

Example: "6400955811c68a034bcef311"
dataSource
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
externalIdColumn
string

The name of the column which will be mapped to external ID. This is required if feature UPSERT_BY_EXTERNAL_ID is activated.

Example: "BP_EXTERNAL_ID"
featuresOn
Array of strings

List of features to be activated.

Items Enum: Description
ACCEPT_EMPTY_VALUES

Allows to import empty values to record in Business Partner.

UPSERT_BY_EXTERNAL_ID

Updates a Business Partners identified by external ID instead of an insert if the external ID is already present in this storage. If this feature is selected, dataSource and externalIdColumn are mandatory. When selected, id must not be provided in a Business Partner.

CUSTOM_DATA_MAPPER

Applies data transformation using data mapper identified by dataMapperDefinitionId field or fetched from the data source identified by dataSource field.

FULL_UPDATE

Forces the job to delete existing records which are not included in the import file. Records to be updated or to be deleted are identified by external IDs, i.e. not by the internal database IDs. To confirm this understanding, UPSERT_BY_EXTERNAL_ID feature must be activated in addition. When a FULL_UPDATE import job is completed, new records from the import file are created, existing ones are updated by keeping their internal database IDs and their external IDs, and records which are not provided by the file are deleted. If this feature is selected, dataSource and UPSERT_BY_EXTERNAL_ID feature are mandatory. Whenever import errors occur then this action is not executed.

Example: ["UPSERT_BY_EXTERNAL_ID"]
file
string <binary>

XLSX or CSV file to be uploaded (SOAP currently only supports CSV). Supports up to 10MB of file size. For the file size greater than 10MB use Upload via Upload Request approach.

Example: "CH-import.csv"
storageId
required
string

Target storage ID for this import.

Example: "72d6900fce6b326088f5d9d91049e3e6"
url
string

Url to file which will be used to import data from. Recommended. The file can be uploaded via File Upload passing through url from the result object.

Example: "customer-uploads/CH-import.csv"
Responses
200

OK

400

The sent request is malformed.

post/jobs/importjobs
Request samples
Response samples
application/json
{
  • "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  • "name": "Process vendor data.",
  • "description": "I started this job to improve quality of our data.",
  • "domain": "BusinessPartner",
  • "createdBy": "76248934691294444",
  • "createdAt": "2024-06-20T07:02:28Z",
  • "modifiedAt": "2024-06-20T07:02:28Z",
  • "progress": "77",
  • "status": "RUNNING",
  • "statusMessage": "The job failed because storage is empty.",
  • "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  • "dataSource": "648824a691d8d2503d65103e",
  • "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  • "externalIdColumn": "BP_EXTERNAL_ID",
  • "featureOn": [
    ],
  • "result": {
    }
}