Data Import

Allows to poll the status of an Import Job.

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.