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

Methods


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.

  • Resources/ExternalLinks
  • Configuration
  • ExternalSystem

For more details on expansions, please see the Expand help topic.

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

An example of retrieving all external system links.

Request Headers

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Response Headers

KeyValueDescription
Content-Typeapplication/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",
      "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": [],
      "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",
      "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": [],
      "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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/json

Request Parameters

KeyValueDescription
$filterType 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

KeyValueDescription
Content-Typeapplication/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",
      "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": [],
      "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.

  • Resources/ExternalLinks
  • Configuration
  • ExternalSystem

For more details on expansions, please see the Expand help topic.

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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/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

KeyValueDescription
Locationhttp://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Typeapplication/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",
  "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": [],
  "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

KeyValueDescription
Content-typeapplication/json
Acceptapplication/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

KeyValueDescription
Locationhttp://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913
Content-Typeapplication/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",
  "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": [],
  "Self": "http://localhost/api/externalsystemlink/a01fc7ed-3492-4792-9a0b-e2b52fa10913",
  "Links": [
    {
      "Title": "Configuration Editor",
      "Href": "http://localhost/api",
      "Rel": "Edit"
    }
  ]
}

Status Code

201 - Created

  • No labels