DREL Complete Reference List

This topic describes all the Data Reference Expression Language (DRELClosed Data Reference Expression Language (DREL) is used to get form data and metadata and add it to a string, such as dates, usernames, or answers to questions in forms.) references and properties supported by ProntoForms.

Info:Test your DREL expressions to make sure you get the results you expect.

Supported on all tiers:

Essentials
Advanced
Enterprise

Contents

Form metadata

You can use DREL expressions to reference form metadata. Use form metadata references to return information about the form like

  • the Form Submission ID
  • the name of the user who submitted the form, and
  • the date and time that the form was submitted, among others.

All form metadata references have a default property and at least one alternative property.

%c - Mobile device information

The mobile device reference returns information about the mobile device from which the user submitted a form.

  • Default property: [displayText]

    This property returns the device model, model number, operating system, operating system version, and the ProntoForms mobile app version. To display only part of the displayText, use one of the other properties.

  • Other properties:

    • [os]: returns the mobile device operating system.

    • [osVersion]: returns the mobile device operating system version.

    • [model]: returns the mobile device model.

    • [modelNumber]: returns the mobile device model number.

    • [prontoFormsClientSoftware]: returns the ProntoForms mobile app type.

    • [prontoFormsClientSoftwareVersion]: returns the ProntoForms mobile app version.

  • Usage examples:

    • %c returns iPhone iPhone 10,4 (iOS 14.4, 12.6.47)

    • %c[os] version %c[osVersion]returns Android version 14.4.1

    • %c[model] returns iPhone

    • %c[modelNumber] returns iPhone 9,4

    • %c[prontoFormsClientSoftware]: returns Windows 10

    • %c[prontoFormsClientSoftwareVersion]: returns v12.4.2.0 (2594)

%d - Date of the form submission

The date reference returns the date that a user submitted a form.

You can customize how the system displays the date. For example, you can:

  • Change the date format: %d[dd/MM/yyyy]

  • Display the day of the week, month, or year, or the week of the year, for example: %d[dd-MM-yyyy w]

  • Display and change the time zone: %d[dd-MM-yyyy z][TeamTZ]

  • Use a combination of format properties: %d[dd/MM/yyyy E w z][TeamTZ]

The following sections describe the %d properties in more detail.

  • Default property: [yyyy-MM-dd]

  • Date format properties:

    You can change the date format by using a combination of the following symbols:

    Symbol Meaning Format supported Output Examples
    y Year [y], [yy], [yyyy] 2019, 19, 2019
    M Month [MM], [MMM], [MMMM] 09, Sep, September
    d Day in the month [d], [dd] 5, 05
    E Day in the week [E], [EEEE] Tue, Tuesday
    D Day in the year [D] 258
    w Week in the year [w] 42
    z Display the time zone [z], [zzzz] EDT, Eastern Daylight Time
  • Time zone override properties:

    The default time zone can vary depending on the context. For example, you can set a “default” time zone for a document.

    Filename field set to "%f - %d[dd/MM/yyyy E w z][TeamTZ], which results in a value of "Form Name - 28/04/2022 Thu 17 EDT", which overrides the "Document Time Zone Source", which is set to "Form Submission" (the time zone on the user's device).

    Use any of the following properties after a date format property to display or apply a different time zone.

    • DataRecordTZ: Time zone on the user’s device.

    • TeamTZ: Time zone configured at the team level.

    • Region/City: A specific time zone. You can use any of the tz database names.

  • Usage examples:

    • Form submitted %d[dd-MM-yyyy] returns Form submitted 25-06-2020.

    • %d[EEEE, MMMM d, yyyy] returns Thursday, June 25, 2020.

    • Week %d[w, yyyy] returns Week 26, 2020.

    • %d[dd-MM-yyyy z][TeamTZ] returns 26-06-2020 EDT when the form was submitted on 25-06-2020 at 11:50 PM PDT, for example.

%f - Form name

The Form name reference returns information about the form used to submit data.

  • Default property: [name]

    The form name is one of the most commonly used references when naming folders and document files.

  • Other properties:

    [id]: returns the unique identifier of the form.

  • Usage examples:

    • %f returns Equipment inspection.
    • Form %f[id] returns Form 145211668

%g - Geo location

The Geo location reference returns the GeoStamp collected when a user submits a form.

Info:To use this DREL expression successfully, you must enable the setting to collect a Geo location on your form. The topic Configure form settings in the Form Builder describes how to configure the Geo location setting.

  • Default property: [address]

    This property displays the street name and number, city, state or province, postal code, and country.

  • Other properties:

    • [timestamp]: returns the date and time when the system collected the Geo location. The system displays the timestamp in the GMT/UTC +0 time zone.

    • [coordinates]: returns the latitude, longitude, and altitude of the Geo location. Alternatively use [coordinates.latitude] [coordinates.longitude], or [coordinates.altitude].

    • [accuracy]: returns the accuracy level of the coordinates in meters.

    • [geoSource]: returns how the system acquired the Geo location. Systems can acquire a location using GPS, for example.

    • [success]: returns true if the system collected the Geo location successfully, or false if the system failed to collect it.

    • [errorMessage]: returns an error message if the system fails to collect the Geo location. If the system collects the location successfully, the system does not return an error message.

    • [addressDetails][secondProperty][thirdProperty]:

      Use this property when you want to retrieve specific information about the address where the user submitted the form.

      When you use this property, you need to include a second property with the following possible values:

      • [street_number]: returns the street number.

      • [route]: returns the street name.

      • [locality]: returns the city name.

      • [postal_code]: returns the zip or postal code.

      • [administrative_area_level_1]: returns the state or province.

      • [administrative_area_level_2]: returns the county.

      • [country]: returns the country.

      The third property is optional. You can include the following values:

      • [longName]: returns the full value. This is the default, so you don’t need to include it.

      • [shortName]: returns an abbreviation of the value. This property only has an effect on the [route], [administrative_area_level_1], and [country] second properties.

  • Usage examples:

    • %g returns 111 Elm Street, Ottawa, ON K1A 2B3, Canada

    • %g[timestamp] returns 2020-01-03T18:34:23.000Z

    • %g[coordinates] returns 41.23443223145432, -23.38029283828193, 123.23874

    • %g[accuracy] returns 14.812454

    • %g[geoSource] returns GPS

    • %g[success] returns true

    • %g[errorMessage] returns Unknown Location

    • %g[addressDetails][street_number] returns 111

    • %g[addressDetails][route] returns Chestnut Boulevard

    • %g[addressDetails][route][shortName] returns Chestnut Blvd.

    • %g[addressDetails][locality] returns Ottawa

    • %g[addressDetails][postal_code] returns K1A 2B3

    • %g[addressDetails][administrative_area_level_1] returns Ontario

    • %g[addressDetails][administrative_area_level_1][shortName] returns ON

    • %g[addressDetails][administrative_area_level_2] returns Ottawa Division

    • %g[addressDetails][country] returns Canada

    • %g[addressDetails][country][shortName] returns CA

%m - Dispatch metadata

DispatchClosed The term "dispatch" refers to the act of sending a form to a mobile user or customer. Typically, a dispatched form includes some information pre-filled to give the recipient context for the work to be done. Dispatch can be manual or automated (using a Dispatch Data Destination or the ProntoForms REST API). metadata is information that a supervisor adds to a form when dispatching it to give mobile users more context. Dispatch metadata includes

  • notes or instructions
  • priority
  • due date, and
  • address.

Info:The topic Dispatch Metadata and Inbox Views describes Dispatch metadata in more detail.

  • Default property: [notes]

    This property returns the text in the dispatch notes or instructions.

  • Other properties:

    • [location]: returns the latitude and longitude of the location in the dispatch metadata. Alternatively use [latitude] or [longitude].
    • [priority]: returns the priority in the dispatch metadata. Priority can be High, Medium, or Low.
    • [duedate]: returns the due date. You can customize the way the system returns dates by using date formats as specified in the Date section.
  • Usage examples:

    • Form priority %m[priority] returns Form priority Medium.
    • Form due %m[duedate][E, dd-MM-yyy] returns Form due Wed, 12-12-2020.

%o - Information stored as a response output

The response output reference returns the information stored after an initial HTTP POST/PUT or Salesforce destination executes. You can use the %o reference in any subsequent destination or its linked document.

Note:The destination that stores the response output must precede the referencing destinations in the Form BuilderClosed The Form Builder is the tool that form designers use to create forms. In the Form Builder, accessed from the ProntoForms Web Portal, form designers can add and edit pages, sections, and questions, as well as attach data destinations and configure the form's settings..

The following Data Destinations can store response outputs:

Response outputs enable you to make sequential requests to third-party systems. This enables you to define relationships between the data or records created in those systems. For example, you can set up a Salesforce Account destination to be the parent of a Salesforce Contact destination. The Account destination uses Response Data Handling to store the response output that the Contact destination references. You map the %o expression in the child Contact destination to link new Contact records to the parent Account record:

Custom Salesforce Field that shows the DREL value expression "%o[Account Destination][id]" mapped to the Salesforce AccountId field.

Info: You can view the parent destination response outputs from the form submission page in the web portal. The topic View Destination Response Outputs in the Web Portal provides more detail on how to find the response outputs.

  • Properties: [Destination Unique Identifier][key]

    In the subsequent destination or its linked document, replace the first property with the Destination Unique Identifier of the initial destination with the response output.

    Replace the second property with a key returned as part of a key:value pair in the third-party system response body. You can find the key name in the third-party API documentation. The key specifies the stored value in the initial destination’s response output.

    Note:You must include both properties when you create a %o reference. Without these properties, ProntoForms can’t retrieve or send data.

  • Usage examples:

    • %o[Account Destination][id] returns a value of 0014x00000YjZWzAAN, which is the Salesforce Account record ID.

%r - Form submission properties

  • Default property: [referenceNumber]

    The Form Submission Reference Number is the unique identifier for a Form Submission. This number identifies each form submission in the Form Submissions page.

    The reference number has two strings of numbers. The first string is the date the first submission version of the form is created, and the second string is the serverDataRecordID number of the form submission.

    Example: A form submitted on June 20, 2019 could have the reference number 20190620-1811278959.

  • Other properties:

    • [id]: returns the serverDataRecordID. The submitted form serverDataRecordID is the second string in the reference number.

    • [name]: returns the name of the form submission. You can't use this property when naming Form Submissions.

    • [pfStatus]: For App‑to‑App callbacks only. Returns the form’s current status on the device as described in the following table.

      Status Description
      Saved A ProntoForms mobile app user opened a form from the Forms box or Inbox, and then saved it.
      Outbox A submitted form is still processing on the user’s device and has not yet been uploaded to the server. This can happen when a device is offline, for example.
      Sent A submitted form was uploaded to the server.
    • [state]: returns the state of a Form Submission.

      The following table describes the states that the server returns, for example, in the case of Form Submission names, document generation, and the configuration of Data Destinations.

      State Description
      Dispatched

      The system dispatched a form to a mobile user. The form is in this state until the user submits, declines, or transfers the form.

      Note:The term transferred only applies to ProntoForms TeamworkClosed ProntoForms Teamwork is an Enterprise tier feature that enables mobile users to transfer incomplete forms for other users to complete as part of a multi-user workflow. This can be useful for jobs that require someone else's expertise or that span multiple shifts.-enabled forms.

      DispatchDeclined

      A mobile user declined a form dispatched to them.

      Complete

      A mobile user sent a completed form. The ProntoForms server received and processed the completed form.

      Incomplete

      A mobile user transferred an incomplete ProntoForms Teamwork-enabled form. The form is now either unassigned or reassigned to another user.

      Edit

      A supervisor sent a completed form for editing.

      The following table describes the states that the ProntoForms mobile app returns when using App‑to‑App callbacks, or for the name of dispatched or submitted forms on the app.

      State Description Visible in Form Names? Visible in App‑to‑App Callbacks?
      Dispatched

      The system dispatched a form to a mobile user. The form is in this state until the user makes changes to it.

      Yes No
      DispatchDeclined

      A mobile user declined a form dispatched to them.

      Yes No
      Complete

      A mobile user sent a completed form. The submitted form might be in the user’s outbox, or it might have been uploaded to the ProntoForms server.

      Yes Yes
      Incomplete

      A mobile user transferred an incomplete ProntoForms Teamwork-enabled form. The form might be unassigned on the ProntoForms server, or reassigned to another user’s Inbox. The form is in this state until a user makes changes to it.

      Yes Yes
      Saved

      A ProntoForms mobile app user opened a form and made changes to it. The form might be saved in the Drafts or Inbox folder.

      Yes Yes
  • Usage examples:

    • Reference number %r returns Reference number 20200211-1811522422.
    • Form %r[state] returns Form incomplete.

%s - FormSpace name

The FormSpaceClosed FormSpaces are where forms are stored and organized in the ProntoForms Web Portal. A ProntoForms Team may have multiple FormSpaces, depending on their needs. Admins can set FormSpace permissions to control which users have access to the forms in that FormSpace. name reference returns the name of the FormSpace where the form is located. Companies commonly set up FormSpaces to reflect different regions or locations, so returning FormSpace information can be useful to sort Form Submissions.

  • Default property: [name]

  • Other properties:

    • [id]: returns the unique identifier of the FormSpace.
  • Usage examples:

    • %s returns Toronto team.
    • %s[id] returns 194522112

%t - Time of the form submission

The time reference returns the time that a user submitted a form.

You can customize how the system displays the time. For example, you can:

  • Change to a 12-hour clock: %t[hh:mm:ss]

  • Add AM or PM after the time: %t[hh:mm:ss a]

  • Display and change the time zone: %t[hh:mm:ss z][Europe/London]

  • Use a combination of format properties: %t[hh:mm:ss a z][TeamTZ]

The following sections describe the %t properties in more detail.

  • Default property: [HH:mm:ss]

  • Time format properties:

    Change the time format by using a combination of the following symbols:

    Symbol Meaning Format supported Output Examples
    h Hour in AM/PM (1-12) [h], [hh] 4, 04
    H Hour in a day (0-23) [H], [HH] 22
    m Minute in an hour [m], [mm] 15
    s Second in a minute [s], [ss] 39
    a AM/PM marker [a] PM
    k Hour in a day (1-24) [k], [kk] 24
    K Hour in AM/PM (0-11) [K], [KK] 0, 00
    z

    Display the time zone

    [z], [zzzz]

    EDT, Eastern Daylight Time

  • Time zone override properties:

    The default time zone can vary depending on the context. For example, you can set a “default” time zone for a document.

    Filename field set to "%f - %t[dd-MM-yyyy HH:mm:ss z][Europe/London], which results in a value of "Form Name - 28-04-2022 19:31:11 BST", which overrides the "Document Time Zone Source", which is set to "Form Submission" (the time zone on the user's device).

    Use any of the following properties after a time format property to display or apply a different time zone.

    • DataRecordTZ: Time zone on the user’s device.

    • TeamTZ: Time zone configured at the team level.

    • Region/City: A specific time zone. You can use any of the tz database names.

  • Usage examples:

    • Form submitted at %t returns Form submitted at 12:06:45.

    • %t[hh:mm a] returns 12:06 PM.

    • %t[HH:mm:ss z][Europe/London] returns 20:06:45 BST. This changes the time zone value.

      Info:You can also use [DataRecordTZ] or [TeamTZ] to change a time zone value, for example: %t[hh:mm:ss a z][TeamTZ]

%u - User information

The User information reference returns information about the user who submitted the form.

  • Default Property: [displayName]

    The Display Name property returns the user's name and username.

    Example: Jane Doe (jdoe@prontoforms.com)

  • Other properties:

    • [id]: returns the user's unique identifier in the ProntoForms system.
    • [username]: returns the user's username.
    • [name]: returns the user's first and last name.
    • [email]: returns the user's email.
    • [alias]: returns the user's alias. Go to Setting Up User Aliases to learn how aliases work.
  • Usage examples:

    • Reply to %u[name] at %u[email] returns Reply to John Doe at johnd@email.com.
    • Form submitted by %u returns Form submitted by Anna Johnson (ajohnson0201).

%v - Form version

The system creates a new form version each time the supervisor updates the form, saves it, and deploys it. It's useful to know the version of a form to keep track of the changes that a supervisor made to it.

  • Default property: [version]

  • Other properties:

    • [id]: returns the unique identifier of the form version.
  • Usage examples:

    • Form version %v returns Form version 12.
    • Form version %v[id] returns Form version 11123.

Questions

Question references can return questions in a form as the user sees them on the Mobile App, and information that a user submitted as answers or comments.

Question references don't have a default property. You must include the Question Unique IDClosed A Unique ID refers to the specific identifier of a question, form page, form section, or Data Destination. Unique IDs are used as reference points when pulling data for conditional logic, Analytics projects, Data Destinations, and Documents. as a property.

%a[Unique ID] - Question answers

The question answer reference returns the information a user submitted as an answer or a comment.

  • Property: [Unique ID]

    Replace with the Unique ID of the question you want to reference.

    Info: The topic Overview Unique IDs describes how to find the Unique ID of a question.

  • Other properties:

    • [Comment]: The comment property returns question comments. Use the comment property after the Unique ID property.

    Info:The topic Question Comments describes question comments in more detail.

  • Usage examples:

    • %a[EquipmentCondition] returns Fair.
    • %a[EquipmentCondition][Comment] returns The equipment has visible signs of wear that don't affect functionality.

%e[Repeatable Section Unique ID] - Answers in a Repeatable Section

The Repeatable Section reference returns information from a specific Repeatable Section in your form. The expression returns all Repeatable Section entries as a string in the order that the rows appear in.

Info:The topic DREL for Repeatable Sections describes in detail the different DREL expressions that can extract responses from a Repeatable Section.

  • Property: [Repeatable Section Unique ID]

    To find the Repeatable Section Unique ID, navigate to the form, and then select the Pages & Questions tab. The Label column contains the Unique ID.

  • To return more specific results, and to return data from nested repeatable sections, add the following properties:

    • [n]: returns a specific row in a Repeatable Section, where [n] is the row number. Because row numbers are zero-based, use [0] to return data from the first row.

    • [inner_drel]: returns the response of the specified DREL expression within a Repeatable Section, where inner_drel is another DREL expression. For example:

      • %e[Repeatable Section Unique ID][%a[Unique ID]] returns the answer to the specified question for every row in a Repeatable Section.

      • %e[Repeatable Section Unique ID][%q[Unique ID]] returns the question text of the specified question for every row in a Repeatable Section.

    • You can also include plain text within the [inner_drel] expression to create a more structured response. For example:

      • %e[Repeatable Section Unique ID][1][Repair %a[Unique ID] immediately.] returns

        Repair answer to question in second row of the Repeatable Section immediately.
    • [delimiter]: separates the returned row values with the specified delimiter, such as [+] or [,].

    • [%e[Nested Repeatable Section Unique ID]]: returns the contents of a nested Repeatable Section.

  • Usage examples:

    A technician records the required materials for a job at a single site:

    A Repeatable Section in the Windows 10 app that displays three rows of entries. The Section is a parts list and the entries list Material Type, Quantity, and if it is already at the work site.

    • %e[PartsList] returns

      30pc Hex Bolts 2 True 50pc Washers 1 True 100pc Drywall Screws 3 False
    • %e[PartsList][0] returns

      30pc Hex Bolts 2 True

      where:

      • [0] is the [n] value that returns the first row of the Repeatable Section.

    • %e[PartsList][%a[MaterialType]][, ] returns

      30pc Hex Bolts, 50pc Washers, 100pc Drywall Screws

      where:

      • [%a[MaterialType] is an [inner_drel] expression that provides the answers to only the first question in every row of the Repeatable Section.

      • [, ] is a [delimiter] that separates the items.

    A technician records the required materials for one of many different locations in a building. They list each location in a Repeatable Section, and each entry contains a nested Repeatable Section for that location’s materials:

    A nested Repeatable Section enables you to create multiple related entries to a single high-level entry. In this example, the nested section provides a list of materials required for a specific work site location.

    • %e[SiteMaterials][0][%a[SiteLocation]: %e[PartsList]] returns

      Basement: 4pc Drywall 20 True Insulation 40 True 100pc Drywall Screws 5 False

      where:

      • [0] is the [n] value that returns the first row in the top-level Repeatable Section.

      • [%a[SiteLocation]: %e[PartsList]] is an [inner_drel] expression that includes two DREL references. The %a reference returns an answer from the top-level Repeatable Section (Basement). The %e reference returns all the contents of the nested Section.

%q[Unique ID] - Question text

The question text reference returns questions as a user sees them on the mobile app.

  • Property: [Unique ID]

    Replace with the Unique ID of the question you want to reference.

    Info: The topic Overview Unique IDs describes how to find the Unique ID of a question.

  • Usage examples:

    • %q[EquipmentCondition] returns Select the condition of the equipment.
    • %q[NumberFireExtinguishers] returns How many fire extinguishers are in the building?

Answers with multiple properties

Some question answers have multiple properties. The %a[Unique ID] expression returns the answer a user submits by default. You can add another property to change what the expression returns using the syntax %a[Unique ID][SecondProperty].

Geo location

Geo location answers return an address by default. You can add a second property to return different information such as coordinates.

  • Default property: [address]

    Returns the street address, city, state or province, zip or postal code.

  • Other properties:

    • [success]: returns true if the system acquires the location successfully, or false if the system is unsuccessful.

    • [geoSource]: returns how the system acquired the location. Systems can acquire a location using GPS, for example.

    • [timestamp]: returns the date and time when the system acquired the location. The timestamp uses the GMT time zone.

    • [coordinates]: returns the latitude, longitude, and altitude of the location. Alternatively use [coordinates.latitude], [coordinates.longitude], or [coordinates.altitude].

    • [accuracy]: returns the accuracy level of the coordinates in meters.

    • [errorMessage]: returns the reason for an acquisition failure. If the acquisition is successful, the system does not return an error message.

    • [addressDetails][thirdProperty][fourthProperty]:

      Use this property when you want to retrieve specific information about the address the system collected.

      When you use this property, you need to include a third property with the following possible values:

      • [street_number]: returns the street number.

      • [route]: returns the street name.

      • [locality]: returns the city name.

      • [postal_code]: returns the zip or postal code.

      • [administrative_area_level_1]: returns the state or province.

      • [administrative_area_level_2]: returns the county.

      • [country]: returns the country.

      The fourth property is optional. You can include the following values:

      • [longName]: returns the full value. This is the default, so you don’t need to include it.

      • [shortName]: returns an abbreviation of the value. This property only has an effect on the [route], [administrative_area_level_1], and [country] second properties.

  • Usage examples:

    • Coordinates %a[SiteLocation][coordinates] returns Coordinates -23.76312, 80.44416, 25.55454.

    • Location acquired via %a[CompanyAddress][geoSource] returns Location acquired via GPS.

    • Delivery address: %a[CustomerAddress] returns Delivery address: 333 Tulip Lane, Kingston, ON, J3K 1A1, Canada.

    • %a[Location][addressDetails][country][shortName] returns CA

Date and time

Date and time answers use default date and time formats. You can add a second property to change how the system returns date and time.

  • Default properties: For dates, [ yyyy-MM-dd]. For time, [HH mm ss]
  • Other properties: You can customize the way the system returns dates and times by using the symbols specified in the %d - Date of the form submission and %t - Time of the form submission sections.
  • Usage examples:

    • Parcel delivered on %a[DeliveryDate][MMMM d, yyyy] at %a[DeliveryTime][hh:mm a] returns Parcel delivered on April 16, 2019 at 09:11 AM.
    • Vehicle purchased in %a[PurchaseDate][yyyy] returns Vehicle purchased in 2018.

Attachment

Attachment answers return information about images or documents that users submitted.

  • Default property: [bytes]

    Attachment answers return the file encoded in Base64 by default.

  • Other properties:

    • [filename]: returns the name of the file.
    • [contentType]: returns the file type.
  • Usage examples:

    • Technician uploaded the file %a[Attachment][filename] returns Technician uploaded the file Inspection_223233.pdf.

Barcode

Barcode answers return numeric or alphanumeric strings that users scanned and submitted.

  • Default property: [barcodeValue]

    Barcode answers return the value of the barcode by default.

  • Other properties:

    • [barcodeType]: returns the type of barcode the user scanned. Barcodes might be UPCs, QR Codes, or other commonly used barcodes.
  • Usage examples:

    • Tracking number %a[TrackingBarcode] returns Tracking number 1234567890.

Related Topics