Upsert Configuration Item Relationship

Submit a bulk operation to create or update one or more relationships between configuration items.

Special Access Rules

To upsert a configuration item relationship, you must have the following user permissions:

IT Service Configuration Item Type Manager
IT Service Configuration Item Owner

See Also

Get Operation Status

Request

JSON example

1mutation UpsertCnfgItemRelationships {
2  upsertCnfgItemRelationships(
3    input: {
4      relationshipRecords: [
5        {
6          sourceCnfgItemId: 22
7          targetCnfgItemId: 33
8          relationshipType: "SD_NOVa"
9        }
10      ]
11    }
12  ) {
13    id
14    status
15    lastModifiedOn
16    details
17    totalRecordCount
18    successRecordCount
19    failureRecordCount
20  }
21}

Properties

Name	Type	Description	Required or Optional	Available Version
`input`	UpsertCIRelationshipBulkInput	The top-level input container for the bulk create or update operation. Contains the array of configuration item relationship objects to process.	Required	67.0

UpsertCIRelationshipBulkInput

The top-level input container for create or update operations.

Name	Type	Description	Required or Optional	Available Version
`relationshipRecords`	RelationshipRecords	An array of configuration item relationship objects to be created or updated in a single bulk operation. Each element defines one relationship between a source and target configuration item.	Required	67.0

RelationshipRecords Input

Defines the structure for a single configuration item relationship within a bulk upsert request.

Name	Type	Description	Required or Optional	Available Version
`sourceCnfgItemId`	String	The unique identifier of the source configuration item in the relationship.	Required	67.0
`targetCnfgItemId`	String	The unique identifier of the target configuration item in the relationship.	Required	67.0
`relationshipType`	String	The developer name of the configuration item relationship type. Use a valid relationship type developer name defined in your Configuration Management Database.	Required	67.0

Response

JSON example

1{
2  "data": {
3    "upsertCnfgItemRelationships": {
4      "id": 109,
5      "status": "Processing",
6      "lastModifiedOn": "2025-11-14T10:15:00.123456Z",
7      "details": "Job queued - Upsert CI Relationship - Canonical API (1 items)",
8      "totalRecordCount": 100,
9      "successRecordCount": 90,
10      "failureRecordCount": 10
11    }
12  }
13}

Properties

Name	Type	Description	Available Version
`id`	Integer	The unique identifier of the asynchronous job. Use this ID with the `getStatus` query to check the operation progress and completion status.	67.0
`status`	String	The initial status of the asynchronous job.	67.0
`lastModifiedOn`	String	The date and time when the job was created or last updated, in YYYY-MM-DDTHH:MM:SSZ format.	67.0
`details`	String	User message describing the job.	67.0
`totalRecordCount`	Integer	The total records in the request.	67.0
`successRecordCount`	Integer	The total records processed successfully.	67.0
`failureRecordCount`	Integer	The total records that failed.	67.0

After submitting the upsertCnfgItemRelationships mutation, use the returned job id with the getOperationStatus query to check the operation progress and completion status.

Note