The integration API for naturalForms on the iPad uses the URL-based x-callback-url interapp communication 1.0 draft spec.
See http://x-callback-url.com for details. The URL scheme implemented by naturalForms is nfapi:// for all supported commands. Structured data is passed via the standard JSON format, and attributes are case sensitive.
All JSON data used by the integration API must be escaped using standard HTTP encoding. On iOS, this can be accomplished via the NSURL method stringByAddingPercentEscapesUsingEncoding: or any other compatible method.
Executing integration commands does not bypass application security. Users will be required to login to the application before a command is executed. If the user is already logged in, but the application is running in the background, they will not be prompted to log in.
Command names are not case sensitive, but are shown in camel case throughout this document for clarity.
Add Documents [addDocument]
Use the addDocument command to add new documents to naturalForms, and pre-populate field values. This command will always create new documents each time the URL is launched. addDocument will not attempt to edit documents created previously, even from the same URL.
Documents Parameter
Type: JSON Array
Format: id [Required] is the form template ID from the NFS database.
name [Required] will be used to describe the document, as shown by naturalForms in the document list.
values [Optional] is a JSON dictionary of field values, as named in the form template. These values will override any values passed in the primary values parameter described below.
You can pass more than one document in the array, and each can have its own values specific to the associated document.
Example
[ { "id": 88125, "name": "My Document", "values": { "FirstName": "Joseph", "LastName": "Carson" } } ]
Values Parameter
Type: JSON Dictionary
Format: The primary dictionary of field values, as named in the form template. These values will apply to all documents in the documents parameter.
Use of this parameter is not required, as each document can contain its own set of values in the documents parameter. However, supplying this parameter helps to shorten the launch URL by providing a pool of values used by all documents, where applicable.
If a field doesn't exist in the form template for a target document, it will be ignored without generating an error.
Example: { "FirstName": "Joe", "LastName": "Carson", "JobNum": 18381 }
x-source Parameter
Type: String
Format: The name of the calling application, as defined in the x-callback-url spec. This may be used by naturalForms in the UI as part of success or failure messages.
Example: My Application
x-error Parameter
Type: URL
Format: The URL to call if an error occurs while trying to execute the command. This URL will be called with the standard errorCode and errorMessage parameters, as defined in the x-callback-url spec.
Example: myapplication://x-callback-url/1.0/addDocumentFailed
Example URL
Note: This example is not http encoded for clarity.
nfapi://x-callback-url/addDocument?documents=[{"id":88125, "name":"Work Order 18381", "values":{"JobNum":18381}}] &values={"FirstName":"Joe","LastName":"Carson"} &x-source=My Application &x-error=myapplication://x-callback-url/1.0/addDocumentFailed