CONTENTS
X

How to Create a Word Document with DSP Class

IN THIS ARTICLE

Our goal in this tutorial is to show how to create a Word document with DSP (Data Source Provider) class assigned to a Docentric Template Library.

Let’s say that we want to create a document ‘Sales Order Preview’ within the Sales Template Library, for the Primary table SalesTable. This document represents a printed sales order and can be generated for any sales order from the Sales orders list page. In order to do that, we should take the following steps:

  • Prepare a DSP class for this document.
    This class collects the required data of the currently selected sales order. A wizard creates the DSP class for us but we have to write business logic to fetch the data we need.
  • Generate the Data Source Package file using this DSP class.
    The document data source containing sales order sample data is created by Docentric AX Framework using the prepared DSP class. It is saved in a physical file called Data Source Package.
  • Create and design the document template using the generated Data Source Package.
  • Synchronize the template, i.e. add it to the Sales Template library.
  • Activate the template.
  • Generate the document from the template on the Sales Orders list page in a standard way.

Let’s start with our task. First, we need to create a new Docentric document type which must be a Template Library for Sales documents, see how . Let’s assume we’ve already created it as a Template Library with templates stored on file system and named it as ‘SalesTL_FS’. We also specified Folder as the template location.

When we want to update the document with new data and/or change its template design, we should take additional steps:

  • Update the DSP class and regenerate the changed Data Source Package file.
  • Modify the document template using the updated Data Source Package.
  • Synchronize the template, if needed. In that case we must activate it again.
  • Generate the document from the template on the Sales Orders list page in a standard way.

On how to update a document, i.e. its template you can learn here.

1. Prepare a DSP class and generate the document data source

To design a document template with the Docentric AX designer we need a document data source saved in 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 document, we need to generate a corresponding DDSP file first. We can do this in two ways: with a dedicated class (Data Source Provider class) or with one or more queries (Data Source Provider query).

In this tutorial we will consider only DSP (Data Source Provider) Class based documents. And we’ll learn about DSP Query based documents in the next tutorial.

So let’s start with creating our DSP class for ‘Sales Order Preview’ document; SalesTable will be our Primary table.

Click the Generate DS button on the Docentric document types form.

The Generate data source form is opened. Enter the Template ID, e.g. SalesOrderPreview and click the marked button on the picture below to activate the wizard for generating a Data Source Provider class.

1.1. Use the wizard to generate the DSP class

On the wizard form specify Primary table name, in our case SalesTable, and then click the Create DS provider artifacts button.

As a result, a temporary project is generated with the Data Source Provider class for the document ‘Sales Order Preview’.

1.2. Implement the generateXmlDataSource()method

The wizard has generated a new Data Source Provider class for us but we still have to implement the generateXmlDataSource() method that actually provides the needed data. This method’s responsibility is to collect, calculate and (re)shape the document data as required.

As you can see on the picture below, we have implemented our key method with just a few lines of code. Learn here how to write a DSP class in detail.

Generally we should avoid writing our DSP classes by just adding records with all fields as we did in this example, although this approach requires least work. A better way is to add only those field groups, fields and display methods we need (or might need) to show in the template. Otherwise the used data sets can become very large and generating such documents can become slower. Template design is also simpler when a data schema contains tens of data fields as opposed to a data schema containing hundreds of them.

1.3. Generate the Data Source Package

When you return to the Generate data source form, you will notice that the Data source provider class field is already updated with our DSP class SalesTableDsProvider. This also caused Primary table to be determined, in our case as SalesTable. Furthermore we can specify whether the Company logo is going to be included in the generating Data Source Package. We can also decide to use a particular record (Primary table RecId) of the Primary table, with more representative data and hence ensure more realistic preview during coming template design.

By clicking the Generate data source button, the data source for the document is generated and saved in a physical file. This file is called Data Source Package and contains the data provided by the selected DSP class. In our case, it contains SalesTable record with RecId = 5637144576 (SalesId = ‘000002’) and all child SalesLine records, according to the implemented method generateXmlDataSource() of our SalesTableDsProvider DSP class. The generated Data Source Package is going to be used in the document ‘Sales Order Preview’ template design.

Note that the Data Source Package file name is the same as the Template ID.

We can reuse the same Data Source Provider class or query for multiple documents with the same Primary table.
We cannot use the same Data Source Package for different documents.

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.

2. Create and design the template

Create a new ordinary Word document and name it as the generated DDSP file (i.e. as the Template ID), in the same file location.

If a template file name differs from the corresponding Data Source Package (DDSP) file name, i.e. from the Template ID, synchronization of the template won’t work. Furthermore, a template and its DDSP file must also be kept together in the same location – this applies to both type of template storage: File System and SharePoint. The same names and keeping together is necessary only for template synchronization but doesn’t affect template design in any way.

This Word document, SalesOrderPreview.docx, will be our template for the ‘Sales Order Preview’ document. Open it and navigate to Docentric AX Word Add-In ribbon. Click the Use As Template button and then load the Data Source Package SalesOrderPreview.ddsp, as shown on the picture below.

If we change a data source, e.g. add some new 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 from the Docentric AX Add-In ribbon.

Template design takes place in Docentric AX Template Designer, which is actually MS Word with a special Add-In. If we activate the Data Source pane, we can see all data provided by our Data Source Provider class or query. Note that Docentric AX Framework automatically adds some common or general data (such as company or current worker) that might be used on every template.

About a structure of Data Source Packages of documents and reports you can learn more here.
We can run the Preview button any time to test the template during design.

The preview of the document is shown below.

Notice that the sales order (SalesId = ‘000002’) that is written out in the document preview is the one, which was selected on the Generate data source form during the Data Source Package generation.

We can also use the built-in XML editor to view and modify the sample template data (actually the data from the data source) in order to test the different aspects of the template. This is particularly useful when we use conditional rendering.

By clicking the View sample data button the XML editor, where we can edit the sample data, is opened.

For example, let's change the value of the attribute SalesId to ‘99999’.

After clicking the Preview button again, we see the result of this change in the generated document.

About Docentric AX Template Designer and how to design templates you can learn here.

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.

2.1. Template storage on SharePoint

In case of template storage on SharePoint, we need to generate a Data Source Package (DDSP file) and save it to a temporary location on file system. When we finish with creating and designing of the template, we need to upload both files to the corresponding SharePoint Document Library.

Synchronization of templates stored on SharePoint is carried out in the same manner as synchronization of templates stored on file system.

3. Synchronize the template and activate it

After the template has been designed, we need to add it to the Sales Template Library. Click the button Synchronize and see the result. The template with ID ‘SalesOrderPreview’ and Primary table SalesTable should appear in the template list.

Templates stored on file system should basically be stored on network drives, i.e. shared folders. If the templates are stored within subfolders, they will be synchronized as well. If a template belongs to another document type, it is not going to be synchronized.

By clicking the Activate button this template becomes visible in a standard dropdown button on the Sales Orders list page. The next step is to test the template, i.e. to generate the document from the Sales Orders list page.

By clicking the Properties button we can view/edit properties of the selected template.

4. Generate the document from the template

Navigate to the Sales Orders list page (Company/Sales and marketing/Common/Sales orders/All sales orders) and position on any sales order with lines. Click the Generate from template dropdown button and notice that the SalesOrderPreview button appears. This menu item button is associated with our document ‘Sales Order Preview’, i.e. its template of the same name. By clicking it the ‘Sales Order Preview’ document will be generated for the currently selected sales order; in our case this is the order with Sales ID ‘000003’.

The generated document ‘Sales Order Preview’ for the currently selected sales order with the ID ‘000003’ has been added to its Attachments.

Click the Open button to open the generated document in MS Word.

Notice that all the number and date formats in the generated report are formatted using English-USA culture. This is because the language in the current AX user’s setup in the Options section is set to ‘EN-US’.

Report previewing during template design uses formatting from the Windows regional settings on the user’s AX client computer whereas the reports generated from the AX client have formatting controlled through the AX user’s setup in the Options section.

Resources

Data Source Provider class Data source (DDSP file) SalesOrderPreview Template

See also

How to Update an Existing Word Document >>
How to Write a Data Source Provider Class >>
How to Use Labels with Word Document >>
How to Design Templates with Docentric AX Template Designer >>
How to Create a Word Document with DSP Query >>
Word Template Examples >>

IN THIS ARTICLE