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
- URL Encoding
- Actions: launch, list, open, and send
- X-Callback Parameters
- Dispatching Data
- Exceptions
- Error Codes and Messages
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
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://
- 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.
Exceptions
Unsupported Question and Data Types
ProntoForms does not support app-to-app dispatching of information into the following question and data types:
|
|
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
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.
Comments
0 comments
Please sign in to leave a comment.