Report references

Use report references to connect two or more reports in order to create a single, complex report as a combination of several simpler reports.

Report references are created and maintained in the Report JSON file.

Each report reference must contain the Report ID of the referenced report as well as all necessary Report Bindings. You can also specify the sorting order of the report references by setting an Order property for each referenced report.

The creation of reports consists of these general steps

  1. Retrieve the report template (Word, Excel, or HTML)
  2. Retrieve the report data in JSON format by using parameters obtained from WorkZone Client.
  3. Bind the report data to the report template.
  4. Include any document cover-pages or contents to the report.
  5. Create subreports from the report references.
  6. Generate parameters for the subreport from the report data (step 2) by using report by bindings.
  7. Repeat steps 1-5 for each subreport and parameters.

The properties of the report references

Report ID

The unique identification number of the report, which is expressed as a GUID. Each report has a unique alphanumeric number used to identify and locate the report in the system, and the Report ID is used to locate and connect to the specific report you want to reference.

Bindings

Report Bindings describe how to obtain the parameters for the subreport from the report data.

You must specify the data you want returned in the properties of the Bindings object.

For each property, you must specify a property name and a property value.

The property name is the parameter name in the referenced report, and the property value is a JPath to the parameter data of the main report.

Example: Case and Record report

In this example, the Case report is the main report and the Record report is the subreport.

For the Case report, the report data would be: { Title: ‘Case title’, FileRecords: [{ ID: 1 }, { ID: 2 }, { ID: 3 }] }

Since the Record report (the subreport) uses the RecordKey as a parameter, the report binding would be { RecordKey: ‘$.FileRecords[*].ID’ }.

This report binding will result in the three different parameters: RecordKey = 1, RecordKey = 2, and RecordKey = 3, which are used to create 3 Record subreports.

Note:

  • If report bindings are not required to connect the reports - for example, if the sub-report does not contain any parameters - the bindings should be specified as an empty JSON.
  • If the report bindings are incorrectly specified, a report will be created without subreports, because the connections required for the subreport would fail.

Limitations

Report references support single-value and multivalue parameters, but, if the subreport contains two or more single-value parameters, the entire report will fail.

  • Single-value parameters: If the subreport contains the RecordKey: ‘’ parameter (single-value parameter), the report binding will result in multiple subreport parameters: RecordKeys: [1], RecordKeys: [2], RecordKeys: [3].

    In the example above, the three ID properties will result in three RecordKey parameters, because the RecordKey is a single-value (non-array) parameter.
  • Multivalue parameters: If the subreport contains the RecordKeys: [] parameter (multivalue parameter), the report binding will result in only one subreport parameter RecordKeys: [1, 2, 3].
  • Single-value and Multivalue parameters: If the subreport contains RecordKey: ‘’ and RecordKeys: [] parameters (one single-value and other multivalues parameters), the report binding result in three subreport parameters:
    • RecordKey = 1 and RecordKeys: [1, 2, 3]
    • RecordKey = 2 and RecordKeys: [1, 2, 3]
    • RecordKey = 3 and RecordKeys: [1, 2, 3]
  • Two or more single-value parameters: If the subreport contains the RecordKey1: ‘’ and RecordKey2: ‘’ parameters (two or more single-value parameters), the report binding will fail, and an error will be thrown.

Order

The order determines in which sequence the referenced reports are added to the referencing (main) report. Any number between 0 and 99 can be used as input, and the referenced reports will thereafter be sorted in ascending order by this value, for example, 1, 5, 7 11, 13, etc.)

If the Order object is not included in the report references or is incorrect, reports will be added to the report references as they are found rather than in a specified order.

In this example, the Case report contains a report reference to the Record report. The Case report is the main report and the Record report is the subreport. The sorting order value is set as "1".

                    {
	"ReportId": "36a4cb00-2e92-4b5a-ac18-c1dbce60718d",
	"References": [
	  {
	    "ReportId": "2a66c0a3-f3c9-4729-a9d9-29dcf8edf381",
	    "Bindings": {
		"RecordKey": "$.Files.FileRecords[*].RecordKey"
	     },
	     "Order": 1
	}
     ],
     "Version": null,
     "EntityType": "File",...

The copy image is missing