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

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

StatusDescription
200 - OKReturned if the request was completed successfully.

Example - Get all external systems

An example of retrieving all external systems.

Request Headers

KeyValueDescription
Acceptapplication/json

Response Headers

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

KeyValueDescription
Acceptapplication/json

Request Parameters

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

Response Headers

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

StatusDescription
201 - CreatedReturned 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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Body

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

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
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

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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesInclude field values in response.

Request Body

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

Response Headers

KeyValueDescription
Locationhttp://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D
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

201 - Created

  • No labels