> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/link-manager-apis/xlsx.md).

# XLSX

## Upload Excel file to create concept-structure relations in bulk

> Creates links between business concepts and data structures in bulk from an Excel (XLSX) file. The file is processed asynchronously; a \`task\_reference\` is returned for tracking.\
> If the same file hash is being processed, the existing event is returned. Errors are reported per row in the job's event record.\
> \
> Links cannot be modified or deleted through this endpoint.\
> \
> \*\*Permissions:\*\* Two levels of checks apply:\
> \- \*\*Enqueue:\*\* The caller must hold \*\*'Manage business concept links'\*\* or \*\*'Link structures'\*\* (checked globally).\
> \- \*\*Per‑row validation:\*\* When the background job runs, each row is validated individually:\
>   \- The source concept's domain requires \*\*'Manage business concept links'\*\* (through the concept abilities).\
>   \- The target structure's domain requires both \*\*'View structures'\*\* and \*\*'Link structures'\*\* on the structure's domain.\
>   Rows that fail these checks are reported in the job's \`errors\` response.\
> \
> \*\*Request body (multipart/form-data):\*\*\
> \- \`relations\` (required, file) – XLSX workbook with the links.\
> \- \`source\` (required, string) – Must be \`"business\_concept"\`.\
> \- \`target\` (required, string) – Must be \`"data\_structure"\`.\
> \
> \*\*Workbook columns:\*\*\
> \- \`id\`, \`current\_version\`, \`concept\_name\`, \`concept\_type\`, \`domain\_external\_id\`, \`domain\_name\`, \`structure\_external\_id\`, \`structure\_name\`, \`structure\_system\`, \`path\`, \`link\_type\`.\
> \- \`concept\_type\` – The template's name (not the label).\
> \- \`link\_type\` – The relationship code as defined (not a translated label).\
> \- \*\*Required on upload:\*\* \`concept\_name\`, \`concept\_type\`, \`domain\_external\_id\`, \`structure\_external\_id\`.\
> \- \*\*Optional:\*\* \`link\_type\` – if omitted, the link is created without a specific type.\
> \
> \*\*Field formats (Excel uploads):\*\*\
> \- \*\*Number\*\* – Excel cell format Number or General.\
> \- \*\*Date\*\* – Excel cell format Date, or Text matching: \`yyyy-mm-dd\`, \`yyyy/mm/dd\`, \`dd-mm-yyyy\`, \`dd/mm/yyyy\`.\
> \- \*\*DateTime\*\* – Excel cell format Date, or Text matching: \`yyyy-mm-dd hh:mm:ss\`, \`yyyy/mm/dd hh:mm:ss\`, \`dd-mm-yyyy hh:mm:ss\`, \`dd/mm/yyyy hh:mm:ss\`.\
> \- \*\*Link\*\* – \`\[Link text] (<https://example.com/)\\`.\\>
> \- \*\*User or Group\*\* – \`user:Full Name\` or \`group:Group Name\` / \`group:Group Alias\`.\
> \- \*\*User\*\* – The user's full name without the \`user:\` prefix.\
> \- \*\*Group\*\* – Group name or alias without the \`group:\` prefix.\
> \- \*\*Table / Dynamic Table\*\* – Column headers separated by semicolons (\`;\`), with a line break inside the cell separating headers from data rows.\
> \- \*\*Multiple Values\*\* – Values separated by pipe (\`|\`).\
> \- \*\*Rich Text\*\* – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\
> \- \*\*Dropdown / Radio / Checkbox\*\* – Values must match the template definition exactly (case‑sensitive).<br>

```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/relations/links/upload":{"post":{"description":"Creates links between business concepts and data structures in bulk from an Excel (XLSX) file. The file is processed asynchronously; a `task_reference` is returned for tracking.\nIf the same file hash is being processed, the existing event is returned. Errors are reported per row in the job's event record.\n\nLinks cannot be modified or deleted through this endpoint.\n\n**Permissions:** Two levels of checks apply:\n- **Enqueue:** The caller must hold **'Manage business concept links'** or **'Link structures'** (checked globally).\n- **Per‑row validation:** When the background job runs, each row is validated individually:\n  - The source concept's domain requires **'Manage business concept links'** (through the concept abilities).\n  - The target structure's domain requires both **'View structures'** and **'Link structures'** on the structure's domain.\n  Rows that fail these checks are reported in the job's `errors` response.\n\n**Request body (multipart/form-data):**\n- `relations` (required, file) – XLSX workbook with the links.\n- `source` (required, string) – Must be `\"business_concept\"`.\n- `target` (required, string) – Must be `\"data_structure\"`.\n\n**Workbook columns:**\n- `id`, `current_version`, `concept_name`, `concept_type`, `domain_external_id`, `domain_name`, `structure_external_id`, `structure_name`, `structure_system`, `path`, `link_type`.\n- `concept_type` – The template's name (not the label).\n- `link_type` – The relationship code as defined (not a translated label).\n- **Required on upload:** `concept_name`, `concept_type`, `domain_external_id`, `structure_external_id`.\n- **Optional:** `link_type` – if omitted, the link is created without a specific type.\n\n**Field formats (Excel uploads):**\n- **Number** – Excel cell format Number or General.\n- **Date** – Excel cell format Date, or Text matching: `yyyy-mm-dd`, `yyyy/mm/dd`, `dd-mm-yyyy`, `dd/mm/yyyy`.\n- **DateTime** – Excel cell format Date, or Text matching: `yyyy-mm-dd hh:mm:ss`, `yyyy/mm/dd hh:mm:ss`, `dd-mm-yyyy hh:mm:ss`, `dd/mm/yyyy hh:mm:ss`.\n- **Link** – `[Link text] (https://example.com/)`.\n- **User or Group** – `user:Full Name` or `group:Group Name` / `group:Group Alias`.\n- **User** – The user's full name without the `user:` prefix.\n- **Group** – Group name or alias without the `group:` prefix.\n- **Table / Dynamic Table** – Column headers separated by semicolons (`;`), with a line break inside the cell separating headers from data rows.\n- **Multiple Values** – Values separated by pipe (`|`).\n- **Rich Text** – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\n- **Dropdown / Radio / Checkbox** – Values must match the template definition exactly (case‑sensitive).\n","operationId":"TdLmWeb.XlsxController.upload","parameters":[],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/XlsxUploadRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XlsxUploadResponse"}}},"description":"Accepted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmBadRequestMissingParamsResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Upload Excel file to create concept-structure relations in bulk","tags":["XLSX"]}}},"components":{"schemas":{"XlsxUploadRequest":{"additionalProperties":false,"properties":{"relations":{"description":"Excel file (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet or application/octet-stream)","format":"binary","type":"string"},"source":{"description":"Source resource type (e.g., business_concept)","type":"string"},"target":{"description":"Target resource type (e.g., data_structure)","type":"string"}},"required":["source","target","relations"],"title":"XlsxUploadRequest","type":"object"},"XlsxUploadResponse":{"additionalProperties":false,"properties":{"file_hash":{"description":"MD5 hash of the uploaded file","type":"string"},"status":{"description":"Upload status (e.g., PENDING, EVENT_FAILED)","type":"string"},"task_reference":{"description":"Reference to the background job (e.g., oban:123)","type":"string"}},"required":["status","file_hash","task_reference"],"title":"XlsxUploadResponse","type":"object"},"TdLmBadRequestMissingParamsResponse":{"additionalProperties":false,"properties":{"error":{"description":"Error code (e.g., missing_params)","type":"string"}},"required":["error"],"title":"TdLmBadRequestMissingParamsResponse","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```