Create a Dossier
A dossier document allows you to obtain a file processed starting from an input template. A typical example of using this feature is the creation of a file with variable content updated at each run. To do this, you need to create a dossier document with a well-configured XML template.
Important
Enterprise Edition
If you purchased Knowage EE, the following features are available only in KnowageER license.
XML Template
Image adding (PPT_TEMPLATE)
Suppose you have to create a ppt/pptx file where to place the images relating to one or more reports. You have only to configure XML template defining some placeholders to be use for replacing and execute it. Below is shown an example of an XML template used for this purpose.
1<?xml version='1.0' encoding='utf-8'?>
2<DOSSIER>
3 <PPT_TEMPLATE name="PPT_TEMPLATE.pptx"/>
4 <REPORTS>
5 <REPORT label="Report-multivalue-parameter">
6 <PLACEHOLDERS>
7 <PLACEHOLDER value = "ph1"/>
8 <PLACEHOLDERS>
9 <PARAMETERS>
10 <PARAMETER type="static" dossier_url_name="state" url_name="state"
11 url_name_description="State" value="Canada"/>
12 </PARAMETERS>
13 </REPORT>
14 </REPORTS>
15</DOSSIER>
The example above is using one placeholder and one static analytical driver.
Warning
Please note that the file to be used as a template must be placed in TOMCAT_HOME/resources/<TENANT_NAME>/dossier
path.
Image replacing (DOC_TEMPLATE)
Suppose that you have to draw up a document where text is static but images related to need to be updated. With this functionality you will be able to use a docx file as a template and replace images inside it. More precisely, you can configure your XML and docx templates to allow Knowage to replace specific images with new ones obtained by the execution of specified documents.
Below is shown an example of an XML template used for this purpose.
1<?xml version='1.0' encoding='utf-8'?>
2<DOSSIER>
3 <DOC_TEMPLATE name="DOC_TEMPLATE.docx" downloadable="true" uploadable="true" />
4 <REPORTS>
5 <REPORT label="DOC_01" imageName="img_DOC_01" sheetWidth="1366" sheetHeight="650" deviceScaleFactor="1.5">
6 <PARAMETERS>
7 <PARAMETER type="dynamic" dossier_url_name="family_dossier" url_name="family_document"/>
8 <PARAMETER type="dynamic" dossier_url_name="category_dossier" url_name="category_document"/>
9 </PARAMETERS>
10 </REPORT>
11 <REPORT label="DOC_02" imageName="img_DOC_02" sheetWidth="1366" sheetHeight="650" deviceScaleFactor="1.5">
12 <PARAMETERS>
13 <PARAMETER type="dynamic" dossier_url_name="family_dossier" url_name="family_document"/>
14 <PARAMETER type="dynamic" dossier_url_name="category_dossier" url_name="category_document"/>
15 </PARAMETERS>
16 </REPORT>
17 <REPORT label="DOC_03" imageName="img_DOC_03" sheetWidth="1366" sheetHeight="650" deviceScaleFactor="1.5" />
18 </REPORTS>
19</DOSSIER>
Note that if the document used to replace an image does not have any parameter, the tag REPORT must be closed inline as you can see for the document with label “DOC_03” in the example above.
Also docx document must be modified to be compatible with the replacer.
In particular: - images in the document must be inserted by copying and pasting from the file system (or using the “insert image” feature); - imageName in the XML template must match the title (alternative text) of the image in the docx; - each image must have a unique name.
Warning
To optimize dossier creation procedure, same document will be executed more than one time if and only if its parameters change. In that scenario sheetHeight, sheetWidth and deviceScaleFactor will be set for every execution. Moreover, if parameters don’t change, document will be executed only one time and sheetHeight, sheetWidth and deviceScaleFactor values will stay the same as the first execution.
My first dossier
You can create a dossier document by using the plus button and choosing “Generic Document”. Proceed by filling in the necessary fields, selecting “Collaboration” as the type and “Dossier engine” as the engine and then choosing the XML template. If the documents to be executed have one or more analytical drivers, these drivers must be added to the dossier document from the DRIVER tab.

Dossier document creation interface.
After saving the document, you can access the dossier activity page by clicking the play button.

Dossier activity interface.
If one or more dynamic analytic drivers are set, the required inputs must be provided in the sliding menu that appears from the right. You will then go to the dossier activity page.
If upload/download are enabled, docx file template can be uploaded/downloaded using the three dot menu on the top right of the “Details” tab.
Warning
This feature is available only for image replacing procedure.
If you want to execute your document, you must enter a name for the activity and click on “LAUNCH ACTIVITY”. A new task will be started in the STARTED state and a new row will be visible in the table below. At the end of the execution of the task, the processed file can be downloaded with the appropriate download icon.

Dossier activity execution finished.
Each line allows you to see useful information on the activity (such as the values of the drivers used for execution) by clicking on the info icon, download the processed file by clicking on the download icon and remove itself by clicking on the trash icon.
Dossier Wizard
Starting from Knowage 8.2 it is possible to configure the dossier template document and his xml template easily using the Dossier Wizard.
You can use this feature opening the wizard from a saved dossier document or directly from the workspace.
Starting from a saved document

Dossier document detail page. Click on Open Designer to open the Dossier Wizard.

Dossier Wizard first page.
In the first Dossier Wizard page user can select a new document template (docx or pptx format) , input the image prefix (the prefix of images text placeholder, for example in our case “img”) and the Uploadable/Downloadable feature, in order to allow user to download and update the document template inside the dossier document.

It is mandatory to select the images placeholder prefix.

This page will show image placeholders found inside the template document, the icon shows that they should be managed.
In the next page if placeholders are found inside the template document, they are shown on the left side panel. In the central-right panel user can click on + button and add a source document in order to link it to the image placeholder.

After selecting the document, user can select the parameters (drivers or views) to be linked to the placeholder. In this example there are 2 drivers (“familia”,”categoria”)
When user selects the document and drivers, they will be shown on the panel and can be configurated as follows. Driver Link Type can be of Dynamic, Static or Inherit type. Inherit type means that the parameter selected will be the same used in the source document selected. We kindly suggest to use “Inherit” for simplifying configuration assets.

User can select the Driver Type.

Driver Link Inherit type.
On other hands user can select to link a VIEW from the source document to the image placeholder:

User can select the view linked to the document.
If user wants to rollback and reset modification, he can click on “Reset placeholder” icon on the image placeholders panel.

Reset placeholder feature.
After clicking on SAVE BUTTON, the xml template should be updated and visible on History-template panel:

Updated dossier xml template.
Starting from the workspace
Another way to use the Dossier Wizard is starting from the Workspace.

Select “My Analysis” for starting a new Dossier document with Dossier Wizard.

Click on + button and select “Dossier”.
Note: End users can create dossier documents using views only. Drivers are not usable for end users.

Example of document with no views associated.