Integrations — EasyVista catalog sync

Integrations — EasyVista catalog sync

What this is for

EasyVista (EV) is one of the ITSM platforms TekReady targets. Once an engagement has been signed-off in TekReady, the agreed Incident and Request catalogues need to land in EV’s SD_CATALOG table so the help desk can actually take tickets against them. This integration removes the “hand-key 200 rows into EV” step.

TekReady exposes two read-only JSON endpoints, one per catalogue. EasyVista’s Easy Connect framework pulls those endpoints on a schedule and maps each node into SD_CATALOG. The integration is one-way: TekReady is the source of truth, EV is the consumer.

Endpoints

The {code} path variable is the engagement’s short code (the same one that appears in the engagement URL, e.g. ACME-2026).

Authentication

Both endpoints are protected by the standard uControl integration-API-key chain. Send the key on every request as either:

• X-Integration-Api-Key: ucm_…, or
• Authorization: Bearer ucm_…

The key must have the tekready:read scope and must belong to a user with access to the engagement (the same engagement-access rules that govern the UI apply — see The Engagement Workflow > Engagement access).

An integration key is generated by an admin under Settings → Integration API Keys. Give the EV consultant the key only — never the user password.

Response envelope

Both endpoints return the same shape:

{
  "engagementCode": "ACME-2026",
  "generatedAt": "2026-05-28T14:22:11Z",
  "prefix": "IT / Corporate",
  "nodes": [
    {
      "code": "TEK-ACME-2026-3f9a0c1b2d",
      "parentCode": null,
      "level": 1,
      "label": "IT",
      "path": "IT",
      "isLeaf": false,
      "metadata": null
    },
    {
      "code": "TEK-ACME-2026-9b1c4e7f08",
      "parentCode": "TEK-ACME-2026-3f9a0c1b2d",
      "level": 2,
      "label": "Corporate",
      "path": "IT / Corporate",
      "isLeaf": false,
      "metadata": null
    },
    {
      "code": "TEK-ACME-2026-c0d2a8e913",
      "parentCode": "TEK-ACME-2026-9b1c4e7f08",
      "level": 3,
      "label": "Cannot sign in to Outlook",
      "path": "IT / Corporate / Office 365 / Outlook / Cannot sign in",
      "isLeaf": true,
      "metadata": {
        "sla": "Gold",
        "impact": "Medium",
        "urgency": "High",
        "group": "Service Desk",
        "workflow": "Standard Incident",
        "ticketCode": "INC_OUTLOOK_NO_SIGNIN"
      }
    }
  ]
}

Field semantics

Ordering contract

Nodes are emitted parent-first (BFS by level). EV’s loader must process the array in order — never sort or reverse it. The guarantee: when the loader reaches node N, every node referenced by N’s parentCode has already appeared in the stream and been inserted.

This avoids the “child arrives before parent” case that breaks naive consumers that would otherwise try to forward-reference a parent code that doesn’t yet exist in SD_CATALOG.

Idempotency

• Codes are deterministic, so UPSERT by code in EV. A re-run of the same engagement’s endpoint produces the same codes for unchanged rows — no duplicates.
• If a row’s levels are edited in TekReady, its path changes ⇒ its code changes. EV will see this as a new node; the old one becomes orphaned. The recommended EV-side cleanup is a nightly sweep that deletes SD_CATALOG rows with codes prefixed TEK-{ENGAGEMENT}- that didn’t appear in the most recent pull.

EasyVista Easy Connect configuration

The end-to-end setup on the EV side (do this once per engagement; repeat for the second catalogue):

1. In EV Administration → Easy Connect, create a Service with the TekReady base URL. Pick HTTPS, GET, application/json.
2. Add the auth header to the Service: X-Integration-Api-Key: ucm_….
3. Create a Resource on the Service:
   • URI template: /api/v1/tekready/engagements/{code}/easyvista/incident-catalog.json (or request-catalog.json).
   • URI variables: add code with the engagement code as the value. Important: if you reopen the Resource later, the EV UI does not always re-display this value — re-enter it before saving any change, or the URL is built with an empty path variable and returns a 404.
   • Test request: should return HTTP 200 and the JSON envelope shown above.
4. Create a Connection that uses the Resource.
5. Configure the Selector on the Connection — EV uses JSONSelect (not JSONPath). The selector to pick the array of node objects is:

   .nodes > object

6. Open the Integration Model and set the Records root node to ['nodes'] with the link path ['_no_next_page'] (the feed is not paginated — this tells EV to stop after one fetch).
7. Map each JSON field to the matching SD_CATALOG column: code → CODE, label → NAME_EN, parentCode → PARENT_CODE (or your equivalent), and the leaf metadata fields to their respective columns.
8. Save, then run the Connection. EV will pull the JSON and write to SD_CATALOG in parent-first order.

Where the admin URL lives in TekReady

An admin-only panel sits at the top of the Incident Categories and Request Categories tabs once those sections are Final. It shows the full endpoint URL ready to paste into EV’s Resource configuration, plus a button to copy it to clipboard. Non-admin users do not see this panel.

Errors