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. |
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
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
- FieldValues
- FieldControls
- 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 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 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
- FieldValues
- FieldControls
- 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. |
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
- FieldValues
- FieldControls
- 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. |
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