Importing Excel files

The import commands for Excel files must have the mandatory operations 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 Excel file:

Example

${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
        }
      ]
    }
  },
}]

Excel parameters

Parameter	Description	Default value
template	The JSON template used to interpret CSV or Excel data. Mandatory.
sheetName	The name of the Excel sheet.	If the name is null and sheetIndex is null, the first sheet of the workbook.
sheetIndex	The index of the Excel sheet.	If the index is null and sheetName is null, the first sheet of the workbook.
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 Excel 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:

Example

["${n}"]

The multivalue separator and quote characters are defined in section 8.1 of the DGC service configuration. If not defined, the separator is , and the quote is ".

Example

The third column in the following Excel example contains two values: C and D.

A	B	C,D

Example

The third column in the following Excel example contains one value: C,D.

A	B	"C,D"

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 \.

Example

Use an escape character before the special character you want to escape:

Excel 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, the multivalue separator, or the escape character in v2 so far, you should no longer do so. This is valid only for importing assets. You can still import multivalues in a relation column when importing complex relations.

Example

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}"
    ]
  }
]