Bridge utilities: Call API

The Call API utility allows you to manage public API calls you make across your automation workflows in Bridge. It has two main components: 

• Profiles: retain information about the system APIs to which you want to connect your workflows. 

• The Make API Call module uses profile data and specific details that you provide to make an API call to a system API.

  This setup requires API and coding knowledge.

Bridge Builder tip

Profiles simplify workflow changes in case key information changes, like your authorization token or the Base URL. An update to the Profile ensures that all modules calling the profile get the latest data to make the call.

Make API Call module 

This is the only module in the utility and contains the following fields:

Endpoint

This field specifies the action you want to take (for example, sort the sheet). In this value, you can add any data references from your Bridge triggers. Here are examples of how to set up for static or dynamic data:

• Static ID value — The URL format for this data type is this: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Specify the sheet ID in this URL, so the API call always sorts that specific sheet. 
• Dynamic Run Log data reference — The URL format for this data is this: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. However, instead of adding the sheet ID, you must add the sheet data reference from the Bridge workflow’s Run Log. This is useful if your Bridge workflow triggers on changes or brings data from multiple sheets. When you use this URL type, the API call sorts the specific sheet referenced in this URL.

Method

Method defines the type of operations that you want to do. Define a method for each API call in the Make API Call module. Most APIs outline the method required for a given API endpoint. For example, with Smartsheet, these are the methods you get to use:

• GET: Bring data into your Bridge workflow by “getting” a row from a sheet.
• POST: Create something. For example, add a row to a sheet.
• PUT: Update something. For example, update a row on a sheet.
• DELETE: Delete something. For example, delete a row from a sheet.

Headers

Headers are the values that you need for the request, and the key-value pairs. They’re usually used to handle authorization (permissions). For example, in Smartsheet calls, you'd have a key Header named Authorization with the value set to Bearer [Enter your API token].

The Profile can set up headers required for every call to a system. In your workflow, the Make API Call module allows you to configure additional headers for specific actions. 

Form Parameters 

Form parameters are also known as query parameters or arguments. Form parameters are additional items that you can define in the request. You set them in the Make API Call module.

A sample scenario would be to apply paging with Smartsheet calls to include some items in the response. For example, you only want to get the first page of a report with 20,000 rows.

HTTP Request Body

A body has the relevant request details that you must send. It's usually in JSON format.

Sending Form Parameters overrides any Body data.

In a Sort Sheet API call, a body would look like this: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. The body in this example could use either of these value types:

• A static value for a specific column in a sheet, or
• A dynamic Run Log data reference where the column ID is shown. 

A body might not be necessary depending on the kind of request you're making. For example, you don't need a body for GET calls.

Output

If the responding API sends back a JSON object, it's saved in the Run Log. This enables you to reference the returned data later in the workflow.

What you need to get started

• A sheet 
  • The sheet ID
  • A column that, when changed in your rows, you want to trigger your Bridge workflow on
• Bridge
  • Smartsheet integration
  • Bridge workflow trigger: Smartsheet - When Column Values are Changed
  • Bridge workflow modules: Make API Call
• A Smartsheet API Key.

To build this workflow in Bridge, authenticate the Smartsheet integration for your Bridge workspace. 

While building your workflow, keep your sheet, Smartsheet API documentation, and your Bridge workflow open in three separate tabs. This makes navigating the build process easier.

Step 1: Construct the basic workflow model

Pull all the modules that you need for the workflow. 

1. Create a new workflow in Bridge. 
2. In the workflow builder, use the panel to add the Make API Call module.
3. Save the workflow.

This is what you should see in your workflow when you're done: 

Brandfolder Image

Set up the workflow trigger

1. Select the Trigger module.
2. In the Integrations section, select the Integrations Page.

3. Locate Smartsheet from the integration list.

   You can use the Connected option under the Bridge logo to get a list of only the integrations authenticated for that workspace.

4. Expand the Triggers row.
5. To create a new trigger, select Add to Triggers.
6. Fill in the following fields:
   • Trigger Name: Create a custom label for your trigger.
   • Sheet ID: Paste the sheet ID for your sheet (the sheet you want to sort).
   • Event Type: Select When Column Values are Changed. 
   • Column Name or ID: Type the name of the Smartsheet column that you want to respond to. For example, if you're going to sort rows on the sheet every time the priority changes, then type the name of your priority column.
   • Select Workflow: Select the new workflow you just created from the dropdown list.
7. Select Save.
8. Copy the column ID in the trigger info. Once you save the workflow trigger, the column ID becomes available in the Trigger info.
9. Paste it in Notepad or any word processor. You will need the column ID for a later step. 
10. Return to your workflow.

Get the API call details

This workflow changes the value in the priority column of your sheet trigger. Once this workflow detects the trigger(s), it performs the necessary actions on the same sheet. We use the runtime (Run Log) data references from the trigger to fill out the Smartsheet modules.

For this workflow, you must make an API call to the Smartsheet Sort Sheet endpoint. Use the Smartsheet API documentation to change the sample to cURL.

Step 2: Set up your first Profile

Profiles are a way to save key information for the system APIs you want to connect your workflows to. When you select a Profile in the Make API Call module, some of the information needed to make your API call is set up for you already. 

1. Navigate to the Integrations tab.
2. Select the Call API utility.
3. Expand the Profiles section, in the Profiles tab.

4. Select Add to Profiles.

   Brandfolder Image

   
5. Name your profile. Each Profile name must be unique.
6. Add the Base URL for the system API you want to connect to.  The base URL for Smartsheet is https://api.smartsheet.com/2.0/
7. Under Secret Headers, add any headers that contain tokens or secret information (e.g. API tokens).
   • For example, in Smartsheet calls, you typically have a key Header named Authorization with the value set to Bearer [Enter your API token].
8. Under Headers, add any headers that should be included in all API calls you make with this profile.
   • In this example, we've used Content-Type as a header with a value set to application/json.
9. Select Save.
10. Return to your workflow.

Bridge Builder tip

The Base URL is the part of the system API's URL that always remains the same, no matter what you're trying to do in that system. The endpoint in the Make API Call module allows you to include the specific details and actions you take with that API call.

Example: We're using the Smartsheet API to sort a sheet. The Base URL for our Smartsheet API Profile is https://api.smartsheet.com/2.0 and the specific action we're taking with the module is to sort a specific sheet, so we must put sheets/sheet_id_or_data_reference_here/sort in the Endpoint field of the module.

Step 3: Set up the Make API Call module in your workflow

1. In the Make API Call module, select your desired API profile to use from the drop-down.
2. In the Endpoint field, include the portion of the URL field that didn't get added to the Base URL field in the profile.
   • In this example, we used sheets/sheet_id_or_data_reference_here/sort.
3. Fill in the following fields. Note that you may not use all of them:
   • Set the Method to POST.
   • In the HTTP Request Body field, a body would look like this: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Form Parameters (if using — not using for this workflow)

4. Save your changes.

   Brandfolder Image

   

Step 4: Test the workflow

1. Open your sheet. 
2. Change a value in your priority column. 
3. Save the sheet. 

If your priority column is a drop-down, the sorted rows are in ascending or descending order (depending on what you defined in the body of the API call) of the values as they show in the column settings. 

Additional settings for the module

• The Make API Call module returns all API calls as a JSON object. If you need the response to return as a string, you can check the Return raw response checkbox under Additional settings in the module.
• If you must include additional headers for a specific call, copy them into the HTTP Request Headers section.

Alternative options for this workflow

• Trigger from a different sheet or column than the one you want to sort. This requires you to change the API Call details to suit the sheet and column you want to sort. 
• Add a condition to your sort. After the workflow is triggered, use a junction module to assess your column value and take different actions based on what change was made in the Priority column (for example: if Priority is 0, move the row off the sheet and if Priority is 1, sort the sheet).
• Use a Schedule trigger. When you use this trigger, you don't need to respond to changes as it sorts the sheet once a day, week, or month.

Use Call API tools across your solutions

• Profiles apply to the workspace, so all workflows in your workspace can use the same Profile in any Make API Call modules used.
• When Profile details must change because a user's permissions have changed or the system API makes changes, there's a single place to make those adjustments and have them apply to workflows in the workspace that are using that Profile.
• For each additional system API you must connect to, you can set up a new unique Profile.
• The Make API Call module succeeds if it receives any response from the target API, including if it receives an error. This is helpful in later steps to determine paths in your workflow for unexpected responses from the API (e.g. if the API call returns an error, you can send an update to a row saying there was an issue). If you prefer that the workflow stops if the API returns an error, you can check the box under the Additional Settings section of the module.