Allows polling the status of an Import Job.
OK
{- "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-11-22T13:20:20Z",
- "modifiedAt": "2024-11-22T13:20:20Z",
- "progress": "77",
- "status": "RUNNING",
- "statusMessage": "The job failed because storage is empty.",
- "storageId": "72d6900fce6b326088f5d9d91049e3e6",
- "dataSource": "648824a691d8d2503d65103e",
- "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
- "dataTransformationDefinitionId": "6440dba32b30176c5917b1b7",
- "externalIdColumn": "BP_EXTERNAL_ID",
- "featureOn": [
- "UPSERT_BY_EXTERNAL_ID"
], - "result": {
- "statistics": {
- "numberOfInserts": "10",
- "numberOfUpdates": "10",
- "numberOfFailed": "10",
- "skipped": [
- {
- "line": "10",
- "column": "10"
}
], - "skippedStartAfter": "10",
- "skippedNextStartAfter": "20"
}
}
}
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:
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:
extenalIdColumn
request propertyBelow 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.
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.
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 Example: "customer-uploads/CH-import.csv" |
OK
The sent request is malformed.
{- "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-11-22T13:20:20Z",
- "modifiedAt": "2024-11-22T13:20:20Z",
- "progress": "77",
- "status": "RUNNING",
- "statusMessage": "The job failed because storage is empty.",
- "storageId": "72d6900fce6b326088f5d9d91049e3e6",
- "dataSource": "648824a691d8d2503d65103e",
- "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
- "dataTransformationDefinitionId": "6440dba32b30176c5917b1b7",
- "externalIdColumn": "BP_EXTERNAL_ID",
- "featureOn": [
- "UPSERT_BY_EXTERNAL_ID"
], - "result": {
- "statistics": {
- "numberOfInserts": "10",
- "numberOfUpdates": "10",
- "numberOfFailed": "10",
- "skipped": [
- {
- "line": "10",
- "column": "10"
}
], - "skippedStartAfter": "10",
- "skippedNextStartAfter": "20"
}
}
}