Web Service Steps

This introduction article will help TDX Administrators to configure Web Service Steps using the TDAdmin interface. The user must have the Admin permissions in the TDAdmin interface.

Overview

Web service steps can be added to a workflow like any other step. An associated web service and method must be selected for a web service. Workflow web service methods are ways of calling other applications (or even calling the TeamDynamix API). For example, a web service method might call your listserv application to create a new listserv with parameters from a ticket. For each web service step, the system can notify different groups of people depending on whether the web service call has succeeded or failed.

Web service steps have two distinct success and failure branches. When a web service call completes and the remote server has indicated that the option was successful (with a HTTP response code in the 200 range), the success branch will be taken. In all other instances, the failure branch will be taken. In addition, when a call is successfully executed, or a call fails with a recognized JSON, plain text, or XML response, the response returned by the server can be stored in the workflow for use with the From the Workflow web service method parameter.

For example, JSON returned by the external server can be stored in the workflow using the Ticket field, and another web service method can use the From the Workflow source parameter, and the Ticket field or even properties such as Ticket.ID. Similarly, the response code returned by the server can also be stored in any field.

Learn more about the TeamDynamix API/Web Services.

Where to Find This

This feature appears in the TDAdmin interface.

TDAdmin is where Users can create/manage Web Services.

Navigate to Workflow Web Services following these paths:

• TDAdmin > Applications > Ticketing Application > Workflow Web Services

Using Web Service Steps

Creating a Web Service Workflow Step

There are several actions required to create a web service workflow step:

1. Define the provider, which serves as the base for the web service.
2. Create authentication credentials for the web service(s) that will be called.
3. Create a web service and associated method to call from the workflow step. The web service method is the actual endpoint or URL to call. This is where the majority of configuration occurs.
4. Create a web service step in a workflow that calls the web service.

Defining the Provider

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

To create a web service provider:

1. In TDAdmin, go to the Admin application.
2. Select Users & Roles then Users in the left navigation.
3. Click the Create button in the Users Detail window.
4. Enter the following details:
   1. Username – web-service-example@your-institution.edu
   2. Security role – Choose an enterprise security role
   3. Password – Make a note of your password
   4. First name – Webby the
   5. Last name – Web Service User
   6. Email – Set to an email address, such as your email address
   7. Alert Email – Same as email

Grant the selected user access to your ticketing application by navigating to User Record > Applications, then select the ticketing application. The Web Services Provider can be a service account as well vs. a user account as described above.

1. Navigate to TDAdmin > Applications > [Ticketing application] > Web Service Providers
2. Click the +New button, then create a web service provider by selecting the following:
   1. Name – TeamDynamix
   2. Base Web Service Provider URL – https://[Your TeamDynamix URL]/TDWebApi/api/
   3. Active – Check the check box
3. Click the Save button.

You now have a TeamDynamix web service provider plus an auth account that you can use to create a TeamDynamix web service method.

Creating Authentication Credentials

If the web service requires authentication, you need to define authentication credentials specific to the ticketing application. Supported types of auth accounts are: Basic, Generic OAuth 2.0, Google OAuth 2.0, Microsoft OAuth 2.0, and TeamDynamix Web API.

Any number of accounts can be created.

To define authentication credentials:

1. In TDAdmin, click Applications in the left navigation.
2. Select the desired Ticketing Application.
3. Select Workflow Web Services.
4. Click Web Service Auth Accounts. 
5. Select +New.

To create a web service auth account:

1. In TDAdmin, navigate to Web Service Auth Accounts, then click the +New button.
2. Enter the following details:
   1. Name – Webby the Web Service User
   2. Account Type – TeamDynamix Web API
3. Click the Save button.
4. Click the Edit button, then enter the following details:
   1. Active – Check the check box.
   2. TeamDynamix Web API URL –
      1. For the sandbox – https://[Your TeamDynamix URL]/SBTDWebApi/
      2. For production – https://[Your TeamDynamix URL]/TDWebApi/
   3. Username – Set to the username of the user you created above.
   4. Password – Set to the password of the TeamDynamix user you created above.

The following authentication models are supported:

• HTTP Basic
• TeamDynamix REST API
• Generic OAuth 2.0 (V9.5+)
• Google OAuth 2.0 (V9.5+)
• Microsoft OAuth 2.0 (V9.5+)

Creating a Web Service

Web services are specific to a ticketing application.

To create a web service:

1. In TDAdmin, click Applications in the left navigation.
2. Select the desired Ticketing Application.
3. Select Workflow Web Services.
4. Click Web Services Providers  
5. Select +New.

Creating a Web Service Method

Once a web service provider has been created, its individual web service methods can be created and edited. Web services allow you to make application programming interface (API) calls to tickets or other outlets using data within TeamDynamix to share within the tool itself or externally.

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 the following examples:

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

To avoid encoding issues, it is recommended that you 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. 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. 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.

Learn more about the TeamDynamix API/Web Services.

The components of web service methods include:

• 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. You should, however, 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 for this web service method. For example, myvalue.
  • Data Type – The type of data of the parameter. For example, an integer.
  • Source – Whether the parameter comes from the ticket data, or whether it is supplied by the workflow.
  • Source property – The field name being passed from the ticket or the workflow 
• Body – The HTTP body to be sent for a PUT, POST, or PATCH request.
• Authentication – The auth account you defined above, if needed.

To create a new web service method:

1. In TDAdmin, click Applications in the left navigation.
2. Select the desired Ticketing Application.
3. Select Workflow Web Services.
4. Select Web Service Methods.
5. A web service method has a URL, HTTP action, any number of headers, and when applicable, a response body. To template out different portions of the call depending on the associated ticket or current state of the workflow, parameters can be defined. Once defined, parameters can be substituted into the URL, headers, and response body as needed, but will not otherwise be submitted to the server.
6. To preview the templated contents of an HTTP request based on different parameter values, a Preview button is available on the detail page for each web service method.

Adding a Web Service Step to a Workflow

With everything set up you can create a web service step in a workflow that calls the web service.

To add a web service step to a workflow follow the link below:

• Learn how to add a step to a workflow here Configuring Ticket Workflows .

Executing Web Service Steps

Web service steps are executed in a separate process and therefore will not run immediately when they start. When an external web service call is made, the result of the attempt is logged and can be viewed through the Workflow Web Service Logs administrative option for a ticketing application.

To view Workflow Web Service Logs:

• In TDAdmin, click Applications in the left navigation.
• Select the desired Ticketing Application.
• Select Workflow Web Services.
• Select Workflow Web Service Logs.

A basic summary of information of the attempt is also posted to the corresponding ticket's feed by the system user.

To view Workflow Web Service Logs Feed entry on a ticket:

• In TDNext, click Applications Menu in the left navigation.
• Select the desired Ticketing Application.
• Select the ticket with the Web Service Step.
• View ticket Feed.

Individuals with the ability to force-approve workflow steps can use a "Skip" option, which will bypass the web service call and take the "Failure" branch. The permission to force-approve can be found in the Ticketing Application Security Roles under the “The user will be able to always approve/reject/skip ticket workflow steps” permission.

Using a Web Service in a Ticket’s Workflow to Update the Value of a Dropdown Attribute

For a higher-level overview of PATCH verbs, see the About Patching article in the TDX API documentation https://solutions.teamdynamix.com/TDWebApi/Home/AboutPatching.
For PATCH verbs more specific to TDX abilities, see https://solutions.teamdynamix.com/TDWebApi/Home/type/TeamDynamix.Api.JsonPatchOperation.

For a broader view of JSON PATCH operations, like op and add, see http://jsonpatch.com/.

Now, to apply this we need to add something like the following to the body. Parameters are not needed here because only an attribute value is being changed. The first item should be the correct syntax, but with human readable explanations. The second is more of a technical example of something that might work in the body of a PATCH call. 

1. 

[
{"So we are declaring we are about to execute on a JSON op": "and specifically a replace operation", "just stating that there will be a path to find the content": "/we want to look at the attributes folder/insert the TDX generated attribute ID1234", "this is just defining that we will supply a value to make the replace op work properly in the PATCH": "this is the TDX generated ID number of the attribute choice that we want to set"},
]

2.

[
{"op": "replace", "path": "/attributes/1234", "value": "5678"},
]

Gotchas & Pitfalls

• Creating Web Service Steps requires some knowledge and skill set in working with API endpoint. It usually helps getting some additional assistance by someone with development skills on your team.
• The Web Service Provider e.g. "Webby" does not go against your TDX licensing count.

Examples

Here are a few suggestions on what web services can be used for, with instructions to set up each.

• Create a ticket workflow step to Post to Slack
• Create a ticket workflow step that will add a feed entry to a ticket and notify the requestor

• Create a ticket workflow step that will change the status of a ticket.
• Create a ticket workflow step to copy a ticket.

• Create a ticket workflow step that will create a child ticket.
• Create a ticket workflow step that will create a second ticket.
• Using web services to post to Twitter