External System Link
Resource: External System Link ( /api/externalsystemlink/{id} )
Allows the retrieval of details for a single external system link (Incident, Requirement, UseCase link etc.).
This resource supports the following methods: DELETE, GET, PATCH
Methods
DELETE
Deletes the external system link and optionally removes all associated references and events.
Required Permissions
Resources/ExternalLinks
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
|---|---|
200 - OK | Returned if the request was completed successfully. |
404 - NotFound | Returned if external system link does not exist. |
Example - Delete External System Link (and retain external system references)
An example of deleting an external system and retaining all the external references and events (previously synchronized entities will remain unchanged after deleting the link).
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | a01fc7ed-3492-4792-9a0b-e2b52fa10913 |
|
keepReferences | true | Keep references but delete the link (this is the default value for this parameter and can be omitted). |
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Status Code
200 - OK
Example - Delete External System Link (and remove external system references)
An example of deleting external system and removing all external system references and events.
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | a01fc7ed-3492-4792-9a0b-e2b52fa10913 |
|
keepReferences | false | Remove all references and events associated with this link. |
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Status Code
200 - OK
GET
Retrieves a single external system link by its identifier.
Required Permissions
Resources/ExternalLinks
Supported Expansions
Configuration
ExternalSystem
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
|---|---|
200 - OK | Returned if the request was completed successfully. |
403 - Forbidden | Returned if you do not have the necessary permissions to view this external system link. |
404 - NotFound | Returned if external system link does not exist. |
Example - Get External System Link
An example of retrieving an external system link by its identifier.
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | a01fc7ed-3492-4792-9a0b-e2b52fa10913 |
|
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
"ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
"ProjectName": null,
"Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"Type": "Incident",
"TypeForDisplay": null,
"ExternalSystemName": "Jira PROD",
"ExternalSystemImplementationType": "Jira",
"ExternalSystemConnectionType": null,
"Name": "Project X",
"Enabled": false,
"LastSynchronizedAt": "2012-01-01T14:04:07Z",
"LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
"LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
"ConfigurationComplete": true,
"ConfigurationProblems": [],
"AutoSelect": "NotApplicable",
"Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"Links": [
{
"Title": "Configuration Editor",
"Href": "http://localhost/api",
"Rel": "Edit"
}
]
}
Status Code
200 - OK
PATCH
Updates the enabled state of the external system link to enabled or disabled.
Required Permissions
Resources/ExternalLinks
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
|---|---|
200 - OK | Returned if the request was completed successfully. |
404 - NotFound | Returned if external system link does not exist. |
Example - Enable External System Link
An example of changing the enabled state of a link by its ID.
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | a01fc7ed-3492-4792-9a0b-e2b52fa10913 |
|
Request Body
{ "Enabled": true }
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
"ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
"ProjectName": null,
"Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"Type": "Incident",
"TypeForDisplay": null,
"ExternalSystemName": "Jira PROD",
"ExternalSystemImplementationType": "Jira",
"ExternalSystemConnectionType": null,
"Name": "Project X",
"Enabled": true,
"LastSynchronizedAt": "2012-01-01T14:04:07Z",
"LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
"LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
"ConfigurationComplete": true,
"ConfigurationProblems": [],
"AutoSelect": "NotApplicable",
"Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"Links": [
{
"Title": "Configuration Editor",
"Href": "http://localhost/api",
"Rel": "Edit"
}
]
}
Status Code
200 - OK