Call URL

You can call to the third-party websites to use data your need in a database, for example, currency exchange rates, companies’ logos, cities and addresses, etc. In this case the Call URL workflow action can be added to the trigger or custom button.

The "Example: Call URL" database demonstrates the "Call Url" functionality with Text, JSON and XML response parsing. To check how it works, just order a free trial of the "Example: Call URL" database.

The Call URL workflow action performs HTTP GET requests (support for POST and more advanced options is planned for the next stage) and understands responses in plain text, XML and JSON formats. To create this type of action:

Select a corresponding option on the workflow action type selecting form.

Beside the general purpose (Name and Description fields) the action has the Url field. Also, you should use <% %> code blocks to provide parameters.

Upon request the service can either return a failure code [this will be added in a log and further processing will be stopped] or report OK and provide an error message in the response. To help dealing with such situation there is the Error Formula field - you can extract error message from the response or return NULL if response is OK.

To deal with the data returned by the server there is a new Response() function that takes three forms:
Response() with no arguments returns the "raw" content of the server response - you can use it if the server provides the result in a plain text format.

Response("text") - extracts named data from the response in the XML or JSON format. In case of XML the text should be a valid XPath expression, in case of JSON it’s a string in form of "property.property[index].property". The function returns the value as text.

Response("text", Type) - performs as previous one but also tries to convert the result to TeamDesk-specific type.
You can use calls to Response() in both error formulas and assignments.

Once the action is created, the Assignment can be added to it:

Use the following form to create the assignment for extracting the value from the third-party website and updating this value in the column:

Moreover, below the action form you can find the Log keeping the detailed info regarding to the last 100 calls of the action.

Call URL’s On Error option

The quick recap on Call URL logic:

Step1: TeamDesk calls third-party server.
If there is a network error, roll back all changes and display error message.

Step 2: TeamDesk evaluates response status.
If status indicates error, roll back all changes and display generic message.

Step 3: TeamDesk evaluates Error Message formula, if not empty.
If formula evaluates to some text, roll back all changes and display text as error message.

Step 4: Execute assignments and subsequent triggers and actions normally.

The On Error option controls the behavior at step 2.

If set to Stop Execution we use old logic - this option is a default.

If you need greater flexibility, set On Error to Continue Execution. Step 2 will be skipped. Error Message formula, if set, handles both successful and error responses. The formula has a chance to evaluate response status using the ResponseStatus() function. Then it can extract a specific error message from server’s response and abort execution if needed, or return NULL to suppress error and continue execution.

If execution is not aborted, you can use assignments to flag whether the record was successfully processed or not, for example:

If(ResponseStatus() = 200, "OK", "FAILED!") // to Status

File Uploads with Call URL actions

In Call URL actions you can use <%=[File Attachment Column]%> placeholder to refer to file’s content. This extension opens the possibility to integrate with a wide range of cloud storage, document conversion and e-signature services.

An actual code we generate depends on a request body format.

File Uploads with text-based body formats

For text-based body formats (XML, JSON, Text) we encode file’s content as base64 string. This is most common way to inject non-text data into larger, otherwise text-based document, JSON structure for example.

Some, but not all APIs that use this encoding are Microsoft Graph API (Mail), SendGrid and DocuSign. To fully describe the file in addition to file’s data these services may require two more parameters: file’s name and file’s media type. To help deal with these, we added two functions: FileName([attachment]) and FileType([attachment]). Both are available only in Call URL action’s body formula context.

Below is a sample setup for Microsoft Graph API - the action sends an email to the email address specified in [To], using [Subject] and [Message] and optionally attaches the file, if specified in [File] column.

Please note the use of conditional expression <%?not IsNull([File]%>. In absence of the file <%=[File]%> construct would generate null, that will likely lead to API error. With conditional expression we can omit whole "attachments" section when there is no file.

Also, "name", "contentType" and "contentBytes" keys in attachment descriptor are no way standard across the APIs. SendGrid API, for example, names these keys as "filename", "type" and "content" respectively.

File Uploads with Form body format

Form body format sends the data just as browser does. In its simple form the payload is a list of key=value pairs separated by & sign. But this way of encoding is limited to text-only data. But once files appear in the payload things are going far more complicated. We’ll save you from all the technical details; simply add key=<%[File Attachment Column]%> and we’ll do the rest properly. Box.com API uses form file uploads.

New File body format

File body format is new. When selected we send the content of the file as a request payload. This opens the road for upload integration with multiple cloud storage services, including but not limited to Google Drive, OneDrive and DropBox.

With File body format the formula accepts sole <%=[File Attachment Column]%> and nothing else.

We’ve prepared a sample database that demonstrates file upload capabilities to four cloud storage providers: Google Drive, OneDrive, Dropbox and Box.com — feel free to explore.

Iterators in Call URL actions

Let’s take an integration with Xero accounting software as an example.

As Xero reports Invoice information together with line items we can use iterators to copy all invoice data in one shot. Xero’s invoice information is quite long, here is excerpt with some essential info:

<Response>
  <Invoices>
    <Invoice>
      <InvoiceID>01234567-0123-4567-8901-012345678901</InvoiceID>
      <Date>2021-01-01T00:00:00</Date>
      <Contact>
        <Name>John Doe</Name>
      </Contact>
      <LineItems>
        <LineItem>
          <LineItemID>01234567-0123-4567-8901-012345678901</LineItemID>
          <Description>Acme Wild-Cat</Description>
          <UnitAmount>100.00</UnitAmount>
          <Quantity>2.0000</Quantity>
        </LineItem>
        <LineItem>
          <LineItemID>98765432-3210-3210-3210-109876543210</LineItemID>
          <Description>Weyland-Yutani Xenomorph</Description>
          <UnitAmount>200.00</UnitAmount>
          <Quantity>1.0000</Quantity>
        </LineItem>
      </LineItems>
    </Invoice>
  </Invoices>
</Response>

Iterators in Call URL actions are organized the same way as in webhooks, so we won’t repeat step-by-step guide from above, just the final result:

Please note the use of ParentKey() function - it will allow you to connect newly created line items to their parent invoice record.