How to Use a Built-in SSRS Report as Docentric Report

Our goal in this tutorial is to show how to turn a built-in SSRS Report (Design) into a Docentric report in order to improve its design, updating and management in general.

One Docentric report can replace a single SSRS Report Design.

Let’s say we want to enhance the Birthdays SSRS report from the Human resources module with Docentric functionality. Before we begin, let's take a look at the built-in Birthdays report. Navigate to Company/Human resources/Reports/Workers and click the Birthdays menu item. Report dialog form is opened.

By clicking the OK button, the built-in Birthdays report is shown.

Enhance only report design

In order to turn a built-in SSRS Report Design into a Docentric report we need to take the following steps:

Register an SSRS Report Design as Docentric report
Generate the report Data Source Package
Create and design at least one Docentic report template (i.e. report layout, i.e. design), so called the default template

Learn more >>

Add additional data to a report

If we need to add additional data to a report, the following has to be done:

Create a custom DSP (Data Source Provider) class
Implement the generateXmlDataSource() method of this class to add additional data
Regenerate the report Data Source Package
Update the affected report templates

Learn more >>

Use more than one template per report

Different templates for different companies and languages can be used for one SSRS Report Design. When a report runs, a single template is automatically selected considering the run-time language and company. Templates can be also company and language neutral.

Learn more >>

1. Register an SSRS report as Docentric report

Let’s start with our task. First, we need to register the Birthdays SSRS report as a Docentric report. In order to do that, we need to find out the name of the corresponding SSRS Report and used Report Design. We can easily do that by opening the Birthdays menu item within HRM/Reports/Workers submenu.

We can see that the Birthdays report comprises the HcmBirthday SSRS Report with the Report Report Design.

Now navigate to Company/System administration/Area page and under Setup section you will see the Docentric AX menu, specifically the Reporting submenu. The Reporting submenu includes functionalities related to management of both Docentric SSRS and Basic reports.

Click the Reports menu item. The Docentric reports form opens. Click the New SRS report button and select HcmBirthday as SRS report name and Report as Report design name.

In order to turn on the Docentric functionalities with the added SSRS report (i.e. SSRS Report Design) we have to select the Is active (SRS only) check box.

Docentric’s enhancement of an SSRS report can be easily turned on or off by using the Is active flag. Also, built-in SSRS print destinations and the original report template (i.e. the original SSRS Report Design) can be also used for a currently active Docentric SSRS report. This feature can be set up – check the Reporting parameters form located in Company/System administration/Setup/Docentric AX/Reporting, the SRS reports tab page.

1.1. Use built-in SSRS and Docentric functionalities side-by-side

Navigate to the Company/System administration/Setup/Docentric AX/Reporting menu, open the Reporting parameters form and select the SRS reports tab page. You will see the SRS print destinations can be used along Docentric print destinations checkbox.

If the SRS print destinations can be used along Docentric print destinations option is not set, the Docentric’s Print destination settings form shows only Docentric print destinations:

If the SRS print destinations can be used along Docentric print destinations option is set, the Docentric’s Print destination settings form shows both the Docentric’s and the built-in print destinations:

If we select a built-in SSRS print destination, the original SSRS report template, i.e. built-in SSRS Report Design will be used likewise SQL Reporting Services to render the report.

2. Generate the report Data Source Package

To design a report template with the Docentric AX designer we need a report data source saved to a physical file. This file is called Docentric Data Source Package (DDSP) file. In other words, to be able to design a template for a report, we need to generate a corresponding DDSP file first.

Data Source Package generation is available as a special report print destination (“Generate DS”) and can be hidden if needed through the Generate data source option. We can also set up the Include company logo and Include hidden parameters options for generating the Data Source Package for a report.

Now go back to the HRM module and run the Birthdays report. This time when you click on the Destinations button the Docentric’s Print destination settings form is opened.

Select the Generate DS print destination and enter Data Source file name.

DDSP file for the Birthdays report is generated and saved to the file location we’ve specified.

Click the Open file location button to access the generated DDSP file.

Each Docentric report has exactly one Data Source Package and one or more templates. All report templates have to use the same Data Source Package.

About Docentric Data Source Packages (DDSP files) that represent design-time data sources intended for designing templates of Docentric documents and reports you can learn more here.

3. Create the template and assign it to the report

3.1. Create and design the report template

Docentric AX report templates are ordinary Word documents. Hence create a new blank Word document and store it on file system or SharePoint Document Library depending on which template storage type you use. You don’t have to store DDSP files along report template files neither to follow any naming convention for them although it’s always recommended to enforce one.

To create a new template you can always start from a blank Word document. However, the best practice is to copy and use in advanced prepared template that already defines company specific styles, headers and footers. This way you can easily achieve consistent look of all business documents companywide.

Open the newly created Word document, click the Use As Template button on the Docentric AX ribbon and load the report DDSP (Docentric Data Source Package) file.

Template design takes place in Docentric AX Template Designer, which is actually MS Word with a special Add-In. In the Data Source pane we can see the report data source schema as defined by the Data Source Package and that is at our disposal for template design. Notice that Docentric AX Framework automatically adds some common or general data (such as company or current worker) that might be used on every template.

Now we will design the template. In order to do that please follow this step by step tutorial.
The finished template looks like this.

Click the Preview button on Docentric AX ribbon to preview the report.

3.2. Assign the template to the report

The next step is to assign the newly created template to the Birthdays (HcmBirthday.Report) report. Open the Reports form, select the HcmBirthday.Report report and click the Add button on the Report templates tab page.

On the Report template form click the marked button and select the report template file.

Click the marked button on the Report template form to fill Template ID from the report template file name and then click the OK button.

The new template with HcmBirthday.Report_Default as Template ID is added to Report templates of the report as its default template.

When a Docentric SSRS report is executed, one of the default templates is used. If we want to use a non-default template, then we have to create a custom Data Source Provider class and implement its overrideReportRunSettings() method. Learn more >>

Template ID has to be globally unique across all Docentric reports. Identical Template IDs can be used for more templates of a single report as long as they have been set up for the different companies and languages. If the company/language of the template is not set, the template is company/language neutral, i.e. valid for all companies/languages.

The Is default flag is applied to all templates with the same Template ID. This means that the default template is determined considering the Is default flag and the report run-time company (usually current company) and run-time language (usually current user language, or Customer/Vendor language).

After the template is assigned to the Birthdays report, print the report to Screen.

4. Add additional data to the report

Let’s say we want to add some additional data to the report. For example, we are going to add the Birthday Date field for the year selected in the report parameters for each employee. We need this date so that we wil be able to group employees by the day in the month selected by report parameters.

4.1. Create the custom DSP class

In order to add additional data to a Docentric SSRS report, we need a custom DSP (Data Source Provider) class. So far, we have used the default (base) DSP class for Docentric SSRS reports that automatically build Data Source Package (DDSP file) reusing the built-in report RDP class and tables.

Open the Reports form and click the Create data source provider class link button.

The Create SRS report artifacts form is open. After we enter the names of artifacts and click the Create report artifacts button, a temporary private project with the DSP class is created and this class is assigned as Data source provider class of the report.

Take a look at the created project and DSP class.

Open the class in the editor and implement the generateXmlDataSource() method so that the additional Birthday Date field is included. Learn how to add additional data to a SSRS report in detail >>

4.2. Regenerate the report Data Source Package

When the generateXmlDataSource() method of the DSP class is implemented, we need to regenerate the report Data Source Package (DDSP file). We can do this in the same way we’ve generated it initially: open the report dialog form and select the Generate DS print destination.

4.3. Update the template

Always when the report data source is changed we need to update all report templates with the new DDSP file in order to refresh a template data source.

If we change a data source, e.g. add some additional fields or records, update of the template data source WILL NOT OCCUR automatically. In order to refresh it, we must reload the updated corresponding DDSP file by clicking the Load Data Source button on the Docentric AX ribbon tab (in MS Word).

We can open the template directly from the template location (file system or SharePoint) or by clicking the Design button on the Report templates action pane.

After the template document is open, navigate to the Docentric AX ribbon and click the Load Data Source button. Notice that the current template data source schema does not contain the new Birthday Date field.

After the new DDSP file has been loaded, the new Birthday Date field appears in the template data source schema. Just to be sure that the updated version of the template has been used for report generation, we will make a small change on the template by changing the page color. The new Birthday Date field will be used on a new template of the same report later.

Remember, when the report data source is changed it is best to update all report templates with the new DDSP file no matter if the changes affect a template.

5. How to use more than one template for the same report

Different templates for different companies and languages can be used for one SSRS Report Design. When a report runs, a single template is automatically selected considering the run-time language and company. Learn more on how to get automatically selected different templates for different companies and languages >>

And if we want to change the default behaviour of template selection and to use a non-default template instead of the default one, the only way to do this is to switch templates dynamically, i.e. during report execution. Hence we have to perform the additional steps:

Create a custom DSP (Data Source Provider) class, if we haven’t already done that
Implement the overrideReportRunSettings() method of this class to use an alternative template. In this method we can also change the selected print destination and its settings, replace custom placeholders etc.
We can also add Template ID, Company ID and Language ID as Data Member Attributes to the SSRS Report Data Contract to make them visible as report parameters on the report dialog form. This way we will get an option to select a particular template on the report dialog form.

Let’s say that we want show the same data differently under some special circumstances. For example, if the report parameters FromDate and ToDate refer to the May month, we will group all employees who have birthday in May by day and for each of them we will print a Birthday card. To achieve this, we will create a new non-default (alternative) template that will use the same report data.

5.1. Create the alternative report template

Create another blank Word document and follow the same instructions as for the first template.

Load the same report Data Source Package (DSP file).

Design the template by following this step by step tutorial .

The finished template looks like this.

5.2. Assign the alternative template to the report as a non-default template

The next step is to assign the newly created template to the Birthdays (HcmBirthday.Report) report as a non-default template. Open the Reports form and click the Add button on the Report templates tab page.

After we select the HcmBirthday.Report.docx document and click the OK button, the new template with HcmBirthday.Report as Template ID is added to Report templates as a non-default template.

Return to HRM module and run the Birthdays report with selected May month for the From and To report parameters. As you can see below, the default template has been used. The question is, how to use the alternative template when we select May month for the report paramters?

5.3. How to use the alternative template

We can switch the automatically selected (default) template and change the other report print settings (language, report caption etc.) likewise the print destinations settings only dynamically, i.e. during report execution.

In order to do that, we have to implement the overrideReportRunSettings() method of the report custom DSP class.

The business logic for our example would look something like this:

In case that the FromDate report parameter belong to May and the selected print destination is Screen, we are going to replace the currently selected, i.e. default template with the alternative template, change the selected print destination to File, set the output format to Word document, open the report output file after the report executes and suppress the message about successful report execution.

You can learn here how to override report run settings in detail.

Now let’s try out the Birthdays report again.

This time the alternative report template is used, the report is generated in Word output format and sent to the File print destination instead to be sent to Screen.

5.4. Enable template selection on report dialog form

You can also add Template ID, Company ID and Language ID as Data Member Attributes to the SSRS Report Data Contract to make them visible as report parameters on the report dialog form. We still have to implement the same overrideReportRunSettings() method but this way we will get a possibility to select any of the existing report templates on the report dialog form.

Use the DocSrsReportTemplateId EDT as a data type of the Template ID Data Member Attribute. This Extended Data Type has the FormHelp property set to the DocSrsReportTemplateLookup form, enabling this way use of the custom lookup form that already supports templates filtering by the current report.

If we do so for our Birthdays report the report dialog form looks like below.

In the HcmBirthdayContract class we’ve added three new data member attributes.

You can download the HcmBirthdayContract class here:

Class_HcmBirthdayContract.xpo

Sample implementation of the overrideReportRunSettings() method looks like:

public DocPlaceholderManager overrideReportRunSettings(DocReportRunContext _reportRunContext,
                                         boolean _replaceStandardPlaceholders = true)
{
    DocPlaceholderManager       placeHolderMng;
    DocReportTemplate           docTemplate;
    HcmBirthdayContract         hcmBirthdayDc      = this.getSrsRdpContract();
    DocReportTemplateId         selectedTemplateId = hcmBirthdayDc.parmTemplateId();
    LanguageId                  selectedLanguageId = hcmBirthdayDc.parmLanguageId();
    CompanyId                   selectedCompanyId  = hcmBirthdayDc.parmCompanyId();

    
    // Replace all standard placeholders, if any.
    placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);
    
    // If the template has been selected, use it for the report execution.
    // Otherwise, the default template will be used.
    if (selectedTemplateId)
    {
        docTemplate = DocReportTemplate::findTemplateId(
            selectedTemplateId, selectedCompanyId, selectedLanguageId);
         if (docTemplate)
        { 
            _reportRunContext.parmTemplateId(docTemplate.TemplateId);
            _reportRunContext.parmTemplateCompanyId(selectedCompanyId);
            _reportRunContext.parmTemplateLanguageId(selectedLanguageId);
        }
    }
    
    return placeHolderMng;
}

public DocPlaceholderManager overrideReportRunSettings(DocReportRunContext _reportRunContext,

boolean _replaceStandardPlaceholders = true)

{

DocPlaceholderManager placeHolderMng;

DocReportTemplate docTemplate;

HcmBirthdayContract hcmBirthdayDc = this.getSrsRdpContract();

DocReportTemplateId selectedTemplateId = hcmBirthdayDc.parmTemplateId();

LanguageId selectedLanguageId = hcmBirthdayDc.parmLanguageId();

CompanyId selectedCompanyId = hcmBirthdayDc.parmCompanyId();

// Replace all standard placeholders, if any.

placeHolderMng = super(_reportRunContext, _replaceStandardPlaceholders);

// If the template has been selected, use it for the report execution.

// Otherwise, the default template will be used.

if (selectedTemplateId)

{

docTemplate = DocReportTemplate::findTemplateId(

selectedTemplateId, selectedCompanyId, selectedLanguageId);

if (docTemplate)

{

_reportRunContext.parmTemplateId(docTemplate.TemplateId);

_reportRunContext.parmTemplateCompanyId(selectedCompanyId);

_reportRunContext.parmTemplateLanguageId(selectedLanguageId);

}

return placeHolderMng;

}

In order that the selected Language ID and Company ID affect label translations and data formats on the printed report, please use either the preRunGenerateDS() method of your custom Docentric DSP class and change this.parmParams().parmDsLanguageId() / this.parmParams().parmCompanyId(), or the preRunModifyContract() method of your derived SrsReportRunController controller class.

Resources

Data source provider class Data source (DDSP file)
Report Template 1 Report Template 2

CONTENTS

How to Use a Built-in SSRS Report as Docentric Report

IN THIS ARTICLE

Enhance only report design

Add additional data to a report

Use more than one template per report

1. Register an SSRS report as Docentric report

1.1. Use built-in SSRS and Docentric functionalities side-by-side

2. Generate the report Data Source Package

3. Create the template and assign it to the report

3.1. Create and design the report template

3.2. Assign the template to the report

4. Add additional data to the report

4.1. Create the custom DSP class

4.2. Regenerate the report Data Source Package

4.3. Update the template

5. How to use more than one template for the same report

5.1. Create the alternative report template

5.2. Assign the alternative template to the report as a non-default template

5.3. How to use the alternative template

5.4. Enable template selection on report dialog form

Resources

See also

IN THIS ARTICLE