Creating a Workflow Web Service Method that Uses Google OAuth 2.0

With TeamDynamix Version 9.5, workflow web services now support OAuth authentication. This means that you can create web service calls to any external system that supports OAuth 2.0 and incorporate those calls into your workflows.

In this example, we are going to create a Google Docs spreadsheet that will be updated by TeamDynamix as part of a TeamDynamix workflow.

For more information on OAuth 2.0 support in TeamDynamix, please see OAuth 2.0 Web Service Accounts. For more information on how to configure workflow web services, please see Getting started with web services.

Registering an Application with Google

Since Google supports OAuth 2.0 in its APIs, we're going to take advantage of that by registering an application to use them. Start by following Google's steps for Creating a Google API Console project and client ID. When performing this step, make sure to use the Google account for the user that will own the spreadsheet that we'll be writing to.

Create Google Credentials

When registering your application, Google will prompt you for "Authorized JavaScript origins" and "Authorized redirect URIs" values.

When prompted for authorized Javascript origins, you must provide your TeamDynamix origin. This value will be the base URL that you use to access TeamDynamix. For example, if you log in to TeamDynamix using the URL "https://abuniversity.teamdynamix.com/TDNext/Login.aspx", then the origin you should provide is https://abuniversity.teamdynamix.com.

For the authorized redirect URIs, you must provide your TeamDynamix base URL followed by "/TDAdmin/OAuth/Callback". In the above example, you would provide https://abuniversity.teamdynamix.com/TDAdmin/OAuth/Callback as the authorized redirect URI.

Google Restrictions

Once you've completed that process, Google will provide you with a client ID and client secret. Keep track of these as you'll need them later on.

Creating a Google Sheet

The next thing we'll need to do is create the Google sheet that we'll be using to write to in our web service method. To do this, go to Google Sheets, log in as the user you just registered your application with, and create a new blank spreadsheet.

Make sure to give your spreadsheet a name, and then type "Last Processed Ticket" into the A1 cell.

Create a Google Sheet

Changes to your spreadsheet will save automatically. Once you're finished, you'll need to take note of your sheet's ID. You can find this in the URL of your browser while you have the sheet open.

Google Sheet ID

The ID of your sheet is the string of letters and numbers between the slashes immediately preceeding the word "edit" in your URL. For example, if the URL for your sheet is "https://docs.google.com/spreadsheets/d/1oRRC0tBid05MUP6emVRSCzYRceyCVoYJGzNb-0vQWK0/edit#gid=0", then the ID of your spreadsheet is 1oRRC0tBid05MUP6emVRSCzYRceyCVoYJGzNb-0vQWK0.

Keep track of your spreadsheet ID as you'll need it later.

Creating the Web Service Auth Account

Now that you have your Google OAuth 2.0 credentials, it's time to create a web service auth account in TeamDynamix that uses them. To do this, we'll be creating a Google OAuth 2.0 web service auth account. See OAuth 2.0 Web Service Auth Accounts  for more information.

Log in to the Admin application and navigate to the following page.

Admin  >  Applications  >  [Application Name]  >  Web Service Auth Accounts  >  New

Once there, give your web service auth account a name and description, then choose the Google OAuth 2.0 as the Account Type. This will display additional options on the page for you to fill out. At this point, you must provide information for the following fields:

  • Client ID
  • Client Secret
  • Scope

For Client ID and Client Secret, use the values provided to you by Google when you registered your application. The scope you need to provide will be determined by what permissions your web service call will need. See Google's documentation for a full list of available scopes. In our case, we'll be writing to a Google sheet, so the scope we need to provide is https://www.googleapis.com/auth/spreadsheets.

New Google Auth Account

At this point, you're ready to authorize access, so click on the Generate Tokens buttons. This will prompt you for the username and password of the Google account for which you just registered your application. You'll notice that it will ask you for offline access. Allow it, and you'll notice that you've generated access and refresh token for the auth account.

At this point, make sure the account is marked as Active (by checking the Active checkbox if you have not already done so) and click the Save button.

Creating the Web Service Provider for Google Sheets

We now have the auth account ready to use, but now we need to create a web service provider for Google sheets. This will allow us to build a web service call to the Google Sheets API. We can get started by navigating to the page below.

Admin  > Applications  >  [Application Name]  >  Web Service Providers  >  New

For the Name field, let's call it "Google Sheets API". Then we need to provide the base web service URL. In the case of the Google Sheets API, that URL is https://sheets.googleapis.com/v4/spreadsheets. At this point, give the provider a useful description, mark it as active, and click Save.

Google Sheets Web Service Provider

Configuring the Web Service Method

Now you're ready to create the web service method that communicates with Google's servers. To do this, start by navigating to the page below.

Admin  > Applications  >  [Application Name]  >  Web Service Methods  >  New

Follow the steps below to configure a web service method that writes a ticket ID to a Google Sheet.

  1. Give your web service a useful name. In our case, let's call it "Write Ticket ID to Google Sheet" because that's what this API call is going to do.
  2. Choose "Google Sheets API" as the Web Service Provider. This will automatically fill in the URL for you.
  3. Change the web service type from GET to POST.
  4. Update the URL to be https://sheets.googleapis.com/v4/spreadsheets/[spreadsheetID]/values/A2:A2?valueInputOption=RAW where spreadsheetID is the ID of the Google sheet you created earlier.

    Web Service URL
     
  5. Create a TicketID parameter. Do this by clicking on the parameters tab and providing the following information for the parameter before clicking the Add button. Once finished, you'll see the parameter count increase from 0 to 1.
    1. Provide "TicketID" as the Name
    2. Select Integer as the Type
    3. Choose the "From Ticket" option
    4. Select ID as the ticket field
    5. Click Add

      Web Service Parameters
       
  6. Click on the Body tab and paste in the following snippet.
     
    {
      "range": "A2:A2",
      "majorDimension": "ROWS",
      "values": [
        [{{TicketID}}]
      ],
    }

    Web Service Body
     
  7. Click on the Authentication tab and select "Google Authentication".

Now we're ready to test our new web service method out. You can do this by clicking the Test Request button at the top of the page. Provide a value for the TicketID parameter and click the Send button.

Test Web Service Request

If everything worked correctly, you should see a response with a status of 200 OK and your Google sheet will get updated with the value you provided for TicketID!

Google Sheet Web Service Method Result

*Important: Make sure to click the Save button on your new web service method before leaving the page.

Adding the Web Service Method to a Workflow

At this point, you should now have a fully functional web service method that writes the ID of a ticket to a Google sheet! That web service can now be incorporated into a workflow as a web service step. When that step of the workflow is reached, the A2 cell of your spreadsheet will get updated with the ID of the ticket that reached the step!

For more information on how to configure ticket workflow steps, please see Configuring Ticket Workflows in 9.1+.

Details

Article ID: 21977
Created
Mon 12/12/16 3:23 PM
Modified
Tue 6/11/19 12:02 PM