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
- Widgets
- 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
- Widgets
- 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
- Widgets
- 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