How to Customize Docentric SSRS Replicas

When you start a new project, we recommend installing the latest version of Docentric AX (the core product) and the latest version of Docentric SSRS replicas.

We recommend installing Docentric SSRS replicas in the form of Project because of better readability.

Download Docentric SSRS Replicas >>

Set up Docentric SSRS replicas

The next step, after you finish the installation process, is to open Docentric report setup from the Docentric AX workspace in D365FO and click the Reload all button. All Docentric replicas will appear in the setup and be ready for use.

 

 

Learn how to set up Docentric replicas with Free Edition >>
Learn how to unlock Full Edition with a valid license >>

Customizing Docentric SSRS replicas

Each replica consists of a Docentric design (aka template) and the corresponding custom Docentric DSP class.

Customizing Docentric designs

Provided Docentric designs look identical to built-in SSRS designs so you will probably want to replace them with your own designs. Where to store them and how to deploy them, please read in the next chapter.

Customizing Docentric DSP classes

Docentric DSP classes provide report specific placeholders available for use in print destination settings such as Email body and Output filename. These classes also enable use of Print archive improved by Docentric. But most importantly, Docentric DSP classes should serve as a starting point for your customization:

  • Full Edition: adding additional data fields and data sets to the report data source to be printed out on Docentric designs or used as User-defined placeholders, reshaping report data source, creating report data source from scratch for both existing and new custom reports.
  • Free Edition: adding Additional email attachments.
  • Free and Full Edition: adding Custom placeholders, changing report metadata used for emailing with Additional attachments, saving to Attachments, Print archive, Report Log, etc.; changing dynamically any print destination settings to achieve custom scenarios such as signing additional attachments, selecting a specific network printer or Docentric template, changing report runtime language, changing number of copies, etc.

You can customize Docentric DSP classes via:

Inherit or extend DSP classes

For this approach, first create a new model, which will reference the Docentric AX, Docentric AX Extension and Docentric AX SSRS Replicas models (and all other models you will need for report customization, e.g. Application Suit).
Then, in this model you can create new DSP classes (1) by inheriting or (2) by extending the existing DSP classes from the Docentric AX SSRS Replicas model for those reports to which you want to add additional data and/or placeholders.

Learn how to add additional data to report data source >>
Learn how to create additional Custom placeholders >>

Both Inheritance and Extensions are recommended approaches for customizing DSP classes. However, Inheritance is more powerful approach, because you will be able to override all methods without calling the super() method.
When you create a new DSP class using Inheritance, you need to assign it to your report in Docentric report setup.
On the other hand, when using Extensions, there is no additional step in this regard.

Overlay DSP classes

If you decide to use Overlayering, you also need to create a new model that overlays the Docentric AX SSRS Replicas model in a layer higher than ISV, for example CUS. Overlayering is a powerful tool to perform advanced customizations of the source code but may increase the cost of upgrading Docentric Replicas to a new version.

Change DSP classes directly

Alternatively, you can change the code in the provided Docentric DSP classes directly, in order to add additional data, new placeholders or change some print settings. If no overlayering or extensions are used, the Docentric AX SSRS Replicas model will become yours in terms of development and maintenance.

Learn what this means for the upgrade >>

Where to keep Docentric designs

Docentric replicas designs (aka templates) are Word documents representing copies of the built-in SSRS designs. To start with customization, you first need to choose the template storage. Which template storage to choose depends on your customization process and deployment procedure.

There are four different template storage types: (1) Azure Blob storage, (2) SharePoint, (3) File system (only for on-premises or during development on OneBox) and (4) AOT Resources.

Store custom Docentric designs as AOT Resources

If you choose to store your custom Docentric designs (aka templates), which are just ordinary MS Word documents, as AOT Resources, you will need to create a new model to place it, probably the same model used for your customization artifacts for Docentric DSP classes. This way, your custom Docentric templates will also be added to DevOps Version Control (TFS). These kinds of templates are called System templates and they will be deployed alongside other customizations via deployable packages.

After deployment, System templates have ability to load themselves in Docentric report setup. If needed, your users can then replace them (i.e. change them) with some other templates stored on Azure Blob storage, SharePoint or File system. These templates are called Customized system templates.

One approach is to use Customized system templates while retaining initial Docentric SSRS replicas templates as System templates.

Learn more about template storage >>

Store custom Docentric designs on Azure storage, SharePoint or File system

However, you don’t have to operate with System templates, but instead use only so-called Custom templates. In this case, in your UAT/Test/Production environment you will upload/download your templates freely to/from Azure Blob storage, SharePoint (which supports template versioning OOTB) or File system.

When using Custom or Customized system templates, we provided Export/Import tools to support transfer of both metadata and content for all templates that are not stored as AOT Resources between environments. Also, by copying one environment to another including Azure storage, your custom templates files stored on Azure storage get copied automatically.

Suppressing Docentric Replicas Templates

You can avoid reloading Docentric replicas templates as System templates by decorating their AOT Resource artifact with the SkipLoadSystem=true entry in Tags.

Upgrading Docentric SSRS replicas

Once Docentric SSRS replicas are installed and in use, which means that you added additional data and new placeholders by customizing their DSP classes, created your templates and tested them, it is quite possible that you will no longer need to upgrade the Docentric AX SSRS Replicas model for the current project. Unless if there is a breaking change by Microsoft such as introducing and forcing a new version of an existing SSRS report such was Payment advice Version 2, then the upgrade is mandatory.

Also, if your customization approach of Docentric SSRS replicas was to use Inheritance or Extensions, then the upgrade should be more or less straightforward. Learn about possible customization approaches >>

How to know if you need to upgrade?

Docentric SSRS replicas are fully featured but with each new version of the Docentric AX core models (Docentric AX, Docentric AX Extension, Docentric AX Emails), we also publish a new version of Docentric SSRS replicas, i.e. the Docentric AX SSRS Replicas model.

In the new versions you can expect additional Docentric SSRS replicas or new utility classes such as classes for adding Taxes or Inventory dimensions to report data sources through customization of Docentric DSP classes. Occasionally, we also fix the bugs affecting mainly borderline cases or the system misbehaviors not necessarily related to Docentric.

Although we recommend regular updates of Docentric SSRS replicas, you are welcome to read the release notes and decide for yourself if it’s worth upgrading – for the current project. For all new projects, please use the latest version.
Read Docentric AX SSRS Replicas Release Notes >>

See also

How to Improve a Print Management SSRS Report Design >>
How to Set Up Reports >>
How to Set Up Report Templates >>
How to Use Placeholders in Print Destinations >>

IN THIS ARTICLE