> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/guides/working-with-the-import-api-v2/importing-csv-and-excel-files/importing-excel-files.md). # Importing Excel files The import commands for Excel files must have the mandatory operations fields and identifier requirements as the [import commands](/api/guides/working-with-the-import-api-v2/import-commands.md). The difference is that the [JSON template](/api/guides/working-with-the-import-api-v2/importing-csv-and-excel-files/formatting-json-template-files.md) contains placeholders for the data that must be retrieved from the Excel file: {% tabs %} {% tab title="Example" icon="glasses-round" %} `${n}`, where *n* represents the number of the table column. {% endtab %} {% endtabs %} {% hint style="info" %} The first column is 1. {% endhint %} {% hint style="warning" %} 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. {% endhint %} You can use a combination of placeholders and hard-coded values in the JSON template. ## JSON template structure ```json [{ "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](/api/guides/working-with-the-import-api-v2/importing-csv-and-excel-files/formatting-json-template-files.md) 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](/api/guides/working-with-the-import-api-v2/importing-json-files.md): {% tabs %} {% tab title="Example" icon="glasses-round" %} `["${n}"]` {% endtab %} {% endtabs %} 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 `"`. {% tabs %} {% tab title="Example" icon="glasses-round" %} The third column in the following Excel example contains two values: `C` and `D`. | A | B | C,D | | ------------- | - | --- | | {% endtab %} | | | | {% endtabs %} | | | {% tabs %} {% tab title="Example" icon="glasses-round" %} The third column in the following Excel example contains one value: `C,D`. | A | B | "C,D" | | ------------- | - | ----- | | {% endtab %} | | | | {% endtabs %} | | | ## 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 `\`. {% tabs %} {% tab title="Example" icon="glasses-round" %} 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** | | {% endtab %} | | | | {% endtabs %} | | | ## 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. {% tabs %} {% tab title="Example" icon="glasses-round" %} Column numbers `x`, `y`, `z`,and `n` are all considered as single value columns. ```json [ { "resourceType": "Asset", "identifier": { }, "relations": { "00000000-0000-0000-0000-000000007001:SOURCE": [ { "name": "${x}", "domain": { "name": "${y}", "community": { "name": "${z}" } } } ] }, "tags": [ "${n}" ] } ] ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.collibra.com/api/guides/working-with-the-import-api-v2/importing-csv-and-excel-files/importing-excel-files.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.