External System
Resource: External System ( /api/externalsystem/{id} )
Allows the retrieval of the details for a single external system (Defect Tracker, Enterprise Architect connection etc.).
This resource supports the following methods: DELETE, GET, PATCH, PUT
Methods
DELETE
Delete the external system.
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 does not exist. |
Example - Delete an external system and retain references.
Delete an external system and retain references (previously synchronized entities will remain unchanged after deleting the system).
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | A01FC7ED-3492-4792-9A0B-E2B52FA10913 | Unique identifier of the external system to delete. |
keepReferences | true | Keep references but delete the external system (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 an external system and remove references.
Delete an external system and remove references (previously synchronized entities will no longer show as being synchronized to the external system).
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | A01FC7ED-3492-4792-9A0B-E2B52FA10913 | Unique identifier of the external system to delete. |
keepReferences | false | Do not retain references (previously synchronized entities will have all references for this system removed). |
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Status Code
200 - OK
GET
Retrieves a single external system by its identifier.
Required Permissions
Resources/ExternalLinks
Supported Expansions
Configuration
ExternalSystemLinks
AdditionalConfigurationLinks
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. |
404 - NotFound | Returned if external system does not exist. |
Example - Get External System
Example of fetching an external system by ID
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
{
"Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"OrganisationId": null,
"Name": "TFS",
"Type": "TFS2010",
"ConnectionType": "TFS2010",
"ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects",
"Enabled": true,
"QualifiedName": null,
"TypeDescription": null,
"NumberOfLinks": 0,
"Categories": [],
"UserName": "remote_tfs",
"HasPassword": true,
"ConfigurationComplete": true,
"ConfigurationProblems": [],
"Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913"
}
Status Code
200 - OK
Example - Get External System with configuration problems
Example of fetching an external system by ID which has configuration problems.
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
{
"Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
"OrganisationId": null,
"Name": "TFS",
"Type": "TFS2010",
"ConnectionType": "TFS2010",
"ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects",
"Enabled": true,
"QualifiedName": null,
"TypeDescription": null,
"NumberOfLinks": 0,
"Categories": [],
"UserName": null,
"HasPassword": false,
"ConfigurationComplete": false,
"ConfigurationProblems": [
"UserName is not configured",
"Password is not configured"
],
"Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913"
}
Status Code
200 - OK
PATCH
Updates the enabled state of the external system to enabled or disabled.
Required Permissions
Resources/ExternalLinks
Supported Expansions
Configuration
ExternalSystemLinks
AdditionalConfigurationLinks
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. |
404 - NotFound | Returned if external system does not exist. |
Example - Enable an external system
Enabling a disabled external system (will cause validation of external system configuration).
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | 744904d6-9612-4e87-a718-7b5d80c0060d | Unique identifier of the external system to update. |
Request Body
{ "Enabled": true }
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
"OrganisationId": null,
"Name": "Jira",
"Type": "Jira",
"ConnectionType": "Jira",
"ConnectionString": "http://mycompany.com:8090/",
"Enabled": true,
"QualifiedName": null,
"TypeDescription": null,
"NumberOfLinks": 0,
"Categories": [],
"UserName": "remote",
"HasPassword": true,
"ConfigurationComplete": true,
"ConfigurationProblems": [],
"Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}
Status Code
200 - OK
PUT
Update the external system.
Required Permissions
Resources/ExternalLinks
Supported Expansions
Configuration
ExternalSystemLinks
AdditionalConfigurationLinks
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. |
404 - NotFound | Returned if external system does not exist. |
Example - Update external system
An example of updating an external system with full configuration supplied in field values (Note: we set 'Enabled' true, which will cause the configuration to be validated).
Request Headers
Key | Value | Description |
|---|---|---|
Content-type | application/json |
|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
{id} | 744904d6-9612-4e87-a718-7b5d80c0060d | Unique identifier of the external system to update. |
$expand | FieldValues | Include field values in response as well. |
Request Body
{
"Type": "Jira",
"Name": "Jira",
"Enabled": true,
"FieldValues": {
"Url": "http://mycompany.com:8090/",
"UserName": "remote",
"Password": "password",
"IgnoreInvalidRemoteCertificates": false
}
}
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Id": "744904d6-9612-4e87-a718-7b5d80c0060d",
"OrganisationId": null,
"Name": "Jira",
"Type": "Jira",
"ConnectionType": "Jira",
"ConnectionString": "http://mycompany.com:8090/",
"Enabled": true,
"QualifiedName": null,
"TypeDescription": null,
"NumberOfLinks": 0,
"Categories": [],
"UserName": "remote",
"HasPassword": true,
"ConfigurationComplete": true,
"ConfigurationProblems": [],
"FieldValues": {
"Url": "http://mycompany.com:8090/",
"UserName": "remote",
"Password": "password",
"IgnoreInvalidRemoteCertificates": false
},
"Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d"
}
Status Code
200 - OK