Resource: External System Links ( /api/externalsystemlinks )

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

Root Relation: ExternalSystemLinks

This resource supports the following methods: GET, POST

Methods

GET

Retrieves all (or a subset) of external system links.

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

Required Permissions

Resources/ExternalLinks
TestManagement/ManageRequirements/View
TestManagement/ManageScripts/View
TestManagement/ManageIncidents/View
TestManagement/ManageExecutions/View

Supported Expansions

Configuration
ExternalSystem

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 system links

An example of retrieving all external system links.

Request Headers

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

Response Headers

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

Response Body

{
  "Top": 25,
  "Total": 2,
  "Items": [
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Incident",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    },
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Requirement",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ]
}

Status Code

200 - OK

Example - Get all external system links filtered by type

An example of retrieving a set of external system links by type and project Id, by using the ODATA $filter query parameter.

Request Headers

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

Request Parameters

Key	Value	Description
$filter	Type eq 'Incident' and ProjectId eq guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'	The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Incident'%20and%20ProjectId%20eq%20guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'

Response Headers

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

Response Body

{
  "Skip": 0,
  "Top": 25,
  "Total": 1,
  "Items": [
    {
      "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
      "ProjectName": null,
      "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Type": "Incident",
      "TypeForDisplay": null,
      "ExternalSystemName": "Jira PROD",
      "ExternalSystemImplementationType": "Jira",
      "ExternalSystemConnectionType": null,
      "Name": "Project X",
      "Enabled": false,
      "LastSynchronizedAt": "2012-01-01T14:04:07Z",
      "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
      "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
      "ConfigurationComplete": true,
      "ConfigurationProblems": [],
      "AutoSelect": "NotApplicable",
      "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
      "Links": [
        {
          "Title": "Configuration Editor",
          "Href": "http://localhost/api",
          "Rel": "Edit"
        }
      ]
    }
  ],
  "Self": "http://localhost/Enterprise/ExternalSystemLinks?$filter=Type eq 'Incident' and ProjectId eq guid'3AFBE0DD-55CA-419E-B75D-D21C821D7281'"
}

Status Code

200 - OK

POST

Create a new external systems link.

Required Permissions

Resources/ExternalLinks

Supported Expansions

Configuration
ExternalSystem

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 a new external system link

Create a new External System Link between a project in ET and a project in Jira, synchronizing requirements.

The ID of the project in ET is specified in the 'ProjectId' parameter of the Source FieldVaues object.

The ID of the project in Jira is specified in the 'ProjectId' parameter of the Destination FieldValues object.

Note: To determine the required FieldValues you can supply the '$expand=InitialFieldValues' query parameter when retrieving the list of External Sources from /api/externalsources, to include examples of what FieldValues are expected.

Request Headers

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

Request Body

{
  "Source": {
    "Key": "Requirement",
    "Id": null,
    "FieldValues": {
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281"
    }
  },
  "Destination": {
    "Key": "Synchronization",
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "FieldValues": {
      "ProjectId": "12345"
    }
  },
  "Name": "Project X"
}

Response Headers

Key	Value	Description
Location	http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Type	application/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Requirement",
  "TypeForDisplay": null,
  "ExternalSystemName": "Rally",
  "ExternalSystemImplementationType": "Rally",
  "ExternalSystemConnectionType": null,
  "Name": "Project X Requirements",
  "Enabled": true,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created

Example - Create a new external system link which is disabled

Create a new External System Link between a project in ET and a project in Jira, synchronizing requirements, and create it with the 'Enabled' state set to false.

Request Headers

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

Request Body

{
  "Source": {
    "Key": "Requirement",
    "Id": null,
    "FieldValues": {
      "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281"
    }
  },
  "Destination": {
    "Key": "Synchronization",
    "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
    "FieldValues": {
      "ProjectId": "12345"
    }
  },
  "Name": "Project X",
  "Enabled": false
}

Response Headers

Key	Value	Description
Location	http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Type	application/json; charset=utf-8

Response Body

{
  "ExternalSystemId": "b5ee119f-bc44-4b3c-befe-919f2fe3f4f7",
  "ProjectId": "3afbe0dd-55ca-419e-b75d-d21c821d7281",
  "ProjectName": null,
  "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Type": "Requirement",
  "TypeForDisplay": null,
  "ExternalSystemName": "Rally",
  "ExternalSystemImplementationType": "Rally",
  "ExternalSystemConnectionType": null,
  "Name": "Project X Requirements",
  "Enabled": false,
  "LastSynchronizedAt": "2012-01-01T14:04:07Z",
  "LastDestinationToSourceSynchronizationAt": "2012-01-01T14:04:05Z",
  "LastSourceToDestinationSynchronizationAt": "2012-01-01T14:04:06Z",
  "ConfigurationComplete": true,
  "ConfigurationProblems": [],
  "AutoSelect": "NotApplicable",
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created