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. |
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
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. |
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": [],
"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. |
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": [],
"Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"Links": [
{
"Title": "Configuration Editor",
"Href": "http://localhost/api",
"Rel": "Edit"
}
]
}
Status Code
200 - OK