Building Nintex Mobile links

Blog: Nintex Mobile deep linking

Tutorial: Auto-submitting QR codes

This topic provides examples and parameter descriptions for Nintex Mobile links. Nintex Mobile links provide deep linking support, facilitating external app integration.

You can build Nintex Mobile links that perform the following functions in the Nintex Mobile app and in custom-branded apps developed in Nintex App Studio.

  • Display a specific form in the app
  • Pre-populate form fields with specified values and optionally submit the form automatically
  • Navigate to a specified URL after form submission

The following sections provides information about the Syntax of a Nintex Mobile link to use for Classic, Responsive and New Responsive Forms.

Important: Deep linking is supported only for List forms (Start forms) and cannot be used with workflow task forms. For more information about form types, see Types of forms.

Usage

Use Nintex Mobile links to ease deployment of Nintex Mobile and custom-branded apps in your organization.

  • Customers and employees can quickly access forms with form navigation-enabled links. They don't have to remember the form name or location. All they need to do is tap or click the link on their mobile device and then sign in.

Syntax

The following example describes the syntax of a Nintex Mobile link, where ACTION represents the optional action for the link and PARAMETERS represents the optional parameters specified for the link.

  • Nintex Mobile (uses the "nintexmobile" URL scheme): 

    • nintexmobile://[{ACTION}][?{PARAMETERS}]

    Replace {ACTION} and {PARAMETERS} with the action and parameter you want. Actions and parameters available are described in sections below. For example, if you are using the 'form' action and the 'ntx-name' parameter, the link to open the form will be nintexmobile://form?ntx-name=formname

  • Nintex App Studio (uses the custom URL scheme defined for your app, which begins with "ntx-"): 

    • [CUSTOMURLSCHEME]://[{ACTION}][?{PARAMETERS}]

Specifying nintexmobile:// with no action or parameters launches the Nintex Mobile app.

Specifying [CUSTOMURLSCHEME]:// with no action or parameters launches the custom-branded app for which the scheme was defined.

Action descriptions

This section describes the actions available for use in the {ACTION} portion of the Nintex Mobile link syntax. This portion of the link specifies whether it's a Classic, Responsive or New Responsive Form.

nintexmobile://[{ACTION}][?{PARAMETERS}]

Action Description

form

Applicable for Classic and Responsive forms.

Navigates to the form indicated by the specified parameters.

For example, if you are using the the 'ntx-name' parameter, the link to open the form will be nintexmobile://form?ntx-name=formname
universalform

Applicable for New Responsive forms.

Navigates to the New responsive form indicated by the specified parameters.

For example, if you are using the the 'ntx-name' parameter, the link to open the form will be nintexmobile://universalform?ntx-name=formname

For more information, see the Examples given below.

Parameter descriptions

This section describes the parameters available for use in the {PARAMETERS} portion of the Nintex Mobile link syntax.

nintexmobile://[{ACTION}][?{PARAMETERS}]

A parameter is a name-value pair, using equals (=) between the name and value. Separate parameters using ampersands (&).

All parameter values should be URL encoded. For information on URL encoding, see HTML URL Encoding Reference.

For more information, see the Examples given below.

 

Form navigation parameters

This section describes the parameters to identify the form to display, customize messages, and automatically submit the form.

Form navigation parameters apply only when the ACTION is set to form. For examples of links using these parameters, see Examples.

For instructions on pre-populating form fields, see Form field pre-population.

Parameter Data type Description

ntx-autosubmit

String

Optional. Automatic submission. Use with true value to automatically submit the identified form with the indicated values in specified form fields (see Form field pre-population).

Default value: false

ntx-category

String

Optional. Form category. Use to uniquely identify a form when multiple forms of the same name exist.

This parameter is used only when the ntx-name parameter is specified.

ntx-id

String

Optional. Unique form identifier on the server.

The ntx-id parameter has precedence over the ntx-name parameter; if the specified value for ntx-id is found, then the ntx-name parameter is ignored.

ntx-msgError

String

Optional. Custom heading text to display when automatic submission (ntx-autosubmit parameter) fails.

Default value: empty

Default heading text: Validation issues prevent submission

ntx-msgLoading

String

Optional. Custom heading text to display during processing and loading of the Nintex Mobile link.

Default value: empty

Default heading text: Working on it

ntx-msgSuccess

String

Optional. Custom heading text to display when automatic submission (ntx-autosubmit parameter) succeeds.

Default value: empty

Default heading text when not specified: Done

ntx-name

String

Optional. Form name. Form names are case-sensitive.

The ntx-id parameter has precedence over the ntx-name parameter; if the specified value for ntx-id is found, then the ntx-name parameter is ignored.

ntx-returnUrl

String

Optional. Redirect URL for use when customer navigates away from specified form.

Example redirect URLs:

  • Host website: https%3A%2F%2Fcrestan.com%2Fmyformcompleted.aspx
  • Facebook app: fb%3A%2F%2Fprofile%2F123456

Upon redirection, Nintex Mobile appends an ntx-action parameter to the supplied ntx-returnUrl parameter to indicate whether or not the form was submitted. Possible values for the ntx-action parameter follow.

  • success
  • cancel

For the example host website above, the URLs used for redirection are as follows.

  • Customer successfully submits the form: 

    https://crestan.com/myformcompleted.aspx?ntx-action=success

  • Customer cancels form submission:

    https://crestan.com/myformcompleted.aspx?ntx-action=cancel

Examples

The example links in this section use the "nintexmobile" URL scheme for the Nintex Mobile app. To build links for a custom-branded app developed in Nintex App Studio, use the custom URL scheme specified for that app.

Classic and Responsive forms: nintexmobile://form?ntx-id=321dfaf8-e45e-49e6-9bef-b5b73c4daa51

Customer experience: Displays the specified form after sign-in.

Classic and Responsive forms: nintexmobile://form?ntx-name=Expense%20Report

New Responsive forms: nintexmobile://universalform?ntx-name=Expense%20Report

Customer experience: Displays the "Expense Report" form after sign-in.

Classic and Responsive forms: nintexmobile://form?ntx-name=Expense%20Report&ntx-returnUrl=http%3A%2F%2Fwww.crestan.com

New Responsive forms: nintexmobile://universalform?ntx-name=Expense%20Report&ntx-returnUrl=http%3A%2F%2Fwww.crestan.com

Customer experience: Displays the "Expense Report" form after sign-in. Upon form submission, redirects to http://www.crestan.com.

Classic and Responsive forms: nintexmobile://form?ntx-name=Expense%20Report&FullName=John%20Smith&ntx-autosubmit=true&ntx-msgloading=Loading

New Responsive forms: nintexmobile://universalform?ntx-name=Expense%20Report&FullName=John%20Smith&ntx-autosubmit=true&ntx-msgloading=Loading

Customer experience: After sign-in, the initial loading message displays with "Loading" and then the default successful submission message displays, indicating that the form was automatically submitted. After the customer dismisses the message, the forms list of the app is displayed.

Note: If the form submission is not successful, then the default submission error message displays instead of the default successful submission message.

Classic and Responsive forms: nintexmobile://form?ntx-name=Expense%20Report&FullName=John%20Smith

New Responsive forms: nintexmobile://universalform?ntx-name=Expense%20Report&FullName=John%20Smith

Customer experience: After sign-in, displays the "Expense Report" form with the "Full Name" field pre-populated with the value "John Smith."

Customer experience

This section describes the customer experience when clicking a Nintex Mobile link.

  1. Loading message: The Nintex Mobile app or custom-branded app loading message briefly appears (see ntx-msgLoading).

  2. Sign-in: The sign-in screen is displayed, with fields empty.

    If the customer is already signed in before clicking the link, then this step is skipped.

    If the customer is not yet signed in, then the sign-in process must be completed before continuing.

  3. App (forms list): If no form is identified in the link, then the forms list of the app is displayed.
  4. Form: If a form is identified in the link (see Form navigation parameters), then behavior after sign-in depends on configuration of automatic submission.
    • Automatic submission: If ntx-autosubmit is set to true, then the following steps occur.

      1. A message is displayed indicating submission status for the identified form and specified form field values (see Form field pre-population).

        If form submission is successful, then the success message appears (see ntx-msgSuccess).

        If form submission is not successful (the form cannot be found or specified form field values fail validation), then an error message appears (see ntx-msgError).

        If the device is offline, then a message appears notifying the customer that the form will be submitted when the device is online.

      2. The customer dismisses the message; subsequent behavior depends on configuration of the redirect URL.
        • If no redirect URL is identified in the link, then the app closes. App closing behavior is platform-specific.
        • If a redirect URL is identified in the link (see ntx-returnUrl), then the app closes and the specified URL is displayed (assuming the device is online).
    • Manual submission: If ntx-autosubmit is unspecified or set to false, then the following steps occur.
      1. The form is displayed.
      2. The customer completes and submits the form; subsequent behavior depends on configuration of the redirect URL.
        • If no redirect URL is identified in the link, then the forms list of the app is displayed.
        • If a redirect URL is identified in the link (see ntx-returnUrl), then the app closes and the specified URL is displayed (assuming the device is online).

Form field pre-population

This section describes how to pre-populate fields in identified forms.

Form field pre-population applies only when the ACTION is set to form and a form is identified.

To pre-populate a form field, specify the field name (control name) as a name-value pair, using equals (=) between the name and value.

Note: Control names are case-sensitive. The words "name" and "id" are reserved for backwards-compatibility in Nintex Mobile links. While the reserved words can be used in association with the "form" option, they cannot be used elsewhere in the link. For example, do not use reserved words to reference form fields. If you want to build links that pre-populate fields that use reserved words as names, you must rename the fields first.

For example, let's say you want to build a Nintex Mobile link for a QR code that pre-populates the field "Title" to say "Front Door" for a security check protocol. Furthermore, you want to autosubmit the form and customize the loading and success messages. In this case, you would create the following link.

nintexmobile://form?ntx-name=Security%20Check&Title=Front%20Door&ntx-autosubmit=true&ntx-msgLoading=Loading%20Security%20Form&ntx-msgSuccess

This link uses the "nintexmobile" URL scheme for the Nintex Mobile app. To build links for a custom-branded app developed in Nintex App Studio, use the custom URL scheme specified for that app.

Follow parameter guidelines (ampersand separation, URL encoding). No referenced form field names can start with "ntx-" as "ntx-" is a reserved prefix for link parameters.

Legacy Nintex Mobile links are supported for backwards compatibility only. For example, a link using the legacy parameter name as in nintexmobile://form?name=Expense%20Report is supported. However, if the parameter ntx-autosubmit is added to this link, then the app assumes that the link has been updated and it ignores any legacy parameters (such as name). 

To pre-populate a form field, add getQueryStringParameter("parameter") formula and pass the parameter through the link.

Link: nintexmobile://universalform?ntx-name=formname&parameter=parametervalue

Note: In addition to this, the getQueryStringParameter("parameter") formula can be added as variables, configuration panel, or rules depending on your use case.