Capture OnTheGo

With the Designer you can create Capture OnTheGo templates. COTG templates are used to generate forms for the Capture OnTheGo mobile application. For more information about the application refer to these websites: Capture OnTheGo and Capture OnTheGo in the Resource Center.

COTG Forms

A Capture OnTheGo Form is actually just a Web Form that has a number of characteristic features:

• Its action always specifies a Workflow HTTP Server Input task, so that when the Form is submitted, the form data is sent to the Workflow server. (See: Specifying an action.)
• It may contain special COTG Input elements, like a Signature, Geolocation, or Camera element. These require the COTG JavaScript library to be added to the template. This happens automatically when the Form is created with a COTG Template Wizard.
• Thanks to the mobile app, it may be used offline. The app will submit the Form data when a connection to the internet is available. Just make sure, if the Form uses remotely stored style sheets or JavaScript files, that the option 'Use cached Capture OnTheGo resource' is enabled when adding the resources to the template. This prevents that the app tries to download a file again that has already been downloaded.
• It may be reusable. This depends on a setting in the Output to Capture OnTheGo plug-in (found on the Connectors tab) in Workflow (see the Workflow Help: Output to CaptureOnTheGo). A reusable COTG Form is not deleted from the app's form library when it is submitted, so it can be used again.

Creating a COTG Form

A Capture OnTheGo Form is actually just a Web Form, so you could add a Form element to a Web page in the Web context without the use of a Template Wizard. It is strongly recommended however, to start the COTG Template using one of the COTG Template Wizards. They all include the appropriate JavaScript files and style sheets to create user-friendly, responsive forms; see Capture OnTheGo template wizards.

Before starting to create a COTG Form, take some time to structure the design process and to get familiar with the principles of form design, as explained in the topic Designing a COTG Template.

Reusable forms

Capture OnTheGo forms can be single-use or reusable. This doesn't depend on the design (although, of course, this should be reflected in the design). What makes a form reusable is a setting in the Output to Capture OnTheGo plugin in Workflow; see Output to CaptureOnTheGo. In the Capture OnTheGo app a reusable form is called a 'template'.

Forms for offline use

Capture OnTheGo forms can be used offline. This is the case even when the form relies on remotely stored source files like JavaScript files and style sheets, provided that the option Use cached Capture OnTheGo resource is checked when adding them to the form.

Specifying an action

The action of the Capture OnTheGo Form element should specify a Workflow HTTP Server Input task (see Workflow Help: HTTP Server Input) that receives and handles the submitted data. The action will look similiar to this: http://192.168.175.1:8080/actionname (where actionname is the HTTP action of the HTTP Server Input task).
For information about specifying an action for a Form, see Adding a Form or Changing a Form's properties.

Filling a COTG template

Before inserting elements in a COTG Form, have the design ready; see Designing a COTG Template.

In a Capture OnTheGo form, you can use special Capture OnTheGo Form elements, such as a Signature and a Barcode Scanner element. For a description of all COTG elements, see: COTG Elements. To learn how to use them, see Using COTG Elements.

Foundation, the framework added by the COTG template wizards, comes with a series of features that can be very useful in COTG forms; see Using Foundation.

Naturally, Web Form elements can also be used on COTG Forms (see Forms and Form Elements) as well as text, images and other elements (see Content elements).

Capture OnTheGo templates can be personalized just like any other type of template; see Variable Data and Personalizing content.

Using JavaScript

COTG plugin

Capture OnTheGo widgets do not function without the COTG plugin: cotg-2.x.x.js. This plugin also makes it possible to add COTG Elements dynamically, set defaults for COTG elements, react to events that occur when a user interacts with a COTG element, etc. For more information see: Using the COTG plugin.

Foundation

For COTG templates created with a COTG template wizard, lots of features are already available through the Foundation framework; see Using Foundation.
The Foundation JavaScript files and style sheets are only added automatically when you start creating a COTG template with a template wizard; see Capture OnTheGo template wizards.

Other JavaScript files

You may add other JavaScript files, libraries and frameworks to a template, to enhance your Capture OnTheGo Forms; see Using JavaScript.

Testing the template

A Capture OnTheGo (COTG) template will be used to create a form that can be downloaded, filled out and submitted using the COTG app. Before starting to actually use the template, you will want to make sure that it produces a form that looks good and functions as expected. How to preview the form, how to submit data and how to preview the submitted data is described in another topic: Testing a Capture OnTheGo Template.

Sending the template to the Workflow tool

After testing the template (see Testing a Capture OnTheGo Template) the template must be sent to the Workflow module. Templates sent to the Workflow module can be used in any process within it.

How to send the template and the corresponding data mapping configuration to the Workflow tool is explained in another topic: Sending files to Workflow.

Next, you can start building a Workflow configuration that receives and handles the submitted data. The configuration should start with a HTTP Server Input task (see Workflow Help: HTTP Server Input) of which the HTTP action is the one specified in the COTG Form's action.

Receiving and extracting data from a COTG Form

When a user submits a Capture OnTheGo Form, the submitted data are sent to the address specified in the action of the form (see Specifying an action). They will be received by the process that starts with the matching Server Input task (see Workflow Help: HTTP Server Input).
The data is passed on as XML.
The next task in the process typically is an Execute Data Mapping task. This task can extract the data using a data mapping configuration that must be tailor-made for this XML. In order to create this data mapping configuration you will need an XML file with the exact same structure. The easiest way to get this is to test the template and use the "Get Job Data File on Submit" option; for instructions see Submitting and previewing data.

Using COTG data in a template

When a user submits a COTG Form, a Workflow configuration may store the information in a database and/or push it into other Workflow processes, for example to send a letter or an email receipt. To be able to use the submitted data in a template for that letter or email receipt, follow these steps:

1. Get sample data
   Before you can create a template that uses COTG data that is submitted from a certain COTG Form, you have to get access to a sample of that data. There are two ways to do this:
   • Using the option Get Job Data File on Submit in Connect Designer; see Testing a Capture OnTheGo Template. This way you don't have to create a Workflow configuration first. Once the Job Data File is received by the Connect server, a dialog appears asking where to store it.
     
   • Using a Workflow configuration. When a user submits a Capture OnTheGo Form, the data are received by a Workflow HTTP Server Input task (see Workflow Help: HTTP Server Input) that receives and handles the submitted data. Even when no other tasks are present in that Workflow configuration, Workflow can output an XML file that contains the submitted data, in a location specified for the Send To Folder plugin in Workflow.
   When a COTG Form is submitted, by clicking or touching the Submit button, the name and value of form elements are submitted. If a Checkbox or Radio Button is not checked, its name and value are not sent when the form is submitted. Fortunately, there is a workaround for this; see Using COTG Elements.
   The Form's validation should ensure that the data that the user submits is valid (see Changing a Form's validation method and How to make COTG elements required).
2. Create a data mapping configuration
   Use the resulting XML file to create a data mapping configuration (see Data mapping configurations).
1. Choose File > New > Data mapping Wizards > From XML file.
2. Select the XML data file as its source and click Next.
3. Set the XML Elements option to /request/values. This will automatically add an extraction step for the submitted form fields.
4. Click Finish​. The file is opened in the DataMapper and the form fields are automatically extracted including the data for the signature and camera object.
5. Save the data mapping configuration.
3. Create a template
   Create a Designer template and personalize it using the data mapping configuration (see Personalizing content). Strings, base64-encoded strings and SVG data, stored in data fields using the DataMapper can be added to the template just like any other variable data; see Variable Data. They will show up in the template as they are.
   Strings and base64-encoded strings show up as strings.
   SVG data will be interpreted and displayed as an image.
   The Signature data returned by the COTG app (as of Android 10.6.0, iOS 10.6.0, and Windows 6.0) is formatted so that the signature will automatically be scaled to fit in the containing box in a template. With previous versions of the app the format of returned signatures could vary.

Adding ​​​Camera data to the template

The Camera widget submits a base64-encoded string, which can be put in a data field using the DataMapper. When this data field is dragged into a template, the string will show up in the content, instead of the image.
To make the image appear in a template, the data has to be used as the URL of an image.
The below procedure describes how to use Camera data as an image inside a <div> container. The benefit of this approach is that the image automatically scales to the size of the container.

1. Click the Insert Inline Box icon on the toolbar. The Insert Inline Box dialog appears.
2. Enter an ID for the box (anything will do, as long as it helps you identify the box) and click OK​. The box is added to the text flow and can be resized if needed.
3. Switch to the Source tab and replace the content of the box:

   <p>
   	Div content goes here
   </p>

   by this text:

   <img id="camera" src="" width="100%">

4. Switch back to the Design tab. You will see a small, empty rectangle inside at the top of the inline box.
5. Right-click the empty rectangle and choose New Script... in the contextual menu. The Edit Script dialog appears. The selector of the script is automatically set to the ID of the selected element (#camera).
   Alternatively, you could add a new script on the Scripts pane and make sure that the Selector field is set to #camera.
6. Enter the following script code:

   results.attr("src", record.fields.photo);​

   The name of the data field (in this case: photo) must be that of the Camera data in your data model.
   ​​This script updates the attribute “src” with the field containing the base64 image.
7. Click OK to save the script and toggle to the Preview​ mode to see the result. You should see your image. When you resize the inline box that surrounds the image, the image should be resized as well.
   If the inline box isn't visible, click the Show Edges button in the toolbar.