FastReport reports

Easy

Attention. The FastReport functionality will be retired in Creatio version 8.0.3.

The Report setup section enables users to create reports using the Creatio tools and configure such reports using the FastReport Designer.

Attention. You can set up custom reports using Creatio version 7.15.3 and up.

To open the Report setup section:

  1. Open the System Designer by clicking scr_Settings_button.png.
  2. In the System setup block, select the Report setup link.
scr_ReportSetup_path.gif

The Report setup section interface 

The report setup section page will open. The page contains the following elements:

  • The Close button – closes the report setup section.
  • The New report button – selects the type of report to add (FastReport or MS Word).
  • The Delete button – removes the selected report from the section list. The button appears when you select an existing report.
  • The Search string – performs the search of a report by name.
scr_ReportSetup_startpage.png

Selecting the FastReport option, a report setup page will open. The page contains several functional areas with the tools to create and set up a report.

scr_ReportDesigner.png

Toolbar 

The Toolbar (1) has the following buttons:

  • Apply – saves the created report.
  • Cancel – closes the report setup without saving the changes.

The setup area of display parameters 

The setup area of display parameters (2) includes the following elements:

  • The Report title field – sets the name for the report. Depending on your settings, the report name will display in the menu of the Print button in a section or on a record page, as well as in the Reports button drop-down list of a section in the dashboard view.
  • The Section field – a drop-down list of sections that you can select for generating your report.
  • The Show on the section list review checkbox – determines whether the report displays in the drop-down list of the Print button in a section.
  • The Show on the section record page checkbox – determines whether the report displays in the drop-down list of the Print button on a page of a section record.
  • The Show in the section analytics view checkbox – determines whether the report displays in the drop-down list of the Reports button in the section dashboard view. In this case, you can use a custom page of additional filtering. Set the filtering parameters using a schema. Specify this schema in the Filter page field. To set the filtering parameters, select a report (click the Reports button in the section dashboard view and select the report from the drop-down list).
  • The Filter page field – a drop-down list of pages with filters. The field only appears if you select the Show in the section analytics view checkbox. You can select the SimpleReportFilterPage standard filtering page or create a custom filtering page and specify the BaseReportFilterPage schema as its parent schema.

Note. Standard filters are implemented in the SimpleReportFilterPage filtering page schema. After you select a report from the drop-down list of the Reports button in the section dashboard view, you will see a page where you can specify the following report parameters:

  • Selected records.
  • Filtered records in list.
  • All records in list.

The information Note area 

The Note area (3) contains a short instruction on how to set up the reports.

Working area 

Use the working area of the report setup page (4) to set up your report. The report setup working area contains the flowing elements:

  • The Specify data sources for the report block – use it to enter the sources of data for your report and set localizable strings in the json format.
  • The Download file with data sources to design a report in the FastReport Designer – use it to download the report template (a *.frx file). To do this, click the Download file button.
  • The Import a file with the report template block – use it to upload the template to Creatio after you set it up using FastReport. To do this, click the Upload file button.

Algorithm of creating a report 

  1. Install the FastReport Designer (you only perform it once).
  2. Create a report in the Report setup section.
  3. Specify the data sources for the report.
  4. Create a report data provider that will implement processing of data logic.
  5. Download the file with data sources and set it up in the FastReport Designer.
  6. Upload the configured report template to Creatio.

Installing the FastReport Designer 

Note. You will need the following components to work with the Report Designer:

  1. Windows OS.
  2. 64-bit Microsoft .Net Framework 4.7.2.

To install the FastReport Designer, use the following link and download the zip archive.

Creating a new report 

To create a new report:

  1. Open the System Designer by clicking scr_Settings_button.png. In the [System setup] block, click the Report setup link.
  2. Click New report —>FastReport.
  3. In the parameter setup area (2) specify the report title, the section for the report, the display parameters.

Specifying the report data sources 

In the Specify data sources for the report block of the working area (4), specify the list of objects, their columns and connections that will be used to receive data. Specify the localizable strings if needed. Use the JSON format. Example of providing a data source

Example of providing a data source
{
    // Name of the data provider class.
    "ProviderName": "YourProviderName",
    // Table structure for the report template.
    "Schemas": {
        // Name of the database table or virtual tables, whose columns need to be added to the report.
        "TableName1": {
            // Name of the column that needs to be added to the report.
            "ColumnName1": {
                // Column data type.
                "DataValueType": DataValueType1
            },
            "ColumnName2": {
                "DataValueType": DataValueType2
            }
        },
        "TableName2": {
            "ColumnName1": {
                "DataValueType": DataValueType1
            },
            "ColumnName2": {
                "DataValueType": DataValueType2
            }
        },
        // Report localizable strings.
        "LocalizableStrings": {
            // Name of the report localizable string.
            "LocalizableString1": {
                // Data type of the localizable string.
                "DataValueType": 1
            },
            "LocalizableString2": {
                "DataValueType": 1
            }
        }
    }
}

Note. The DataValueType parameter contains a value from the Terrasoft.core.enums.DataValueType enumeration.

Click Apply in the toolbar (1) to save the data.

Creating a report data provider 

The report data provider is a custom class written in C#. To create the provider:

  1. In the custom development package, create a Source Code type schema.
  2. Create a service class in the schema source code. Use the Terrasoft.Configuration namespace or any of its embedded namespaces. Mark the class with the DefaultBinding attribute containing the necessary parameters. The service class must be the inheritor of Terrasoft.Configuration.Reporting.FastReport.IFastReportDataSourceDataProvider.
  3. Add the GetLocalizableStrings(UserConnection) method implementation to the class. The method implements localization of the report fields.
  4. Add the ExtractFilterFromParameters(UserConnection, Guid, IReadOnlyDictionary) method implementation to the class. This method is responsible for adding the interface filters.
  5. Add the GetData(UserConnection, IReadOnlyDictionary) method implementation to the class. This method must return a Task<ReportDataDictionary> type value. Describe the logic of receiving the report data in the method.
  6. Publish the source code schema.
Example of implementing the report data processing logic
namespace Terrasoft.Configuration
{
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Terrasoft.Configuration.Reporting.FastReport;
    using Terrasoft.Core;
    using Terrasoft.Core.Factories;
    
    // Name of the data provider class for the report, whose logic needs to be implemented.
    [DefaultBinding(typeof(IFastReportDataSourceDataProvider), Name = "YourProviderName")]
    public class YourProviderName : IFastReportDataSourceDataProvider
    {
        // The code for implementing the logic of getting data for the report.
        
        // Localization of the report strings.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetLocalizableStrings(UserConnection userConnection) {
            var localizableStrings = _localizableStringNames.ToDictionary(
                x => x,
                x => (object)(new LocalizableString(userConnection.ResourceStorage, _resourceManagerName, $"LocalizableStrings.{x}.Value")).Value);
            return new[] { localizableStrings };
        }
        
        // Adding the interface filters.
        private IEntitySchemaQueryFilterItem ExtractFilterFromParameters(UserConnection userConnection, Guid entitySchemaUId,
                IReadOnlyDictionary<string, object> parameters) {
            var managerItem = userConnection.EntitySchemaManager.GetItemByUId(entitySchemaUId);
            return parameters.ExtractEsqFilterFromReportParameters(userConnection, managerItem.Name) ?? throw new Exception();
        }
        
        // Adding data to the report.
        public Task<ReportDataDictionary> GetData(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {            
            
        }
    }
}

Setting up templates in the FastReport Designer 

Download the file with data sources. Click the Download file button in the Download file with data sources to design a report in the FastReport Designer block (4) of the working area. The file must have the *.frx extension.

Double click the downloaded file to open it in FastReport and configure the template layout. Learn more about configuring the template in the FastReport documentation.

Note. The file saves the structure of the data source implemented in the Report setup section.

Attention. The FastReport Designer is a third party application. The template preview function is not available.

Uploading the configured template to Creatio 

Click the Upload template button in the Import a file with the report template block (4) of the working area to upload the prepared template to Creatio. After you upload the template, you can generate a report in the section dashboard view or on a record page. You can specify this in the parameter setup area (2). The generated report will be saved in the pdf format.

Attention. The Print and Reports buttons display in corresponding sections and on record pages if there is at least one report configured and published for a specific section.

Multilingual interface elements in reports 

The Translations section in the System Designer enables setting the values of interface elements for a multilingual report. To find the previously localized strings of the report, use the Configuration:SchemaName key (e.g., Configuration:UsrContactDataSourceCode). You can find a report field using the following key: Configuration:SchemaName:FieldName (e.g., Configuration:UsrContactDataSourceCode:LocalizableStrings.ReportTitle.Value).

If the Show on the section list review and Show on the section record page checkboxes are selected, translate the report title. You can find the report title using the following key: Configuration: SchemaName:Caption (e.g., Configuration:UsrContactDataSourceCode:Caption). If the Show in the section analytics view checkbox (2) is selected, translate the report title. You can find the report title using the following key: Data:SysModuleAnalyticsReport.Caption:FieldIdentificator (e.g., Data:SysModuleAnalyticsReport.Caption:d52e8b78-772b-77ee-3394-bdb3616d859a).

Learn more about working with the Translations section in the article.

Transferring the package to another development environment 

To transfer the package with the report to another environment, go to the Configuration section -> the Data tab and bind the data of the following elements:

  • FastReportTemplate_ReportName – the report template. To bind it, use the template Id from the dbo.FastReportTemplate database table.
  • FastReportDataSource_ReportName – the source of the report data. To bind it, use the source Id from the dbo.FastReportDataSource database table.
  • SysModuleReport_ReportName – the report. To bind it, use the report Id from the dbo.SysModuleReport database table.

Note. You can view the record Id in the database table even if you do not have access to the database. To do this, display the Id system column in the window of binding data to packages.

Create the FastReport report
Medium

Attention. The FastReport functionality will be retired in Creatio version 8.0.3.

Example. Create a "Contact Data” base report that would display the following information about the contacts:

  • Full name;
  • Birthday;
  • Gender;
  • Account.

Example implementation algorithm 

1. Set up the report display parameters 

Specify the following values for the created report in the parameter setup area (2):

  • Report title – "Contact Data”;
  • Section – "Contacts”;
  • Show in section – select the checkbox;
  • Show in card – select the checkbox;
  • Show in the section analytics view – select the checkbox;
  • Filter pageSimpleReportFilterPage.

Note. SimpleReportFilterPage – a client schema that implements standard simple filters.

The report setup page
scr_ReportDesigner.png
Setting up the report display parameters
scr_Parameters_example.png

2. Specify the data sources 

In the Specify data sources for the report block of the working area (4), add the code below:

ContactDataProvider
{
    // Name of the data provider class.
    "ProviderName": "ContactDataProvider",
    "Schemas": {
        "ContactData": {
            "Full name": {"DataValueType": 1},
            "Birthday": {"DataValueType": 1},
            "Gender": {"DataValueType": 1},
            "Account": {"DataValueType": 1}
        },
        // Added for localization.
        "LocalizableStrings": {
            "ReportTitle": {"DataValueType": 1},
            "FullNameLabel": {"DataValueType": 1},
            "BirthdayLabel": {"DataValueType": 1},
            "GenderLabel": {"DataValueType": 1},
            "AccountLabel": {"DataValueType": 1}
        }
    }
}

Click Apply to save and apply the changes (1).

3. Create the report data provider 

Go to the Advanced settings section -> Configuration -> Custom package -> the Schemas tab. Click Add —> Source Code.

Specify the following parameters for the created object schema:

  • Title – "Contact Data";
  • Name – "UsrContactDataSourceCode".
scr_PackageSettings_example.png

The complete source code of the module is available below:

ContactDataProvider
namespace Terrasoft.Configuration
{
    using System;
    using System.Collections.Generic;
    using System.Collections.ObjectModel;
    using System.Linq;
    using System.Threading.Tasks;
    using Terrasoft.Common;
    using Terrasoft.Configuration.Reporting.FastReport;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;
    using Terrasoft.Core.Factories;
    using Terrasoft.Nui.ServiceModel.Extensions;
    using EntitySchema = Terrasoft.Core.Entities.EntitySchema;
    using EntitySchemaColumn = Terrasoft.Core.Entities.EntitySchemaColumn;

    // Name of the data provider class for the report, whose logic needs to be implemented.
    [DefaultBinding(typeof(IFastReportDataSourceDataProvider), Name = "ContactDataProvider")]
    public class ContactDataProvider : IFastReportDataSourceDataProvider
    {

        private Guid _entitySchemaUId = new Guid("16BE3651-8FE2-4159-8DD0-A803D4683DD3");
        // Name of the source code schema.
        private readonly string _resourceManagerName = "UsrContactDataSourceCode";
        private readonly string[] _localizableStringNames = new[] {
            "ReportTitle",
            "FullNameLabel",
            "BirthdayLabel",
            "GenderLabel",
            "AccountLabel"
        };

        // Populating the report columns.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetContactData(
            UserConnection userConnection,
            Guid entitySchemaUId,
            IEntitySchemaQueryFilterItem filter) {
                // Getting the object schema.
                var entitySchema = userConnection.EntitySchemaManager.GetInstanceByUId(entitySchemaUId);
                // Creating the object of the EntitySchemaQuery class.
                EntitySchemaQuery query = new EntitySchemaQuery(entitySchema);
                // Adding columns to query.
                query.AddColumn("Name");
                query.AddColumn("BirthDate");
                var gender = query.AddColumn("Gender.Name");
                var account = query.AddColumn("Account.Name");
                // Adding the created filter.
                query.Filters.Add(filter);
                // Getting the collection of contacts.
                var contacts = query.GetEntityCollection(userConnection);
                var contactsCollection = new Collection<Dictionary<string, object>>();
                // Populating the report columns.
                foreach (var entity in contacts)
                {
                    contactsCollection.Add(new Dictionary<string, object> {
                        ["Full name"] = entity.GetTypedColumnValue<string>("Name"),
                        ["Birthday"] = entity.GetTypedColumnValue<string>("BirthDate"),
                        ["Gender"] = entity.GetTypedColumnValue<string>(gender.Name),
                        ["Account"] = entity.GetTypedColumnValue<string>(account.Name)
                    });
                }
                return contactsCollection;
        }
        
        // Localization of the report title.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetLocalizableStrings(UserConnection userConnection) {
            var localizableStrings = _localizableStringNames.ToDictionary(
                x => x,
                x => (object)(new LocalizableString(userConnection.ResourceStorage, _resourceManagerName, $"LocalizableStrings.{x}.Value")).Value);
            return new[] { localizableStrings };
        }
        
        // Adding the interface filters.
        private IEntitySchemaQueryFilterItem ExtractFilterFromParameters(UserConnection userConnection, Guid entitySchemaUId,
                IReadOnlyDictionary<string, object> parameters) {
            var managerItem = userConnection.EntitySchemaManager.GetItemByUId(entitySchemaUId);
            return parameters.ExtractEsqFilterFromReportParameters(userConnection, managerItem.Name) ?? throw new Exception();
        } 

        // Getting data.
        public Task<ReportDataDictionary> GetData(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {
            var filter = ExtractFilterFromParameters(userConnection, _entitySchemaUId, parameters);
            var result = new ReportDataDictionary {
                // Populating the report columns.
                ["ContactData"] = GetContactData(userConnection, _entitySchemaUId, filter),
                ["LocalizableStrings"] = GetLocalizableStrings(userConnection)
            };
            return Task.FromResult(result);
        }
    }
}

Populate the localizable strings of the report with the following values:

Setting up the localizable strings
Name English (United States)
ReportTitle Contact Data
FullNameLabel Full name
BirthdayLabel Birthday
GenderLabel Gender
AccountLabel Account

Publish the schema.

4. Download the template and set up its layout in FastReport 

Download ContactData.frx. Click Download file in the Download file with data sources to design a report in the FastReport Designer block (4) of the working area.

To open the template in the Report Designer:

  1. Run the Terrasoft.Reporting.FastReport.Designer.exe file from the zip archive and open the FastReport designer.

    scr_FastReport_opening.png
  2. Click Open... in the window that pops up.

    scr_FastReport_Open_button.png
    You can also open the report template from the File menu -> Open... or by pressing Ctrl+O key combination.
    scr_FastReport_Open_button_File.png
  3. Navigate to the folder containing the downloaded report (usually, it is the “Downloads” folder), select the file with the template and click Open.

    scr_FastReport_ChooseTemplate.png

Set up the template layout.

scr_FastReport_template.png

5. Upload the configured report template to Creatio 

To upload the ContactData.frx, file, click Upload template in the Import a file with the report template block of the section working area (4). Confirm that the template has been uploaded successfully.

As a result, the "Contact Data” report will be available on the contact page under the Print.

scr_Print_button.png

You can also find the report on the Contacts sectin dashboard view, under the Reports button.

src_ReportInAnalytics.png

The report is generated as per the selected Filtered records in list option in the filtering page. To upload the report, click Create report. To close the filtering page and cancel generating the report, click Cancel.

scr_FilterPage.png

The report looks as follows:

scr_Report.png

Report by several records in a section 

To receive the report with several records:

  1. Enable the Show in section checkbox and select several records in the section list.
  2. You can use the section filters or the filtering page with the Show in the section analytics view checkbox selected.

To include information from several section records to your report:

  1. Open the needed section.
  2. Apply filters if needed.
  3. Click Actions —> Select multiple records.
  4. Select the needed report in the Print button drop-down list.
scr_Print_button_Records.gif

The report looks as follows:

scr_ReportRecords.png
Create the FastReport report with an image
Medium

Attention. The FastReport functionality will be retired in Creatio version 8.0.3.

Example. Create an "Account Info" report that would display the following information about the accounts:

  • Name;
  • Logo.

Example implementation algorithm 

1. Set up the report display parameters 

Set the following values in the parameter setup area:

  • Report title – "Account Info".
  • Section – "Accounts".
  • Show in section.
  • Show in card.
  • Show in the section analytics view.
  • Filter pageSimpleReportFilterPage.

Note. SimpleReportFilterPage – a client schema that implements standard simple filters.

The report setup page
scr_ReportDesigner.png
Setting up the report display parameters
scr_Parameters_example.png

2. Specify the data sources 

In the Specify data sources for the report block of the working area (4), add the code below:

AccountInfoProvider
{
    // The name of the data provider class.
    "ProviderName": "AccountInfoProvider",
    "Schemas": {
        "Data": {
            "Name": {  "DataValueType": 1 },
            "Logo": { "DataValueType": 14 }
        },
        // Added for localization.
        "LocalizableStrings": {
            "ReportTitle": {"DataValueType": 1},
            "NameLabel": {"DataValueType": 1},
            "LogoLabel": {"DataValueType": 1}
        }
    }
}

Click Apply to save and apply the changes (1).

3. Create the report data provider 

Go to the Advanced settings section -> Configuration -> Custom package -> the Schemas tab. Click Add —> Source Code. Learn more about creating a schema of the Source Code type in the "Create the Source Code schema" article.

Specify the following parameters for the created object schema:

  • Title – "Account Info";
  • Name – "UsrAccountInfoSourceCode".
scr_PackageSettings_example.png

The complete source code of the module is available below:

ContactDataProvider
namespace Terrasoft.Configuration
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using Terrasoft.Common;
    using Terrasoft.Configuration.Reporting.FastReport;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;
    using Terrasoft.Core.Factories;

    // The name of the data provider class for the report, whose logic needs to be implemented.
    [DefaultBinding(typeof(IFastReportDataSourceDataProvider), Name = "AccountInfoProvider")]
    public class AccountInfoProvider : IFastReportDataSourceDataProvider
    {
        // The name of the schema with the source code.
        private readonly string _resourceManagerName = "UsrAccountInfoSourceCode";
        private readonly string[] _localizableStringNames = new[] {
            "ReportTitle",
            "NameLabel",
            "LogoLabel"
        };

        // Populating columns in the report.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetData(UserConnection userConnection, IEntitySchemaQueryFilterItem filter) {
            var esq = new EntitySchemaQuery(userConnection.EntitySchemaManager, "Account");
            // Adding columns to the request.
            var nameColumn = esq.AddColumn("Name").OrderByDesc();
            var logoColumn = esq.AddColumn("AccountLogo.Data");
            // Adding the created filter.
            esq.Filters.Add(filter);
            return esq.GetEntityCollection(userConnection)
                .Select(x => new Dictionary<string, object> {
                    ["Name"] = x.GetTypedColumnValue<string>(nameColumn.Name),
                    ["Logo"] = x.GetStreamValue(logoColumn.Name)?.ToArray()
                });
        }
        
        // Localization of the report title.
        private IEnumerable<IReadOnlyDictionary<string, object>> GetLocalizableStrings(UserConnection userConnection) {
            var localizableStrings = _localizableStringNames.ToDictionary(
                x => x,
                x => (object)(new LocalizableString(userConnection.ResourceStorage, _resourceManagerName, $"LocalizableStrings.{x}.Value")).Value);
            return new[] { localizableStrings };
        }

        // Adding the interface filters.
        private IEntitySchemaQueryFilterItem ExtractFilterFromParameters(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {
            return parameters.ExtractEsqFilterFromReportParameters(userConnection, "Account") ?? throw new Exception();
        }

        // Receive data.
        public Task<ReportDataDictionary> GetData(UserConnection userConnection, IReadOnlyDictionary<string, object> parameters) {
            var filter = ExtractFilterFromParameters(userConnection, parameters);
            var result = new ReportDataDictionary {
                // Populate columns in the report.
                ["Data"] = GetData(userConnection, filter),
                ["LocalizableStrings"] = GetLocalizableStrings(userConnection)
            };
            return Task.FromResult(result);
        }
    }
} 

Populate the localizable strings of the report with the following values:

Setting up the localizable strings
Name English (United States)
ReportTitle Account Info
NameLabel Name
LogoLabel Logo

Publish the schema.

4. Download the template and set up its layout in FastReport 

Download the AccountInfo.frx file. Click Download file in the Download file with data sources to design a report in the FastReport Designer block (4) of the working area.

To open the template in the Report Designer:

  1. Run the Terrasoft.Reporting.FastReport.Designer.exe file from the zip archive and open the FastReport designer.

    scr_FastReport_opening.png
  2. Click Open... in the window that pops up.

    scr_FastReport_Open_button.png
    You can also open the report template from the File menu -> Open... or by pressing Ctrl+O key combination.
    scr_FastReport_Open_button_File.png
  3. Navigate to the folder containing the downloaded report (usually, it is the "Downloads" folder), select the file with the template and click Open.

    scr_FastReport_ChooseTemplate.png

Set up the template layout.

scr_FastReport_template.png

Attention. To display an image in the Logo column of the report, select Picture in the BindableControl field of the report designer when setting up the template.

5. Upload the configured report template to Creatio 

To upload the AccountInfo.frx file, click Upload template in the Import a file with the report template block of the section working area (4). Confirm that the template has been uploaded successfully.

As a result, the "Account Info" report will be available on the contact page under Print.

scr_Print_button.png

You can also find the report in the Accounts section dashboard view under Reports.

src_ReportInAnalytics.png

The report is generated as per the selected Filtered records in list option on the filtering page. To upload the report, click Create report. To close the filtering page and cancel generating the report, click Cancel.

scr_FilterPage.png

The report looks as follows:

scr_Report.png

Report by several records in a section 

To receive the report with several records:

  1. Enable the Show in section checkbox and select several records in the section list.
  2. You can use the section filters or the filtering page with the Show in the section analytics view checkbox selected.

To include information from several section records in your report:

  1. Open the needed section.
  2. Apply filters if needed.
  3. Click Actions —> Select multiple records.
  4. Select the needed report in the Print button drop-down list.
scr_Print_button_Records.gif

The report looks as follows:

scr_ReportRecords.png