.png?sv=2022-11-02&spr=https&st=2025-03-12T19%3A18%3A12Z&se=2025-03-12T19%3A28%3A12Z&sr=c&sp=r&sig=6GXnrlGs2JPPUJ9TObDIfl%2BLXRBrcm1kicFqejfJsb0%3D){kind=logo}
Retrieving References Endpoint Replaced
- 11 Feb 2025
-
DarkLight
-
PDF
Retrieving References Endpoint Replaced
- Updated on 11 Feb 2025
-
DarkLight
-
PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Deprecation Notice
Beginning with the Platform 6 release, the /references-to endpoint is deprecated in favor of the /discoverReferences endpoint.
Retrieving References Prior to Platform 6
In the early versions of Itential Platform (IP/2022.1 → IP/2023.2 ), the /references-to endpoint was used to retrieve the assets that were referencing the target asset. The endpoint requires two query parameters, target-type and target-identifiers.
The example code blocks below demonstrate a proper GET request to /references-to and the expected response. In the example, the target asset is a workflow named childWorkflow that is referenced by two other workflows named parentWorkflow1 and parentWorkflow2.
GET Request
/automation-studio/references-to?target-type=workflow&target-identifiers=a5dd53e1-0459-4616-bbe3-50b29da3a299
Response
{
"referencesByTarget": [
{
"target": {
"identifier": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
"type": "workflow",
"name": "childWorkflow"
},
"totalReferencingInstances": 2,
"totalReferences": 2,
"references": [
{
"type": "workflow",
"_id": "56cb9387-2238-400f-9068-6e45e8bec241",
"name": "parentWorkflow1",
"canvasVersion": 3,
"referencePaths": [
"tasks.b700.variables.incoming.workflow"
]
},
{
"type": "workflow",
"_id": "96e76283-de19-4085-bb90-d8563d7a5985",
"name": "parentWorkflow2",
"canvasVersion": 3,
"referencePaths": [
"tasks.9c41.variables.incoming.workflow"
]
}
]
}
]
}
Note:
/references-to can only look “upward”, meaning in a child-parent relationship like this example, running /references-to on one of the parent workflows will not return any assets since nothing is referencing either of them
Retrieving References After Platform 6
With the Platform 6 feature release, the /discoverReferences endpoint has been implemented to provide a wider range of functionalities in regards to retrieving relevant assets for a particular asset, including projects. With /discoverReferences, you are able to specify what direction you want to be searching in, relative to the target asset (up, down, or all) and whether the search should be executed recursively past just one layer up/down (recursive: true or false).
This newly implemented endpoint fully encompasses the designed functionality of /references-to and the previous example can be reproduced with /discoverReferences as shown below.
POST Request
/automation-studio/discoverReferences
With the following body:
{
"resourceIdentifiers": [
{
"resourceType": "workflow",
"resourcePointer": "name",
"resourceId": "childWorkflow"
}
],
"includeResources": false,
"recursive": false,
"include": {
"workflow": "up"
}
}
Note:
In this example, we are only looking for references from workflows, but any of the asset tags listed in the metadata.ignore of the response can be added to the include property with a specified direction to search upon (up, down, or all).
Response
A data array containing the root resource and the retrieved assets.
{
"message": "Successfully discovered references",
"data": [
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
"parents": [
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
"parentPointer": "/tasks/9c41/variables/incoming/workflow"
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
"parentPointer": "/tasks/b700/variables/incoming/workflow"
}
],
"root": true
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
"parents": []
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
"parents": []
}
],
"metadata": {
"ignore": {
"jsonForm": "all",
"mopCommandTemplate": "all",
"mopAnalyticTemplate": "all",
"transformation": "all",
"template": "all",
"goldenConfig": "all",
"compliancePlan": "all",
"resourceModel": "all",
"automation": "all",
"trigger": "all",
"form": "all",
"configParser": "all",
"configSpec": "all",
"deviceBackup": "all",
"deviceGroup": "all",
"group": "all",
"integrationModel": "all",
"jsonSpec": "all",
"project": "all",
"role": "all",
"serverProfile": "all",
"serviceConfig": "all",
"tag": "all",
"user": "all"
}
}
}
Note:
If you set includeResources to true in the POST request body, then each item in the data array would include a resource property that contains the entire data object for that asset.
Enabling the Recursive Property
If you were to add another workflow named grandparentWorkflow that references the parentWorkflow1 and switched the recursive property to true, the response would include grandparentWorkflow even though it is not directly referencing childWorkflow, yet it is found in the recursive, upwards search.
Response
{
"message": "Successfully discovered references",
"data": [
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "a5dd53e1-0459-4616-bbe3-50b29da3a299",
"parents": [
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
"parentPointer": "/tasks/9c41/variables/incoming/workflow"
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
"parentPointer": "/tasks/b700/variables/incoming/workflow"
}
],
"root": true
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "56cb9387-2238-400f-9068-6e45e8bec241",
"parents": [
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "9d0784a6-c3a9-4879-bdbc-07c46ade39eb",
"parentPointer": "/tasks/2372/variables/incoming/workflow"
}
]
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "96e76283-de19-4085-bb90-d8563d7a5985",
"parents": []
},
{
"resourceType": "workflow",
"resourcePointer": "/_id",
"resourceId": "9d0784a6-c3a9-4879-bdbc-07c46ade39eb",
"parents": []
}
],
"metadata": {
"ignore": { … }
}
}
Was this article helpful?
