# External Catalog References

Catalog mapping is a mechanism for organizing reference data used in workspace documents. Catalog data from the integrating system are represented inside workspacees by external reference records. External reference records can be created directly by the user or indirectly by the system when it creates documents in the workspace.

The list of catalog types supported by the workspace can be obtained from the workspace record.

For catalog synonyms API see synonyms.

# Data Model

All entities used for this API follow canonical Entity Envelope data format. Below is the external reference record entity body schema.

Field Type Description
workspace UUID Reference to the parent workspace.
xtype string Catalog type.
ownerParty UUID Reference to the organization record for the integration party which has created this external reference. Used to identify the source catalog.
name string User-friendly textual representation of the catalog item.
xref string An external ID associated with this item in the party's internal system integrated with Bridge APIs.

# Example Body

{
    "workspace": "a2070b04-ca32-4a36-af58-c56e25715cb5",
    "ownerParty": "017950f1-7e14-44ae-b171-38b6903676d0",
    "name": "Gasoline Blendstock / GTAB",
    "xtype": "products",
    "xref": "50_26891"
}

# List External Reference Records for Catalog

GET /v2/workspaces/{workspace_id}/xrefs/{xtype}

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type string yes
limit Maximum number of records to return integer no 25
offset The number of records to skip integer no 0
sort List of comma-separated ordering criteria string: field:asc|desc no "created_at:desc, id:asc"

# Request body

None

# Response

An array of entity envelopes with the type set to navarik.bridge.externalReference and the body formatted to the external reference record model.

# Create External Reference Record

POST /v2/workspaces/{workspace_id}/xrefs/{xtype}

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type string yes

# Request body

See data model

# Response

A single entity envelope with the type set to navarik.bridge.externalReference and the body formatted to the external reference record model.

# Get External Reference Record by ID

GET /v2/workspaces/{workspace_id}/xrefs/{xtype}/{id}

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type string yes
id External reference record ID UUID yes

# Request body:

None

# Response

A single entity envelope with the type set to navarik.bridge.externalReference and the body formatted to the external reference record model.

# Update External Reference Record

PATCH /v2/workspaces/{workspace_id}/xrefs/{xtype}/{id}

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type string yes
id External reference record ID UUID yes

# Request body

Parameter Description Type Required Default
body Changes to the entity body. object yes
body.xtype Catalog type. string no
body.ownerParty Reference to the organization record for the integration party which has created this external reference. string no
body.name User-friendly textual representation of the catalog item. string no
body.xref An external ID associated with this item in the party's internal system integrated with Bridge APIs. string no

Note: Workspace reference can not be updated. Attempting to update workspace reference produces an error.

# Response

A single entity envelope with the type set to navarik.bridge.externalReference and the body formatted to the external reference record model.

# Delete External Reference Record

DELETE /v2/workspaces/{workspace_id}/xrefs/{xtype}/{id}

# Request parameters

Parameter Description Type Required Default
workspace_id Workspace ID UUID yes
xtype Catalog type string yes
id External reference record ID UUID yes

# Request body:

None

# Response

The latest known version of the deleted record as entity envelope with the type set to navarik.bridge.externalReference and the body formatted to the external reference record model.

← Synonyms →