Importing CSV files

The import commands for CSV files must have the mandatory operation fields and identifier requirements as the import commands. The difference is that the JSON template contains placeholders for the data that must be retrieved from the CSV file:

${n}, where n represents the number of the table column.

The first column is 1.

Define each asset in consecutive rows. Mixing rows of one asset with the rows of another asset can cause the removal of the asset attributes or relations.

You can use a combination of placeholders and hard-coded values in the JSON template.

JSON template structure

 
[{
  "resourceType": "Community"
  "identifier": {
    "id": "${n}" //placeholder, where n = 1, 2, 3...)
  },
  "parent": {
    "id": "9f01ccd6-3329-49ef-af9a-3e1c9826f731"
  },
},
{
  "resourceType": "Domain"
  "identifier": {
    "id": "${n}"
  },
  "name": "${n}",
  "description": "${n}",
  "community": {
    "name": "${n}"
  },
  "type": {
    "name": "${n}"
  },
},
{
  "resourceType": "Asset"
  "identifier": {
    "name": "${n}",
    "domain": {
      "name": "${n}",
      "community": {
        "name": "${n}"
      }
    },
    "relations": {
      "relationTypeId:TARGET": [ //for example "9f01ccd6-3329-49ef-af9a-3e1c9826f737:TARGET"
        {
          "name": "${n}",
          "domain": {
            "name": "${n}",
            "community": {
              "name": "${n}"
            }
          }
        }
      ],
      "relationTypeId2": [ //the direction is not needed if it can be implicitly resolved
        {
          "name": "${n}",
          "domain": {
            "name": "${n}",
            "community": {
              "name": "${n}"
            }
          }
        }
      ]
    },
    "attributes": {
      "attributeTypeId": [
        {
          "value": "${n}"
        }
      ],
      "attributeTypeId2": [
        {
          "values": ["${n}"] //a multivalue attribute
        }
      ]
    }
  },
}]

CSV parameters

Parameter Description Default value
template The JSON template used to interpret CSV or Excel data. Mandatory.  
separator The delimiter character used to separate entries. ;
quote The delimiter character used for quoted entries. "
escape The delimiter character used to escape separator or quote character. \
strictQuotes Whether the characters outside quotes should be ignored. false
ignoreLeadingWhitespace Whether whitespace characters before quotes should be ignored. false
headerRow Whether the first row of the imported CSV file is the header. false

Multivalue separator and quote characters

Use the multivalue separator and quote characters when you import multiple values from the same column or the same line of your CSV file.

You can import multiple values from the same column, in an array, indicated by a placeholder enclosed in square brackets in your JSON template:

["${n}"]

If you use the default API request field separator (;), the multivalue separator is ,. Otherwise, the multivalue separator is ;.

For the default API request field separator parameter, the third column in the following CSV example contains two values: C and D.

A;B;C,D

If you use the default API request quote ("), the multivalue quote is |. Otherwise, the multivalue quote is ".

For the default values for the API request quote parameter, the third column in the following CSV example contains one value: C,D.

A;B;|C,D|

You can import multiple resources from the same row, in an array, indicated by the import command enclosed in square brackets:

For the default values for the API request separator parameter, the following combination of CSV and import template upserts two assets: A and B.


Name;Domain;Community;Asset Type
A,B;New Business Terms;Data Governance Council;Business Term


[
  [
    {
      "resourceType": "Asset",
      "identifier": {
        "name": "${1}",
        "domain": {
          "name": "${2}",
          "community": {
            "name": "${3}"
          }
        }
      },
      "type": {
        "name": "${4}"
      }
    }
  ]
]

The escape character

You can use an escape character to have the Import API treat the following special characters as normal characters when they are part of the values you are importing:

  • Separator characters
  • Quote characters
  • Escape characters

The default escape character is \.

For single value columns and rows, use one escape character before the special character you want to escape:

CSV value Escaped special character Imported value
C\;D Default separator character: ; C;D
\"CD\" Default quote character: " "CD"
C\\D Default escape character: \ C\D

For multivalue columns and rows, use two escape characters before the special character you want to escape:

CSV value Escaped special character Imported value
C\\,D Default multivalue separator character: , C,D
\\|CD\\| Default multivalue quote character: | |CD|
C\\\D Default escape character: \ C\D

Relation and Tag columns

To provide backward compatibility with version 1 of the Import API, version 2 processes Relation and Tag columns as a single value column. Though these columns are still within an array [] in the template, they are not parsed to extract multiple values. If you had escaped or quoted special characters such as the multivalue quote or multivalue separator in v2 so far, you should no longer do so. For the rows to be parsed correctly you must still escape the special characters in a CSV file such as the default escape character, which is the backslash, the default quote, which is the double quote or the default separator, which is the comma. This is valid only for importing assets. You can still import multivalues in a relation column when importing complex relations.

Column numbers x, y, z,and n are all considered as single value columns.

[
  {
    "resourceType": "Asset",
    "identifier": {

    },
    "relations": {
      "00000000-0000-0000-0000-000000007001:SOURCE": [
        {
          "name": "${x}",
          "domain": {
            "name": "${y}",
            "community": {
              "name": "${z}"
            }
          }
        }
      ]
    },
    "tags": [
      "${n}"
    ]
  }
]