App-to-App Communication

 

About

The ProntoForms app supports certain types of app-to-app communication. You can create links from other apps which allow you to link directly to a screen within the ProntoForms app.

Currently, the ProntoForms app supports:

iOS Android Windows 10
  •  launching the app from another app;
  •  triggering a reconcile to ensure users have the most up-to-date forms on their device;
  • opening a particular form using the formID;
  • opening a partially-completed form with clientDataRecordID.
  • App-to-App Dispatching using the Open action.
  • opening a particular form using formIterationID*
  • sending a particular form to the server, such as a draft or outbox form submission to the server, or opening a form populated with dispatched information and sending it to the server
  • launching the app from another app;
  • launching the app and showing the user a particular tab of the app;
  • opening a particular form using the formID;
  • opening a particular form using formIterationID.*
  • opening a form using the form name.
  • App-to-App Dispatching using the Open action
  • sending a particular form to the server, such as a draft or outbox form submission to the server, or opening a form populated with dispatched information and sending it to the server
  • launching the app from another app;
  • launching the app and showing the user a particular tab of the app;
  • opening a particular form using the formID;
  • opening a partially-completed form with formIterationID.
  • opening a form using the form name.
  • App-to-App Dispatching using the Open action
  • sending a particular form to the server, such as a draft or outbox form submission to the server, or opening a form populated with dispatched information and sending it to the server

You can also launch the ProntoForms app from another Android app using Android Intents. Learn more here.

* The only iterations accessible through formIterationID are the ones available to the client, i.e. active and draft, where formspace permissions allow testing.

[ top ]

 

URL Scheme

Specify prontoforms as the scheme in your app-to-app URL. 
Use the following scheme when invoking an app-to-app call: 
prontoforms://
The following URL scheme may be used in the case where a custom scheme may not be allowed, such as within the body of an email: 
https://www.prontofor.ms/
Note: If you are a white label customer, the ProntoForms team will provide a scheme that is unique to your mobile apps.

[ top ]

 

Host

The host or external app is where your user is coming from. It is always identified by iOS as x-callback-url in the ProntoForms app-to-app communications URLs.  This tells the device where the request came from and what external app hosts the ProntoForms app.

Example:

prontoforms://x-callback-url/

[ top ]

 

Action

You can create links from the external app which allow you to link to a particular form screen or open a specific form. The example below will open a specific form when combined with additional information.

Example:

prontoforms://x-callback-url/open?

Action

Description

Supported Action Parameters

Supported x-callback Parameters

launch

Launches the application

reconcile (optional)

 

list

Presents the user with a particular form screen

type (optional)
reconcile (optional)

 

open

Opens various forms based on the supplied parameter. Used in app-to-app dispatching.

formID (optional)
Form Name* (optional)
formIterationID (optional)
dataRecordID (optional)
clientDataRecordID (optional)

x-success
x-error

send

sends a particular form to the server, such as a draft or outbox form submission to the server, or opening a form populated with dispatched information and sending it to the server

type

formID (optional)

formIterationID (optional)

dataRecordID (optional)

clientDataRecordID (optional)

Any additional parameters will be treated as dispatched data by question label, except when the type is Outbox.

x-success
x-error

* See Description in Action Parameters below.

[ top ]

 

Action Parameters

Action Parameters are pieces of additional information that allow you to:

  • trigger a reconcile to ensure users have the most up-to-date forms;
  • select which form screen to open, whether it is Inbox, Drafts, Outbox, or Sent;
  • specify a form to open;
  • open a partially-filled or complete form.

In this example, we will open the ProntoForms app and direct it to open a particular form. Each ProntoForms form has a unique ID to identify it.

prontoforms://x-callback-url/open?formID=15872001

 Note: You can find any form's unique formID or formIterationID by following the instructions on this page.

Action Parameter

Description

Type

Expected Values

iOS

Android

Windows

(v5.8 and above)

reconcile

Triggers a reconcile in the ProntoForms app to ensure users have the most up-to-date forms. 

boolean

0 (default)
1

type

Opens the selected ProntoForms app screen: forms, drafts, inbox, or sent.

string

forms (default)
drafts
inbox
sent

 ✔

clientDataRecordID

Opens a form started by the ProntoForms app user, usually a form saved in drafts.

string

user-defined

 ✔

dataRecordID

Opens a dispatched or completed form.

string

user-defined

 ✔

formID

Opens a specific form for the user to start filling out.

string

user-defined

 ✔

formIterationID

Opens a specific form version for the user to start filling out.

string

user-defined

 ✘

name (Form Name)

Opens a form based on the form name. This allows partial string matches. *

 string user-defined  ✔

tag **

Opens a form based on form tags. Should be used with the type parameter to specify where the app-to-app call is targeting.

string user-defined

Note: As form names are alphanumeric and may not be unique, here are guidelines for use with the Open action:

  • As the app-to-app URL uses URL encoding, if there are any spaces or special characters in the form name, encode them appropriately (percent encoding). There is one exception: the "(" and ")" symbols should not be encoded in Android platform dispatches.
  • Uses string matching to bring up matching form names. This means that it will bring up a list of partial matches to the string match. Users select the appropriate form if there are multiple matches.
  • All subsequent parameters/dispatched information will be parsed to the selected form. If there is information dispatched to question labels that do not exist in the form, that information will be ignored.

** Form Tags: 

  • This call is only applicable to forms in the Forms List, and dispatched forms in the Inbox (i.e., type="forms" or type="inbox").
  • While both tag and type should be present in the app-to-app call, if type is missing, it defaults to type="forms" or the Forms List.
  • This app-to-app call will return a list of all forms that have the tag requested.
    • If there is one, it will automatically open the ProntoForms app and open the form or dispatch immediately.
    • If there is more than one form matching the requested tag/type, it will show the Forms or Inbox list with all matching forms/dispatches.

 

[ top ]

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments