Markers, User Tokens, and Field References

You can use the markers and field references listed in the tables below to configure the Message body of your webhook.

In webhooks, variables are signified with %, for example, use:

%curuser%

to refer to the current user.

In reports, variables are signified with an underscore, for example, use:

_curuser_

to refer to the current user when you are building report filters.

Markers

You can use the following field markers in the message body of your webhook:

User Tokens

You can create your own user tokens in Quickbase and use them to run APIs. Many API calls that use a ticket can instead take the usertoken parameter. For example:

%user.token.SalesToken%

When you create a webhook, you are the owner. When you put a user token in the body of the message, it is shown in the message body as %user.token.$your_userid.first token%. For example: %user.token$jsmith.first token% That token appears in the list in the Fields & Markers dropdown, and is translated to the actual user token when the webhook is saved.

When you edit or copy a webhook you don’t own, the user token is shown in the message body as %user.token.$someuserid.first token%. That token does not appear in the list in the Fields & Markers dropdown (only your tokens appear there).

Field references

You can also insert field references to configure your webhook the way you want. Field references act like variables in your message body. For instance, if you might use a field reference to get a value from the "Last Modified By" field.

A field marker is simply the field name enclosed by square brackets, e.g., [LastModifiedBy]. When you click inside either the Endpoint URL or Message body, you'll see a list of valid field references you can use. You can also type these in manually, if you know the field names. But keep in mind, depending on the type of message you're composing, and the insertion point, certain field markers are not valid.

Field reference prefixes

You can use field references to capture the original value from a field (that is, before it was changed). To do so, add the prefix old. in front of the field name, as in [old.status] or [old.description].

  Status changed from [old.status] to [status].

If a user were to change the value in the status field from Open to Closed, this line would be displayed as:

  Status changed from Open to Closed.

Process multiple rows in a single event

In some cases, a single Quickbase event can affect multiple rows of a table. This can happen as a result of:

• Grid edits
• CSV imports
• Search and replace operations
• Table merges
• API calls, e.g., ImportFromCSV, PurgeRecords
• Connected table refreshes

You can repeat of portion of the message body by surrounding it with the %RepeatOn% and %RepeatOff% markers.

If the format is JSON and the last non-whitespace character in a repeated section is a comma, Quickbase will trim the trailing comma and whitespace for the last repeat. For example, in the following template:

[%repeatOn%[Field1], %repeatOff%]

if Field1 changed in three records, the result would be: 

[Closed, Open, Hold]

Warning:If there are field references that aren't between %repeatOn% and %repeatOff%, and there is a multi-record operation (such as grid edit), the field values will be replaced with the value of the first changed record.

Field reference suffixes

By default, field values are formatted based on the message format you select (XML, JSON, RAW).

If you don't use any suffix, the specified message format is used and provides default escaping. For example, tokens in the URL field are URL-escaped by default and don't require a suffix. Similarly, tokens in the template body are escaped based on the template format (XML, JSON, RAW).

However, you may not always want to use the default formatting. Field suffixes allow you to override the default behavior for each message format. For example, the following use of the .CSV suffix would csv-encode the previous value of the field "My field name":

[old.My field name.csv]

You can append the following suffixes to a field reference: .xml, .json, .csv, .url, ,or .raw. If you append any of these suffixes to the field reference, the field value will be encoded using the specified encoding,not the encoding of the entire message. For example, when you use API_ImportFromCSV, the overall message would be XML, but the record information needs to be CSV-encoded. 

Use these suffixes to escape data for the following formats:

.xml -- Escapes data in an XML document.

.json -- Escapes data in a JSON document.

.csv -- Escapes data in a CSVdocument.

.url -- Escapes data in the query string of a URL.

.raw -- Does not escape any data in the message.

The following table shows how field suffixes are used to reformat special characters.

Note that for .csv:

• If there is at least one special character in the field value, the value will be enclosed with double-quotes.
• A new line is considered to be a special character. Quickbase does not change it, but does add enclosing double-quotes.

Formatting with the.raw and .printable suffixes

The .raw suffix means to not use the JSON or XML formatting. So, if the body is JSON or XML, adding the .raw suffix will ignore the default formatting for the designated field.

Use the .printable suffix to apply default or custom formatting as specified in Quickbase field settings.

Related topics:

• About webhooks

• Webhooks FAQ

• Configure a webhook

• Create and manage webhooks

• Webhooks error log

• Support and troubleshooting