Create the Report JSON file
The Report JSON file is a JSON file that contains all information necessary for successful execution of the report and is used to update report data in the WorkZone database.
The WorkZone PDF Installer program uses the Report JSON file to install custom reports when the Configure Database target option is selected during the PDF installation. You can also manually update existing reports and add new ones to the WorkZone database, but it is not recommended.
After you have created the OData quereies, you must create a Report JSON file. As JSON files are normal text files, you can use any text-editor program to create and edit the Report JSON file.
The Report JSON file contents
The Report JSON file contains the following information
Parameter | Type, Length | Description | Required |
---|---|---|---|
ReportId |
String, 38 |
A unique identifier, i.e. a GUID. |
|
Version |
Number, 12 |
The version number of the report. The format is 8 to 10 ordinal numbers: for example, xxxxxxxxxx. The following algorithm is used for forming a version number: major+minor +build+revision (xx.xx.xxxxx.xx). If "minor" and "revision" parts contain 0, 0 may be omitted: 0x = x. |
|
EntityType |
String, 30 |
The entity type for which the report is intended, for example, |
|
Localizations |
String, 255 |
The name, description, culture name, and file name (one or several localizations are allowed). |
|
OdataQueries |
String, 2000 |
The OData queries used by the Report JSON. |
|
Parameters |
String, 2000 |
JSON with parameters that will pass into the OData. |
|
Caption |
String, 255 |
In reports, the caption value can be used in the following context:
In Report JSON, you must specify a path to the caption value. See How to compose a JSON Path.
Example: Report JSON: A path in Report JSON: Caption value: |
|
DefaultOutput |
String, 12 |
The file type of the report requested by WorkZone Client. Use the file extension in the upper-case format, for example, PDF, XLSX, DOCX, PBIX, etc. |
|
AccessCode |
|
The read rights on report (see WorkZone Client permissions documentation). |
|
UpdateCode |
|
Specifies Update rights on report (see WorkZone Client permissions documentation). |
|
System |
|
Specifies type of the report: True – standard (deployed as a part of installation); False – customized for the customer's needs. |
|
Default |
|
Defines which report of the same EntityType WorkZone Client will use as the default one. |
|
The OData query section in the Report JSON file
The OData query section of the Report JSON file must contain the following:
- A root (or main) element
- A tree structure of elements, from the root entity to deeper related entities that correspond to parts of the resource path in the OData URL.
- A #Query property under each node with a value that either corresponds to the query options in OData URL (starts from “?”) or contains the empty value “” if there are no query options for current resource.
If you want to retrieve an array of objects, you must encompass the objects in question with square brackets ( [ ] ).
Parameters passed to the Report JSON must be prefixed with @.
Example: OData section of the Report JSON file
{
"Records": [
{
"#Query":"('@RecordKeys')?$select=File/FileNo,
File/Title,RecordNo,RecordKey,Title,RecordType_Summary&$expand=File",
"SupplementaryDocuments": [
{
"#Query": "?$select=RecordKey,Title"
}
]
}
]
}
Additional examples of OData queries can be seen in the Standard Reports in the Reports table (OData_queries column)
Tip:
- Do not include the same fields for the same entities in different places in the OData section.
For example, if you specify a field under a branch, make sure that the same field does not appear for parent elements when using theexpand
command. - Check the syntax of the JSON file prior to executing the file. You can use various internet sources for the syntax check, for example, http://jsoneditoronline.org/.
Report JSON example
The following is an example of a Report JSON file. There are two custom report Word templates:
- DocListSuppDocs_En.docx (English version)
- DocListSuppDocs_Da.docx (Danish version)
Note the “Parameters” section
Tip: Remember to use hard brackets ( [] ) for multiple values. If you expect to only pass single values, use normal brackets ( {} ), according to standard JSON rules.
{
"ReportId": "5c7f89d4-a0db-4365-bc08-48ffa7f193b0",
"Version": null,
"EntityType": "Records",
"Localizations": [
{
"Name": "DocListSuppDocs",
"Description": "A document list with supplementary documents",
"CultureName": "en-GB",
"FileName": "DocListSuppDocs_En.docx"
},
{
"Name": "DocListSuppDocs",
"Description": "En dokumentliste med bilag",
"CultureName": "da-DK",
"FileName": "DocListSuppDocs_Da.docx"
}
],
"ODataQueries": {
"Records": [
{
"#Query": "('@RecordKeys')?$select=File/FileNo,File/Title,
RecordNo,RecordKey,Title,RecordType_Summary&$expand=File",
"SupplementaryDocuments": [
{
"#Query": "?$select=RecordKey,Title"
}
]
}
]
},
"Parameters": {
"RecordKeys": []
},
"DefaultOutput": "PDF",
"AccessCode": null,
"UpdateCode": "CONFIGADM",
"System": true,
"Default": true
}
The following report JSON examples are taken from the report JSON files included in the WorkZone suite installation and are therefore available to all users and not customized for any specific customer.
The following example of a report JSON file is taken from the Agenda report which is installed with the WorkZone suite.
{
"ReportId": "297ecb46-f2eb-49cd-b213-51146b225d3f",
"Version": null,
"EntityType": "Agenda",
"Localizations": [
{
"Name": "Agenda",
"Description": "An agenda with documents list",
"CultureName": "en-GB",
"FileName": "Agenda_En.docx"
},
{
"Name": "Dagsorden",
"Description": "Dagsorden med documentliste",
"CultureName": "da-DK",
"FileName": "Agenda_Da.docx"
}
],
"ODataQueries": {
"FileAgendas": {
"#Query": "('@AgendaKey')?$select=SortGroup",
"FileRef": {
"#Query": "?$expand=Text&$select=Title,Text/Text",
"Records":
[
{
"#Query": "?$expand=Record&$select=Record/RecordKey,Record/Title,
Record/RecordType_Summary,Record/Extension,Record/State_Value"
}
]
}
}
},
"Parameters": { "AgendaKey": "" },
"Caption": "$.FileAgendas.FileRef.Title",
"DefaultOutput": "PDF",
"AccessCode": null,
"UpdateCode": "CONFIGADM",
"System": true,
"Default": true
}
The following example of a report JSON file is taken from the Case report which is installed with the WorkZone suite.
{
"ReportId": "36a4cb00-2e92-4b5a-ac18-c1dbce60718d",
"Version": null,
"EntityType": "File",
"Localizations": [
{
"Name": "Case",
"Description": "A case with parties and documents",
"CultureName": "en-GB",
"FileName": "Case_En.docx"
},
{
"Name": "Sag",
"Description": "En sag med parter og dokumenter",
"CultureName": "da-DK",
"FileName": "Case_Da.docx"
}
],
"ODataQueries": {
"Files": {
"#Query": "('@FileKey')?$expand=Parties/Name",
"FileRecords": {
"#Query": "('@FileKey')?$expand=Parties/Name",
"FileRecords":
[
{
"#Query": "('@RecordKeys')?$expand=Parties/Name&$filter=Pax ne 'A'",
"SupplementaryDocuments": [
{
"#Query": "?$expand=Parties/Name"
}
]
}
]
}
},
"Parameters": {
"FileKey": "",
"RecordKeys": [ ]
},
"Caption": "$.Files.Summary",
"DefaultOutput": "PDF",
"AccessCode": null,
"UpdateCode": "CONFIGADM",
"System": true,
"Default": true
}