Resource: External Systems ( /api/externalsystems )

This is a collection resource which allows the search and retrieval of all or a subset of external systems (Defect Trackers, Enterprise Architect connections etc.).

Root Relation: ExternalSystems

This resource supports the following methods: GET, POST

Methods

GET

Retrieves all (or a subset) of external systems.

This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.

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.

Example - Get all external systems

An example of retrieving all external systems.

Request Headers

Key	Value	Description
Accept	application/json

Response Headers

Key	Value	Description
Content-Type	application/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "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"
    },
    {
      "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"
    }
  ],
  "Self": "http://localhost/ExternalSystems"
}

Status Code

200 - OK

Example - Get external systems filtered by type

An example of retrieving a set of external systems by type using the ODATA $filter query parameter.

Request Headers

Key	Value	Description
Accept	application/json

Request Parameters

Key	Value	Description
$filter	Type eq 'Jira'	The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Jira'.

Response Headers

Key	Value	Description
Content-Type	application/json; charset=utf-8

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "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"
    }
  ],
  "Self": "http://localhost/ExternalSystems?$filter=Type eq 'Jira'"
}

Status Code

200 - OK

POST

Create a new 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
201 - Created	Returned if the request was completed successfully.

Example - Create new external system

An example of creating a new external system (without any additional field values).

Request Headers

Key	Value	Description
Content-type	application/json
Accept	application/json

Request Body

{
  "Type": "Jira",
  "Name": "Jira"
}

Response Headers

Key	Value	Description
Location	http://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
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

201 - Created

Example - Create new external system (with field values)

An example of creating a new external system with full configuration supplied in field values.

Request Headers

Key	Value	Description
Content-type	application/json
Accept	application/json

Request Parameters

Key	Value	Description
$expand	FieldValues	Include field values in response.

Request Body

{
  "Type": "Jira",
  "Name": "Jira",
  "FieldValues": {
    "Url": "http://mycompany.com:8090/",
    "UserName": "remote",
    "Password": "password",
    "IgnoreInvalidRemoteCertificates": false
  }
}

Response Headers

Key	Value	Description
Location	http://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
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

201 - Created