Workiva Support Center

Looking to connect to a third party application beyond Workiva's prebuilt Premium Connectors? You can achieve this by leveraging the HTTP Request Connector Commands to interact with REST APIs. In this Connected Learning Path, we will update our Chain to use the Bearer Token in a Command that uses the list Spreadsheets endpoint to give us a list of Spreadsheets within the Workspace.

Note: Although this is labeled as HTTP Request, HTTPS (Secure HTTP) is supported (and recommended).

Step 1: Create the Workspace Variables

In order to use Workiva API details across multiple Chains and Commands, we will create Workspace Variables to store that information. We will create a new Workspace Variable for the Platform API URL.

1. From Chain Builder, navigate to Workspace Settings.
2. Under Workspace Variables, click the plus sign to create a new Workspace Variable.

3. Configure the variables using the following information:

   • Name: wsv-BaseURL-Platform
   • Value: Based on your region, use the appropriate value. You can verify the region by checking the URL; if the URL contains EU or APAC, use the corresponding URL. Otherwise use the US value.

   Note: US region contains "app" only.

   • US Region
   • EU Region
   • APAC Region

   Field	US Value
   IAM Base URL	https://api.app.wdesk.com/platform/v1

   Field	EU Value
   IAM Base URL	https://api.eu.wdesk.com/platform/v1

   Field	APAC Value
   IAM Base URL	https://api.apac.wdesk.com/platform/v1

4. Save Workspace Settings.

Note: You should see all four of these variables in your Workspace Settings.  If not, revisit the Prerequisites noted above

Step 2: Copy and Modify a Chain

1. Navigate to Chain Builder and locate the Chain named CLP | Generate a Token.
2. Click the vertical ellipse on the right hand side and select Copy.
3. Once the chain copy has been created, click the pencil icon to edit the chain.
4. Click Chain Settings in the top right.
5. Rename the Chain: CLP | HTTP Request List Spreadsheets.
6. (Optional) Enter a Description: "This Chain generates a new Workiva API Access Token. You must provide a valid Client ID and Client Secret from a previously generated API Grant in the variable values below. It then retrieves a list of all Spreadsheets within the Workspace. Your Workspace must have at least one or more Spreadsheets."
7. Save the Chain.

Step 3: List Spreadsheets

To retrieve a list of our Spreadsheets, this chain uses a GET Command from the HTTP Request Connector.

4. Add a Get Command from the HTTP Request Connector to the Chain canvas.
5. Connect the Post - Retrieve a Token Command to the Get Command.
6. Double click the Command to configure it.
   1. Rename the Command: Get - List of Spreadsheets
   2. Click the Command and then the associated pencil icon to edit the Command.
   3. Check the Show Response checkbox.
   4. Click in URL and then click Workspace in the "Select a variable" panel, and select the variable you created in Step 1 (wsv-BaseURL-Platform).
   5. Add /spreadsheets after the variable.  
      
      
      We will next tell the endpoint how to execute, by specifying Headers in the Get form. 
      These Headers will pass the Bearer Token to the API to show that we have access to get a list a spreadsheets.
   6. Click the gray plus (+) button next to the Header section twice and populate each field with the values below, paying special attention to letter case and the space after "Bearer".
      • Header field 1:
        • Key: Accept
        • Value: application/json
      • Header field 2:
        • Key: Authorization

        • Value: Bearer <Post - Retrieve a Token - Response>
          Replace <Post - Retrieve a Token - Response> with the output from the POST - Retrieve a Token Command.

          

          1. Within the Select a Variable panel, click the Runtime down arrow to expand POST - Retrieve a Token
          2. Click the down arrow next to Response to expand the variable options.
          3. Select Access_token.

7. Populate Content type with: application/json.

   

8. Populate the Response with the sample payload below. By doing this, we are providing a format to the Command output, making each variable returned easier to use.

   {
     "data": [
       {
         "created": {
           "dateTime": "2018-10-21T15:03:27Z"
         },
         "name": "Year-end review",
         "id": "124efa2a142f472ba1ceab34ed18915f",
         "modified": {
           "dateTime": "2018-10-21T15:03:27Z"
         },
         "template": false
       },
       {
         "created": {
           "dateTime": "2020-02-20T15:03:27Z"
         },
         "name": "Q1 Review",
         "id": "164cfb2b132c4623a2cfaa31ef13925a",
         "modified": {
           "dateTime": "2020-03-29T13:15:27Z"
         },
         "template": false
       }
     ],
     "@nextLink": "<opaque_url>"
   }

9. (Optional) Enter a Description: "This command returns one page of a list of Spreadsheets. For more information, see the developer documentation at https://developers.workiva.com/platform-v1/platform-getspreadsheets/"

   Tip! To determine how to populate the Header and Response fields, check out the developer documentation for the API endpoint you're connecting to, in this case we are using the "Get Spreadsheets" endpoint.

10. Save the Command.

Step 4: Test the Exercise

Now that the Chain is complete, test the result.

1. Publish the Chain.
2. Click Execute and then Run Chain.
3. Once the Chain completes its run, you should see a list of spreadsheets in the Outputs tab - Response Body of the Get Command.

To continue to challenge yourself and learn more about using the HTTP Request Connector to connect to a third party API, check out the next exercise: CLP - HTTP Request Get a Single Spreadsheet.