Skip to main content

App-to-App Communication (replaced by new topics)

  • Updated

New and improved content available! This article is replaced by topics in the following sections:

ProntoForms supports x-callback-urls for app-to-app communication, allowing other apps to trigger actions in ProntoForms. On iOS we leverage the Universal Links convention, and on Android, we use App Links. Both utilize a custom URL scheme, as described below, to send data from one app to another.  The same custom URL scheme works with the ProntoForms for Windows 10 app.


URL Scheme

The ProntoForms custom URL scheme is prontoforms://.

Actions can be called through the x-callback-url API using the following format:

prontoforms://x-callback-url/[action]?[action parameters]&[x-callback parameters]

 For more information regarding the URL format, see the official specification.

 

URL Encoding

URLs will require UTF-8 percent encoding for all special characters and spaces, except for open and close parenthesis ( ), which should be input normally. For further information on HTML URL encoding, please see the following link. An example of an encoded url has been provided below. 

Original: 

prontoforms://x-callback-url/open?name=Inspection Form


Encoded: 

prontoforms://x-callback-url/open?name=Inspection%20Form


Actions

ProntoForms supports the following actions, as described below: launch, list, open, and send. The parameters described below will function for iOS, Android, and Windows (v5.8 and above) unless otherwise noted. 


launch

Launch the ProntoForms application. 

Action Parameters

reconcile

Trigger a reconcile in the ProntoForms app to ensure users have the most up-to-date forms. Using this action parameter is optional.
Expected values: 0 (default), 1.

Supported x-callback Parameters

None

Example

Launch the ProntoForms App:

prontoforms://x-callback-url/launch
Launch and reconcile the ProntoForms App:
 prontoforms://x-callback-url/launch?reconcile=1

 

list

Present the user with a particular form screen. (Inbox, Drafts, Outbox, or Sent)

Action Parameters

reconcile

Trigger a reconcile in the ProntoForms app to ensure users have the most up-to-date forms. Optional.
Expected values: 0 (default), 1.

type

Open the selected ProntoForms app screen: forms, drafts, inbox, or sent. Optional. 
Expected values: forms (default), drafts, inbox, sent.

Supported x-callback Parameters

None

Example

Launch and reconcile the ProntoForms App, and open the Inbox page: 

prontoforms://x-callback-url/list?reconcile=1&type=inbox

 

open

Open a form based on the supplied parameter.  

Action Parameters 

name

Open a form based on the form name. This parameter allows for partial string matches, allowing the user to select from a list of partial matches. The form name must be entered using UTF-8 percent encoding. 

tag

Open a form, or list of forms based on a form tag. This parameter can be used in conjunction with the type parameter. If there is more than one form matching the requested tag and type, a list of matching items will be shown from either the Forms or Inbox list. 

type

When using the tag parameter, the type parameter can be used to identify where the forms will be found.
Expected values: forms (default), or inbox. 

 formID

Specify the form to be opened by referencing the form ID. 

formIterationID

Specify the form version to be opened using the form iteration ID. 

dataRecordID

Open a dispatched or completed form.

clientDataRecordID

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

Supported x-callback Parameters

x-success

x-error

x-cancel

Examples

Open a form with the name "Asset List":

prontoforms://x-callback-url/open?name=asset%20list

Open the form in the Inbox with tag "install": 

prontoforms://x-callback-url/open?tag=install&type=inbox

 

send

Send a form to the server. The form might be a draft or outbox form submission, or a form populated with dispatched data in the inbox. 

Action Parameters

type 

This specifies the location of the form on the app. The type parameter is required for the send action. There is no default value. If the value specified is invalid, the x-error callback will be called, else the end-user will receive an error message.  
Expected values: drafts, inbox, sent. 

formID

Specify the form to be sent by referencing the form ID. If there are multiples items with the same formID, the user will be presented with a list from which to select the correct item. 

formIterationID

Specify the form version to be sent using the form iteration ID. 

dataRecordID

Sends a dispatched or completed form.

clientDataRecordID

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

Supported x-callback Parameters

x-success

x-error

Example

Find an item in the Inbox with Data Record ID "18121244038", and submit. 

prontoforms://x-callback-url/send?dataRecordID=18121244038&type=inbox

Find an item in the Drafts folder with Form ID "147220048", and submit. 

prontoforms://x-callback-url/send?formID=147220048&type=drafts

X-Callback Parameters

If the action in the target method is intended to return a result to the originating app, the x-callback parameter should be included and provide a return callback parameter to return to this app. On completion of the action in ProntoForms, callback URL will be opened. If a return callback parameter is not provided, the user will stay in the ProntoForms app on successful completion of the action. For optimal user experience and efficiency, it is best practice to include all three callback parameters in your request. 

x-success

URL will be opened if the requested action resolves successfully. The ProntoForms app returns one of the three following values for the pfStatus parameter:

Value Description Example
Saved The ProntoForms app user saved the record manually as a “Draft”. customapp://x-callback-url?clientDataRecordID=317A230F-70C3-4CC9-B9ED-697C0CB35174&pfStatus=Saved
Outbox The ProntoForms app user tapped to “Send” and complete the form, but a lack of connectivity resulted in the record being queued in the outbox of the ProntoForms app. customapp://x-callback-url?clientDataRecordID=317A230F-70C3-4CC9-B9ED-697C0CB35174&pfStatus=Outbox
Sent The ProntoForms server received the record sent by the ProntoForms app user. customapp://x-callback-url?dataRecordID=184555066&pfStatus=Sent

x-error

URL will be opened if the requested action generates an error and cannot be completed successfully.

x-cancel

URL will be opened if the requested action is cancelled, e.g. tapping the Back button on Android, thereby discarding the form.

Example

If the data record with data record ID "18121248743" is sent successfully, then open the app "Slack" using the slack:// URI.

prontoforms://x-callback-url/send?dataRecordID=18121248743&type=inbox&x-success=slack://
Additional parameters that may be appended to the URL include:
  • clientDataRecordID (this is the ID of the data record as stored on the user's device) if the form was saved as a draft.
  • serverDataRecordID (this is the ID of the data record as stored on the ProntoForms servers) if the form was completed and sent.

Dispatching Data

Building an app-to-app dispatch URL starts with the open action and the formID, name, or formIterationID. Data can be passed to answer fields in ProntoForms using key value pairs passed as query arguments in the URL, in the format “key1=value1&key2=value2”.

Example

prontoforms://x-callback-url/open?name=Job%20Estimate&Phone%20Number=416-555-0192

This example will open a form named "Job Estimate" and enter the value "416-555-0192" into the question with unique ID "Phone Number".

If your dispatch string contains parameters (unique IDs) that are not contained in the form, that data will be ignored. 

Note: The type of data being dispatched must match the question it is being dispatched into. If dispatching into a numeric question, ensure that your data is numeric. When dispatching into a dropdown question, ensure the answer you are dispatching is one of the answers available to that dropdown question.

Exceptions

Unsupported Question and Data Types

ProntoForms does not support app-to-app dispatching of information into the following question and data types:

  • Label information
  • Button Group
  • Concatenation 
  • Digit Extraction 
  • Time based math and calculations
  • Number (currency) calculation
  • Date/Time Stamp
  • Slider
  • Range Slider
  • Attachments
  • Geolocation/GPS-related questions
  • Barcode
  • Multi-Select Questions


URL Scheme Exceptions

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://prontofor.ms/x-callback-url/

For example, to open a form with the tag "jha":

https://prontofor.ms/x-callback-url/open?tag=jha
Note: If you are a white label customer, the ProntoForms team will provide you with a scheme that is unique to your mobile apps.

Error Codes and Messages

ProntoForms has a number of defined error codes. As follows: 

PFErrorCodeListNotFound / 2001

if the request is
prontoforms://x-callback-url/list 
prontoforms://x-callback-url/list?type=forms
Error message: Form list not found.

if the request is
prontoforms://x-callback-url/list?type=inbox
Error message: Inbox not found.

if the request is
prontoforms://x-callback-url/list?type=sent
Error message: Sent list not found.

 

PFErrorCodeItemNotFound / 1010

if the request is
prontoforms://x-callback-url/open?formID=15872001
A form with the requested ID does not exist. FormID = 15872001

if the request is
prontoforms://x-callback-url/open? formIterationID=15872001
A form with the requested iteration ID does not exist. FormIterationID = 15872001

prontoforms://x-callback-url/open?formName=Inspection 
A form with the requested name does not exist. FormName = Inspection

if the request is
prontoforms://x-callback-url/open?DataRecordID=15872001
A Data Record with the requested ID does not exist. DataRecordID = 15872001

if the request is
prontoforms://x-callback-url/open?clientDataRecordID=15872001
A Data Record with the requested local data record ID does not exist. ClientDataRecordID = 15872001

if the request is
prontoforms://x-callback-url/list?type=inboxList
Error message: A list that is named “inboxList“ does not exist.

Related articles

Comments

0 comments

Please sign in to leave a comment.