How to Create a Word Document with DSP Class
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.
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.
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.
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.
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.
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.
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’.
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 >>