Reports

In many business scenarios, it is necessary to generate dynamic documents whose content varies based on real-time data or provided parameters. Whether it’s sending personalized emails, generating automated attachments, filling out documents live, or producing contextual reports from a common template, the needs are diverse and must adapt to each situation. To meet these needs, Activator offers a powerful and flexible reporting system that allows users to design, structure, and produce dynamic documents on demand, while seamlessly integrating with other components of the platform.

✋Note: This component is based on the integration of TextControl software. This documentation focuses exclusively on its integration and use within ERP Activator. For further information on its general use, advanced functionalities or graphical aspects, please consult the official documentation available at https://www.textcontrol.com/docs/.

Creation

In Activator Admin, XML Schemas are located within the menu container, among the items listed under 📈Reporting. As shown at (1) on the image below.

✋NB: Make sure you are in the System Component main module.

After initiating the creation of the Report, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields

🔬After filling in the name and description fields, let's focus on the Meta Data field.

As for the Meta Data field, let's take a closer look at its JSON content in the next point.

JSON Meta Data Content

Below is the JSON structure used to create a report in Activator. This template defines essential elements such as the data source, content format, input parameters, accepted output formats and access rules. It forms the configuration basis for dynamically generating documents in various formats (PDF, DOCX, HTML, etc.) from JSON data.

{
    "schema": "",
    "dataSource": {
        "name": "",
        "type": "Model",
        "dataFormat": "Json"
    },
    "qrCodes": [],
    "images": [],
    "title": "ReportTitle",
    "description": "ReportDescription",
    "parameters": [
        {
            "name": "modelJson",
            "description": null,
            "dataType": "string",
            "required": false
        }
    ],
    "acceptedOuputFormats": [
        "doc",
        "docx",
        "pdf",
        "html"
    ],
    "ui": {
        "resourceName": "",
        "titleResKey": "",
        "descResKey": "",
        "icon": "fas fa-chart-line"
    },
    "tags": [],
    "settings": [],
    "accessControl": {
        "execute": {
            "roles": [
                "sys.everyone"
            ],
            "roleFilters": [],
            "optionStrict": false
        },
        "read": {
            "roles": [
                "sys.everyone"
            ],
            "roleFilters": [],
            "optionStrict": false
        },
        "modify": {
            "roles": [
                "sys.everyone"
            ],
            "roleFilters": [],
            "optionStrict": false
        },
        "delete": {
            "roles": [
                "sys.everyone"
            ],
            "roleFilters": [],
            "optionStrict": false
        }
    }
}

Meta Data Description

PROPERTY	REQUIRED	DEFAULLT VALUE	DESCRIPTION
`schema`	No	`""`	Field used to structure the data format used in the report. It is written in XML and is used to define a validation scheme for incoming data, guaranteeing its conformity to an expected structure.
`dataSource`	Yes	`{ "name": "", "type": "Model", "dataFormat": "Json" }`	Defines the origin of the data used to generate the document. Three types are possible: Type Model: Used when the data model will be sent directly to the report. `{ "name": "", // in this case, the 'name' field is left empty "type": "Model", "dataFormat": "Json" }` Type Function: Calls an existing storedFunction in Activator. `{ "name": "activatord.storedfunctions.functionName", // name of the storedFunction "type": "Function", "dataFormat": "Json" }` Type Query: Executes a storedQuery: `{ "name": "codelabs.storedqueries.storedQueryName", // name of the storedQuery "type": "Function", "dataFormat": "Json" }` 💡Tip: For reports that don't require a dataSource (the case of frozen reports), the developer should always put the JSON corresponding to the Model type in the dataSource field and then, when executing the report, send an empty {} object as the value of the `modelJson` parameter.
`parameters`	Yes	`[ { "name": "modelJson", "description": null, "dataType": "string", "required": false } ]`	List of parameters expected by the report. Two main cases: for parameters whose `dataSource` is Model: Activator imposes a `string` parameter named `modelJson`. Example: `{ "parameters": [ { "name": "modelJson", //name of parameter (must be modelJson) "description": null, //parameter description "dataType": "string", "required": false } ] }` For reports with a `dataSource` of type `Function` or `Query`, Activator requires that the parameters be defined and named exactly as specified in the component referenced by `dataSource.name`. This ensures that the reporting system can properly execute the `dataSource` and pass the expected values—arguments in the case of a `storedFunction`, or parameters in the case of a `storedQuery`—in accordance with their original definitions. Example: `{ "parameters": [ { "name": "paramName", //name of the parameter (no spaces, no hyphens, and starts with a letter) "description": null, //description of the parameter "dataType": "string", //can be one of this list [”guid”, ‘model’, ‘string’] "required": true //true or false } ] }`
`acceptedOuputFormats`	No	`[ "doc", "docx", "pdf", "html" ]`	This field lists the formats (extensions) through which this report can be read/generated. `{ "acceptedOutputFormats": [ "doc", // Microsoft Word format used for text documents. "docx", // Newer Word format, based on XML, offering better compatibility and advanced formatting options. "pdf", // Portable format designed to preserve document layout. "html" // Allows displaying structured content with text, images, and links. ] }`

🚨Note:
🔎 For an understanding of the other fields present in the report creation structure (such as ui, title, accessControl, etc.), please refer to the general metadata description page.

Reports API and UI

How To Execute a Report (API)

This API allows you to execute a report by name, passing it the expected parameters and the desired output format. The generated document is returned in base64 encoded content.

PROPERTY	DESCRIPTION
URL	`https://v2_reportingapi_dev.asmlogic.com/api/tenants/{tenantId}/reports/{reportName}/execute`
METHOD	POST
BODY	`{ "xmlData": "", // Empty string "format": "string", // The format of the document that will be returned after report execution. It must be included in the acceptedOutputFormats field of the metaData "parameters": [ { "name": "string", "value": "string" } ] }`
RESPONSE	`{ "payload": { "format": "string", // Format/extension of the document "base64Content": "string" // Base64 content of the document } }`

Description

PROPERTY	REQUIRED	DEFAULLT VALUE	DESCRIPTION
`xmlData`	Yes	`""` (empty)	XML content used to populate the document. It is mandatory but can remain empty (`""`) if not used.
`format`	Yes	`"pdf"` (or other accepted format), `"docx"`, `"html"`	The desired format of the generated document (must correspond to a value in `acceptedOutputFormats`).
`parameters`	No	`[]`	List of parameters required to run the report, defined according to the `dataSource` configuration. Each parameter must contain a `name` and a `value`.

How to send live report for editing on Activator Client

To enable a user to edit a report directly in the Activator Client interface, the following function can be used to trigger the opening of the document being edited:

$activator.documents.edit({
    id: fileId,        // File identifier (the document must already exist in an Activator record)
    container: Container, // Target component in which the document will be displayed
    title: 'xxx'       // Custom title if document is opened in a modal
});

PROPERTY	DESCRIPTION
`id`	Document identifier. It must point to an existing file saved in Activator, for example via a `file` or `document` type field.
`container`	Component or display area in which the document will be rendered (often a modal or dedicated view).
`title`	(Optional) Title displayed in the header if the document is opened in a modal window.

💡 Behavior Based on File Extension:
If the document has a .doc or .docx extension, it will be opened in edit mode using the integrated editor, allowing the user to modify and save the file in real time.
For other extensions (e.g., .pdf, .html, .xlsx), the file will be displayed in read-only mode, with no option for direct editing.

Conclusion

In summary, the Reports component in Activator provides a comprehensive solution for generating, editing, and distributing dynamic documents. Thanks to the integration of the TextControl engine, users can produce customized documents from templates based on real-time data and use them for both viewing and live editing directly within the Activator interface. This system streamlines document-related communication (letters, reports, etc.), enhances productivity, and integrates seamlessly into business workflows. To further enrich the user experience, the available APIs, dynamic parameters, and multiple output formats offer great flexibility to meet a wide range of needs.