Skip to main content

Help Docs

Custom report templates: Create

Judah Sali
  • Updated

The examples below show a Custom Report Template and the corresponding report generated by doForms. Although the example shows an Excel file result, the Custom Report Template can be used to generate either Excel or PDF files.

Custom Report Templates are created using Excel. If you know how to format Excel documents, then you are already an expert at building Custom Report Templates, which can include most formatting functions of Excel. But to understand how to build Custom Report Templates in doForms, you need to understand how the “data_name” property of the questions in your forms are used to “map” data values into a report.

{data_name} Tags

Data_names are unique identifiers that you set up in the Properties of each of the questions in your form. These unique identifiers are used throughout the doForms data collection and data management process to organize your data as shown below.

Data_Name property in the Build forms tab

Data_Name property in the View data tab

doForms uses these same data_names to relate (or “map”) the answers being collected in your form to cell locations in the Custom Report Template. For example, the Photo Survey form above contains a text question with the data_name “Subject_Description”. As the name implies, this is where a mobile user enters description text for their photo survey. Note how the Custom Report Template below utilizes the same data_name to specify where these values will be displayed in the report using the “{ }” brackets. This tells the doForms to “map” the answers to the Subject_Description to that particular cell. In the View Data screen above there is a completed record with the Subject_Description = “Dudley Gardens”. Note how this answer value is mapped to the completed report below.

If your form includes Repeatable section or Table containers, the format of the corresponding data_name tags is as follows: {data_name(i)}, where “i” is the repeat number. So in the Excel Template example above, the captions and images are specified as {Caption(i)} and {Image(i)} respectively. This is also the data_name format used to reference data in grid tables.

Create a template file automatically

Follow these steps to create a template with all data fields automatically mapped:

  1. Open the form using Build forms > Open.
  2. Select File > Create report template.
  3. An Excel file will be downloaded with all fields in the form mapped into a single worksheet.
  4. {Data_Name} tags can be deleted, removed and duplicated as desired.
  5. Follow steps 4 to 9 below to format and save the file.

Create a template file manually

Follow these steps to create a template file manually:

  1. Open Excel and start a new document.
  2. Add tabs/worksheets as desired into the Excel document to better organize your report.
  3. Specify which cells will contain which answers with the {Data_Name} tags.
  4. Add titles, captions and any other text into their own cells and format as desired.
  5. Add any desired graphics, such as logos, using the Excel “Insert” functions (do not use Excel "Smart Art").
  6. Add any desired page breaks using the Excel “Layout” functions.
  7. You can use merged cells to better control the size and position of any images (pictures and signatures).
  8. If your report includes numeric values, add any desired calculations or charts which employ these values.
  9. Use File > Save to save the file as Excel Workbook (xlsx) or Excel Macro-Enabled Workbook (xlsm).

Read more on how to format custom report templates.

Important notes

  • Certain features of Excel are not supported in the template. These include shape drawings, smart-art, certain chart types, and others. So test your templates carefully before deploying!
  • Only the formula functions listed here are supported. Even if a function is listed as supported, it may not evaluate exactly as it does in Excel.
  • In most cases, you may place multiple data_name tags in a single cell.
  • If you specify the data_name for a GPS location, both the latitude and longitude values will be written into the same cell but separated by a comma.
  • If your images look stretched, follow the instructions under Format images in this article.
  • If you want a link to an image instead of the image itself, include any additional text in the cell. For example: 
    {My_Image}
    will merge an image, but 
    My image: {My_Image}
    will merge a link to the image.
  • For audio and video files, a link to the corresponding media files will be merged.
  • To include a map that shows all GPS locations captured in a form, use the tag
    {@FinalGPSMap@}

Multiple projects and forms

Custom Report Templates can also be created and used to aggregate data from different forms into a single report. Note that this is for different forms, NOT for different data records of the same form. The format is as follows:

{"project"="Project_Name","form"="Form_Name","common-field"="Data_Name","field"="Data_Name"}
  • Project_Name is the name of the project that contains the data.
  • Form_Name is the name of the form that contains the data.
  • Data_Name is as previously described.
  • Common-field is the Data_Name value of the common field.

So for example, assume that I have two forms in a project named “Insurance” for which I want to aggregate the data from two different forms. The first form is named “Car”, which contains data about a customer’s car. The second form is named “House”, which contains data about a customer’s house. Both forms contain the common-field called “Customer_ID”, which is a unique numeric number to identify each customer. If we wish to create {…} tags in the aggregate report to display the customer’s {car_make} and {house_construction} we would use:

{"project"="Insurance","form"="Car","common-field"="Customer_ID","field"="car_make"}
{"project"="Insurance","form"="House","common-field"="Customer_ID","field"="house_construction"}

Note that you only need to use the long format of the {…} tag above if data is being read from a form that is different from the form that the report is being generated for. So for example, if we were generating reports for the House form, we could simply use the tag {house_construction}. But if we want to include data from the Car form in the report for the House form, then we would need to use the long format of the {…} tag. Similarly, if you wanted to use the same Excel Report Template for generating the same report for both the Car form and the House form, then you would need to use the long form of the {…} tags.

Common field restrictions

  • All values inside the {…} tag are case-sensitive and cannot contain any special characters, including \ / : * ? " > < | = { }.
  • Common-fields are restricted to text, numeric-integer, lookup and barcode question types.
  • Common-fields must be unique. So, in the example above, no two customers can have the same ”Customer_ID”.
  • No single form can contain more than one data record that has the same value of the common-field. So, in the example above, the Car form and the House form can NOT contain more than one record each with the same value for the “Customer_ID” field.
  • If any of the restrictions above are violated, an error will occur in the report that is generated.

Uploading the template

After the custom template has been created, follow these instructions to upload it to your doForms website: Manage custom report templates

Tip: After you upload a Custom Report Template, this template becomes available for use with any form in your account, provided that the form has exactly matching data name and common-field values for the {…} tags.

Related articles