HTTP Call Utility Function

Applies to

Bridge by Smartsheet

With the HTTP call module, you can call out to any external system to send a request and retrieve data. This can be very useful if Bridge doesn't have the modules you need out of the box to interact with another system.

This requires knowledge of HTTP.

HTTP call fields

URL

In this field, add the HTTP or HTTPS URL of the resource you want to update.

For Smartsheet, you'd use the base URL: https://api.smartsheet.com/2.0/ and the endpoint you want. Then in that URL, add any data references you need from your Bridge triggers.

Here are examples on how to set up for static or dynamic data: 

  • Static ID value: The URL format for this type of data is this: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. You have to 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 similar to that of the static ID value: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. However, instead of adding the sheet ID, you’d need to 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 type of URL, the API call will sort the specific sheet referenced in this URL.

Method

Method defines the type of operations you're trying to do. Most APIs outline the method required for a given API endpoint. For example, with Smartsheet, these are the methods you’ll 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 you need for the request, and the key-value pairs. They’re usually used to handle authentication. For example, in Smartsheet calls, you’d have a key Header named Authentication with the value set to Bearer [Enter your API token].

Form Parameters 

Form Parameters are also known as Query Parameters or Arguments. They’re additional items you can define in the request. 

A sample scenario would be applying paging with Smartsheet calls so only a certain number of items are included in the response. For example, you only want to get the first page of a report with 20,000 rows.

Body

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

Sending Form Parameters will override 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 above 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. 

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

Returned data

If the responding API sends back a JSON object, you'll have the option to save this response. Saving it lets you reference the returned data in later parts of the workflow.

To save a response, select Response Handler.

Now, you know the fields you’ll encounter when you set up the HTTP Call Utility Function. Read on to learn more about how to set up and use this utility function. 

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: HTTP Call
  • A Smartsheet API Key

Getting started

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

Read the steps on how to set up the Smartsheet integration for Bridge

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

 Construct the basic workflow model

Before everything else, pull all the modules you need for the workflow. 

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

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

Screenshot of basic workflow model

Set up the workflow trigger

After creating the basic workflow model, start setting up the workflow trigger.

  1. Select the Trigger module.
  2. To open the Integration panel in a new tab, 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 Trigger icon.
  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 want 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. In the Trigger info, copy the column ID.
    • The column ID will be available in the Trigger info once you save the workflow trigger.
  9. Paste it in a notepad or any word processor. You’ll need the column ID for a later step. 
  10. Return to your workflow.
    If you want to return to the original tab, refresh the page to see the trigger.

Set up the HTTP Call module

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

Step 1: Get the HTTP Call details

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

Keep this example open while setting up the HTTP Call module. It has almost all the information you need. But always check for the latest version of API documentation when setting up API calls.

HTTP calls

Step 2: Set up the HTTP Call module

  1. Copy this URL for the Short Sheet endpoint: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. 
  2. In the URL field, paste the URL for the Sort Sheet endpoint. 
  3. Replace the {sheetId} section of the URL with the actual sheet ID. 
  4. In the Method list, choose POST
  5. Expand the Headers section.
  6. In the Headers section, fill in the following fields:  
    • For Key #1: Use the first -H value from the API example Authorization.
    • For Key #2: Use the second -H value Content-Type.
    • For Value #1: Use Bearer {Your API key}.
    • For Value #2: Use application/json.
  7. Copy the -d value from the API example {"sortCriteria": [{"columnId": 4583173393803140, "direction": "DESCENDING"}]}.
  8. In the Body field, paste the -d value from the API example {"sortCriteria": [{"columnId": 4583173393803140, "direction": "DESCENDING"}]}.
  9. In the columnId section of the sample URL, paste the column ID you saved from the Trigger setup. 
  10. Choose whether you want the rows to sort in ascending or descending order. 
  11. Adjust the body accordingly. 
  12. To ensure any API response received is logged in the workflow’s Run Log, select the Response Handler option. 
  13. Save the workflow.

See an example of the setup below. Note that your workflow will be slightly different because of your API Key and ID values.

Image of the workflow the relevant fields

Step 3: 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 dropdown, the sorted rows will be in ascending or descending order (depending on which you chose) of the values as they are shown in the column settings. 

Alternative options

Here are some ideas on how you can customize this workflow:

  • Trigger from a different sheet or column than the one you want to sort. This will require you to change the HTTP 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 (e.g. 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 won’t have to respond to changes at all as it’ll sort the sheet once a day, week, or month.