Call URL

You can call third-party websites to retrieve the data you need for your database, such as currency exchange rates, company logos, cities, and addresses. In this case, the "Call URL" workflow action can be added to a trigger or custom button.

The "Example: Call URL" database demonstrates the functionality of "Call URL" with Text, JSON, and XML response parsing. To see how it works, you can request a free trial of the "Example: Call URL" database.

To create this type of action select the corresponding option on the workflow action type selecting form.

General Properties

Name

Enter the name of the action.

Notes

Holds any comments you need 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

Authorization

Choose one of the following options:

• None: choose an existing 3rd-Party Account
• New Account: create a new account for authorization.

Request Properties

Method

The following HTTP calls are available:

• GET
• POST
• PUT
• PATCH
• DELETE

Url

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 a separate line. As each header type requires a value in its format, we do not expect much use for database content. Nevertheless, headers behave like query strings. Read more…

Body

This field is visible when the method selected is POST, PUT, PATCH, or DELETE. You may interpret the Body as:

• Text
• Form
• XML
• JSON
• File

Response Properties

Upon request, the service can either return a failure code (this will be added to a log, and further processing will be stopped) or report OK and provide an error message in the response.

Format

The following options are available:

• Auto-Detect
• Text
• XML
• JSON
• File
• CSV

In most cases, the Auto-Detect option works fine. Yet, if a server reports a wrong format, you may force response interpretation as one of the available formats.

If the format is set to File, you can use the assignments section to retrieve binary content and store it in the file attachment column. Use the Response() formula in the "From" part of the assignment entry.

On Error

This option controls the behavior when TeamDesk evaluates response status.

The quick recap on Call URL logic:

• Step1: TeamDesk calls a third-party server. If there is a network error, roll back all changes and display an error message.
• Step 2: TeamDesk evaluates response status. If the status indicates an error, roll back all changes and display a generic message.
• Step 3: TeamDesk evaluates the Error Message formula if not empty. If the formula evaluates to some text, roll back all changes and display text as an error message.
• Step 4: Execute assignments and subsequent triggers and actions normally.

If set On Error to Stop Execution, the system roll back all changes and display a generic message.

If you need greater flexibility, set On Error to Continue Execution. Step 2 will be skipped. The 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 the 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

Error Message

An Error Formula can be entered in this field. This formula can extract an error message from the response or return null if the response is OK.

Adding Assignments

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

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 the case of XML, the text should be a valid XPath expression, in the case of JSON, it’s a string in the form of "property.property[index].property". The function returns the value as text.
• Response("text", Type) - performs as the 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.

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: Enter the formula extracting the value from the third-party website. This value will be later inserted into a predefined record field.
• To: 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 the last 100 calls of the action.