Reference 360 > Reference 360 REST API > import version 3

import version 3

Use this resource to import code values, value mappings, and hierarchy relationships based on an internal ID or alias.

Import code values (v3)

Imports code values with optional custom headers into a code list based on an internal ID or alias.

Note: Validation checks are not performed when you import code values.

POST request

To import code values into a code list based on an internal ID or alias, submit a POST request with the following URI:

/rdm-service/external/v3/import

The request contains form-data with the following parameters:

file: Specify a CSV file that contains the code value attributes. The columns specified depend on your data model. The CSV must contain one or two header rows, followed by the data rows. If the occurrence of header row is one in the import CSV file, you must set the repeatHeaders field to false.; For example, you might have the following code values:
importSettings: Specify the file-specific configuration and container details.; The importSettings parameter includes the following attributes:

Field	Type	Description
headerLinePresent	Boolean	Indicates whether the header line is present. Value is true or false. Default is true.
nestedFieldSeparator	String	Separator used to separate a nested field. Value is SEMICOLON or DOT. Default is DOT.
headerLineNumber	String	Line number from which the header line starts. Default is 1.
delimiter	String	Delimiter used to separate values. Value must be COMMA, SEMICOLON, SPACE, or TAB.
textQualifier	String	Symbol used to indicate where a text begins and ends. Value must be DOUBLE_QUOTE, SINGLE_QUOTE, or NO_QUOTE.
codepage	String	Code page used for the import file. Value must be UTF8 or MS_WINDOWS.
dateFormat	String	Format used for dates. Use one of the following formats: - DE. For dd.mm.yyyy format. - ISO. For yyyy-mm-dd format. - US_HYPHEN. For mm-dd-yyyy format. - US_SLASH. For mm/dd/yyyy format.
containerType	String	Type of asset that contains code values. Value must be codelist.
containerKey	String	Internal ID or alias of the code list to which you want to import code values.
startingRow	String	Line number from which to start importing data. By default, all rows are imported.
repeatHeaders	Boolean	Optional. Indicates whether the file has two headers. Value is true or false. Default is true.
mappings	Object	Optional. Maps the column headers in the CSV file with the target attributes of code lists in the key-value format. - You can map the user-defined column name to source field name if required. - You can either choose to ignore the mapping or map all the columns in an import CSV file. Note: The key represents the header in the CSV file, and the value represents the field names in Reference 360. For example, if the business ID column in the input CSV is labeled as sequence, the following mapping represents the mapping for the business ID column: "sequence" : "businessID" If mappings aren't specified in the import settings, Reference 360 selects the businessID column by default.
approvalOptions	Array	Includes details about the approval parameters.
priority	String	Optional. Defines the priority of the approval request. Value can be LOW, MEDIUM, HIGH, or CRITICAL.
dueDate	String	Use the following format: yyyy-MM-dd.
Comments	String	Comments that the requester adds to explain the changes.

POST response

The response contains the details of the import job.

The following table describes the attributes in the response body:

Field	Type	Description
jobId	String	ID of the job.
state	String	Status of the job. Values are CREATED, INPROGRESS, COMPLETED, SUSPENDED, FAILED, STOPPED, QUEUED or WARNING.
startTime	Number	Time, in milliseconds, when the job started.
numOfRecordsProcessed	Number	Number of records processed.
numOfRecordsFailed	Number	Number of records that failed to be imported.
numOfRecordsSucceeded	Number	Number of records successfully imported.

POST example

To import code values based on an internal ID or alias, you might use the following request:

POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/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

{
"headerLinePresent":true,
"nestedFieldSeparator":".",
"headerLineNumber":1,
"delimiter":"COMMA",
"textQualifier":"DOUBLE_QUOTE",
"codepage":"UTF8",
"dateFormat":"ISO",
"containerType":"CODELIST",
"containerKey":"ent_country",
"startingRow":3,
"repeatHeaders":false,
"mappings":{
"CL_Name":"Name",
"CL_Code":"Code",
"CL_Description":"Description"
"Business_ID":"Business ID"
},
"approvalOptions":{
"priority":"LOW",
"dueDate":"2024-12-30",
"comments":"Please approve the request"
}
}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

The CSV file might contain the following header rows and data rows:

CL_Name,CL_Code,Business_ID
Afghanistan,AFG,RDM001
Aland Islands,ALA,RDM002
Albania,ALB,RDM003
Algeria,DZA,RDM004
American Samoa,ASM,RDM005

The following sample response shows the status of the import job:

{
"jobId":"32121c139c84a8edc8696c0c",
"state":"INPROGRESS",
"startTime":1631086520325,
"numOfRecordsProcessed":100,
"numOfRecordsFailed":25,
"numOfRecordsSucceeded":75
}

Import crosswalk values (v3)

Imports value mappings into a crosswalk based on an internal ID or alias.

POST request

To import value mappings into a crosswalk based on an internal ID or alias, submit a POST request with the following URI:

/rdm-service/external/v3/import

The request contains form-data with two parameters:

file: Specify a CSV file that contains the code value attributes. The columns specified depend on your data model. The CSV must contain one or two header rows, followed by the data rows. If the occurrence of header row is one in the import CSV file, you must set the repeatHeaders field to false.; For example, you might have the following code values:
importSettings: Specify the file-specific configuration and container details.; The importSettings includes the following attributes:

Field	Type	Description
delimiter	String	Delimiter used to separate values. Value must be COMMA, SEMICOLON, SPACE, or TAB.
textQualifier	String	Symbol used to indicate where a text begins and ends. Value must be DOUBLE_QUOTE, SINGLE_QUOTE, or NO_QUOTE.
codepage	String	Code page used for the import file. Value must be UTF8 or MS_WINDOWS.
dateFormat	String	Format used for dates. Use one of the following formats: - DE. For dd.mm.yyyy format. - ISO. For yyyy-mm-dd format. - US_HYPHEN. For mm-dd-yyyy format. - US_SLASH. For mm/dd/yyyy format.
containerType	String	Type of asset that contains value mappings. Value must be crosswalk.
containerKey	String	Internal ID or alias of the crosswalk to which you want to import value mappings.
startingRow	String	Line number from which to start importing data. By default, all rows are imported.
repeatHeaders	Boolean	Optional. Indicates whether the file has two headers. Value is true or false. Default is true.
mappings	Object	Optional. Maps the column headers in the CSV file with the target attributes of code lists in the key-value format. - You can map the user-defined column name to source field name if required. - You can either choose to ignore the mapping or map all the columns in an import CSV file. Note: The key represents the header in the CSV file, and the value represents the field names in Reference 360.
approvalOptions	Array	Includes details about the approval parameters.
priority	String	Optional. Defines the priority of the approval request. Value can be LOW, MEDIUM, HIGH, or CRITICAL.
dueDate	String	Use the following format: yyyy-MM-dd.
Comments	String	Comments that the requester adds to explain the changes.

POST response

The response contains the details of the import job.

The following table describes the attributes in the response body:

Field	Type	Description
jobId	String	ID of the job.
state	String	Status of the job. Values are CREATED, INPROGRESS, COMPLETED, SUSPENDED, FAILED, STOPPED, QUEUED or WARNING.
startTime	Number	Time, in milliseconds, when the job started.
numOfRecordsProcessed	Number	Number of records processed.
numOfRecordsFailed	Number	Number of records that failed to be imported.
numOfRecordsSucceeded	Number	Number of records successfully imported.

POST example

To import value mappings into a crosswalk, you might use the following request:

POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/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",
"startingRow":null,
"codepage":"UTF8",
"dateFormat":"ISO",
"containerType":"CROSSWALK",
"containerKey":"ent_country",
"repeatHeaders":true,
"mappings":{
"key":"sourcePKey",
"from":"_from.id.sourcePKey",
"to":"_to.id.sourcePKey"
},
"approvalOptions":{
"priority":"LOW",
"dueDate":"2024-12-30",
"comments":"Please approve the request"
}
}
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

The CSV file might contain the following header rows and data rows:

key,from, to
key,from, to
AF_AFG,AF,AFG
AL_ALA,AL,ALA
ALB_ALB,ALB,ALB
DZ_DZA,DZ,DZA
AS_ASM,AS,ASM

The following sample response shows the status of the import job:

{
"jobId":"32121c139c84a8edc8696c0c",
"state":"INPROGRESS",
"startTime":1631086520406,
"numOfRecordsProcessed":100,
"numOfRecordsFailed":25,
"numOfRecordsSucceeded":75
}

Import hierarchy relationships (v3)

Imports hierarchy relationships for code values and top-level code values into a hierarchy, with custom headers as optional settings. You can use this resource to import hierarchy relationships into a hierarchy based on an internal ID or alias.

POST request

To import hierarchy relationships based on an internal ID or alias, submit a POST request with the following URI:

/rdm-service/external/v3/import/hierarchy

The request contains form-data with two parameters:

file: Specify a CSV file that contains the hierarchy relationships. The CSV file contains one header row with two columns: Code and ParentCode. You can list the related code values below the header.; For example, you might have the following relationships in the CSV file:; If you import top-level code values, only use the Code column in the header row.; For example, you might have the following top-level code values:
importSettings: Specify the file specific configuration and container details.; The importSettings includes the following attributes:

Field	Type	Description
delimiter	String	Delimiter used to separate values. Value must be COMMA, SEMICOLON, SPACE, or TAB.
textQualifier	String	Symbol used to indicate where a text begins and ends. Value must be DOUBLE_QUOTE, SINGLE_QUOTE, or NO_QUOTE.
codepage	String	Code page used for the import file. Value must be UTF8 or MS_WINDOWS.
hierarchyKey	String	Internal ID or alias of the hierarchy to which you want to import relationships.
parentCodeListKey	String	Internal ID or alias of the parent code list. Note: If you import top-level code values, you do not need to provide this attribute.
childCodeListKey	String	Internal ID or alias of the child code list.
startingRow	String	Line number from which to start importing data. By default, all rows are imported.
repeatHeaders	Boolean	Optional. Indicates whether the file has two headers. Value is true or false. Default is true.
mappings	Object	Optional. Maps the column headers in the CSV file with the target attributes of code lists in the key-value format. - You can map the user-defined column name to source field name if required. - You can either choose to ignore the mapping or map all the columns in an import CSV file. Note: The key represents the header in the CSV file, and the value represents the field names in Reference 360.

POST response

The response contains details of the import job.

The following table describes the attributes in the response body:

Field	Type	Description
jobId	String	ID of the job.
state	String	Status of the job. Values are CREATED, INPROGRESS, COMPLETED, SUSPENDED, FAILED, STOPPED, QUEUED or WARNING.
startTime	Number	Time, in milliseconds, when the job started.
numOfRecordsProcessed	Number	Number of records processed.
numOfRecordsFailed	Number	Number of records that failed to be imported.
numOfRecordsSucceeded	Number	Number of records successfully imported.

POST example

To import hierarchy relationships into a hierarchy based on the internal ID or alias, you might use the following request:

POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/import/hierarchy HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=import.csv
Content-Type: text/plain

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

{
"delimiter":"COMMA",
"textQualifier":"DOUBLE_QUOTE",
"startingRow":0,
"codepage":"UTF8",
"hierarchyId":"eeb38899dd463330df844b8e",
"childCodeListId":"3ebff6c89e03c41d5dd08acc",
"parentCodeListId":"68c3ba1b4c3402a7cc18169a",
"mappings":{
"state":"Code",
"country":"ParentCode"
}
}--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

The CSV file might contain the following header row and data rows:

Code,ParentCode
C1,P1
C2,P2
C3,P3

To import top-level code values into a hierarchy, you might use the following request:

POST https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v2/import/hierarchy HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=import.csv
Content-Type: text/plain

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

{
"delimiter":"COMMA",
"textQualifier":"DOUBLE_QUOTE",
"startingRow":0,
"codepage":"UTF8",
"hierarchyId":"eeb38899dd463330df844b8e",
"childCodeListId":"3ebff6c89e03c41d5dd08acc",
"parentCodeListId":"68c3ba1b4c3402a7cc18169a",
"mappings":{
"state":"Code",
"country":"ParentCode"
}
}--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

The CSV file might contain the following header row and data rows:

Code
P1
P2
P3

The following sample response shows that status of the import job:

{
"jobId":"32121c139c84a8edc8696c0c",
"state":"INPROGRESS",
"startTime":1631086520353,
"numOfRecordsProcessed":100,
"numOfRecordsFailed":25,
"numOfRecordsSucceeded":75
}

Get import job status (v3)

Retrieves the status of an import job based on an internal ID or alias.

GET request

To get the status of an import job based on an internal ID or alias, submit a GET request with the following URI:

/rdm-service/external/v3/import/job/<job ID>

GET response

The response contains the details of the import job, such as the status of the import job, start time, and number of records processed for import.

The following table describes the attributes in the response body:

Field	Type	Description
jobId	String	ID of the job.
state	String	Status of the job. Values are CREATED, INPROGRESS, COMPLETED, SUSPENDED, FAILED, STOPPED, QUEUED or WARNING.
startTime	Number	Time, in milliseconds, when the job started.
numOfRecordsProcessed	Number	Number of records processed.
numOfRecordsFailed	Number	Number of records that failed to be imported.
numOfRecordsSucceeded	Number	Number of records successfully imported.

GET example

To get the status of an import job based on the internal ID or alias, you might use the following request:

GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/import/job/dd1b2018cb47cef99f8d0f42 HTTP/1.1
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

The following sample response shows the status of an 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
}

Get failed import job report (v3)

Retrieves an error report for a failed import job based on an internal ID or alias.

By default, the error report shows the first 100,000 records. To retrieve more records or to view the next page of records in the error report, use the query parameters.

GET request

To retrieve an error report for a failed import job based on an internal ID or alias, submit a GET request with the following URI:

/rdm-service/external/v3/import/job/<job Id>/errorDetails

To retrieve the paginated error report, submit a GET request with the following query parameters appended to the URI:

/rdm-service/external/v3/import/job/<job Id>/errorDetails?pageNum=<page number>&recordsPerPage=<records per page>

GET request query parameters

You can append the query parameters to the URI to retrieve paginated errors.

The following table lists the query parameters:

Parameter	Description
jobId	ID of the job.
pageNum	Optional. Page number to display. Default value is 0.
recordsPerPage	Optional. Number of records to display per page. Default value is 100000.

GET response

The response contains the error details, such as the line where the error occurred and the reason.

The following table describes the attributes in the response body:

Field	Type	Description
jobId	String	ID of the job.
entityType	String	Type of entity imported. Value is BusinessEntity or Relationship.
fileName	String	Name of the file. Value must end with the .csv file extension.
entityName	String	Name of the entity.
errorDetails	Array	Includes the error details.
lineNumber	Number	Line number where the error occurred.
entitySourcePkey	String	Column identifier.
reasons	Array	Explanation of failure.

GET example

To retrieve an error report for a failed import job based on the internal ID or alias, you might use the following request:

GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/import/job/dae4301e9369c16c08bf0881/errorDetails HTTP/1.1

To retrieve the second page of records in a paginated error report with 100 records per page, you might use the following request:

GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v3/import/job/dae4301e9369c16c08bf0881/errorDetails?pageNum=2&recordsPerPage=100 HTTP/1.1

The following sample response shows the error report for a failed code values import job:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 395
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX

{
"jobId":"5984980d317a4b00cfe18880",
"entityType":"BusinessEntity",
"fileName":"import.csv",
"entityName":"rdm.value.be.442ac56e11d5fc9bb11f6a3f",
"errorDetails":[
{
"lineNumber":1,
"entitySourcePkey":"Code-1101",
"reasons":[
"The code value INX does not exist in the picklist that is in the path Country. Specify a code value from the picklist."
]
}
]
}

The following sample response shows the error report for a failed value mappings import job:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 354

{
"jobId":"dae4301e9369c16c08bf0881",
"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."
]
}
]
}