Report Execution Guidelines

BI reports are created and executed using one of three methods:

• The BI's Designer module

• Using Fabric's Jobs Mechanism

• Using Deep Link

The sections below describe these options.

Reports Generation Using the Designer Module

Generate the report in the Designer module using the icon in the Report Tree or the Run button in the report editor.

You can set up various report generation options using the Report Options (applicable for Advance Reports) by clicking Advanced > General Options:

For example, you can define the report behavior when there is no qualified data for a report. This is done by setting the No Data Qualify Display Mode argument to one of the following options:

• Show Message:
  • When running a report via the BI's Designer, No Data Qualified message is displayed.
  • When a report is generated via the Fabric Job, the extract file is not created.
• Show Report:
  • When running a report via the BI's Designer, static data of the report (such as column titles) is displayed.
  • When a report is generated via the Fabric Job, the extract file is created and it includes static data only.

Reports Generation Using the Fabric Jobs Mechanism

Generate the report using the STARTJOB command using the following syntax:

startjob GENERATE_BI NAME='<name>' [UID='<uid>'] [AFFINITY='<affinity>'] <ARGS='<args>'> [EXEC_INTERVAL='<execInterval>'];

Set the job parameters as follows:

• Use the GENERATE_BI as the job type.

• Set the NAME to be the full path from the root folder to the report. In the below example, the NAME is 'Public/Reports/Subsc_List'.

  

  • Note that 'My Reports' folder is intended for local work only and is not exposed via the REST API. As a result, the reports defined within 'My Reports' folder cannot be generated by a job.

• Populate all the job input parameters inside the ARGS as follows:

  • OUTPUT_NAME - extract file name. For example, you can concatenate parameters such as IID or datetime to the original report name or even provide a completely different name for the extract file.
  • TYPE - export file format can be one of the following: csv, excel, pdf, rtf.
  • DESTINATION - the name of the Fabric interface where the export file should be placed. It can be either a Local File System or an SFTP interface type.
  • SESSION_PARAMS - array of the session parameters used by the report. Only the Id (name) and the Value attributes of the parameter are mandatory. The other attributes (such as Type) are optional.

• The following are optional ARGS:

  • FILTER (optional) - parameters to filter the report's results. Note that this is a run-time filter and it is not related to the built-in filter which is added as part of report creation (whose value is set using the session parameters). The filter parameters are sent as a JSON object. Only the FilterText and the Values parameters are required. The FilterText should include a data object and a column on which to apply the filter. Operator is set to 0 (EqualTo) by default.
  • SORT (optional) - parameters to sort the report's results. Note that this is a run-time sort and it is not related to the built-in sort which is added as part of report creation. The sort parameters are sent as a JSON object. The fields EntityName and ColumnName (data object and column to sort on) are required. The AscendingFlag is optional and set to false by default.

Click to get more information about the GetExecute REST API and the valid values of the data types of Filter and Sort structures.

Example of GENERATE_BI Job with Session Parameter

startjob GENERATE_BI NAME='Public/Reports/Subsc_List' ARGS='{"OUTPUT_NAME":"Subscribers_list_20211101_v120", "TYPE":"csv", "DESTINATION":"MyLocalFS", "SESSION_PARAMS": "[{\"Id\":\"customer_id\", \"Value\":\"120\" }]"}';

Note that SESSION_PARAMS is a mandatory parameter for all reports based on Fabric LU data. Such reports require at least one session parameter definition - to pass the IID of the LU's root table to perform GET INSTANCE command. When the report is based on PostgreSQL or Oracle data source, sending SESSION_PARAMS is optional.

Example of GENERATE_BI Job with a run-time filter

startjob GENERATE_BI name='Public/task_exe_test1' ARGS='{"OUTPUT_NAME":"task_exe_20211101", "TYPE":"csv", "DESTINATION":"LocalListener", "FILTER":"{\"FilterText\":\"TASK_EXECUTION_ENTITIES_9.LU_NAME\", \"Values\":[\"Billing\"] }" }';

Example of GENERATE_BI Job with a run-time sort

startjob GENERATE_BI name='ForReporting/Load/TDM_3_4_TEST' ARGS='{"OUTPUT_NAME":"TDM_20211101", "TYPE":"csv", "DESTINATION":"localFileSystem", "SORT":"{\"EntityName\":\"TASK_EXECUTION_ENTITIES_9\",\"ColumnName\":\"TARGET_ENTITY_ID\", \"AscendingFlag\":true}" }';

Reports and Dashboards Generation Using Deep Link

Generate the report or a dashboard using a direct link to it in a separate browser, as follows:

<host>:<port>/app/BI/<report path in BI>

Where report path in BI contains the full path of the report including the Root folder and all folders up to the report name.

For example, the deep link to the report mig_rep under the folder test_designer running on a localhost is:

http://localhost:3213/app/BI/test_designer/mig_rep

When a report or a dashboard name is unique, it is sufficient to provide the name only and skip the full path. For example, the deep link to the Dashbrd-v0 dashboard under the folder DemoProj can be:

http://localhost:3213/app/BI/Dashbrd-v0

Starting from V6.5.4, report generation via a direct link is parameterized. This means you can send session parameters and a run-time filter. The syntax is:

<host>:<port>/app/BI/<report path in BI>?pkey1=pval1&pkey2=pval2&k2filters=[encoded filter]

Where pkey1, pkey2, etc. are names of the session parameters used by the report and, pval1, pval2, etc. respectively are the values of these parameters.

k2filters is a run-time filter applied on the report results. It is not applicable for dashboards. Follow these steps to create a k2filters part of the URL:

1. Prepare the filter object using the following syntax:

   k2filters=[{ "FilterText":table_name.column_name,"Values":[values]}]

For example:

   [{ "FilterText": "ADDRESS.CITY", "Values": ["Berlin"] }]

Note that the default operator is EqualTo. To use a different operator, add it to the filter as follows:

   [{ "FilterText": "table_name.column_name", "Operator": "NotEqualTo", "Values": [values] }]

2. Encode the whole filter message including the brackets using any URL Decoder tool, such as: https://meyerweb.com/eric/tools/dencoder/.

   The encoded string looks like this:

   %5B%7B%20%22FilterText%22%3A%20%22ADDRESS.CITY%22%2C%20%22Values%22%3A%20%5B%22Berlin%22%5D%20%7D%5D

3. Copy the encoded string to use it in the URL.

Example of a Link with Session Parameter

http://localhost:3213/app/BI/subsc_list_per_cust?customer_id=345

Example of a Link with a Run-Time Filter

First, prepare the filter, for example when the report results should be filtered by one of its columns, the syntax is as follows:

[{ "FilterText": "SUBSCRIBER_REF.SUBSCRIBER_DESC", "Values": ["SOHO"] }]

Then encode the filter and include it in the full URL as follows:

http://localhost:3213/app/BI/subsc_list_per_cust?k2filters=%5B%7B%20%22FilterText%22%3A%20%22SUBSCRIBER_REF.SUBSCRIBER_DESC%22%2C%20%22Values%22%3A%20%5B%22SOHO%22%5D%20%7D%5D

Click to get more information about the JavaScript API Filter data type valid values.