Sample Project: COTG Timesheets

The COTG Timesheets Sample Project creates a Capture OnTheGo project that creates a web page with a web form and serves it to the COTG app. When the form is submitted, the project handles the submitted data by creating an XML, JSON and PDF output file in a folder.

For an introduction to this Sample Project, see Sample Projects overview video on the OL Learn website (start at 25:19) or on Youtube: COTG Timesheets.

Installing the project

From the menu, select File > New > Sample Projects > COTG Timesheets to start the wizard.

Alternatively, open the Welcome screen, click New at the left, then Project at the right and select the project type.

Tip: Click the Home icon icon at the top right to reopen the Welcome screen.

The wizard lets you select the folder in which you want the solution to be installed. Since Sample Projects are versioned (see Versioned projects), the software suggests to store it in the OL Connect folder that is located in your Documents folder. By default, all versioned project have their own folder under Documents/Connect.

In the selected folder, the Sample Project will create two subfolders: Configurations and Workspace.
The project's resource files are saved to the Configurations folder.
The Workspace folder is used for debugging or running the solution. It has an In folder that may be used to monitor incoming data and an Out folder to write output files to.

The selected folder's path is saved to a global variable in the Workflow configuration (see The Workflow configuration).

You also need to enter the host. This address will be used by the COTG app to download forms and submit data to the OL Connect Workflow service.
If you want to use localhost, the OL Connect Server, Workflow and COTG app must be installed on the local machine.

A valid COTG account, Repository ID and password are also necessary. You could use dummy data to create the Sample Project and finish the installation, but you won't be able to test the project.

For more information about the options, see: COTG Timesheets - Sample Project.

Finally, enter the username and password that will allow the software to access the Connect Server.

Tip: If you own OL Connect (Professional or Enterprise edition), free COTG trial licenses may be available to you; see http://www.captureonthego.com/en/promotion/.

Note: Your network setup may make it impossible for the COTG app to communicate with the OL Connect Workflow service. The app needs to be able to communicate with OL Connect Workflow in order to download forms and submit data. Network and firewall settings may block these requests. Please contact your local IT department for advise on how this can be resolved in your setup.

Testing the project

Once the Sample Project has finished the installation, the project is ready to be tested.

If the templates and data mapping configurations haven't been sent to Workflow yet, do that first (see Sending files to Workflow).
This requires that the Workflow service is running (see Starting the Workflow service in Workflow's Online Help).
Send the Workflow configuration to the Workflow service; see Saving and sending a Workflow Configuration in Workflow's Online Help.
Open the Workflow configuration from the project's Resources\Workflow folder.
Select the cotg_ts_deploy_form process, open the Debug ribbon and click Run to execute the process. This deploys a number of forms to the COTG account entered in the Wizard.

Note: The process is pre-configured to use the sample data file, which comes with the project, when it runs in Debug mode.
Alternatively you could copy the sample data file to the In folder.
Launch the COTG app and log in using the COTG account that you entered in the Sample Project.
In the app, open the Repository and download one of the forms.
From the app's Library, open the form.
Enter data and draw a signature.
Submit the form.

Note: If the COTG app is unable to submit the data, you may have to change your network setup or remove the built-in restrictions in Windows 10 that prevent applications from sending data to the same computer. See Installing the project.

Project details

The templates

The form

The COTG Timesheet Form template contains a Web context with one Web section: Section 1 (see Web pages and Forms). The form has regular Form elements as well as COTG elements (see Form Elements and COTG Elements).

The template was started with the Time Sheet Wizard (see Capture OnTheGo template wizards), which also provides the necessary JavaScript files and style sheets.

Most of the scripts are simple Text Scripts (see Using the Text Script Wizard). They put data in one of the form's fields, selecting the field by its ID.

Tip: Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.

The guid script adds data to the guid field. This is a hidden field. It is only visible in the Source view.
The result of the form action script is added to the form's action attribute. To see how that is done, double-click the script; then click Options.
The Year script puts the current year in the footer of the page. This is a custom script. For more information about writing scripts, see: Writing your own scripts.

The report

The COTG Timesheet Report template contains a Print context with one Print section: Section 1 (see Print sections) and one Master Page (see Master Pages).

Personalization is mostly done via simple text scripts. Such scripts look for a text surrounded by @ (e.g. @city@) and replace that by the correct data. (See: Variable data in text: scripts and placeholders.)

The template also contains a dynamic table which is filled and expanded dynamically by the scripts in the Table folder. To learn how to insert and edit such a table, see Dynamic Table.

Note that this table does not use one of the default table styles, and that the style sheet with the default table styles is not present in the template. To add that style sheet to the template, insert a table using the Dynamic Table wizard.

The data mapping configurations

This project has two data mapping configurations, made with The DataMapper. To open one of them, select File > Open from the menu in the Designer and browse to the Configurations\Resources folder.

COTG Timesheet Form

The COTG Timesheet Form data mapping configuration is designed to extract data from the sample data file (Sample Data.xml).
The configuration also adds two fields to each record, using JavaScript: a unique ID (guid) and a field that contains the action of the Form.
Note that the COTG account is the same in all of the records in the sample data. It is inserted into the sample data by the Sample Project.

COTG Timesheet Report

The COTG Timesheet Form data mapping configuration is designed to extract the data that are submitted via the app. It first extracts the common fields, and then the information from the rows in the form, in a loop. For information about how to extract a variable number of similar elements from an XML file, see: From an XML file.

In order to create this data mapping configuration, the input data needed to be saved to a file first (see Saving input as sample data).
The sample data file is located in the Configurations\Data folder, but you will also see it when you open the data mapping configuration itself.

The Workflow configuration

There are four processes in the COTG Timesheets Workflow configuration. Some of them use the OL Connect tasks that are normally used in a Web process or a Print process (see Web processes with OL Connect tasks and Print processes with OL Connect tasks).

Creating the forms

The cotg_ts_deploy_form process is triggered when any file enters the Workspace\In folder, but its Execute Data Mapping task expects an XML file that is structured exactly like the Sample Data.xml file (in the Resources\Data folder).
The Execute Data Mapping task outputs records in the Metadata.
Subsequently, the Metadata Sequencer task creates a loop; the rest of the process is performed as many times as there are records in the Metadata, for one record at a time:

The Set Job Infos and Variables task reads data from the (current record in the) Metadata and puts them into variables.
The Create Web Content task merges the record with the COTG Timesheet Form template.
The Send to Folder task saves the form to the Forms folder in the project folder, using the value of one variable as the file name.
Finally, the Output to Capture OnTheGo task sends information about the form to the COTG Server. Double-click the task to see how variables are used in its settings.

The Delete task is an Output task that does nothing, actually; it doesn't even remove anything. However, this step is useful when running the project step by step in Debug mode. Tasks will only return their output to the process - where it can be viewed - as long as they are followed by another task.

Serving a form

When the user chooses to download a form in the app, the app sends a request using the URL that was set for the form in the properties of the Output to Capture OnTheGo task (on the Deposit tab). The URL contains one parameter: a unique ID.
The cotg_ts_serve_form process receives the request and loads the form (if it exists). The Load External File task replaces the job file with the form. At the end of the process the Server Input task returns the job file (the form) to the app.

Capturing data and generating output

When the user submits a form, the cotg_ts_capture_data process writes the job file - the request in the form of XML - to a Temp folder in the Workspace and sends a response code to the app. This way there is no need for the COTG user to wait while output is being generated. The response to the app can be sent right away.

The cotg_ts_generate_report process picks up the XML file from the Temp folder, converts it to JSON and saves it to a JSON file. Note how the Branch task keeps a backup of the job file. It is the backup file - the XML - that is handed down to the next Branch, where it is saved as an XML file.
Finally, the process extracts data from the job file and merges them with the COTG Timesheet Report template, generating a PDF.
All output files are stored in the Workspace\Out folder

Customizing the project

A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project.

Do you intend to expand the project into a solution where Workflow runs on a different machine that also has a different regional setting? Then indicate the desired encoding in the Designer preferences (see Sample Project deployment settings) before installing the project.

The form

If you want to add inputs to the form and extract the submitted data, here's how to do that.

Open the Web section and add elements to the Web Form (see Using COTG Elements and Using Form elements).
You could also add text, images and other elements (see Content elements) and change the layout of the page (see Styling and formatting).
Save the template and send it to Workflow (see Sending files to Workflow).
Upload the Workflow configuration to the server (see Saving and sending a Workflow Configuration in Workflow's Online Help) and let the process save the input data to a file (see Saving input as sample data).
Use the saved file to expand the data mapping configuration (see Opening a data mapping configuration). Send the data mapping configuration to Workflow.
Send the Workflow configuration to the server.

Saving input as sample data

Testing a process in Debug mode is only possible with a sample data file. The process is pre-configured to use the Sample Data.xml file located in the Configurations\Data folder.
To create your own sample data file:

Locate the Workflow configuration in the Configurations\Workflow folder and open it in Connect Workflow.
Select the process.
Enable the Send to Folder step (step 2 in the process).
Send the Workflow configuration to the Workflow service (see Saving and sending a Workflow Configuration) and run it again, with a custom name value.
The Send to Folder step will now write the input data - the job file - to a file in the Workspace\Debug folder.

When you select the file as sample file (on the Debug ribbon), it can be used to debug the process.

Tip: The saved file can be used to create a data mapping configuration.

The report

Using different data in the report requires changing the COTG Timesheet Report template (see Personalizing content).

Tip: The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both.

You could also:

Add text, images and other elements (see Content elements)
Change the layout (see Styling and formatting)
Change the Media. If you have an image of the stationery the PDF will be printed upon, add it to the Media to make designing the template little easier.
Change the Master Pages
Add sections (see Print context)

Once the template is ready, send it to Workflow (see Sending files to Workflow) and send the Workflow configuration to the server again.

Workflow configuration

To transform the project into a real solution, the Workflow configuration has to be adapted in two important respects.

The timing and manner of the production of forms will need to change. The Input task of the cotg_ts_deploy_form process must be adapted to the actual input data. You will also need to create an appropriate data mapping configuration for that data, which probably means saving the input as sample data first (see Saving input as sample data).
How the submitted data must be handled depends entirely on what they are used for. You may have to write them to a database and use them in an email, for example.
The cotg_ts_generate_report process demonstrates only a few of the things that you can do with the submitted data.
Tip: The Submitting Data with Web Forms Wizard shows how to use a data selection function - xmlget() - to read data from the request XML and how to store data in the Data Repository (see Sample Project: Submitting Data with Web Forms).

For general information about processes in Workflow see About Processes and Subprocesses, in the Online Help of Workflow.