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.
Name | In the Name field enter the name of the action. |
---|---|
Notes | Notes field holds any comments you need to keep for this action. |
Execute Triggers | TeamDesk allows cascading execution of record change triggers. It is controlled via the Execute Triggers option of the action. If the action should activate other record change triggers, choose the Yes option, otherwise the No option is selected. |
Authorization | In the Authorization section you can choose an existing 3rd-Party Account or create a new one. |
Method | In the Method field choose the GET , POST , PUT , PATCH or DELETE HTTP calls. |
Url | In the Url field enter the external url that should be called. Use <% %> code blocks to provide parameters. |
Headers | HTTP headers consist of name: value pairs each pair is placed on separate line. As each header type require value in its own format, we do not expect much use for database content. Nevertheless, headers behave like quest strings. Read more … |
Body | This field is visible when the method selected is POST , PUT or PATCH . You may interpret the Body as Text , Form , XML or JSON . Read more … |
Format | In most cases Auto-Detect option works fine. Yet if a server reports a wrong format, you may force response interpretation as Text , XML or JSON using this option. |
Error Message | In the Error Message field an Error Formula can be entered. This formula can extract an error message from the response or return NULL if the response is OK. |
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:
From… | In the From field enter the formula extracting the value from the third-party website. This value will be later on inserted into a predefined record field. |
---|---|
To… | In the To list select the field (column) to which the formula calculated value should be inserted. |
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.