‍

We’ve moved!

Our Help Center has a new home and our URLs have changed. Please update your bookmark to this page before April 30, 2026

Xurrent GraphQL Connector

Specialized connector for high-volume record retrieval and targeted CMDB lookups within the Xurrent platform.

Overview

Direct access to the Xurrent GraphQL API. Exposes a generic GraphQL query action plus three higher-level helpers for paginated record retrieval and CMDB lookups (people and software). Use it when you need to read data from Xurrent that the dedicated Xurrent connector's typed actions do not cover, or when you need to drive your own paginated queries from a runbook.

Prerequisites

A Xurrent account with API access.
Either an OAuth Application (Client credentials grant) configured from the Settings console in Xurrent, or a Personal Access Token generated from My Profile.

Authentication

Configure one of two credential modes on the outbound connection:

OAuth2 Client Credentials

Server-to-server. Create an OAuth Application from the Settings console in Xurrent (Client credentials grant), and paste the Client ID and Client secret into the connection.

Personal Access Token

Quick setup. Generate a token from My Profile > Personal Access Tokens in Xurrent and paste it as the Personal Access Token field. The token inherits the permissions of the user that created it. When set, PAT takes precedence and the OAuth client fields are not required.

An optional Account ID overrides the iPaaS account when you need to target a different Xurrent account from the same connection. The connector sends it as the x-xurrent-account header.

Triggers

None. This connector is outbound only.

Actions

Xurrent GraphQL Query

Minimal wrapper around the Xurrent GraphQL API. Send a raw query (with optional variables and operation name) and receive the raw data payload along with the rate-limit and cost-limit metadata returned by Xurrent.

Use case: any read or mutation that is not covered by the higher-level actions — e.g. ad-hoc reporting queries, deep field selections, mutations driven by runbook input.

Input Parameters

Parameter	Type	Required	Default	Description
`query`	String	Yes	-	The GraphQL query or mutation document.
`variables`	Hash	No	-	GraphQL variables. Secret-string values inside the hash are decrypted before the request is sent.
`operation_name`	String	No	-	Operation name to execute when the document defines multiple.

Example Input

{
"query": "query($id: ID!) { node(nodeID: $id) { ... on Person { id name primaryEmail } } }",
"variables": { "id": "5C5jO0e..." },
"operation_name": null
}

Output

Field	Type	Required	Description
`data`	Hash	Yes	The GraphQL `data` payload returned by Xurrent.
`ratelimit.limit`	Integer	No	Maximum requests permitted in the rate-limit window (`x-ratelimit-limit`).
`ratelimit.remaining`	Integer	No	Requests remaining in the current window (`x-ratelimit-remaining`).
`ratelimit.reset`	Integer	No	UTC epoch seconds when the rate-limit window resets (`x-ratelimit-reset`).
`costlimit.limit`	Integer	No	Maximum cost points permitted in the 60-minute window (`x-costlimit-limit`).
`costlimit.cost`	Integer	No	Cost of the current request (`x-costlimit-cost`).
`costlimit.remaining`	Integer	No	Cost points remaining in the current window (`x-costlimit-remaining`).
`costlimit.reset`	Integer	No	UTC epoch seconds when the cost window resets (`x-costlimit-reset`).
`request_id`	String	No	The `x-request-id` header from the Xurrent API response.

Example Output

{
"data": { "node": { "id": "5C5jO0e...", "name": "Ada Lovelace", "primaryEmail": "ada@example.com" } },
"ratelimit": { "limit": 7200, "remaining": 7188, "reset": 1714492800 },
"costlimit": { "limit": 5000, "cost": 12, "remaining": 4988, "reset": 1714492800 },
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Handling

HTTP error — the action fails the job with HTTP error from Xurrent GraphQL API: <status> '<body>' for any non-200 response that is not 429 or 503.
GraphQL errors — when the response body contains an errors array, the action fails the job with Errors from Xurrent GraphQL API: <errors json>.
Empty data — a 200 response with no data payload fails the job with No data from Xurrent GraphQL API.
Rate limit (429) / Service unavailable (503) — the action backs off for the duration in Retry-After (numeric seconds or HTTP-date) or 60 seconds when the header is missing or unparseable.

Retrieve Xurrent Records

This action retrieves all records of a certain type using the Xurrent GraphQL API. It builds a connection(first, view, filter, order, after) { pageInfo, totalCount, nodes } query, drives the cursor across pages via the iteration state, and emits one page per run.

Use case: bulk export of a record type into a downstream CMDB or report; backfilling a system that needs the full set of Xurrent records of a given type.

Input Parameters

Parameter	Type	Required	Default	Description
`connection`	String	Yes	-	The GraphQL connection name (e.g. `people`, `requests`, `configurationItems`). Must match `[A-Za-z0-9]+`.
`node_fields`	String	No	-	Additional fields to select on each node (e.g. `name primaryEmail`). `id` is always included.
`filter`	Array of `{field, value}`	No	`[]`	Each entry becomes a `field: value` clause inside `filter: { … }`. `field` must match `[A-Za-z0-9]+`. `value` is inlined verbatim — quote string literals yourself (e.g. `""foo""`).
`view`	String	No	-	View enum literal inlined as `view: <value>`. Each connection has its own view enum — e.g. `PersonView` accepts `all`, `all_with_roles`, `archive`, `current_account`, `trash`; `ConfigurationItemView` accepts `all`, `archive`, `current_account`, `spare_cis`, `supported_by_my_teams`, `trash`. Defaults to `current_account` when omitted.
`order`	Array of `{field, direction}`	No	`[]`	Each entry becomes `{ field: <field>, direction: <asc\|desc> }` inside `order: [ … ]`.
`page_size`	Integer	No	`100`	Records per page, 1–100.

Example Input

{
"connection": "people",
"node_fields": "name primaryEmail",
"filter": [{ "field": "disabled", "value": "false" }],
"view": "all",
"order": [{ "field": "name", "direction": "asc" }],
"page_size": 50
}

Output

Field	Type	Required	Description
`total_count`	Integer	Yes	`totalCount` returned by the connection.
`has_next_page`	Boolean	Yes	`true` when another page is available — the iteration state captures `endCursor`.
`nodes`	Array of Hash	Yes	Records on this page; each contains `id` plus any fields requested in `node_fields`.
`ratelimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`costlimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`request_id`	String	No	The `x-request-id` header from the Xurrent API response.

Example Output

{
"total_count": 412,
"has_next_page": true,
"nodes": [
  { "id": "5C5jO0e...", "name": "Ada Lovelace", "primaryEmail": "ada@example.com" }
],
"costlimit": { "limit": 5000, "cost": 18, "remaining": 4970, "reset": 1714492800 }
}

Error Handling

Empty connection result — when the connection name returns no payload (e.g. an unknown connection or one the credentials cannot read), the action fails the job with Content for connection.
All HTTP, GraphQL, rate-limit, and cost-limit failure modes match Xurrent GraphQL Query.

Fetch People from Xurrent for CMDB

Fetch people by searching across multiple identifier fields (authenticationID, primaryEmail, sourceID, employeeID, supportID). Returns a hash keyed by the input identifier with person data (id and any requested node fields). Identifiers are accepted as secret_string so they round-trip through the platform encrypted; the action decrypts them only when building the GraphQL request.

Use case: CMDB synchronisation where the source system supplies a list of user identifiers (emails, employee IDs) and the runbook needs to resolve each one to a Xurrent person record.

Input Parameters

Parameter	Type	Required	Default	Description
`identifiers`	Array of Secret string	Yes	-	Identifiers to resolve. Encrypted at rest for GDPR; decrypted only at request time.
`identifier_fields`	Array of String	No	`["authenticationID", "primaryEmail", "sourceID", "employeeID", "supportID"]`	Person fields to search. The action issues one `people` query per field, all aliased into a single GraphQL request.
`node_fields`	String	No	-	Additional Person fields to return on each record (e.g. `name jobTitle disabled`). `id` is always included.
`page_size`	Integer	No	`100`	Identifiers per batch, 1–100. The action paginates over the input list, one batch per run.

Example Input

{
"identifiers": ["ada@example.com", "alan@example.com"],
"identifier_fields": ["primaryEmail"],
"node_fields": "name jobTitle",
"page_size": 100
}

Output

Field	Type	Required	Description
`identifier_map`	Hash	Yes	Map keyed by the original (encrypted) identifier. Values are the matched person record.
`records`	Array of Hash	Yes	Deduplicated person records found in this batch. Each contains `id` plus the requested `node_fields`.
`has_next_page`	Boolean	Yes	`true` while more batches of input identifiers remain.
`stats.total_found`	Integer	No	Number of distinct persons returned for this batch.
`stats.total_searched`	Integer	No	Number of identifiers in the current batch.
`stats.batches_processed`	Integer	No	Always `1` — emitted per page rather than as a running total.
`ratelimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`costlimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`request_id`	String	No	The `x-request-id` header from the Xurrent API response.

Example Output

{
"identifier_map": {
  "ada@example.com": { "id": "5C5jO0e...", "name": "Ada Lovelace", "jobTitle": "Engineer" },
  "alan@example.com": { "id": "9HpQ2k8...", "name": "Alan Turing", "jobTitle": "Researcher" }
},
"records": [
  { "id": "5C5jO0e...", "name": "Ada Lovelace", "jobTitle": "Engineer" },
  { "id": "9HpQ2k8...", "name": "Alan Turing", "jobTitle": "Researcher" }
],
"has_next_page": false,
"stats": { "total_found": 2, "total_searched": 2, "batches_processed": 1 }
}

Error Handling

All HTTP, GraphQL, rate-limit, and cost-limit failure modes match Xurrent GraphQL Query.
Identifiers that resolve to no person are absent from identifier_map. The runbook treats missing keys as "not found in Xurrent".
Each identifier_fields query is capped at 100 matches by the underlying people(first: 100) clause; if a single identifier matches more than 100 persons the extras are dropped.

Fetch Software from Xurrent for CMDB

Fetch configuration items (software) by searching across name and alternateName fields. Returns an array of software records and a hash keyed by the input software name with CI data. Defaults to CI statuses reserved, being_built, installed, being_tested, standby_for_continuity, and in_production.

Use case: CMDB synchronisation where the source system reports installed software names and the runbook needs to map each to a Xurrent CI.

Input Parameters

Parameter	Type	Required	Default	Description
`software_names`	Array of String	Yes	-	Software names to resolve to Xurrent CIs.
`statuses`	Array of String	No	`["reserved", "being_built", "installed", "being_tested", "standby_for_continuity", "in_production"]`	CI statuses to include. Values are Xurrent `CiStatus` enum members.
`filter_fields`	Array of String	No	`["name", "alternateName"]`	Configuration-item fields to search across. The action issues one `configurationItems` query per field, aliased into a single GraphQL request.
`node_fields`	String	No	-	Additional CI fields to return on each record. Inlined verbatim into the GraphQL `nodes { … }` selection set, so nested selections are supported (e.g. `label status product { brand model supplier { name } }`). `id`, `name`, and `alternateNames` are always included.
`page_size`	Integer	No	`100`	Names per batch, 1–100. The action paginates over the input list, one batch per run.

Example Input

{
"software_names": ["Slack", "Zoom"],
"statuses": ["installed", "in_production"],
"filter_fields": ["name", "alternateName"],
"node_fields": "label status product { brand model }",
"page_size": 100
}

Output

Field	Type	Required	Description
`records`	Array of Hash	Yes	Deduplicated CI records found in this batch. Each contains `id`, `name`, `alternateNames`, plus the requested `node_fields`.
`name_to_record_map`	Hash	Yes	Map keyed by the input software name (and any of its alternate names that appear in the input).
`has_next_page`	Boolean	Yes	`true` while more batches of input names remain.
`stats.total_found`	Integer	No	Number of distinct CIs returned for this batch.
`stats.total_searched`	Integer	No	Number of names in the current batch.
`ratelimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`costlimit`	Nested	No	Same fields as Xurrent GraphQL Query.
`request_id`	String	No	The `x-request-id` header from the Xurrent API response.

Example Output

{
"records": [
  {
    "id": "C1abc...",
    "name": "Slack",
    "alternateNames": ["Slack Desktop"],
    "label": "Slack 4.40.0",
    "status": "in_production",
    "product": { "brand": "Slack Technologies", "model": "Slack Desktop" }
  }
],
"name_to_record_map": {
  "Slack": {
    "id": "C1abc...",
    "name": "Slack",
    "alternateNames": ["Slack Desktop"],
    "label": "Slack 4.40.0",
    "status": "in_production",
    "product": { "brand": "Slack Technologies", "model": "Slack Desktop" }
  }
},
"has_next_page": false,
"stats": { "total_found": 1, "total_searched": 2 }
}

Error Handling

All HTTP, GraphQL, rate-limit, and cost-limit failure modes match Xurrent GraphQL Query.
Names that match no CI are absent from name_to_record_map. The runbook treats missing keys as "not found in Xurrent".
Each filter_fields query is capped at 100 matches by the underlying configurationItems(first: 100) clause; if a single name matches more than 100 CIs the extras are dropped.

Best Practices

Prefer the dedicated Xurrent connector (Xurrent Query / Xurrent Mutation) when its typed, schema-introspected actions cover your use case. Reach for Xurrent GraphQL Connector for queries that need raw control or high-volume pagination.
Set node_fields to the minimum set of fields the runbook actually consumes. Over-selecting inflates costlimit consumption and slows pagination.
On long-running iterations, branch on has_next_page and costlimit.remaining to schedule work — the connector backs off automatically on 429, but spreading load avoids hitting the wall in the first place.
Use Personal Access Token for one-off integrations and short-lived prototypes; switch to OAuth2 Client Credentials once the integration is owned by a service rather than a person, so it survives staff changes.
For CMDB sync flows, pass identifiers as encrypted secret strings where applicable (the Fetch People from Xurrent for CMDB action requires it). This keeps PII out of plain runbook logs.

Common Use Cases

Bulk CMDB seeding — Retrieve Xurrent Records with connection: "configurationItems" and a view/filter matching the CIs to ingest, fed into the downstream CMDB writer.
Person reconciliation — source system emits a list of user emails; Fetch People from Xurrent for CMDB resolves each to a Xurrent person; the runbook updates the source system with Xurrent IDs.
Software inventory mapping — endpoint-management agent reports installed software names; Fetch Software from Xurrent for CMDB resolves each to a Xurrent CI; the runbook links discovered installations to their CIs.
Custom export — Xurrent GraphQL Query with a hand-tuned query and operation_name, used for reporting feeds that don't fit the paginated record shape.

ITxM Platform

Xurrent GraphQL Connector

Overview

Prerequisites

Authentication

OAuth2 Client Credentials

Personal Access Token

Triggers

Actions

Xurrent GraphQL Query

Input Parameters

Example Input

Output

Example Output

Error Handling

Retrieve Xurrent Records

Input Parameters

Example Input

Output

Example Output

Error Handling

Fetch People from Xurrent for CMDB

Input Parameters

Example Input

Output

Example Output

Error Handling

Fetch Software from Xurrent for CMDB

Input Parameters

Example Input

Output

Example Output

Error Handling

Best Practices

Common Use Cases

References

In this article