Service Endpoints in Team Services

Last Update: 3/6/2017

Service endpoints are a way for Team Services to connect to external systems or services. They are a bundle of properties securely stored by Team Services which includes but is not limited to:

  • Service Name
  • Description
  • Server URL
  • Certificates or Tokens
  • User names and passwords

Extensions are then able to leverage the service endpoint to acquire the stored details to perform the necessary operations on that service. Follow this guide to create a new Service Point contribution and leverage it in your extension.

Tutorial Overview

This tutorial walks through developing a service endpoint by creating an example extension for Team Services that includes:

  • A custom service endpoint with data sources. This enables a build task or dashboard widget to call a REST endpoint on the service/server defined by the endpoint.
  • A build task which defines 2 properties: The service endpoint & a picklist which has values populated from the REST endpoint data source.

Note: Service endpoints created by users will be created at the project level, not the account level.

The steps involved in completing this tutorial are:

Note: This tutorial will refer to the home directory for your project as "home".

Step 1: Create the manifest file: vss-extension.json

The manifest file defines the custom endpoint and links to the task.json manifest for the build task.

In this tutorial, the manifest file creation is separated into three parts:

Create basic manifest file

Create a json file (vss-extension.json, for example) in the home directory of your extension.

{
"manifestVersion": 1,
  "id": "service-endpoint-tutorial",
  "version": "0.1.1",
  "name": "Sample extension that leverages a service endpoint",
  "description": "A sample Visual Studio Team Services extension which shows how to create a custom endpoint and dynamic build task parameters taking value from a REST API.",
  "publisher": "francistotten",
  "targets": [
    {
      "id": "Microsoft.VisualStudio.Services"
    }
  ],  
  "files": [
    {
      "path": "BuildTaskFolder"
    }
  ]
}

Note: You will need to update the publisher property.

Note: "BuildTaskFolder" is the path where we'll eventually place our build task definition

Add the custom endpoint contribution

Add the following contributions array underneath the targets array of the basic manifest content.

  "contributions": [
    {
      "id": "service-endpoint",
      "description": "Service Endpoint type for Fabrikam connections",
      "type": "ms.vss-endpoint.service-endpoint-type",
      "targets": [ "ms.vss-endpoint.endpoint-types" ],
      "properties": {
        "name": "fabrikam",
        "displayName": "Fabrikam server connection",
        "url": {
          "displayName": "Server Url",
          "helpText": "Url for the Fabrikam server to connect to."
        },
        "dataSources": [
          {
            "name": "Fabrikam Projects",
            "endpointUrl": "{{endpoint.url}}api/projects/index",
            "resultSelector": "jsonpath:$[*].nm"
          }

        ],
        "authenticationSchemes": [
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-token"
          },
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-basic",
            "inputDescriptors": [
              {
                "id": "username",
                "name": "Username",
                "description": "Username",
                "inputMode": "textbox",
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              },
              {
                "id": "password",
                "name": "Password",
                "description": "Password",
                "inputMode": "passwordbox",
                "isConfidential": true,
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              }
            ]
          }

        ],
        "helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"
      }
    },
  ],

If you have successfully added the service contribution correctly, you will see the Fabrikam endpoint when trying to add a new Service Endpoint to your Team Services account.

Go ahead and create a service endpoint using the Fabrikam endpoint.

Add the build task contribution

Inside the contributions array from the previous step, add the following object to the end.

{
      "id": "build-task",
      "description": "Task with a dynamic property getting data from an endpoint REST data source",
      "type": "ms.vss-distributed-task.task",
      "targets": [ "ms.vss-distributed-task.tasks" ],
      "properties": {
        "name": "BuildTaskFolder"
      }
    }

Note that the datasource endpointUrl is usually computed from the url of the endpoint (or a fixed url), and some additional values. For this tutorial this REST call will return nothing and is meant to be replaced by any REST calls you wish to make to your service.

It’s possible to use other parameters than the endpoint url for the REST URL, for instance some endpoint properties. For instance, assuming that we had a property in the endpoint named subscriptionId, the REST URL could use it with the following syntax: $(endpoint.subscription)

Step 2: Create the build task: task.json

The task.json file describes your build task.

NOTE

Take a look at the build task reference to find the schema for the build task json file.

Create a task.json file in your BuildTaskFolder directory, if you have not created this folder yet, do so now.

{
  "id": "6557a6d2-4caf-4247-99ea-5131286a8753",
  "name": "build-task",
  "friendlyName": "Build Task that uses the service endpoint",
  "description": "Task with a dynamic property getting data from an endpoint REST data source",
  "author": "francistotten",
  "helpMarkDown": "Replace with markdown to show in help",
  "category": "Build",
  "visibility": [
    "Build",
    "Release"
  ],
  "demands": [],
  "version": {
    "Major": "0",
    "Minor": "1",
    "Patch": "1"
  },
  "minimumAgentVersion": "1.95.0",
  "instanceNameFormat": "Service Endpoint Build Task $(project)",
  "inputs": [
    {
      "name": "FabrikamService",
      "type": "connectedService:Fabrikam",
      "label": "Fabrikam service/server end point",
      "defaultValue": "",
      "required": true,
      "helpMarkDown": "Select the Fabrikam end point to use. If needed, click on 'manage', and add a new Service Endpoint of type 'Fabrikam server connection'"
    },
    {
      "name": "project",
      "type": "pickList",
      "label": "Fabrikam Project",
      "required": true,
      "helpMarkDown": "Select the name of the Fabrikam Project to analyze.",
      "properties": {
        "EditableOptions": "True"
      }
    }
  ],
  "dataSourceBindings": [
    {
      "target": "project",
      "endpointId": "$(FabrikamService)",
      "dataSourceName": "Fabfrikam Projects"
    }
  ],
  "execution": {
    "Node": {
      "target": "sample.js",
      "argumentFormat": ""
    },
    "PowerShell3": {
      "target": "sample.ps1"
    }
  }
}

task.json components

The FabrikamService input object
This is the first field, of type connectedService:Fabrikam. connectedService expresses the fact that this is an endpoint type, and Fabrikam is simply the name of the object.

The project input object
This is the second field. It’s a picklist

  • This field is populated by a REST call.
  • The values from the field “project” are taken from the “Projects” REST data source of the custom endpoint.
  • This is expressed in the dataSourceBindings array
    • The target is the name of the build task field to be populated (“project”)
    • The endpointId is the name of the build task field containing the custom endpoint type
    • The REST call is chosen by the dataSourceName

If you've added the Build Task successfully, you should now see the Build Task when adding tasks to a Build Definition

Once you've added the Build Task to your definition, confirm that it can see the Fabrikam endpoint you created. The projects dropdown in this tutorial will be blank since we are not using a real service. Once you replace Fabrikam with your service, replace the Projects call with your own REST api call to leverage dynamic data inside your build task

Authentication Documentation

The authentication scheme in a service endpoint determines the credentials that would be used to connect to the external service. Check out the authentication schemes documentation for more information and to see the following authentication schemes:

  • Basic authentication
  • Token based authentication
  • Certificate based authentication
  • No authentication

Next Steps:

Now that you've written your extension, the next steps are to Package, Publish, and Install your extension. You can also check out the documentation for Testing and Debugging your extension.