Getting Started With Workflow Web Services

Summary

• What is Workflow Web Services?
• How to create a Service Account
• How to create a Web Service Auth Account & Web Service Provider
• Overview of Web Service Methods examples
• Tips & Tricks

What is Workflow Web Services?

Workflow web services allow us to use the TeamDynamix Web API to do a variety of different things against tickets in TeamDynamix ticketing applications. They can also be applied in ticketing workflows directly, so if you're using a ticket workflow, you can incorporate workflow web services to automate processes such as creating a new ticket in a different ticket application.

How to create a Service Account

To configure a service account:

1. In TDAdmin, navigate to > Users & Roles > Users.
2. Click Create > Create Service Account.
3. Enter a Username. This must be unique among all the usernames in the system
4. Click Next.
5. Fill in the required fields:
   1. First Name and Last Name - Service accounts require a separate first and last name (like a user) so that they can display in lists of users and accounts.
   2. Security Role - The selected security role will be applied to actions taken by the service account.
   3. Password
6. Click Finish to create the service account.
7. Use the Applications tab to add applications the account can access.
8. Use the Accts/Depts tab to add Accounts/Departments the account is associated with.

How to create a Web Service Auth Account & Web Service Provider

To create a Web Service Auth Account: 

1. In TDAdmin , go to Applications > [Ticketing application] > Workflow Web Services.
2. Select Web Service Auth Account and +New . 
3. Fill out the Name, Account type will be TeamDynamix Web API 
4. Leave the radio button marked to Enabled
5. Enter in the Service Account username and password.
6. Save

To create a Web Service Provider: 

1. Navigate to your Ticketing application in TDAdmin via Applications > [Ticketing App] > Workflow Web Services
2. Select Web Service Providers
3. 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.

Overview of Web Service Methods examples

Please visit the following articles for more detailed examples of using Web Service Methods:

• Using Web Services to Create a Second Ticket
• Using Web Services to Create a Ticket Task
• Using Web Services to Move Tickets

Tips and Tricks

Locating your API Catalog

The location of your API catalog will vary depending on if you have a vanity URL, or a standard-issue TeamDynamix URL.

Standard SaaS TeamDynamix URL:

• Production: https://ORGNAME.teamdynamix.com/TDWebAPI
• Sandbox: https://ORGNAME.teamdynamix.com/SBTDWebAPI

Vanity URL:

• Production: https://yourVanityURL/TDWebAPI
• Sandbox: https://yourVanityURL/SBTDWebAPI

Working with Parameters

In order to work with variables within your TeamDynamix workflow web service step, you need to declare them as parameters. Your TeamDynamix API catalog will indicate what aspects of the URL can be treated as variables by putting within a set of single { } curly braces. Within the API documentation, TeamDynamix only uses single curly braces in order to remain tool-agnostic, however, within TeamDynamix, a variable is declared by using a set of double {{ }} curly braces. Any parameters you declare in the parameters tab can then by referenced by including the parameter within a set of {{ }} anywhere within the workflow web service step.

E.g., you want to work with the endpoint from your API Catalog to patch a ticket within a workflow, https://YourDomain.teamdynamix.com/TDWebApi/api/{appid}/tickets/{id}

1. You can explicitly declare the ticketing appid within the API call (e.g., 100)
2. Change the URL from {id} to {{id}}
   • {id} is the documentation indicating that this can be a variable
   • {{id}} is how TeamDynamix recognizes that there is a variable and will check your declared parameters list to find the value of said variable
3. In the Parameters tab, set the following:
   1. Name as id (case-sensitive!)
   2. Data type as Integer (String will also work)
   3. Source is From Ticket
   4. Source Property is ID

The newly constructed URL is https://YourDomain.teamdynamix.com/TDWebApi/api/100/tickets/{{id}} which will assign the ID of the ticket to the variable id, and which will then perform the API call within Ticketing App, ID 100.

Constructing the API Body (Working with JSON)

When creating a Workflow Web Service Body for PATCH or POST, you may come across using these following pieces in your JSON:

• Angle Brackets: < >
• Parentheses: ( )
• Brackets: [ ]
• Braces: { }

For more information on working with JSON, reference the official JSON site.

Testing your Workflow Web Service Steps

There are two primary ways to test your newly constructed workflow web service step:

1. Using the Test Request button within the workflow web service, or
2. Assigning the workflow web service to a workflow step and sending a ticket through the workflow to trigger the step.