Import Glossary Terms
import_glossary_termsCreate many business terms and their hierarchy in one call, resolving parents by name and validating before import. Reports per-row success or failure.
Instructions
Create many business terms, and their hierarchy, in one call.
Building a hierarchy one term at a time means a call per term and a wait between levels, because a child needs the parent's id from the previous response. This uses the glossary's own bulk import instead: one request for the whole tree, with parents resolved by name rather than by id, so nothing has to be threaded through.
Give each row a name and, for a child, a parent — the name of
another row in the same batch, or the path of a term that already exists
(levels separated by a backslash). Rows may be given in any order; they
are sorted so every parent is created before its children.
Attribute values take the same forms as create_glossary_term —
True/False for a boolean, a list for a multi-select — and are
validated here, per term type, before anything is sent. So are the term
type's required attributes: a row missing one fails inside the job
with a message naming only the field, so the batch is refused here
instead, before any of it is committed.
The import runs as a job and reports rows individually. A row can
fail while the rest succeed, so the result carries created,
failed and a failures list naming each bad row and why. Treat a
non-empty failures as a partial import: the successful rows are
already committed.
The result names the term each row became. terms carries
{name, path, term_id, existed} per row, so the next step — assigning
an asset, re-parenting, reading one back — needs no lookup. This costs
one filtered request per 40 distinct names, not one per term.
Two things the import does that a per-term create does not:
A row is written whole. With
update_existingthe term at that path is replaced, so an attribute the row omits is reset — not left as it was. Without it the existing term is left alone. Either way the job counts the row as successful, socreatedcounts rows the job accepted;newis the count of terms that did not exist before, withalready_existedthe rest andexistedsaying which is which per row.Omitted attributes take the term type's default, on new rows as well as replaced ones — the same as creating a term through the API.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| terms | Yes | The rows to create. Each is ``{"name": ..., "parent": ..., "definition": ..., "description": ..., "attributes": {...}}``; ``term_type`` may be given per row to mix types in one batch. | |
| dry_run | No | Validate and show what *would* be imported without importing anything: the rows in the order they would be sent, each with its resolved parent path and encoded attributes. Use it to let the person confirm a batch first — in a client that renders interactive views the preview appears as a table with an Import button; elsewhere, call again with ``dry_run=false`` once they agree. | |
| term_type | No | The term type for rows that do not name one. | |
| timeout_seconds | No | How long to wait for the import job (default 600). | |
| update_existing | No | Replace a term that already exists at the same path (default false, which leaves it untouched). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||