Help Contents

 

External System

updated by Catch Admin (Mar 09, 2016)

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).

StatusDescription
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned 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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}A01FC7ED-3492-4792-9A0B-E2B52FA10913Unique identifier of the external system to delete.
keepReferencestrueKeep references but delete the external system (this is the default value for this parameter and can be omitted).

Response Headers

KeyValueDescription
Content-Typeapplication/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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}A01FC7ED-3492-4792-9A0B-E2B52FA10913Unique identifier of the external system to delete.
keepReferencesfalseDo not retain references (previously synchronized entities will have all references for this system removed).

Response Headers

KeyValueDescription
Content-Typeapplication/json; charset=utf-8

Status Code

200 - OK

GET

Retrieves a single external system by its identifier.

Required Permissions

  • Resources/ExternalLinks

Supported Expansions

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).

StatusDescription
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned if external system does not exist.

Example - Get External System

Example of fetching an external system by ID

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Response Headers

KeyValueDescription
Content-Typeapplication/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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}a01fc7ed-3492-4792-9a0b-e2b52fa10913

Response Headers

KeyValueDescription
Content-Typeapplication/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

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).

StatusDescription
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned 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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}744904d6-9612-4e87-a718-7b5d80c0060dUnique identifier of the external system to update.

Request Body

{ "Enabled": true }

Response Headers

KeyValueDescription
Content-Typeapplication/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

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).

StatusDescription
200 - OKReturned if the request was completed successfully.
404 - NotFoundReturned 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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
{id}744904d6-9612-4e87-a718-7b5d80c0060dUnique identifier of the external system to update.
$expandFieldValuesInclude 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

KeyValueDescription
Content-Typeapplication/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