HTML Reports



Overview

HTML based reporting enables you to design your service report template using HTML and Javascript and use this template across our three mobile applications, to generate a service report for single or multiple activities and capture the customers signature–completely offline.


How it Works

Sequence Description
1. Design your template as an HTML file and upload it to our administrator console. You can use our sample template as a starting point.
2. In Admin, set up a workflow step with the screen type “ Report” . When the technician navigates to this step, they will be prompted to select the template they would like to use. Single or Group based checkout are supported.
3. Synchronize the mobile device so the template is downloaded and can be used offline.
4. A report can be generated and presented to the user, with the option to sign directly on the report itself.
5. The report is then converted to a PDF document and attached to the service checkout created.

Technical Details

HTML reports are based on two primary components:

  1. An HTML file (which renders the report using HTML markup): this file is created by you, the customer, and uploaded to the cloud as described in the previous chapter
  2. A data file (which contains the data to be rendered in the HTML): this file is created by the mobile applications each time you preview or generate an HTML report.

Whenever an HTML report is previewed or generated in a mobile app, the following sequence of events occurs:

  1. The mobile app unpacks the HTML report template zip file to a temporary location
  2. The mobile apps creates a data file (called data.js) to the same location, containing all data the HTML report has access to and can display
  3. The mobile app opens the template.html file from the temporary location and displays it in an embedded web view

ATTENTION: Please note that the app DOES NOT link the data from the data file to the HTML page, it only exports the data and opens the template.html page. It is therefore the responsibility of the template.html page to read the contents of the data.js file and render the HTML accordingly.


Sample HTML Report

To make it easy for you to get started with HTML reports, we have created a sample HTML report which is based on a Service Call and its related data. When the template.html file from this report is opened and a corresponding data.js file exists in the same location, the report will read the contents of data.js and render a relatively complex report in HTML.

The sample report demonstrates the following functionalities:

  • Support for multiple activities with data aggregation & summaries, plus individual activities details
  • Tables (including headers, footers with aggregation, data grouping)
  • Attachments
  • Signatures
  • Data validation (with HTML highlight and prevention of report generation on fail)
  • Checklists (all elements including tables, series and tables inside series, attachments, pickers etc)
  • Localization (translations, local date/time/numeric formatting etc)

The sample HTML report should work out-of-the-box and serve as a starting point for you to customize it to your needs. To that end technical knowledge of HTML, Javascript as well as HandlebarsJS is needed. The report files template.html and template.js contain detailed comments explaining the approach taken, the architectural overview of the different pieces and how they work together as well as detailed line-by-line explanations of the code.

HTML Report

Note: the sample HTML report is just one way of rendering an HTML report based on the data exported by the application and you are free to customize it further or take a completely different approach.

Regardless of whether you use the sample HTML report or you would like to go for a different approach and implement your own, it is very useful while implementing the report to be able to see the data.js generated for your report. Although the structure of the generated data and the available fields are defined in the subsequent chapters, having the actual data for a specific Service Call on hand can save a lot of time when implementing or modifying an HTML report.

To this end we provide another sample report which will simply display this data in several textarea fields. To use this report, use the process of uploading it to the cloud as described above, then choose it from the mobile app and generate it. Once generated you can simply copy/paste the report data out of the textarea fields and analyze it in your favorite text editor.

JSON Report Template


JSON Serialization

The mobile applications export the HTML report data to the data.js file mentioned in the previous chapter. Although a javascript file, the data is exported in a JSON-like format. The file is a javascript file because it will expose in the global javascript scope several variables containing the report data, which can then be easily accessed from the HTML generating code. These variables are:

Variable Description
serviceCall Contains data regarding the service call and it’s underlying items.
currentUser Contains data regarding the current user logged in in the application.
companyInfo Contains data regarding the current selected company.
reportInfo Contains data regarding the current report, such as the report language for example.

Report Validation

Regardless of how you decide to implement the HTML report (starting from our provided sample or roll your own), it is possible to implement report validation. This means that you can control when and if the user is able to generate the final report in the mobile app, perhaps depending on some of his input in the HTML report. One such use case is to only allow the user to generate the final report if it has been signed in the HTML.

The validation mechanism works as follows:

  • In the mobile apps, when the user tries to generate the final report, the app will call a function named “validateReport” that must exist in the HTML report’s global scope.
  • If this function doesn’t exist, the app will consider no validation is needed and the report will be generated.
  • If the function exists, it must return an object with two properties:
    • isValid: true or false. If false, the mobile app will not generate the final report.
    • validationFailedReasons: string array. If isValid is false, then the app will display the strings in this array as a validation failed message to the user so he can correct the mistakes and try again.

In our sample HTML report you can find an example for this function which implements validation for signature, while also highlighting the signature fields in red if they are missing.


Setup and Configuration

Admin

User Rights

To upload report templates, you must have access to the Admin console.


Company Settings

The following company setting must be enabled for the HTML Reports functionality to be available on available:

Company Setting Required Value Impact
CoreSystems.Assignment.IsWorkflowDriven true By enabling, workflow steps (including the Report workflow step) will now be visible in the mobile application.

Permissions

Create HTML Report in Admin

In order to create an HTML report template in Admin, the report template permission must be configured as follows:

Object CRUD Method Operation Permissions Impact
Report Template Read All The assigned user group will be able to view ALL report templates.
Report Template Create All The assigned user group will be able to create ALL report templates.

Create HTML Report on Mobile

In order to view all HTML report templates and generate an HTML report in the mobile application, the report template permission must be configured as follows:

Object CRUD Method Operation Permissions Impact
Report Template Read All The assigned user group will be able to view ALL report templates.
Report Template Create OWN The assigned user group will be able to create own report templates.

Admin Console

The HTML file, with its contents, should be uploaded as a ZIP file in Admin

Reports > Report Templates > create new template and select HTML report type

Figure 1: Create a new report

You can define the supported languages which can be used on the mobile to switch between the embedded translations strings.

Object Type defines the objects that are used in the template.

After creating the report you can upload the zip file containing the HTML template and any translation files or images to be used in the report.

Figure 2: Upload ZIP file containing the report


Workflow steps

The HTML template selection step is displayed by navigating to the “Report” workflow step. This step should be defined in admin where the service workflows are set up.

Note: You can not use the Checkout workflow step and the report workflow step in the same service workflow, these steps conflict with each other and will cause a logic loop on the devices.

Figure 3: Service workflow with the Report step


Mobile

When the technician navigates to this screen , they will be promoted to select the template they would like to use. Here they can also enter details about the customer that will sign the report and this information will accessible in the JSON data.

Figure 4: Report template selection screen on mobile


Signatures

Unlike the previous Jasper reports, signatures are no longer treated as an attachment.

Where there is a need to capture a signature, either from customers or technicians, a drawable canvas element will be included in the HTML report template.

Single or Group reports

  1. Same permissions are to be used in current checkout process described here
  2. ServiceCheckout determines if it’s a single group or finished work checkout.
  3. If it’s a single checkout, then only the current activity is used in the report.
  4. If it’s a group checkout, then the user can select multiple activities for the report, if the meet the checkout conditions (the work is finished).

Closing Activities

Please note the following conditions:

  • If after the Report the step they define only the Close step, then the activity will be automatically closed after generating the report PDF (without the need for the user to press the close or done button).
  • If after the Report step there is another step defined (e.g Travel) and the step there is not close, then the activity will not be closed after the report is generated, the user has to first go to travel step and then manually to close
    • Example: Accept - Work - Report - Close.
  • Activity will be closed when the PDF report is generate
    • Example: Accept - Work - Report - Travel - Close.
  • Activity will be closed when the close step is triggered, the PDF report is still generated after the reported step is complete.
  • Close step here represents the old hardcoded “close” or the new ScreenType “Close”.
  • If there is any step after the close, then it will be ignored.

Example steps: New - Travel - WorkItems - Report

If the user navigates to the “Report” step and then cancels the checkout and goes back to the activity details, the activity will revert to the previous step (so they see the next available step as - “Report” and any other alternative steps available).