Reference 360 > Reference 360 REST API > Using REST APIs to import and export
  

Using REST APIs to import and export

You can use the Reference 360 REST APIs to import or export code values and value mappings in bulk.

REST APIs for import and export

You can use a set of REST APIs to import or export data, retrieve the status of an import job, or retrieve a failed import job report.
The following table describes the REST APIs for importing and exporting data:
REST API
Description
Import code values
Import code values into a code list.
Import value mappings
Import value mappings into a crosswalk.
Get import job status
Retrieve the status of an import job.
Get failed import job report
Retrieve an error report for a failed import job.
Export code values
Export the code values in a code list.
Export value mappings
Export the value mappings in a crosswalk.

Filter criteria

You can filter the reference data that you want to export. For example, you can export a filtered set of code values in a code list.
When you filter code values, you can only filter values in the Code attribute or values in attributes that are configured as display attributes. For example, you might want a filter to include values with 001 in the Code attribute.

Field types

The filter operators available depends on the field type of the attribute.
The following table describes the filter operators supported for each field type:
Field Type
Supported Filter Operators
Filter Values
Boolean
_equals
_notEquals
_isEmpty
Boolean
Decimal or Integer
_equals
_notEquals
_isEmpty
_greaterThan
_greaterThanEquals
_lessThan
_lessThanEquals
Number
String
_equals
_notEquals
_isEmpty
_startsWith
_endsWith
_contains
_notContains
Text
Date
_equals
_notEquals
_isEmpty
_from, _to, _range
ISO 8601 date or date and time
For example, 2019-12-24 or 1969-12-15T14:17:04Z.
Reference Data
_equals
_notEquals
_isEmpty
_in
Values in the Code attribute or values in the display attributes for the reference data.

Filter examples

To filter assets with text fields that are empty, you might use the following filter operator:
{
"textField":{
"_isEmpty":true
}
}
To filter assets with boolean fields that are equal to true, you might use the following filter operator:
{
"booleanField":{
"_equals":true
}
}
To filter assets with number fields that are greater than 1 and less than 2, you might use the following filter operators:
{
"numberField":{
"_greaterThan":1,
"_lessThan":3
}
}
To filter assets with date fields between specified dates, you might use the following filter operators:
{
"dateField":{
"_from":"2019-01-01",
"_to":"2019-06-15"
}
}
To filter assets with date fields for a time range based on a reference date or time, you might use the following filter operators:
{
"dateField":{
"_range":{
"_months":6,
"_reference":"2020-01-01"
}
}
}
To filter assets with reference data attribute fields, you might use the following filter operators:
{
"referenceDataAttributeField.name":{
"_in":[
"EUR",
"USD"
]
}
}
To use multiple field operators, you might use the _and or _or operators like the following example:
{
"_and": [
{
"_or": [
{
"name": {
"_startsWith": "G"
}
},
{
"name": {
"_endsWith": "g"
}
}
]
},
{
"currencyLookup.name": [
"EUR"
]
},
{
"founded": {
"_to": "1951-08-29"
}
},
{
"population": {
"_greaterThan": 8e7
}
},
{
"monarchic": false
}
]
}
When you use a comma to separate operators inside a field, the comma acts like an _and operator. For example, the following examples filters for a name that starts with "Ger" and ends with "many", or equals "Japan":
{
"_or": [
{
"name": {
"_startsWith": "Ger","_endsWith": "many"
}
},
{
"name": {
"_equals": "Japan"
}
}
]
}

Importing code values

You can import code values into a code list. After you start an import job, you can check the status of the import job. If the import job fails, you can retrieve an error report.
Before you begin, you must get a session ID and identify the asset ID. The session ID authenticates your requests. The asset ID is the ID of the code list to which you want to import code values. For more information, see Session IDs and Asset IDs.
    1To import code values into a code list, use the Import code values REST API.
    For more information about the Import code values REST API, see Import code values.
    For example, the following request imports code values:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import HTTP/1.1
    Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    Content-Disposition: form-data; name=file; filename=import-code-values.csv


    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    Content-Disposition: form-data; name=importSettings
    Content-Type: application/json;charset=UTF-8

    {
    "delimiter":"COMMA",
    "textQualifier":"DOUBLE_QUOTE",
    "codepage":"UTF8",
    "dateFormat":"ISO",
    "containerType":"CODELIST",
    "containerId":"9ab3201990a54dcdc86f54cf",
    "startingRow":null
    }
    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
    The CSV file might contain the following header rows and data rows:
    Name,Code
    Name,Code
    Afghanistan,AFG
    Aland Islands,ALA
    Albania,ALB
    Algeria,DZA
    American Samoa,ASM
    Note: The containerId attribute is the ID of the code list to which you want to import code values.
    For example, the Import code values REST API returns the following job ID and details about the import job:
    {
    "jobId":"dd1b2018cb47cef99f8d0f42",
    "state":"INPROGRESS",
    "startTime":1561367377428,
    "numOfRecordsProcessed":100,
    "numOfRecordsFailed":25,
    "numOfRecordsSucceeded":75
    }
    2To check the status of an import job, use the Get import job status REST API.
    For more information about the Get import job status REST API, see Get import job status.
    For example, the following request retrieves the status of an import job:
    GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import/job/dd1b2018cb47cef99f8d0f42 HTTP/1.1
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
    For example, the Get import job status REST API returns the following status of the import job:
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Content-Length: 193
    {
    "jobId":"dd1b2018cb47cef99f8d0f42",
    "state":"INPROGRESS",
    "startTime":1561367376330,
    "numOfRecordsProcessed":100,
    "numOfRecordsFailed":25,
    "numOfRecordsSucceeded":75
    }
    3To retrieve an error report for a failed import job, use the Get failed import job report REST API.
    For more information about the Get failed import job report REST API, see Get failed import job report.
    For example, the following request retrieves the error report for a failed import job:
    GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import/job/dd1b2018cb47cef99f8d0f42/errorDetails HTTP/1.1
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
    For example, the Get failed import job report REST API returns the following details of the failed import job:
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Content-Length: 354

    {
    "jobId":"dd1b2018cb47cef99f8d0f42",
    "entityType":"Relationship",
    "fileName":"import.csv",
    "entityName":"rdm.crosswalk.rel.21ffd6b5f92d10c744acc27c.fc66c441288cf898c6fe5023",
    "errorDetails":[
    {
    "lineNumber":1,
    "entitySourcePkey":"AF_AFG",
    "reasons":[
    "The requested resource with ID 'AFG' does not exist."
    ]
    }
    ]
    }

Importing value mappings

You can import value mappings into a crosswalk. After you start an import job, you can check the status of the import job. If the import job fails, you can retrieve an error report.
Before you begin, you must get a session ID and identify the asset ID. The session ID authenticates your requests. The asset ID is the ID of the crosswalk to which you want to import value mappings. For more information, see Session IDs and Asset IDs.
    1To import value mappings into a crosswalk, use the Import value mappings REST API.
    For more information about the Import value mappings REST API, see Import value mappings.
    For example, the following request imports value mappings:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import HTTP/1.1
    Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    Content-Disposition: form-data; name=file; filename=import-value-mappings.csv

    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
    Content-Disposition: form-data; name=importSettings
    Content-Type: application/json;charset=UTF-8

    {
    "delimiter":"COMMA",
    "textQualifier":"DOUBLE_QUOTE",
    "codepage":"UTF8",
    "dateFormat":"ISO",
    "containerType":"CROSSWALK",
    "containerId":"9ab3201990a54dcdc86f53AB",
    "startingRow":null
    }
    --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
    The CSV file might contain the following header rows and data rows:
    sourcePKey,_from.id.sourcePKey,_to.id.sourcePKey
    sourcePKey,_from.id.sourcePKey,_to.id.sourcePKey
    AF_AFG,AF,AFG
    AL_ALA,AL,ALA
    ALB_ALB,ALB,ALB
    DZ_DZA,DZ,DZA
    AS_ASM,AS,ASM
    Note: The containerId attribute is the ID of the code list to which you want to import value mappings.
    For example, the Import value mappings REST API returns the following job ID and import job information:
    {
    "jobId":"dd1b2018cb47cef99f8d0f43",
    "state":"INPROGRESS",
    "startTime":1561367377428,
    "numOfRecordsProcessed":100,
    "numOfRecordsFailed":25,
    "numOfRecordsSucceeded":75
    }
    Note: You use the job ID to check the status of an import job.
    2To check the status of an import job, use the Get import job status REST API.
    For more information about the Get import job status REST API, see Get import job status.
    For example, the following request retrieves the status of an import job:
    GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import/job/dd1b2018cb47cef99f8d0f43 HTTP/1.1
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
    For example, the Get import job status REST API returns the following status of the import job:
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Content-Length: 193
    {
    "jobId":"dd1b2018cb47cef99f8d0f43",
    "state":"INPROGRESS",
    "startTime":1561367376330,
    "numOfRecordsProcessed":100,
    "numOfRecordsFailed":25,
    "numOfRecordsSucceeded":75
    }
    3To retrieve an error report for a failed import job, use the Get error report for failed import job REST API.
    For more information about the Get failed import job report REST API, see Get failed import job report.
    For example, the following request retrieves the error report for a failed import job:
    GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/import/job/dd1b2018cb47cef99f8d0f43/errorDetails HTTP/1.1
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
    For example, the Get error report for failed import job REST API returns the following error report:
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Content-Length: 354

    {
    "jobId":"dd1b2018cb47cef99f8d0f43",
    "entityType":"Relationship",
    "fileName":"import.csv",
    "entityName":"rdm.crosswalk.rel.21ffd6b5f92d10c744acc27c.fc66c441288cf898c6fe5023",
    "errorDetails":[
    {
    "lineNumber":1,
    "entitySourcePkey":"AF_AFG",
    "reasons":[
    "The requested resource with ID 'AFG' does not exist."
    ]
    }
    ]
    }

Exporting code values

Export code values in a code list.
Before you begin, you must get a session ID and identify the asset ID. The session ID authenticates your requests. The asset ID is the ID of the code list that contains the code values that you want to export. For more information, see Session IDs and Asset IDs.
    bulletTo export code values in a code list, use the Export code values REST API.
    For more information about the Export code values REST API, see Exporting code values.
    For example, the following request exports code values:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/export HTTP/1.1
    Content-Type: application/json
    Accept: application/octet-stream
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    {
    "delimiter" : "SEMICOLON",
    "codepage" : "UTF8",
    "decimalSeparator" : "COMMA",
    "thousandSeparator" : "DOT",
    "dateFormat" : "ISO",
    "filename" : "testdata.csv",
    "containerType" : "codelist",
    "containerId" : "1989aae96bdaa4c2b8768fcc"
    }
    Note: The containerId attribute is the ID of the code list that contains the code values that you want to export.
    For example, the Export code values REST API exports the following CSV file with the data:
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename=testdata.csv
    Content-Type: application/octet-stream
    Content-Length: 124

    status.key;effectiveDate;approvedOn
    status.status.key;effectiveDate;approvedOn
    ActiveStatus;myEffectiveDate;myApprovedOn
    ActiveStatus;myEffectiveDate;myApprovedOn

Exporting filtered code values

Export filtered code values based on filter criteria. You can filter code values based on values in attributes or reference data attributes.
Before you begin, you must get a session ID and identify the asset ID. The session ID authenticates your requests. The asset ID is the ID of the code list that contains the code values that you want to export. For more information, see Session IDs and Asset IDs.
    1To export code values that contain a status, use the Export code values API with a filter operator for the status field.
    For more information about the Export code values REST API, see Exporting code values.
    For example, the following request exports code values with any status:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/export HTTP/1.1
    Content-Type: application/json
    Accept: application/octet-stream
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    {
    "delimiter":"SEMICOLON",
    "codepage":"UTF8",
    "decimalSeparator":"COMMA",
    "thousandSeparator":"DOT",
    "dateFormat":"ISO",
    "filename":"testdata.csv",
    "containerType":"codelist",
    "containerId":"1989aae96bdaa4c2b8768fcc",
    "filter":{
    "_and":[
    {
    "Status":{
    "_isEmpty":false
    }
    }
    ]
    }
    }
    Note: The containerId attribute is the ID of the code list that contains the code values that you want to export.
    For example, the Export code values REST API exports the following CSV file with the data:
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename=testdata.csv
    Content-Type: application/octet-stream
    Content-Length: 124

    status.key;effectiveDate;Name;Code;Description
    status.status.key;effectiveDate;Name;Code;Description
    Active;;US;001;United States of America
    Active;;CAN;002;Canada
    2To export filtered code values based on a display attribute for a reference data attribute and an attribute, use the Export code values API with multiple filter operators.
    For more information about the Export code values REST API, see Exporting code values.
    For example, the following request exports filtered code values that contain Dollar in the Name display attribute for the Currency reference data attribute and 00 in the Code attribute:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/export HTTP/1.1
    Content-Type: application/json
    Accept: application/octet-stream
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    {
    "delimiter":"SEMICOLON",
    "codepage":"UTF8",
    "decimalSeparator":"COMMA",
    "thousandSeparator":"DOT",
    "dateFormat":"ISO",
    "filename":"testdata.csv",
    "containerType":"codelist",
    "containerId":"1989aae96bdaa4c2b8768fcc",
    "filter":{
    "_and":[
    {
    "Currency.Name":{
    "_contains":"Dollar"
    }
    },
    {
    "Code":{
    "_contains":"00"
    }
    }
    ]
    }
    }
    Note: The containerId attribute is the ID of the code list that contains the code values that you want to export.
    For example, the Export code values REST API exports the following CSV file with the data:
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename=testdata.csv
    Content-Type: application/octet-stream
    Content-Length: 124

    status.key;effectiveDate;Name;Code;Description;Currency.Code
    status.status.key;effectiveDate;Name;Code;Currency.Currency.Code
    Active;;US;001;United States of America;USD
    Active;;CAN;002;Canada;CAD
    Note: When you filter on a specific display attribute for a reference data attribute, the filtered code values appear in the CSV file, but the code value is represented by the Code attribute.
    3To export filtered code values based on a reference data attribute and an attribute, use the Export code values API with multiple filter operators.
    For more information about the Export code values REST API, see Exporting code values.
    For example, the following request exports filtered code values with EUR in the Currency reference data attribute and an in the Name attribute:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/export HTTP/1.1
    Content-Type: application/json
    Accept: application/octet-stream
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    {
    "delimiter":"SEMICOLON",
    "codepage":"UTF8",
    "decimalSeparator":"COMMA",
    "thousandSeparator":"DOT",
    "dateFormat":"ISO",
    "filename":"testdata.csv",
    "containerType":"codelist",
    "containerId":"1989aae96bdaa4c2b8768fcc",
    "filter":{
    "_and":[
    {
    "Currency":"EUR"
    },
    {
    "Name":{
    "_contains":"an"
    }
    }
    ]
    }
    }
    Note: The containerId attribute is the ID of the code list that contains the code values that you want to export.
    For example, the Export code values REST API exports the following CSV file with the data:
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename=testdata.csv
    Content-Type: application/octet-stream
    Content-Length: 124

    status.key;effectiveDate;Name;Code;Description;Currency.Code
    status.status.key;effectiveDate;Name;Code;Description;Currency.Code
    ;;Netherlands;NLD;Netherlands;;EUR
    ;;Germany;DEU;Germany;;EUR
    ;;Ireland;IRL;Ireland;;EUR
    ;;Finland;FIN;Finland;;EUR
    Note: When you filter on values in a reference data attribute without specifying a display attribute to filter on, the filter applies on values in the Code attribute.

Exporting value mappings

Export value mappings in a crosswalk.
Before you begin, you must get a session ID and identify the asset ID. The session ID authenticates your requests. The asset ID is the ID of the crosswalk that contains the value mappings that you want to export. For more information, see Session IDs and Asset IDs.
    bulletTo export value mappings in a crosswalk, use the Export value mappings REST API.
    For more information about the Import value mappings REST API, see Export value mappings to a CSV file.
    For example, the following request exports value mappings:
    POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/export HTTP/1.1
    Content-Type: application/json
    Accept: application/octet-stream
    IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

    {
    "delimiter" : "SEMICOLON",
    "codepage" : "UTF8",
    "decimalSeparator" : "COMMA",
    "thousandSeparator" : "DOT",
    "dateFormat" : "ISO",
    "filename" : "testdata.csv",
    "containerType" : "crosswalk",
    "containerId" : "5d123f6e4077c700010d59e4"
    }
    Note: The containerId attribute is the ID of the crosswalk that contains the value mappings that you want to export.
    For example, the Export value mappings REST API exports the following CSV file with the data:
    HTTP/1.1 200 OK
    Content-Disposition: attachment;filename=testdata.csv
    Content-Type: application/octet-stream
    Content-Length: 124

    status.key;effectiveDate;approvedOn
    status.status.key;effectiveDate;approvedOn
    ActiveStatus;myEffectiveDate;myApprovedOn
    ActiveStatus;myEffectiveDate;myApprovedOn