Getting started with web services

Ticketing applications can define web services: providers, authorization accounts, and methods. Web service methods can then be used within a ticket workflow, for example to post a message to Twitter or Slack.

When you realize you want to add a step to your workflows to call a web service, you need to do three things:

  1. Define the provider.The provider is the "base" for the web service.
  2. Define the "auth account," if needed. The "auth account" is how to authenticate to the web service, if the web service requires authentication.
  3. Define the web service method(s). The web service method is the actual "endpoint" or URL to call. This is where the majority of configuration occurs.

Define the provider

The web service provider is the "root" or the base of the web service method(s) you are going to define. Typically you would have one provider per web site.

Web service providers need a name and a base URL. Optionally, you can provide a description. Please make sure the "active" checkbox is checked before you use them.

Define the "auth account"

If the web service requires authentication, you need to define an "auth account." Two types of auth accounts are supported: "Basic" and "TeamDynamix Web API."

Define the web service method(s)

You need to define a web service method for each combination of URL + HTTP method that you want to call. For example, you would have a different web service method defined for each of these examples:

  • GET http://example.com/123
  • POST http://example.com/123
  • GET http://example.com

There are several components to web service methods:

  • Name: this is whatever you want to call the web service method. The name is seen in the workflow builder.
  • Web Service Provider: this is the appropriate web service provider that you defined above.
  • Method: this can be set to GET, POST, PATCH, or other methods.
  • URL: this is the actual URL to use. It is seeded when you select the web service provider. However, you should then edit the URL to whatever the appropriate URL is for this method.
  • Headers: any HTTP headers that should be sent along with this request.
  • Parameters: the information that you need from the workflow for this web service.
    • Parameter name: What you want to call the parameter (e.g. "myvalue") for this web service method
    • Data Type: what type of data the parameter is, e.g. an integer
    • Source: should this parameter come from the ticket data, or should it be supplied by the workflow
    • Source property: the field name being passed from the ticket or the workflow 
  • Body: the HTTP body to sent for a PUT, POST, or PATCH request.
  • Authentication: the auth account you defined above, if needed.

Default Request Encoding

If you do not specify a Content-Type header with a specific encoding type, external web service method calls may encode your data in unexpected ways. To avoid encoding issues, it is highly recommended to validate which Content-Type header each of your external endpoints expect and set that as the Content-Type header on each TeamDynamix web service method respectively. For example, many RESTful APIs expect some sort of text/json or application/json content type. These are also the only two content types supported with the TeamDynamix RESTful APIs.

100% helpful - 1 review

Details

Article ID: 18610
Created
Wed 11/16/16 4:32 PM
Modified
Thu 6/20/19 12:37 PM

Related Articles (1)