advertisement
User manual
XperiDo template design add-in for Microsoft Word
Last updated: 05-01-2016
Your documents. Automated.
Master your data flows. Boost your output streams.
Table of contents
User manual XperiDo template design add-in for Microsoft Word 2
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 3
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 4
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 5
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 6
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 7
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 8
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 9
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 10
Your documents. Automated.
Master your data flows. Boost your output streams.
1 Introduction
1.1 XperiDo add-in for Microsoft Word
This document is a user manual for the XperiDo add-in for Microsoft Word (from here on simply referred to as the add-in ). With the add-in you can create and edit XperiDo templates for automatic document creation. The aim of this manual is to guide you through the essential features of the add-in.
For more detailed information on XperiDo and the XperiDo add-in for Microsoft Word, please visit www.xperido.com
or contact your local XperiDo partner.
1.2 About this document
1.2.1 Disclaimer
In this manual, we try our best to explain every function of the add-in in a manner that's understandable to everyone. If something isn't clear, wrong or missing, please let us know by sending an email to [email protected]
.
The images in this document are taken from various versions of the add-in. If you notice that the screenshots in this manual don't always fully correspond to your screen, know that the main functionality hasn't changed, and that purely aesthetic changes might not be updated immediately in the manual.
1.2.2 Version
This manual is up to date with the latest stable release of the Word add-in .
User manual XperiDo template design add-in for Microsoft Word 11
Your documents. Automated.
Master your data flows. Boost your output streams.
2 Setup
This chapter explains how to install, update and uninstall the add-in.
2.1 Installing the add-in
2.1.1 Before installation
Before you install the add-in, please verify that your computer meets the following requirements and possesses the following prerequisites:
2.1.1.1 System requirements
We advise the following:
Operating system : Windows 7 / Windows 8 / Windows Vista service pack 1 / Windows XP service pack
3
Memory : 512 MB+
Disk space : 120 MB+
Processor speed : Pentium 1 Ghz+
Internet access (access to the XperiDo server)
2.1.1.2 Software prerequisites
The installer will verify that the following prerequisites are present on your system and it will prompt you to download and install missing components, provided that these are freely available for download.
Windows Installer 3.1+
Internet Explorer 5.01+
Microsoft Word 2007/2010/2013
Microsoft .NET Framework 4.5+
Microsoft Visual Studio 2010 Tools for Office Runtime
2.1.2 Installation
Follow these steps to install the add-in:
1) Download the installer from this page .
2) Run the installer. This will start a wizard that will guide you through the process.
User manual XperiDo template design add-in for Microsoft Word 12
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Follow the wizard's steps until the end.
The installer will verify that your system meets the necessary requirements and it will prompt you to download and install missing components, provided that these are freely available for download.
2.1.3 After installation
Once the add-in is installed on your system, a new XperiDo tab will appear in the Microsoft Word ribbon.
You are now ready to connect to the project where your templates are stored. More information about how to
set up can be found on this page .
If the XperiDo tab does not appear in the ribbon, you can check a few things:
2.1.3.1 Verify the prerequisites
Verify that these prerequisites are installed on your computer:
Windows Installer 3.1+
Internet Explorer 5.01+
Microsoft Word 2007/2010/2013
Microsoft .NET Framework 4.5+
User manual XperiDo template design add-in for Microsoft Word 13
Your documents. Automated.
Master your data flows. Boost your output streams.
Microsoft Visual Studio 2010 Tools for Office Runtime
2.1.3.2 Verify that the add-in is active
Navigate to File > Options > Add-Ins and verify that the XperiDo add-an is marked as an Active Application
Add-In .
If it is listed with the Inactive Application Add-Ins , select COM Add-Ins and click the Go button at the bottom of the dialogue box.
In the window that pops up, check the box next to XperiDo Document AddIn and click OK .
User manual XperiDo template design add-in for Microsoft Word 14
Your documents. Automated.
Master your data flows. Boost your output streams.
Should the XperiDo add-in not appear in the list, select Disabled Items at the bottom of the screen and click Go .
The XperiDo add-in might appear in the list in the window that pops up. If so, select it and click Enable .
2.1.3.3 Further help
If you are unable to get the add-in working on your system, please contact our helpdesk .
2.2 Updating the add-in
If you want to update your add-in, you need to check the version numbers of both your current version and of the version you wish to install.
You can check your version number by clicking About in the XperiDo ribbon:
The version number is the one between brackets: 6.6.68
in the above screenshot. 6.6 is the major version, 68 is the minor version.
User manual XperiDo template design add-in for Microsoft Word 15
Your documents. Automated.
Master your data flows. Boost your output streams.
If both versions have the same major version number , you can run the new version's installer and install the new add-in over the previous one .
If both versions have a different major version number , you need to remove the add-in before you can install the new one.
2.3 Uninstalling the add-in
To uninstall the add-in, follow these steps:
1) Go to the Windows Control Panel .
2) Open Programs & Features .
3) Find the XperiDo Document Add-in .
4) Right-click it and click Uninstall .
The add-in is now removed from your system.
User manual XperiDo template design add-in for Microsoft Word 16
Your documents. Automated.
Master your data flows. Boost your output streams.
3 Server connection
XperiDo is a server application, which means that you need to establish a connection between your local computer and an XperiDo server. This chapter explains how to set up and manage your connections.
3.1 Accessing your connections
To connect to your XperiDo server, click the Connection button in the XperiDo ribbon:
This opens the Connect window.
Click the blue pencil inside the empty connection box to open the connection settings.
These settings can also be opened by clicking Properties in the XperiDo ribbon, followed by clicking Server
Instances .
User manual XperiDo template design add-in for Microsoft Word 17
Your documents. Automated.
Master your data flows. Boost your output streams.
3.2 Managing your connections
In this window, you can manage your different connections. This is useful when you have multiple environments/XperiDo servers to connect to.
3.2.1 Creating a new connection
To create a new connection, click New .
In here, you'll need to specify a few things:
Host is the DNS name of the XperiDo server.
Port is the port through which the XperiDo server is accessible (usually 8080).
User manual XperiDo template design add-in for Microsoft Word 18
Your documents. Automated.
Master your data flows. Boost your output streams.
The type of connection is either by using an XperiDo native ID or through a Microsoft account (also known as a Windows Live ID). If you want to use an XperiDo native ID, click the blue XD icon, if you want to use a Microsoft account, click the Microsoft logo.
3.2.1.1 XperiDo native ID
An XperiDo native ID uses the credentials you got from your XperiDo partner. Input them in the correct boxes and click Apply to save the connection properties.
If you want to go back to selecting an XperiDo native ID/Microsoft account, click the green arrow to the right.
Click Test Connection to test the connection.
User manual XperiDo template design add-in for Microsoft Word 19
Your documents. Automated.
Master your data flows. Boost your output streams.
3.2.1.2 Microsoft account (Windows Live ID)
You can also use your Microsoft account to authenticate yourself. This is only possible if your email address has been recognized by the applicable XperiDo server. If you wish to use this method for authentication, please contact our helpdesk so that we can register your e-mail address.
To use your Microsoft account, type in localhost in the host box, then click Test Connection . A window will pop up, asking for your credentials. Log in to Microsoft with your email address. Once this is done, you will need to give XperiDo authorization to use your email address for authentication. This email address is used to assign rights to you.
Clicking Yes will send the email address to the XperiDo server, which will allow you to work with XperiDo by using your Microsoft account.
Additionally, you can choose to sign in beforehand, by setting the properties in the XperiDo options. To do this, click Properties .
Then, choose Live ID . Click Sign In .
User manual XperiDo template design add-in for Microsoft Word 20
Your documents. Automated.
Master your data flows. Boost your output streams.
The authentication procedure (as described above) will start. Once logged in, you can see the information that is retrieved from the server.
3.2.2 Exporting and importing connections
You can export a connection so that someone else can import it. To do this, select a connection, fill in the credentials and click Export :
Export : this exports the connection with the username but without the password.
Export without usernames : this exports the connection without the username and password.
Export with passwords : this exports the connection with both the username and password.
User manual XperiDo template design add-in for Microsoft Word 21
Your documents. Automated.
Master your data flows. Boost your output streams.
The connection will be exported as an XML file. To import an XML connection file, click Import and select the file.
3.3 Connecting to your project
Once you have set up a connection, it will be selectable in the dropdown list in the Connect window. In the following screenshot, the xbprod connection is chosen.
After choosing your connection, the Projects dropdown list will show the available projects. Select the project you want to connect to, then navigate to the template you want to open.
User manual XperiDo template design add-in for Microsoft Word 22
Your documents. Automated.
Master your data flows. Boost your output streams.
4 Template basics
Before you can dive into template design, it's good to know how XperiDo deals with templates.
4.1 Converting templates into documents
The goal of templates is to, at some point, convert them into documents by filling placeholders with data.
XperiDo has two ways of converting templates into documents: single template and multiple templates .
4.1.1 Single template
In a single template document generation scenario, one template is converted into one document .
The benefit of working this way is that it's simple: one template becomes one document. This means that everything you put in the template ends up in your document (barring possible conditional content).
4.1.2 Multiple templates
In a multiple templates document generation scenario, multiple segment templates are grouped into one composed template , which is then converted into one document .
User manual XperiDo template design add-in for Microsoft Word 23
Your documents. Automated.
Master your data flows. Boost your output streams.
The benefit of working this way is that you can re-use segment templates by using them in multiple composed templates.
4.2 Template zones
Each template is split into multiple zones. This is useful for the assembly of composed templates, as you can assign segment templates to each zone of the composed template .
There are four template zones: the body , header , footer and insert zone.
4.2.1 Body zone
The body zone features the main content of the template. If the body content exceeds the available space in the body zone of a page, a new page is added to the generated document. This means that a lot of body content will result in a generated document spanning multiple pages.
User manual XperiDo template design add-in for Microsoft Word 24
Your documents. Automated.
Master your data flows. Boost your output streams.
4.2.2 Header zone
The header zone is the space at the top of each page . The same header content is repeated on every page of the generated document, which makes it ideal for (for instance) a company name and logo.
4.2.3 Footer zone
The footer zone is the space at the bottom of each page . The same footer content is repeated on every page of the generated document, which makes it ideal for (for instance) contact details and a page number.
4.2.4 Insert zone
The insert zone is at the back of the generated document. This zone is useful for adding complete documents to your template, such as the terms and conditions of a sale.
4.3 Template types
There are a number of different template types, which we'll group into four categories: standard , composed and email .
4.3.1 Standard
Standard templates are templates that can be used for single template document generation. This is the most basic type of template.
In addition to using this for the direct creation of documents, you can also use this template in a composed template, where its body content will be inserted into the body zone of the composed template. As well as using it in the body zone, you can also use it in the insert zone , as an insert.
4.3.2 Composed
Composed templates are templates that group one or more segment templates into a composition master .
User manual XperiDo template design add-in for Microsoft Word 25
Your documents. Automated.
Master your data flows. Boost your output streams.
4.3.2.1 Composition master
Composition masters feature four zones (see above) that can each contain multiple segment templates.
4.3.2.2 Segment
Segment templates are used to populate the template zones of a composition master. There are four segment types:
Body segment
Header segment
Footer segment
Insert segment
These segments correspond to the template zones; e.g. you can only insert header segments in the header zone.
4.3.2.3 Body segment group
Segment group templates are used to group multiple segments of the same type. This is useful if you have a recurring block of segment templates that you wish to use in many composed templates. There currently is one kind of segment group, which is the body segment group .
Body segment groups are composed like composition masters, except that you can't insert headers, footers or inserts. A body segment group can contain standard templates , body segments and other body segment groups .
4.3.3 Email
Email templates are templates that can be used with XperiDo's email functionality, by using their content for the message body of an email. It is not possible to generate documents with email templates, as that is not what they are for.
User manual XperiDo template design add-in for Microsoft Word 26
Your documents. Automated.
Master your data flows. Boost your output streams.
4.4 From composed template to document
With multiple headers, bodies, footers and inserts, there are a few rules XperiDo uses to create one document from all of this.
4.4.1 Used Word parts
Each segment can be fully edited in Word, meaning that you can add content to the Word header , the Word body and the Word footer . However, depending on the segment type, certain content will be ignored:
For bodies , only the Word body of the template is used. Any content inside the Word header and footer is ignored.
For headers , only the Word header of the template is used. Any content inside the Word footer and
Word body is ignored.
For footers , only the Word footer of the template is used. Any content inside the Word header and
Word body is ignored.
For inserts , every part of the template is used: Word headers, Word footers and the Word body.
For instance, you can design a standard template, fully with Word headers and footers. When using this template on its own for outputting a document, all of the Word content will be used. However, when using it in the body zone of a composed template, only Word's body content is used. Conversely, using it in the insert zone keeps the header and footer content in the document.
User manual XperiDo template design add-in for Microsoft Word 27
Your documents. Automated.
Master your data flows. Boost your output streams.
4.4.2 Composition rules
The following rules are used to generate a document when there are multiple segment templates in the composed template:
Multiple segments of the same type results in their contents being added to the document in the order in which they are defined in the composed template:
Inserts always start on a new page - so they appear the same in every composed template.
The headers/footers are repeated on every page where there is body content. On insert pages, the
Word header and footer of that insert are used.
4.4.3 First body template settings
The resulting document has a set of settings, such as the bottom margin, that are taken directly from the first body template . You may set these settings in other templates, such as the footer, but all these settings will be overwritten by the settings from the first body template.
User manual XperiDo template design add-in for Microsoft Word 28
Your documents. Automated.
Master your data flows. Boost your output streams.
5 Accessing templates
Using the template design add-in requires that you know how to open or import templates. This chapter covers the basics of opening templates for editing.
5.1 Opening an existing template
To open an existing XperiDo template, go to the Connection panel by clicking the large blue XD icon in the upper left corner of the XperiDo ribbon.
In the window that pops up, select a connection and a project.
Once you have selected a project, a list of the folders and items inside this project opens. There are 2 ways of opening a template: either via the Templates folder or via the DataSets folder.
5.1.1 Via the templates folder
The Templates folder shows you a list of all the templates.
User manual XperiDo template design add-in for Microsoft Word 29
Your documents. Automated.
Master your data flows. Boost your output streams.
In here, select a template to bring up more information about this template:
User manual XperiDo template design add-in for Microsoft Word 30
Your documents. Automated.
Master your data flows. Boost your output streams.
In the Template tab, you can view some of the template's properties. For more detailed information, click the
Properties tab. Click the Samples tab to see which samples are available for this template. For more information about the Language
tab, please read this chapter .
To open your template, click Open or Open and Check out . The difference between these options are due to
XperiDo's revision control system. You can read more about this in this chapter .
5.1.2 Via the datasets folder
To open a template via the datasets folder, go to the DataSets folder:
User manual XperiDo template design add-in for Microsoft Word 31
Your documents. Automated.
Master your data flows. Boost your output streams.
A list of the templates, associated with this data source, will be shown. Select one of them and click Open or
Open and Check out to open it. The difference between these option are due to XperiDo's revision control
system, which you can read more about in this chapter .
5.1.3 Speeding up things
Should you have a very large amount of templates, it might take a while for XperiDo to have finished loading all of them. If you find the waiting time to be too long, you can change XperiDo's loading behaviour to not load all the templates at once.
Click on Properties in the ribbon to open up the XperiDo Options :
Then, go to General and find Show templates when connecting .
User manual XperiDo template design add-in for Microsoft Word 32
Your documents. Automated.
Master your data flows. Boost your output streams.
Disabling this option will speed up the process because templates are only loaded when you click on a data source. Now, you can find the templates associated with a data source by clicking on that data source.
5.2 Importing and exporting templates
5.2.1 Export
You can export templates so you can send them to someone else. This is especially useful when you have a question for the Invenso helpdesk team.
To export templates, follow these steps:
1) Open the template you wish to export.
2) In the XperiDo ribbon, click Properties :
3) Click Support in the left pane of the window:
User manual XperiDo template design add-in for Microsoft Word 33
Your documents. Automated.
Master your data flows. Boost your output streams.
4) Click the Export or the Export & Send button to start the export. Both buttons will produce a file that can be imported later. Export & Send will also open your email client, create a new email and attach the file to the email.
5) A wizard will open to guide you through the process. In the first screen, the names of the document and the datasource will be shown. You can also choose whether to include diagnostic information, such as the version of Microsoft Word you are using. If you are planning to send this template to the
Invenso helpdesk, it is advised to check this box. You can also choose which samples to include. Click
Next to continue.
User manual XperiDo template design add-in for Microsoft Word 34
Your documents. Automated.
Master your data flows. Boost your output streams.
6) On the second screen, you can select a folder where all the export files will be placed. By default, the name of the template will be used as the name for the export file, but you can choose to change it.
There is also an option to remove temporary files that were created during the export process. Click
Next to continue.
7) The final screen shows the progress of the export action. When the export is finished, the location of the file is shown. Click Finish to close the wizard.
User manual XperiDo template design add-in for Microsoft Word 35
Your documents. Automated.
Master your data flows. Boost your output streams.
8) If you clicked Export & Send , a new mail window will be open, with the exported files as attachments.
5.2.2 Import
You can import templates by following these steps:
1) In the XperiDo ribbon, click Properties :
2) Click Support in the left pane of the window:
User manual XperiDo template design add-in for Microsoft Word 36
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Click the Import button to start the import.
4) A wizard will open to guide you through the process. On the first screen, you need to select the file you wish to import. Click Next to continue.
User manual XperiDo template design add-in for Microsoft Word 37
Your documents. Automated.
Master your data flows. Boost your output streams.
5) If this is a valid file, the next screen will show you what is inside the file. If there are samples present, you can select which samples you want to include. Click Next to continue.
6) This screen will show you the connection to use and the project to import into, based on what is in the export file. You can choose to restore the files to their original location, or you can specify a group in which all the files that are imported will be placed. The box that says Import Datasource should be checked if you want to import the data source. When you already have the data source in your repository, you might not want to import the data source. The option Check to overwrite...
should be checked if you want to overwrite items that already exist. If you leave it unchecked, items with the same name will get a suffix added to their name during import. Click Next to continue.
User manual XperiDo template design add-in for Microsoft Word 38
Your documents. Automated.
Master your data flows. Boost your output streams.
7) The final screen shows the progress of the import action. You can choose to open the template upon completion by checking the box that says so. Click Finish to close the wizard.
User manual XperiDo template design add-in for Microsoft Word 39
Your documents. Automated.
Master your data flows. Boost your output streams.
6 Template design basics
In this chapter, we show you the basics of template design, so that you can quickly create a simple template.
6.1 Content types
A template can contain both static and dynamic content.
Static content is regular Word content - anything you can insert without using the add-in. This type of content doesn't change in between documents.
Variable content is data that is collected from other sources - this content is merged into the document when it is created.
6.2 Screen layout
Upon opening a template, you'll see your document, the XperiDo pane and the XperiDo ribbon :
At the top, you can see the XperiDo ribbon . Here are its components:
User manual XperiDo template design add-in for Microsoft Word 40
Your documents. Automated.
Master your data flows. Boost your output streams.
The ribbon gives you quick access to plenty of features XperiDo has to offer:
Connect : used for connecting to the server, changing XperiDo's options and reviewing information about the XperiDo add-in.
View : used to change the view of the XperiDo pane (on the right), opening the XperiDo assets manager, turning on design mode or viewing the thumbnail manager.
Language : used to keep track of your template's language settings.
Insert : used to insert various types of content in your template.
Repository : used for generating previews and everything that has to do with revision control.
Data Set : used for viewing samples, refreshing the data and selecting styles.
Template Properties : provides you with information regarding the current template.
What every button does is explained in detail in the following chapters.
To the right, you can see the XperiDo pane :
User manual XperiDo template design add-in for Microsoft Word 41
Your documents. Automated.
Master your data flows. Boost your output streams.
The pane is where you keep track of the variable content in your template:
Data Set : contains a tree view of the data fields in the data source of the template. The Field Inspector at the bottom shows sample values for selected data fields.
Mapping : contains a list of all the data mappings that are currently in the template.
XperiDo Styles : contains a list of the quick formatting styles that you have defined for this template.
Again, detailed descriptions of how to use these tabs and their functions can be found further in the manual.
6.3 Types of fields
XperiDo works with four types of fields:
Basic fields are fields that are defined by the data set that is used to build the template on.
Pseudo-fields are extra fields that are not part of the data set. They can be used to perform
calculations or apply formulas on basic fields. More information can be found here .
Dynamic fields are extra fields for which an end user can set a value during the document creation
process. More information can be found here .
User manual XperiDo template design add-in for Microsoft Word 42
Your documents. Automated.
Master your data flows. Boost your output streams.
Resultsets are groups of fields that have a filter applied to them. More information can be found
Pseudo-fields, dynamic fields and resultsets are the advanced fields you can use within XperiDo.
6.4 Mapping a field
Mapping a field from your dataset onto your template can be done by following these steps:
1) First, place the cursor at the spot in the document where you want the mapping to be:
2) Next, select the field you want to map. To do this, click its name in the XperiDo pane:
3) Then, you do one of the following: double-click the selected field in the XperiDo pane or click the
Data Field icon in the XperiDo pane:
User manual XperiDo template design add-in for Microsoft Word 43
Your documents. Automated.
Master your data flows. Boost your output streams.
4) You'll see the mapping as follows:
5) Around the mapping, a box will be placed to clearly show that this is a mapping:
When previewing a document or when generating a document, this mapping will be replaced by data.
6.5 Mapping overview
The mapping tab in the XperiDo pane shows you the mappings that are currently in the template. You can jump to any mapping by clicking it in the mapping tab. Inversely, if you click a mapping in your document, it will be highlighted in the mapping tab.
The mapping tab has four controls that you can use to manipulate the mappings in the template:
Settings : adjust the settings of the selected mapping.
Delete : delete the mapping.
User manual XperiDo template design add-in for Microsoft Word 44
Your documents. Automated.
Master your data flows. Boost your output streams.
Toggle View : toggle between the full fieldname and the short fieldname view:
Refresh : refresh the mappings.
6.6 Field names
A field in XperiDo can have multiple names. When using XperiDo for Microsoft Dynamics CRM , each field has a display name, a logical name and a schema name. Behind the scenes, XperiDo always uses the schema name for fields.
In the mapping tab of the XperiDo pane, the schema name is shown - but in the data source tab of the XperiDo pane, the display name is shown. This behaviour can be changed so that the data source tab shows the schema name. To do this, go to the XperiDo options by clicking Properties in the XperiDo ribbon. Then, in the general options, deselect Use alternate names for fields .
When creating a dataset in XperiDo for Microsoft Dynamics CRM, the display name of the fields is decided based on CRM's UI language . That means that, when you create a data set with your UI language set to Dutch, that Word will show these fields' names in Dutch (when available) in the data source tab. However, the mapping tab will still show the schema names, which are in English.
6.7 Templates without a data source
When you open a template that does not have a data set linked to it, the XperiDo ribbon looks a bit different:
User manual XperiDo template design add-in for Microsoft Word 45
Your documents. Automated.
Master your data flows. Boost your output streams.
As well as a simplifief ribbon, the XperiDo pane is completely hidden since there is no data set and thus there are no mappings.
User manual XperiDo template design add-in for Microsoft Word 46
Your documents. Automated.
Master your data flows. Boost your output streams.
7 Revision control
When there are multiple template designers, it is counter-productive if some of them are working on the same template at the same time. They might overwrite each other's changes, so that neither makes any significant progress. To prevent that from happening, XperiDo features a revision control system.
7.1 Concept
The revision control system puts a lock on every template. When a template designer checks out a template for editing, he locks the template on it so that other template designers can no longer edit it until that same template designer checks the template back in, which releases the lock.
7.2 Opening a template
Depending on the state of the template, different options are available.
7.2.1 Opening an unlocked template
When you select an unlocked template, you'll see the following icon at the top:
This lets you know that the template currently isn't locked by anyone, which means you can:
Open it: this creates a local copy of the template on your machine, but the template stays unlocked because you didn't check it out . A warning message will inform you that any changes you make will not be saved unless you check out the template and check it back in to the server. Open is useful for when you want to view a template without editing it.
Open and check out : this creates a local copy of the template on your machine, increases the version number and locks the template on the server so that no-one else can edit it while you're editing it. Use this if you want to make changes to the template.
User manual XperiDo template design add-in for Microsoft Word 47
Your documents. Automated.
Master your data flows. Boost your output streams.
If you intend on editing a template, it is advised to immediately check it out when opening it (by clicking Open and check out ). But you can also open it, make changes, and check it out later.
7.2.2 Opening a template that has been checked out by you
When you select a template that you have checked out, you'll see the following icon at the top:
This indicates that you have locked this template, which means that you can:
Open it : this creates a local copy of the template on your machine and keeps the template locked so that only you can edit it.
Release the lock : this releases the lock you have on the template. A warning message will inform you that no changes will be committed.
7.2.3 Opening a template that has been checked out by somebody else
When you select a template that someone else has checked out, you'll see the following icon at the top:
This indicates that someone else has locked this template, which means you can:
Open it: this creates a local copy of the template on your machine. A warning message will inform you that any changes you make will not be saved unless the other person unlocks the template.
User manual XperiDo template design add-in for Microsoft Word 48
Your documents. Automated.
Master your data flows. Boost your output streams.
Release the lock : this releases the lock the other person has on the template. A warning message will inform you that releasing someone else's lock will prevent them from continuing.
7.3 Options within a checked out template
When working in a template that you've checked out, the following options are available:
7.3.1 Check in
This checks in the template to the central repository and unlocks it again. A window will pop up, allowing you to comment on the version you're checking in.
User manual XperiDo template design add-in for Microsoft Word 49
Your documents. Automated.
Master your data flows. Boost your output streams.
Under the comment box, you can also choose a previously entered comment , or click the button next to it to copy the comment from the previous version. Click OK to check in the template. This updates the version on the server and unlocks it.
7.3.2 Show history
This brings up a window that shows the history of the template - who created what version, when and what they commented.
User manual XperiDo template design add-in for Microsoft Word 50
Your documents. Automated.
Master your data flows. Boost your output streams.
Click a version to select it. Then, you can click the Rollback button to change the content of the current version back to the content of the selected version. Note that no version is over overwritten when rolling back, as rollback simply creates a new version and copies the content from the version you selected. This means that you can always roll back to any version that was checked in.
7.3.3 Cancel edit
This cancels the edits you've made so far. The current version will be abandoned and the template will be locked again, freeing it up for other template designers.
7.4 Options within an unlocked template
When working in a template that's unlocked, the following options are available:
User manual XperiDo template design add-in for Microsoft Word 51
Your documents. Automated.
Master your data flows. Boost your output streams.
7.4.1 Check out
Lock the template on the server so no-one else can make changes to it. This also increases the version number of your local copy, so that the previous copy doesn't get overwritten.
7.4.2 Revert to server version
This removes all the changes you've made since opening the template and reverts it back to the version found on the server. A warning message will inform you that you will lose your changes.
7.5 Administrator privileges
While unlikely, it is possible that an administrator locks or unlocks a template directly on the server while you have it opened. Should this occur, the following message will appear:
In this case, it is best to contact your system administrator and check with them what they changed and why.
There usually is a good reason for the change, so we advise to click Yes so you get the latest version from the server.
User manual XperiDo template design add-in for Microsoft Word 52
Your documents. Automated.
Master your data flows. Boost your output streams.
8 Previews
XperiDo allows you to preview the template you're making, so that you can check what your document will look like.
8.1 Concept
Previews are temporary documents that you create with sample data. They are an important part of the template design process, as they allow you to quickly check the impact of the changes you made in the template.
Because data sets do not contain data, you cannot preview with just a template and a data set. The data you need comes from samples , which hold sample data that you can use for previews.
8.2 Samples
Previewing requires that you have at least one sample attached to the data set of this template. You can attach multiple samples to a data set, which allows you to generate multiple previews - this comes in handy when you want to test your template with different values.
To see whether a sample is attached to your template, click the Samples button in the XperiDo ribbon:
In the above image, there is one sample called ShippingOrderXML.xml
. The blue area around the icon next to the sample name shows that it is currently selected; this is always the case when there is only one available sample. If you have multiple samples, click the one you want to use to select it.
There are two ways to review the content of a sample: the Show sample option and the Field inspector .
8.2.1 Show sample
Click Show sample in the Samples submenu to bring up the following window:
User manual XperiDo template design add-in for Microsoft Word 53
Your documents. Automated.
Master your data flows. Boost your output streams.
In this window, the content of the current sample is shown in XML format . Should your XML not be formatted in a visually appealing way, you can click Pretty Print at the top to re-structure the XML.
If you have a very large sample and you are looking for something, it might be a good idea to use the Find button:
User manual XperiDo template design add-in for Microsoft Word 54
Your documents. Automated.
Master your data flows. Boost your output streams.
8.2.2 Field inspector
The Field inspector is a more user-friendly way of displaying the content of the current sample. First, click on a field in the datasource tab of the XperiDo pane:
Then, the Field inspector (below the datasource) shows the content of the selected element (and its children):
User manual XperiDo template design add-in for Microsoft Word 55
Your documents. Automated.
Master your data flows. Boost your output streams.
The Field inspector is a very easy way of checking whether you are mapping the correct field.
8.3 Previewing
If you want to preview your template, click Preview in the XperiDo ribbon:
Clicking the lower part of the button brings up the following dropdown:
User manual XperiDo template design add-in for Microsoft Word 56
Your documents. Automated.
Master your data flows. Boost your output streams.
This dropdown asks you to choose the format for the resulting document. Click the format of your choice to generate the document.
You can also click the upper part of the button:
In this case, a window pops up:
User manual XperiDo template design add-in for Microsoft Word 57
Your documents. Automated.
Master your data flows. Boost your output streams.
Here, you can choose the default format to use for the generated document. Selecting one here is the same as selecting a format in the XperiDo options :
If you select a format, then clicking on the upper part of the Preview button automatically generates a document in the specified format.
8.3.1 Previewing a template not locked by you
When you try to preview a template that isn't locked by you, you will get the following warning:
User manual XperiDo template design add-in for Microsoft Word 58
Your documents. Automated.
Master your data flows. Boost your output streams.
While you are able to generate a preview, the preview will not contain the changes you might have made to the template.
8.4 Refreshing
Whenever a new or updated version of a data source, sample, template or asset is available on the server, it will not be automatically updated in the XperiDo add-in. For instance, updating a sample in XperiDo for Dynamics
CRM doesn't automatically update the sample in the XperiDo add-in.
To update all of the items related to a template, click the Refresh button in the XperiDo ribbon:
Refreshing your template when you suspect changes to any of the related items is a good way of making sure that you're working with the latest version of the data source, sample etc.
User manual XperiDo template design add-in for Microsoft Word 59
Your documents. Automated.
Master your data flows. Boost your output streams.
9 Loops
Loops are one of the basic functions of the XperiDo add-in. With loops, you have the possibility to map a set of recurring items in a list. You can use loops when you have multiple items you want to show, such as a list of contacts, products or services.
9.1 Concept
Looping in XperiDo is done by following these steps:
1) Select the zone to loop over.
2) Select the recurring field in your dataset.
3) Finalize the loop.
You can then further tweak the loop's settings.
9.1.1 Loop box
When you create a loop in XperiDo, you are actually creating a loop box . A loop box designates the zone that should be repeated for every recurring element.
The following example shows a loop over the item field:
Everything inside the loop box is repeated. Mappings, tables, plain text, images - everything.
9.2 Creating a loop
To create a loop, follow these steps:
1) Either place your cursor in the document, or highlight a zone.
User manual XperiDo template design add-in for Microsoft Word 60
Your documents. Automated.
Master your data flows. Boost your output streams.
2) Select the element in your data set that you want to loop over. Note that this element must be recurring.
3) Click Loop in the XperiDo pane.
4) A loop box will now be inserted. If you just placed your cursor, it will be a one-line loop box. If you selected a zone, it will be a loop box that contains that zone.
User manual XperiDo template design add-in for Microsoft Word 61
Your documents. Automated.
Master your data flows. Boost your output streams.
Note that you do not have to select existing content around which to create a loop box - you can also add content to the box afterwards.
If you want to learn more about how to work with boxes, you can read this article.
9.2.1 Continuity
You can affect the continuity between iterations by inserting the right symbol in the loop box. A few examples:
Putting a ¶ (pilcrow) inside the loop box...
...results in a new paragraph per iteration:
On the other hand, putting spaces in the loop box...
User manual XperiDo template design add-in for Microsoft Word 62
Your documents. Automated.
Master your data flows. Boost your output streams.
...results in spaces being put in between the iterations:
To achieve this, first create your loop, put your cursor behind it (or on the following line) and hit the left key on your keyboard until the cursor is in the loop box (you'll notice when the box becomes visible). Then you can insert your spaces.
If you plan on inserting a word, a comma or something similiar, it might be a good idea to read this article .
9.2.2 Selecting the correct field
An oft-made mistake is selecting the wrong field, which results in the loop box content only being shown once
- or not at all.
For instance, the following screenshot shows a data set that was created with XperiDo for Microsoft Dynamics
CRM :
This data set contains information about one account and multiple contacts associated with that account. The
Contact field is recurring, so you can use it in your loops.
A level higher than the Contact field, we see the contact_customer_accounts field. This is actually a relationship field which binds the Account with its multiple Contacts:
User manual XperiDo template design add-in for Microsoft Word 63
Your documents. Automated.
Master your data flows. Boost your output streams.
When you are choosing the field to loop over, it is important to select the recurring field and not the relationship field.
9.3 Common loop uses
Because loops repeat a certain element, they are basically a kind of list. This makes them ideal to use in conjunction with bullet/numbered lists and table rows.
9.3.1 Bullet lists
If you want to use a bullet list in your loops, you need to create a list with one item and select that as the zone to loop over, like in the following example:
Then, clicking the loop icon results in this:
Here's what the document looks like:
You could go even further and multi-level lists:
User manual XperiDo template design add-in for Microsoft Word 64
Your documents. Automated.
Master your data flows. Boost your output streams.
This is the output:
9.3.2 Numbered lists
Numbered lists work exactly the same as bullet lists. Create a list with one item and loop over that one item.
This is the output:
Again, multi-level lists are no problem:
Here's the output:
User manual XperiDo template design add-in for Microsoft Word 65
Your documents. Automated.
Master your data flows. Boost your output streams.
9.3.3 Table rows
You can use Word tables to loop over table rows. Doing this adds a table row for each recurring element, which is a good way of presenting a list.
Follow these steps to loop over a table row:
1) Create your table by using the standard Word table functionality. In this example, we've set up a 3x2 table.
2) Insert your content. We've added headers in the first row and mappings in the second row.
3) Select the entire second row. It is important that you select the entire row, you can be sure of this by clicking to the left of the row, at the position where the mouse pointer changes :
4) Select the field you want to loop over, then click Loop . You'll see that a loop box has been added.
User manual XperiDo template design add-in for Microsoft Word 66
Your documents. Automated.
Master your data flows. Boost your output streams.
5) Finally (and optionally), style the table and the elements in it. You can use Word's table design tools for this.
Now a loop over the row is in place. You can verify this in the Mapping tab of the XperiDo pane:
All that's left to do is see what the document looks like:
User manual XperiDo template design add-in for Microsoft Word 67
Your documents. Automated.
Master your data flows. Boost your output streams.
Note that you cannot loop over multiple table rows at once - either you pick one or you loop over the entire table. If you want to loop over multiple rows, you need to insert a table (with multiple rows) inside another table and then loop over the row that contains the table.
9.3.4 Looping without a recurring element
A less common way of looping (but still relevant) is looping a number of times without using a recurring element. You can read more about this here .
9.4 Loop settings
You can customize a loop's settings to change its behaviour. To access these settings, select the loop in the
Mapping tab and click Settings .
In the window that pops up, you can change the loop settings.
User manual XperiDo template design add-in for Microsoft Word 68
Your documents. Automated.
Master your data flows. Boost your output streams.
9.4.1 Field vs XPath expression
On the left side of the window, you can change the field to loop over. The field that is selected here is the one that you selected before clicking Loop .
Instead of using a field, you can use an XPath expression . In rare cases, this can be useful - but this is usually reserved for very specific applications. More information about XPath can be found here .
9.4.2 Insert break on each iteration after first
This setting affects the continuity between iterations of a loop. There are 4 settings:
Nobreak : the next iteration is placed directly after the previous one.
Textwrapping : the next iteration is placed on the next line, within the same paragraph.
Column : the next iteration is placed in the next column. If there is no next column, it will be placed on the next page.
Page : the next iteration is placed on the next page.
Note that you can affect the continuity yourself by putting a break symbol in the loop box. You can read more
9.4.3 Enable sorting
Enabling this setting allows you to sort your loop.
User manual XperiDo template design add-in for Microsoft Word 69
Your documents. Automated.
Master your data flows. Boost your output streams.
Sorting is done over a particular field, which you can select by clicking the button in the Field box. In the window that pops up, you select your field and click OK .
It is important that you choose the correct Datatype , as not every type reacts the same way to sorting. For instance, when sorting numbers as text, you'll end up with 1, 10, 2, 3 instead of 1, 2, 3, 10 .
The following options exist:
Text : when your field is a text field (string).
Number : when your field is a number (integer/float).
Date : when your field is a date.
Time : when your field is a time.
DateTime : when your field is a date and a time.
You can also define the Order in which to sort (ascending or descending).
Finally, for text sorting, you can choose how case should be treated by changing the Case-order setting:
Upper first : uppercase comes before lowercase.
Lower first : lowercase comes before uppercase.
Ignore case : lowercase and uppercase letters are treated equally.
User manual XperiDo template design add-in for Microsoft Word 70
Your documents. Automated.
Master your data flows. Boost your output streams.
9.4.4 Loop in reversed order
Enabling this setting reverses the order in which you loop.
9.4.5 Only iterate over the first/last X occurences
Enabling these settings allows you to only loop over a part of the recurring items. Click the number to bring up a window where you can change it:
9.4.6 Remove the last paragraph of each iteration
Enabling this setting removes the last paragraph of each iteration.
9.4.7 Precedence rules
When multiple options are selected, this is the order in which they are executed:
1) Loop in reversed order
2) Only iterate over the first/last X occurences
3) Sorting
For instance, let's say that the set you want to loop over is (ABCD) . Here's what happens:
1) Loop in reversed order: set becomes (DCBA)
2) Only iterate over the first 2 occurences: set becomes (DC)
3) Sort descending: set becomes (CD)
User manual XperiDo template design add-in for Microsoft Word 71
Your documents. Automated.
Master your data flows. Boost your output streams.
10 Groups
Groups give you the power to display items in a loop in groups, instead of all together. This can be used for splitting content into e.g. product types, departments etc.
10.1 Concept
Grouping in XperiDo is done by following these steps:
1) Create a regular loop.
2) Select the zone to group over. The loop should be in this zone.
3) Select the field according to which you want to group the items. This is called the grouping field .
4) Finalize the group.
For instance, here's an ungrouped loop:
And here is the loop grouped according to type :
10.1.1 Group box
When you create a group in XperiDo, you are actually creating a group box . A group box designates the zone that should be repeated for every different value the grouping field has.
There are typically two ways to use the group box: embedded or separate . The difference lies in the position of the group box.
User manual XperiDo template design add-in for Microsoft Word 72
Your documents. Automated.
Master your data flows. Boost your output streams.
10.1.1.1 Embedded
An embedded group box is a group box that is placed directly around the loop box. Let's explain this with an example.
The following is a 2-row table with a loop box (in yellow) over the second row. This sets up the table for looping over the second row:
Creating a document from such a table will result in this:
If we now put an embedded group box in there (in blue) , we get the following scenario:
This is the output:
So, an embedded group box simply re-arranges the loop by grouping the items according to the grouping field.
User manual XperiDo template design add-in for Microsoft Word 73
Your documents. Automated.
Master your data flows. Boost your output streams.
An embedded group box is typically used when you want to sort a loop twice: once in the loop's settings and once using an embedded group box.
10.1.1.2 Separate
A separate group box also works with a loop box, but it defines a larger area. The difference is that not just the loop will be grouped, but everything else inside the group box will also be repeated. Let's explain this with an example.
Here's a diagram of the table (loop box in yellow):
And here's the table with a separate group box (in blue ) which fully encapsulates the table:
This results in the following:
Because the group box included the entire table, the entire table is shown 3 times (since there are 3 types and type is the grouping field).
User manual XperiDo template design add-in for Microsoft Word 74
Your documents. Automated.
Master your data flows. Boost your output streams.
10.2 Creating a group
In order to create a valid group, you need to have a loop box ready around which you can create your group box.
So, once you've set up your loop, follow these steps to set up your group:
1) Select the zone that should be in your group box. Make sure to include the loop.
If you want to use an embedded group over a table row, be sure to select the row by hovering left to the row and clicking where the mouse pointer changes:
2) In your data set, select the grouping field , which is the field according to which you want to group the items.
3) Click Group in the XperiDo pane.
4) A group box will now be inserted.
User manual XperiDo template design add-in for Microsoft Word 75
Your documents. Automated.
Master your data flows. Boost your output streams.
In the Mapping tab of the XperiDo pane, you'll see that the loop is inside the group.
10.2.1 Working with boxes
Since you're always using groups in combination with loops, it's a good idea to take a look at this article , which explains how to work with boxes - loop boxes, group boxes etc.
10.3 Group settings
You can customize a group's settings to change its behaviour. To access these settings, select the group in the
Mapping tab and click Settings .
In the window that pops up, you can change the group settings.
User manual XperiDo template design add-in for Microsoft Word 76
Your documents. Automated.
Master your data flows. Boost your output streams.
10.3.1 Insert break on each iteration after first
This setting affects the continuity between iterations of a group. There are 4 settings:
Nobreak : the next iteration is placed directly after the previous one.
Textwrapping : the next iteration is placed on the next line, within the same paragraph.
Column : the next iteration is placed in the next column. If there is no next column, it will be placed on the next page.
Page : the next iteration is placed on the next page.
Note that you can affect the continuity yourself by putting a break symbol in the group box. You can read more
about this here (written for loops, but the same principle applies to group boxes).
10.3.2 Loop in reversed order
Enabling this setting reverses the order in which you loop the group.
10.3.3 Only iterate over the first/last X occurences
Enabling these settings allows you to only group a part of the recurring items. Click the number to bring up a window where you can change it:
User manual XperiDo template design add-in for Microsoft Word 77
Your documents. Automated.
Master your data flows. Boost your output streams.
10.3.4 Enable sorting
Enabling this setting allows you to sort your group.
It is important that you choose the correct Datatype , as not every type reacts the same way to sorting. For instance, when sorting numbers as text, you'll end up with 1, 10, 2, 3 instead of 1, 2, 3, 10 .
The following options exist:
Text : when your field is a text field (string).
Number : when your field is a number (integer/float).
Date : when your field is a date.
Time : when your field is a time.
DateTime : when your field is a date and a time.
You can also define the Order in which to sort (ascending or descending).
Finally, for text sorting, you can choose how case should be treated by changing the Case-order setting:
Upper first : uppercase comes before lowercase.
Lower first : lowercase comes before uppercase.
Ignore case : lowercase and uppercase letters are treated equally.
User manual XperiDo template design add-in for Microsoft Word 78
Your documents. Automated.
Master your data flows. Boost your output streams.
11 Formatting
When working with data, it is important that that data is formatted correctly - otherwise it might get interpreted incorrectly. To make sure that your data is formatted the way you want it to be, XperiDo has plenty of formatting options.
11.1 Concept
When a field is mapped, you can format it to alter the content. You can turn the field into a number, data, time, an image, a barcode, a hyperlink, an e-signature... All of these change the original mapping's content to something else - that's formatting .
11.1.1 The XperiDo Mapping window
The XperiDo Mapping window is where you apply formatting to your mapping. Double-click a mapping in the
Mapping tab of the XperiDo pane (or select a mapping and click Settings ) to bring it up. Here's the formatting part of that window:
We'll go over all the tabs (Font, Format etc.) in this chapter.
The other parts of the XperiDo Mapping window are explained in the Conditional content chapter .
11.1.2 Reset to default
If you want to reset your mapping's settings to the default values, you can click the Reset to default button:
User manual XperiDo template design add-in for Microsoft Word 79
Your documents. Automated.
Master your data flows. Boost your output streams.
11.2 Font
This tab can be used to style your mapping. You can change the font, color, weight etc.
You can find more information about this tab in the Styling chapter .
11.3 Format
This tab can be used to change the data type of your field. You can convert your field into a number, currency, date, time, percentage, text or any custom type.
By default, all fields are interpreted as text:
Note that displaying numbers as text may make them appear correct, but that you'll need to convert them to numbers/currencies if you want to use them in calculations.
11.3.1 Numbers, times & dates
How the number, time and date formats work is covered in the Numbers & dates chapter .
11.3.2 Capturing groups
Capturing groups can be used to disassemble a field into groups, after which you can choose which of those groups to show and in which order.
11.3.2.1 Creating, moving and removing groups
First, you need to create your groups. Click the green plus to add a new group:
You can add more groups by clicking the green plus . Select a group and click the red X to remove a group.
Finally, you can move a group up or down the list by selecting it and clicking the up or down arrows .
User manual XperiDo template design add-in for Microsoft Word 80
Your documents. Automated.
Master your data flows. Boost your output streams.
11.3.2.2 Defining groups
Now that you've created your groups, you need to define them. Click the .*?
button in a group's text box to bring up a list of regular expressions which you can use to define your group:
You can select one the expressions ( this page has more information about regular expressions) and click OK to insert it, or you can type it in yourself in the text box:
11.3.2.3 Setting the output
Once you've set up and defined your groups, you can decide how to output them. You can type in the group identifiers (such as {0}) and other characters in the Assemble Output text box:
For instance, if group {0} contains A , group {1} contains B and the output is set as in the above screenshot, then this will be the output: A/B.B.B
.
11.3.2.4 Example
Capturing groups is a powerful feature, but it can get quite complex - so let's use a real-life example. Take the following setup, which we use for formatting a telephone number:
User manual XperiDo template design add-in for Microsoft Word 81
Your documents. Automated.
Master your data flows. Boost your output streams.
This setup defines 4 groups with the following rules:
Group {0} contains the first 2 characters of the mapping's content (a dot means any character).
Group {1} contains the following 3 characters.
Group {2} contains the following 2 characters.
Group {3} contains the following 2 characters.
The telephone number that we want to format is 047770123 . This means that the groups will contain the following:
Group {0} : 04
Group {1} : 777
Group {2} : 01
Group {3} : 23
Finally, here's how we set up our output:
This results in the following output: 04/777.01.23
Formatting telephone numbers is only one very basic example, but this should give you an idea of what is possible with capturing groups.
11.4 Text editing
This tab can be used to replace parts of your text, or to insert parts into your text.
11.4.1 Replacing text
To replace part of your text, type the part you wish to replace in the left text box , and the part you wish to replace it with in the right text box :
User manual XperiDo template design add-in for Microsoft Word 82
Your documents. Automated.
Master your data flows. Boost your output streams.
This example will replace all lowercase occurences of invenso with INVENSO. Click the ellipsis ( ...
) to bring up more options:
In here, you can change some settings:
Ignore case : check this if you want to treat lowercase and uppercase letters the same. When this is checked, there is no difference between BLUE, blue, bLUe, Blue etc.
Normal search mode : the text is considered to be plain text without special characters.
Extended search mode : this allows the insertion of special characters in the text. This wikipedia page has more information about special characters.
Regular Expression search mode : this treats the text as a regular expression. This page has more information about regular expressions.
Click OK to save the settings for that text replacement.
After you've set up the text replacement, click the green plus to add it to the list:
You can add multiple text replacements and move the order in which they are checked by selecting one of them and clicking the up and down arrows. If you want to remove a text replacement, select it and click the red
X . Finally, you can update a text replacement by selecting it, changing the text/settings and clicking the update button:
User manual XperiDo template design add-in for Microsoft Word 83
Your documents. Automated.
Master your data flows. Boost your output streams.
11.4.2 Inserting text
To insert text, type the text you want to insert in the text box , choose the position where you want to insert it and click the green plus :
This adds the text insert to the list of text inserts.
There are multiple positions to insert your text:
At the beginning : the typed text is inserted at the beginning of the field's text.
At the end : the typed text is added to the end of the field's text.
From start (forwards) : the typed text is added in the position you specify to the right. 0 is at the beginning, 1 is after the first character etc.
From end (backwards) : the typed text is added in the position you specifiy to the right. 0 is at the end, 1 is before the last character etc.
You can add multiple text inserts and move the order in which they are checked by selecting one of them and clicking the up and down arrows. If you want to remove a text insert, select it and click the red X . Finally, you can update a text insert by selecting it, changing the text/settings and clicking the update button:
11.5 Convert to image/barcode
These tabs can be used to convert your mapping into an image or a barcode.
You can find more information about this tab in the Images & Barcodes chapter.
11.6 Rules
This tab can be used for setting various rules that impact the formatting of your mapping.
User manual XperiDo template design add-in for Microsoft Word 84
Your documents. Automated.
Master your data flows. Boost your output streams.
11.6.1 Removing blank paragraphs
Check the box Remove the paragraph this mapping is in when the value is not specified or blank if you want to prevent blank lines from appearing in this mapping.
For instance, this is very useful when dealing with addresses. Typically, addresses are input in address lines, but not every line is always used:
Turning on this setting fixes this:
11.6.2 Creating hyperlinks
Check the box Create a hyperlink to render your mapping as a clickable hyperlink. The mapping will still contain whatever is in it, but you can define a URL that is links to when you click it.
Insert the URL that you want to go to in the Hyperlink Target text box, or click the button in the text box to insert a field's value for the hyperlink target.
You can change what is shown when hovering over the link in the Tooltip text box. You can insert a field's value by clicking the button in the text box.
11.6.2.1 E-mail hyperlink
If you want to create an e-mail hyperlink, follow these steps:
User manual XperiDo template design add-in for Microsoft Word 85
Your documents. Automated.
Master your data flows. Boost your output streams.
1) Create a pseudo-field of type Text .
2) Give it the value concat('mailto://',${field with link}) , where ${field with link} is the field that contains the link. Insert this by dragging it from the data set.
3) Then, use this created field as the Hyperlink Target by selecting it from the data set after clicking the button inside the Hyperlink Target text box.
By adding the mailto:// , the field is specified to be an e-mail link.
11.6.3 Preserving formatted text
Check the box Preserve formatted text to keep the field's original text formatting. This is very useful for e.g. including HTML text, or entire docx files. These types of content have formatting applied to them, which might lead to XperiDo misinterpreting this formatting.
Note that activating this setting causes Word's and XperiDo's font settings to be ignored. For more information, please read this article.
Once activated, more settings appear:
Format : T he format in which the original content is. We strongly advise you to find the right format before trying the Auto setting.
Import Format mode : what to do with the Word styles that are used in the formatted data. (note that every format is converted to docx before being inserted in the template, which means that all content is assigned a Word style) o
Use destination styles means that your current template's Word styles will overwrite the ones found in the original content. o
Keep source formatting keeps the original styles intact. (as said above, all content is assigned a
Word style. Plain text will get the Normal style, HTML H1 will become Heading 1 etc. The best way
User manual XperiDo template design add-in for Microsoft Word 86
Your documents. Automated.
Master your data flows. Boost your output streams.
of determining how XperiDo converts your original content into Word styles is to preview your template in docx format and then see which styles are assigned to the content)
Datasource : the data type of the value of the mapped field. The following values are available: o
Value : this treats the value of the mapped field as plain text. o
Fileshare : this treats the value of the mapped field as a link to a file, relative to the XperiDo server.
You can use this to get the data from files on the XperiDo server. If you use this option, know that you need to specify the path in between apostrophes and by using forward slashes , like this example: 'c:/temp/file.doc' . o
Repository : this treats the value of the mapped field as a link to a filed in the XperiDo repository.
For instance, /Project/Group/File.docx
. o
URL : this treats the value of the mapped field as a URL. You can use this to get the content of a web page.
Data is base64 encoded : check this when the data is base64 encoded.
Skip external content : checking this prevents XperiDo from waiting on web content that doesn't load by skipping its content. For instance, when including a Word file that has links to images on a website, this setting would not let XperiDo wait until the images are retrieved - the cached versions will be used.
Remove empty paragraphs at the end : check this if you want to remove empty paragraphs at the end.
Finally, there's one more setting, Insert as image .
This setting can be used when you want to insert the content as an image rather than text. This is especially useful for inserting PDF files, as you cannot insert their content as text.
Checking this setting opens up another Settings button. Clicking that brings up a window where you can adjust the image's position, size, text wrapping etc. like you can do with regular Word images.
11.6.4 Converting case
Check the box Apply advanced case-convert rules to change the casing of certain letters in a text.
The following options are available:
Don't change : the text stays as it is.
Sentence case : everything is converted to lowercase, except the first letter and every letter following a dot.
lowercase : everything is converted to lowercase.
UPPERCASE : everything is converted to uppercase.
User manual XperiDo template design add-in for Microsoft Word 87
Your documents. Automated.
Master your data flows. Boost your output streams.
Capitalize Each Word : everything is converted to lowercase except the first letter of each word.
tOGGLE cASE : invert the case of each character.
11.7 E-signature
This tab can be used to convert your mapping into an electronic signature.
You can find more information about this tab in the Electronic signatures chapter .
User manual XperiDo template design add-in for Microsoft Word 88
Your documents. Automated.
Master your data flows. Boost your output streams.
12 Numbers & dates
XperiDo offers you the possibility of using formatted numbers and dates. This article explains what you need to know to use them effectively.
12.1 Set the formatting
The most important part of working with numbers & dates is formatting them as such. You can do this in the
Format tab of the XperiDo Mapping window.
You can access this window by double-clicking a mapping in the Mapping tab of the XperiDo pane.
12.1.1 Format as number
In the Format tab, you can select Number :
User manual XperiDo template design add-in for Microsoft Word 89
Your documents. Automated.
Master your data flows. Boost your output streams.
Here, you can set the number of decimal places and whether to use a 1000 separator. You can also set the
Format Locale , which is explained below. Select Percentage instead of Number to format your field as a percentage:
You can also select Custom Number , which allows you to customize the number formatting:
12.1.2 Format as currency
In the Format tab, you can select Currency :
Here, you can set the number of decimal places and whether to use a 1000 separator. You can choose the symbol to use, and whether to show it before or after the number. You can also set the Format Locale , which is explained below.
You can also select Custom Number , which contains options for formatting as a custom currency as well:
User manual XperiDo template design add-in for Microsoft Word 90
Your documents. Automated.
Master your data flows. Boost your output streams.
12.1.3 Format as date/time
In the Format tab, you can select Date :
Here, you can choose how you want your date to be formatted. You can also set the Format Locale , which is explained below.
You can also select Time , which you can use for formatting times:
Select DateTime if you want to include the time as well as the date:
User manual XperiDo template design add-in for Microsoft Word 91
Your documents. Automated.
Master your data flows. Boost your output streams.
Finaly, you can select Custom Date , which allows you to customize the formatting:
12.2 Locale
A locale is a set of parameters that defines the user's language, country and any special variant preferences.
XperiDo uses these parameters to interpret or output data in a certain way.
12.2.1 Document locale
The document locale determines how input data is converted to usable numbers/dates/times. Setting your document locale correctly is very important, as this effectively tells the add-in how it should treat (for instance) a comma or a dot. Some languages use a comma as a 1000 separator and a dot as a decimal separator, while other languages do it the other way around.
Setting the document locale can be done in the XperiDo options, data formatting tab. You can access the options by clicking Properties in the XperiDo ribbon:
User manual XperiDo template design add-in for Microsoft Word 92
Your documents. Automated.
Master your data flows. Boost your output streams.
12.2.2 Format locale
The format locale determines the formatting of your output. For instance, when you choose to format your field as a Number , the locale then decides which symbols will be used for the 1000 separator and decimal separator.
12.2.3 Difference between document locale and format locale
Simply put, the document locale determines how your input data is interpreted , while the format locale determines the formatting of your output . In other words, input data is converted to a usable number/date, after which you decide how it looks in the final document.
12.3 Examples
We'll use the following example to explain t he difference between the document locale and formate locale:
This is our input data: 10,000.25
In the mapping settings' Format tab, we choose to use a 1000 separator and 2 decimal places
Then, we use the following document locale and formate locale:
User manual XperiDo template design add-in for Microsoft Word 93
Your documents. Automated.
Master your data flows. Boost your output streams.
Document locale: el_GR (Greek, Greece) o
1000 separator: . (dot) o
Decimal separator: , (comma)
Format locale: en_GB (English, United Kingdom) o
1000 separator: , (comma) o
Decimal separator: . (dot)
The document locale is wrongly set to Greek - it's wrong because the input data uses a comma for the 1000 separator and a dot for the decimal separator , whereas the Greek locale is the other way around. Now that the input data is processed incorrectly, the format locale doesn't matter - it won't ever be shown correctly.
To show you how important the correct locale is, here is the result of processing the input data as Greek and outputting it as English: 100,002,500.00
. This is completely wrong!
Here's an example, using the same input data but a different document locale:
Document locale: en_GB (English, United Kingdom) o
1000 separator: , (comma) o
Decimal separator: . (dot)
Format locale: en_GB (English, United Kingdom) o
1000 separator: , (comma) o
Decimal separator: . (dot)
This document locale is correct, as our input data uses the same 1000 and decimal separator as the document locale. Here's the result of this locale setup: 10,000.25
. That's how we wanted it!
Now that the document locale is correct, we can use a different format locale to format the output according to the user's preference. For instance, we're setting up a template for use in Dutch-speaking Belgium, so we use the following locale:
Format locale: nl_BE (Dutch, Belgium) o
1000 separator: . (dot) o
Decimal separator: , (comma)
Here's the result of the output: 10.000,25 . Notice how this differs from the input data ( 10,000.25
) only in the
1000 and decimal separators.
12.4 What you can do
Now that you know how the document locale and format locale work, you should try and match the document locale to the input data. This ensures that XperiDo uses the correct values. Once you have that set up properly,
User manual XperiDo template design add-in for Microsoft Word 94
Your documents. Automated.
Master your data flows. Boost your output streams.
you can decide how you want to output your numbers/dates. Using a different format locale is most useful when working with multiple countries that use different 1000 and/or decimal separators.
User manual XperiDo template design add-in for Microsoft Word 95
Your documents. Automated.
Master your data flows. Boost your output streams.
13 Images & barcodes
While you can use Word's image functionality for inserting static images, XperiDo allows you to insert variable images, convert fields to images, retrieve images from URL etc. How to do that is explained in this chapter.
13.1 Concept
To insert an image/barcode, you have to convert an XperiDo mapping's value to an image/barcode . There are different ways to convert an XperiDo mapping's value to an image:
Asset : here you use a value from the XperiDo Assets folder (more information about XperiDo Assets below).
Asset lookup : here you link each value to a different image from the XperiDo Assets. Depending on the value, a different image is shown.
URL : here you get the image from the internet.
Fileshare : here you retrieve the image from the XperiDo server.
Binary encoded : here the image is stored as a base64 string.
Insert document as image : here a separate document is inserted as an image.
For barcodes, you need to supply the barcode code in a field in your data.
13.2 XperiDo Assets
XperiDo Assets are images that you can add to your project. These images can then be used in all of your templates.
To access your assets, click XperiDo Assets in the XperiDo ribbon:
This brings up the XperiDo Assets manager :
User manual XperiDo template design add-in for Microsoft Word 96
Your documents. Automated.
Master your data flows. Boost your output streams.
The XperiDo Assets manager can be used to manage your assets.
13.2.1 Controls
Click Organize to bring up a submenu:
Add Image : add an image. Select the folder you wish to add it to and click Add image . Select an image from the pop-up window and click Open .
Refresh : refresh the assets.
Delete : remove an image. Select the image you wish to remove and click Delete . Click Yes to confirm.
To create a new folder, first select the parent folder, then click New Folder to create it.
Click the image button to choose your desired view:
User manual XperiDo template design add-in for Microsoft Word 97
Your documents. Automated.
Master your data flows. Boost your output streams.
To rename an image, select it and click F2 or click it again .
13.3 Converting mappings to images
Converting XperiDo mappings' values to images is done through the Convert to image tab in the XperiDo mapping window:
You can bring up this window by double-clicking a mapping in the mapping tab of the XperiDo pane, or by selecting a mapping and clicking the Settings button:
User manual XperiDo template design add-in for Microsoft Word 98
Your documents. Automated.
Master your data flows. Boost your output streams.
You can also click Image in the XperiDo ribbon to create an empty mapping with the Convert to image option enabled:
13.3.1 General controls
The Convert to image tab contains a check box that you need to check if you want the mapping to be converted into an image:
The tab offers a few further options:
Image source specification : here you choose how to convert the mapping's value into an image. o
Type : the method used to convert the mapping value. All of the presented options are further explained below. o
Link to external images : see Url (below). o
Base Location : the prefix that will be added to the mapping's value. This is useful e.g. when your mappings contain the names of the images, but not the location. Instead of adding the location in an expression, followed by the mapping's value, you can specify it in the Base Location . (an example of this can be found in Url below)
Height / Width : here you specify the height and width of the image. Don't change means that you leave the image as is.
Extra : here you can change the hover-over text in Description . Type should best be set to the format of the image.
User manual XperiDo template design add-in for Microsoft Word 99
Your documents. Automated.
Master your data flows. Boost your output streams.
13.3.2 Auto
This option will force XperiDo to guess the correct image source specification.
It is not recommended to use this option unless you cannot be sure how the data is formatted.
13.3.3 Fileshare
This option allows you to retrieve an image from the XperiDo server.
The most important thing here is that you define your image location correctly. Your mapping should contain the location with double backslashes , such as C:\\temp\\sss.png
. If you do not have the location in your data set, then you can use an expression to get the image. In the expression window, you need to enter the location in between apostrophes :
Note that these apostrophes are not needed when the value comes straight from a mapping.
13.3.4 Asset
This option allows you to use one of the images in the XperiDo Assets in your template
As with Fileshare , it's important to define the image location correctly. Specifying this location is done in the same way as you would with Fileshare (see above), except that you're looking for a file relative to your template.
By default, the XperiDo Assets are stored in a folder called Assets . This folder is on the same level as the
Templates folder, which contains your templates. This means that you need to specify the location of your image like this: ..\\Assets\\img.png
. The ..\\ means that you're going up a level.
You can specify this in the expression window:
User manual XperiDo template design add-in for Microsoft Word 100
Your documents. Automated.
Master your data flows. Boost your output streams.
You can also store this location in your data set.
13.3.5 AssetLookup
This option allows you to assign assets to certain values of your mapping. You can decide which values are linked to which image by specifiying value-image pairs in a lookup table .
When you choose this option, an extra button is unlocked:
Click the Lookup button to bring up a window:
User manual XperiDo template design add-in for Microsoft Word 101
Your documents. Automated.
Master your data flows. Boost your output streams.
13.3.5.1 Building your lookup table
The top is where you define which value is linked to which image. Type your value in the left text box:
Then, click the ...
to choose an image from the XperiDo Assets . Select the image you want and click OK :
Now you have created a value-image pair. To finalize this, click Add to add this to the lookup table.
The value-image pair is now added to the lookup table.
You can add more pairs in the same way - there is no limit to the amount of pairs you can add.
If you want to remove a value-image pair, select it in the lookup table and click Delete .
User manual XperiDo template design add-in for Microsoft Word 102
Your documents. Automated.
Master your data flows. Boost your output streams.
13.3.5.2 Default image
You can add a default image to your lookup table. This image will be used when the mapping's value does not correspond to any value in the lookup table.
To add a default image, click Select :
If you no longer want to use the default image, click Clear .
13.3.6 BinaryEncoded
This option allows you to render a base64 encoded value as an image. You can use when your data set includes images that are stored as a base64 string.
For more information about Base64, please visit http://en.wikipedia.org/wiki/Base64 .
13.3.7 Url
This option allows you to retrieve an image from a URL.
If you plan on using this option, you should be aware of the fact that every time a document is generated, the image has to be downloaded. This can impact performance. If you experience severe slowdown issues, we suggest you use the XperiDo Assets feature.
When using URL, the Base Location can prove useful. For instance, let's say your data set contains the following values: intro.png
and menu_button.png
. These are two references to images, but they are not URLs. To fix this, you can add their location to the Base Location, like this: http://www.invenso.com/images/ .
Now they refer to http://www.invenso.com/images/intro.png
and http://www.invenso.com/images/menu_button.png
.
User manual XperiDo template design add-in for Microsoft Word 103
Your documents. Automated.
Master your data flows. Boost your output streams.
Finally, there's a checkbox Link to external images .
Checking this will insert a link to the image instead of the image itself. When the document is opened, the image will then be downloaded. This has the advantage that XperiDo does not time out on images that it cannot access, but the downside is that the image must be downloaded every time the document is opened.
13.4 Converting mappings to barcodes
Converting XperiDo mappings' values to images is done through the Convert to barcode tab in the XperiDo mapping window:
You can bring up this window by double-clicking a mapping in the mapping tab of the XperiDo pane, or by selecting a mapping and clicking the Settings button:
You can also click Barcode/QRcode in the XperiDo ribbon to create an empty mapping with the Convert to barcode option enabled:
User manual XperiDo template design add-in for Microsoft Word 104
Your documents. Automated.
Master your data flows. Boost your output streams.
13.4.1 Controls
The Convert to barcode tab contains a check box that you need to check if you want the mapping to be converted into an image:
You can choose the desired barcode type in the dropdown list:
These are the types you can choose from:
Codabar
Code128
Code39
DataMatrix
Ean128
Ean13
Ean8
Interleaved2of5
ITF14
PDF417
Postnet
QRCode
RoyalMailCBC
UPCA
UPCE
USPSIntelligentMail
While every barcode type has its own settings, the General tab is the same for all barcodes:
User manual XperiDo template design add-in for Microsoft Word 105
Your documents. Automated.
Master your data flows. Boost your output streams.
Bar height : the height of the barcode's bar (in mm).
Resolution : the barcode's print resolution (in dots per inch). A higher resolution results in a more detailed print.
Scale factor : how much the barcode should be scaled. A factor of 2 scales the barcode by 200%.
Quiet zone horizontal : how much white space is added to the left and right of the barcode.
Quiet zone vertical : how much white space is added to the top and bottom of the barcode.
Anti-alias : whether you want the barcode to be anti-aliased.
The Image tab is also the same for all barcodes:
Maintain aspect-ratio : whether to keep the aspect ratio (width/height) intact when scaling the image.
For most barcodes, you will likely want to turn this setting on.
Height : the height of the barcode (in mm).
Width : the width of the barcode (in mm).
Description : the textual description of the barcode.
The Info tab shows you an example of the barcode you selected. The other tabs are barcode-specific.
User manual XperiDo template design add-in for Microsoft Word 106
Your documents. Automated.
Master your data flows. Boost your output streams.
14 Styling
Templates not only need to be functional - you'll want them to look a certain way as well. You might have a house style, design guidelines, corporate typefaces and colors that you want to incorporate in your template.
This chapter explains how to style your template with Word or XperiDo.
14.1 Concept
After a mapping has been formatted, it can be styled to make it look the way you want it to. Styling includes
(but is not limited to) the font, color, borders, text size - anything that alters the appearance of the mapping without changing the content is styling.
For more information about formatting, check out this chapter .
Styling can be done either via Word's regular styling, or you can use XperiDo's own styling options.
14.2 Styling with Word
When styling your template, Word doesn't differentiate between plain text and XperiDo mappings. This means that you can use every styling tool there is available in Word on XperiDo mappings.
To style your mapping, simply select it like you would select plain text:
Then, apply the styling of your choice.
This also applies to tables, where you can use Word's table design tools to style your tables, even if they include loops and groups:
The applied style is a banded style where every other row gets a different background color. XperiDo keeps that styling intact:
User manual XperiDo template design add-in for Microsoft Word 107
Your documents. Automated.
Master your data flows. Boost your output streams.
14.3 Styling with XperiDo's font tab
XperiDo comes with styling options as well. You can access these by double-clicking a mapping in the Mapping tab of the XperiDo pane (or clicking the mapping and then clicking the Settings button in the pane):
In the window that appears, click the Font tab:
You are now presented with the following options:
User manual XperiDo template design add-in for Microsoft Word 108
Your documents. Automated.
Master your data flows. Boost your output streams.
In here, you can change a mapping's styling by changing each setting to your liking.
14.3.1 Inheritance
If you leave a setting on Default , the value for that setting is inherited from Word. This means that every value you set explicitely here overwrites Word's setting.
For the effects, you can either turn them off, on or set them to default:
: off
: on
: default
14.3.2 How to use effectively
XperiDo's font tab is not intended to replace Word's styling options. In fact, we recommend that you use
Word's styling options as much as possible for your styling needs. XperiDo's font tab comes in handy when working with conditional styling & formatting , where you e.g. desplay negative monetary values in red.
You can read more on conditional styling & formatting in this chapter .
User manual XperiDo template design add-in for Microsoft Word 109
Your documents. Automated.
Master your data flows. Boost your output streams.
14.4 XperiDo styles
XperiDo styles allow you to globally define a style which you can then re-use in multiple mappings. Using
XperiDo styles is pretty similiar to using Word styles, except that you have additional options available to use in
XperiDo styles.
You can find XperiDo styles in the XperiDo styles tab of the XperiDo pane:
We encourage you to use XperiDo styles for oft-used styling/formatting settings, as you only need to set them once instead of having to set each mapping's styling/formatting every time.
14.4.1 Setup
To create a new XperiDo style, click the Add button in the XperiDo styles tab:
Give your style a name, then double-click it to change its settings. You can also select it and click Edit :
In the window that pops up, you can change the XperiDo style's styling and formatting settings:
User manual XperiDo template design add-in for Microsoft Word 110
Your documents. Automated.
Master your data flows. Boost your output streams.
In this window, you can change the style's styling and formatting by clicking one of the tabs and changing the
settings. For more information on how these settings work, check out the Styling
The left side
of this window allows you to set up conditional formatting. This chapter explains how to set up
conditional formatting.
Once you are happy with your XperiDo style's setup, click OK to close the window.
14.4.2 Application
There are two ways of applying your XperiDo style to a mapping: direct or with a default field style .
14.4.2.1 Direct
Direct application means that you go into the settings of a mapping and apply your XperiDo style there. To do that, follow these steps:
1) Open the mapping's settings .
User manual XperiDo template design add-in for Microsoft Word 111
Your documents. Automated.
Master your data flows. Boost your output streams.
2) In the window that pops up, you'll see the following XperiDo style-related options:
3) From the drop-down list here, choose the style that you want to apply to this mapping.
4) Click OK to close the window.
That mapping now uses the styling/formatting as set in that XperiDo style.
There are a few more options you can set here:
If you no longer want to use an XperiDo style for that mapping, select <Private> in the drop-down list.
If you are editing a <Private> style, you can turn it into an XperiDo style by clicking Save style as ...
If you no longer need a certain XperiDo style, you can select it in the list and click Remove style .
Remember, this removes it globally.
If you have set up multiple value-condition pairs in the Field Selection window (more information about conditional mappings
in this chapter ), you can choose to
use a different style/formatting for each field , or use the same style/formatting for all fields by choosing the correct setting.
14.4.2.2 Default field style
Using a default field style means that you assign an XperiDo style to a field, after which every new mapping of that field will use that XperiDo style. This is particularly useful for values that are always interpreted the same way, such as monetary values, dates or times.
To assign an XperiDo style to a field, follow these steps:
1) Select your XperiDo style and click Assign .
User manual XperiDo template design add-in for Microsoft Word 112
Your documents. Automated.
Master your data flows. Boost your output streams.
2) In the window that pops up, select the field you wish to assign this XperiDo style to.
3) You'll see the field being added to the list of Default Field Styles :
You can assign multiple fields to the same XperiDo style by repeating the above procedure:
User manual XperiDo template design add-in for Microsoft Word 113
Your documents. Automated.
Master your data flows. Boost your output streams.
14.4.3 Removal
If you want to remove an XperiDo style from the list, select it and click Remove :
You can remove a default field style by selecting the field and hitting Delete :
User manual XperiDo template design add-in for Microsoft Word 114
Your documents. Automated.
Master your data flows. Boost your output streams.
15 Conditional content
Templates are quite dynamic in that they are injected with different data every time you generate a document.
But you can make them even more dynamic by making some parts conditional. These conditions can be based on any combination of multiple field values, giving you plenty of flexibility for setting up your templates.
15.1 Concept
You can make your content conditional in 3 ways: either by using conditional boxes , conditional mappings or conditional styling & formatting .
15.1.1 Condition box
A c ondition box is a user-designated zone whose content is only visible if the associated condition is true.
You can insert anything you like in the box, allowing you to display or hide entire pages, parts of paragraphs, some words, images, text boxes - anything you can insert in a Word document can be inserted into a condition box.
User manual XperiDo template design add-in for Microsoft Word 115
Your documents. Automated.
Master your data flows. Boost your output streams.
15.1.2 Conditional mapping
A conditional mapping is a mapping whose value depends on one or multiple conditions. You assign a value to each condition - the first condition that is true passes on its value.
The above example turns the mapping's value into Mr if the original value is Male , and Ms if it's Female . If there is no original value, Mr or Mrs is displayed.
15.1.3 Conditional styling & formatting
A mapping with conditional styling & formatting is a mapping whose styling & formatting is different depending on some condition.
The above example displays the TotalAmount value in red only when that number is negative.
15.2 Condition box
To insert a condition box, follow these steps:
1) Either place your cursor in the document, or highlight a zone.
User manual XperiDo template design add-in for Microsoft Word 116
Your documents. Automated.
Master your data flows. Boost your output streams.
2) Click Condition in the XperiDo pane's Data set tab. This inserts a default condition that checks whether the selected field occurs.
3) Define your condition in the window that opens. For more information on how to define your
User manual XperiDo template design add-in for Microsoft Word 117
Your documents. Automated.
Master your data flows. Boost your output streams.
4) Once you have defined your condition, click OK to finalize it.
The Mapping tab of the XperiDo pane now shows the condition:
You'll also see the condition box in your template:
More information about how to work with boxes can be found in this article .
15.3 Conditional mapping
15.3.1 Value-condition pairs
Making a mapping's content conditional is done by defining value-condition pairs . A value-condition pair is a combination of a value (this can be a mapping or any expression you like) and a condition . When the document is created, XperiDo cycles through all the value-condition pairs for that mapping. The first condition that is true passes on its associated value, which becomes the value for that mapping.
The following example shows this:
Here, 3 value-condition pairs are defined. The first (top) checks whether the GenderCode field's value is Male . If so, the value Mr is returned. If that condition check isn't true, the next (middle) condition is checked. Here the condition checks whether the GenderCode field's value is Female . If so, the value Mrs is returned.
Finally, the last (bottom) condition is the default condition. This is always true and acts as a fail-safe - if all the other conditions are false, then the value associated with the default condition is used.
User manual XperiDo template design add-in for Microsoft Word 118
Your documents. Automated.
Master your data flows. Boost your output streams.
15.3.2 Setup
To set the value-condition pairs of your mapping, follow these steps:
1) In the XperiDo pane's Mapping tab, select the mapping and click Settings .
This brings up the XperiDo Mapping settings window. The Field selection part shows the current value-condition pairs.
The default value-condition pair is the default condition (always true) paired with the field this mapping refers to.
2) To add another value-condition pair, click Add , then select New (to create a new pair) or Duplicate (to duplicate the selected pair):
User manual XperiDo template design add-in for Microsoft Word 119
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Now you need to change the value of the new pair. Click the pencil that appears when hovering over the value part:
This brings up the Select Value window where you can change the value that should be used when the associated condition is true.
Choose Element / attribute value to select a field from your data set. Choose Expression if you want to
use an expression. This chapter has more information about how to use expressions.
4) Click OK to finalize your value and close the Select Value window.
5) Next, you need to set up the condition associated with this value. Click the pencil that appears when hovering over the condition part:
This brings up a window where you can define your condition.
User manual XperiDo template design add-in for Microsoft Word 120
Your documents. Automated.
Master your data flows. Boost your output streams.
For more information on how to define your condition, click here .
6) Once you have defined your condition, click OK to finalize it.
7) You have now successfully set up your value-condition pair.
Repeat steps 2-6 to set up more pairs.
8) Click OK to save the mapping's settings.
15.3.3 Ordering and removing value-condition pairs
You can re-order your value-condition pairs by selecting the pair you want to move and clicking Up , Down , Top or Bottom :
Finally, you can remove a value-condition pair by selecting the pair you want to remove and clicking Remove :
User manual XperiDo template design add-in for Microsoft Word 121
Your documents. Automated.
Master your data flows. Boost your output streams.
15.4 Conditional styling & formatting
15.4.1 Styling/formatting linked to conditions
Making a mapping's styling & formatting conditional is done by defining conditions that have a styling/formatting linked to them. When the document is created, XperiDo cycles through all the conditions for that mapping. The first condition that is true passes on its styling & formatting to the mapping.
The following example shows this:
On the left, you see 3 conditions. The first (top) checks whether the mapping's value contains the word green , the second (middle) checks whether the mapping's value contains the word blue and the third is the default
(always true) condition, which acts as a fail-safe.
On the right, you see the styling/formatting settings for the second condition , since that is the one that is selected. In this case, the mapping's font color will be changed to blue if the mapping's value contains the word blue .
Note that everything to the right of the conditions can be changed - you can set up Convert to image for one condition and a simple Format change for another, for instance.
15.4.2 Setup
To make your mapping's styling and formatting conditional, follow these steps:
1) In the XperiDo pane's Mapping tab, select the mapping and click Settings .
User manual XperiDo template design add-in for Microsoft Word 122
Your documents. Automated.
Master your data flows. Boost your output streams.
2) This brings up the XperiDo Mapping settings window. The left side of the Field Formatting part shows the current conditions for conditional styling/formatting.
The default condition is always true.
3) To add another condition, click the green plus . This adds another default condition:
4) Select the condition you wish to change and click the blue pencil . This brings up a window where you can define your condition:
For more information on how to define your condition, click here .
5) Once you have defined your condition, click OK to finalize it.
6) Now that your condition is set up, you can change the styling & formatting that's linked to the currently selected condition.
User manual XperiDo template design add-in for Microsoft Word 123
Your documents. Automated.
Master your data flows. Boost your output streams.
Repeat steps 3-6 to set up more conditions.
7) Click OK to save the mapping's settings.
15.4.3 Ordering and removing conditions
You can re-order your list of conditions by selecting the condition you want to move and clicking the up or down buttons:
Finally, you can remove a value-condition pair by selecting the pair you want to remove and clicking the red X .
15.4.4 Conditional styling & formatting in combination with conditional mapping
When you have set up multiple value-condition pairs in your mapping, there is a setting that lets you choose how you want them to interact with the multiple conditions you have set up for conditional styling & formatting:
The option use different formatting for each field gives each value-condition pair its own styling & formatting, allowing you to define multiple conditions for styling & formatting for each value-condition. The other option
( use the same formatting for all the fields above ) gives all your value-condition pairs the same styling & formatting.
15.5 Defining your condition
Whether you use a condition box, conditional mappings or conditional styling & formatting, you'll need to define the condition . Here are the possible conditions:
User manual XperiDo template design add-in for Microsoft Word 124
Your documents. Automated.
Master your data flows. Boost your output streams.
When you choose one of these, more options appear. Adjust the options to your liking, then click OK to finalize the condition.
15.5.1 No condition
No condition means that this condition is always true. This is the default condition.
15.5.2 Check whether a field occurs
Check whether a field occurs checks whether a field is present in the data set.
Most XperiDo products always provide the full data set, which would render this condition option useless, since the field is always present. For that, the checkbox Mark blank fields as none occurence is there: checking this will mark empty/blank fields as not occurring.
15.5.3 Check whether a field occurs multiple times
Check whether a field occurs multiple times checks whether a field is present in your data set a number of times.
User manual XperiDo template design add-in for Microsoft Word 125
Your documents. Automated.
Master your data flows. Boost your output streams.
You can change the operator (greater then, less then, equal to etc.) and the number of occurences. Instead of typing in the number of occurences, you can refer to a field by clicking the data set button:
This opens a window where you can choose the field you want to refer to.
Finally, the checkbox Mark blank fields as none occurence will mark empty/blank fields as not occurring.
15.5.4 Check whether a field has a specific value
Check whether a field has specific value checks whether a field has a certain value.
User manual XperiDo template design add-in for Microsoft Word 126
Your documents. Automated.
Master your data flows. Boost your output streams.
Using this option requires that you specify 4 things:
The value to use in the condition (the first value)
That value's type
The operator used in the check
The value to check the first value against
15.5.4.1 Value to use in the condition
The first thing to decide here is the value that you wish to use in the condition. There are 3 options:
Field : to check whether a field has a specific value. You can select the field in the data set view below.
Expression : to check whether the result of an expression is a specific value.
Selected value : to check whether the value, associated with the first true condition (in the Field selection part where you define your value-condition pairs), has a specific value. (only visible in the conditions for conditional styling & formatting)
Use Field when you want to refer to the same field, regardless of the outcome of the Field selection part. If you want to consider the outcome of the the Field selection part, use Selected value .
15.5.4.2 Value type
Now that you have the value you wish to use in your condition, you need to specify how XperiDo interprets this value.
This can either be text , number or date . Choosing date adds further options, allowing you to choose date , time or datetime :
15.5.4.3 Value to check against
Now that the first value and its type is known, you need to choose the operator and the value to check the first value against.
User manual XperiDo template design add-in for Microsoft Word 127
Your documents. Automated.
Master your data flows. Boost your output streams.
Depending on the type, you have different operators to choose from:
Text : contains, contains not, equal to, not equal to, is blank, is not blank. These are all case-insensitive .
Number : between, not between, equal to, not equal to, greater than, less than, greater than or equal to, less than or equal to.
Date : between, not between, equal to, not equal to, after, before.
Finally, you need to choose the value. You can simply type it in (in the case of text or number), or you can use one of the following options by clicking the corresponding button:
Drop-down : when your data set restricts the options to certain values, you can select one of the options.
Data set reference : when you want to refer to the value of a certain field instead of using a static value.
Time : when you want to input a time.
Date : when you want to input a date or a datetime.
15.5.5 Check whether an expression is true
Check whether an expression is true checks whether an expression returns true. True means any value other than 0, which is false .
This chapter has more information about how to use expressions.
User manual XperiDo template design add-in for Microsoft Word 128
Your documents. Automated.
Master your data flows. Boost your output streams.
16 Pseudo-fields
Pseudo-fields are a special kind of field that you create yourself. You can use these fields to define calculations, complex expressions or text editing functions.
16.1 Concept
Here's how you use pseudo-fields in XperiDo:
1) Define a new pseudo-field.
2) Choose whether it'll be text or a number.
3) Define its value .
4) Map the pseudo-field.
In step 3, you can use other fields' values so that your pseudo-field is actually a modification of other fields' values . For instance, you can use a pseudo-field for:
Calculating totals, subtotals and percentages.
Editing names in full caps (JOHN) to make them less shouty (John).
Defining a new constant value for use in your templates.
The possibilities are endless as you can combine all fields and all functions the XperiDo template design add-in has to offer.
16.1.1 Resultsets
Besides text and number, there's actually a third type of pseudo-field: Resultsets . You can find more information
16.2 Setting up pseudo-fields
16.2.1 Creating a pseudo-field
To create a pseudo-field, follow these steps:
1) In the data set tab of the XperiDo pane, select the parent element of the new pseudo-field. The pseudo-field will become a child element of this element:
User manual XperiDo template design add-in for Microsoft Word 129
Your documents. Automated.
Master your data flows. Boost your output streams.
In the screenshot above, the new pseudo-field will become a child element of product .
2) Click the Add pseudo-field button:
3) This opens a window where you can define your pseudo-field:
User manual XperiDo template design add-in for Microsoft Word 130
Your documents. Automated.
Master your data flows. Boost your output streams.
4) Give your pseudo-field a display name , which automatically creates an internal name:
5) Choose whether the pseudo-field should output a number or text. This is important as choosing text will not allow calculations and you will not get the desired result!
6) The next step is to define your pseudo-field's value as an expression, in the text box under Value . You can insert functions by clicking the Insert Function button and following the wizard, or you can just type them...
...and you can insert fields' values by dragging and dropping them from the right data set viewi:
Clicking and holding the quantity field -
Dragging it to the spot I want to drop it -
User manual XperiDo template design add-in for Microsoft Word 131
Your documents. Automated.
Master your data flows. Boost your output streams.
Dropping it. The field's value is now inserted into the expression. Adding another field:
Our expression now calculates the sum of the quantity and the threshold
information about how to use expressions.
7) Once you've validated your expression (you can check whether your expression is valid by clicking the
Validate button), click OK to save your pseudo-field.
Now you'll see the new pseudo-field in your data set, in blue as opposed to green:
You can now map this field like a regular field. Once you've mapped it, you can style and format that mapping, also like a regular field.
16.2.2 Editing a pseudo-field
After you've created a pseudo-field, you can still edit it. Follow these steps:
1) In the data set tab of the XperiDo pane, select your pseudo-field:
User manual XperiDo template design add-in for Microsoft Word 132
2) Click the Edit pseudo-field button:
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Now the pseudo-field window opens where you can edit your pseudo-field's settings. Make the desired changes and click OK to save them.
What's nice about this 'after-edit' is that you can map your field multiple times and then change the value for all those fields at once. This is a major difference with formulas - the differences are explained here .
16.2.3 Removing a pseudo-field
If you no longer require your pseudo-field, you can remove it following these steps:
1) In the data set tab of the XperiDo pane, select your pseudo-field:
User manual XperiDo template design add-in for Microsoft Word 133
2) Click the Remove pseudo-field button:
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Confirm the removal.
Your pseudo-field is now gone.
16.3 Common pseudo-field uses
Since you define pseudo-fields yourself, you decide how to use them. But there are some uses that we encounter more often:
16.3.1 Calculations on recurring elements
You can use pseudo-fields to perform calculations on recurring elements by defining a single (recurring) element as the only argument of certain functions.
For instance:
sum(${/warehouse/product/quantity}) will return the sum of all the quantity fields in the data set.
avg(${/warehouse/product/quantity}) will return the average of all the quantity fields in the data set.
max(${/warehouse/product/quantity}) will return the maximum of all the quantity fields in the data set.
This feature is often used on quotes or invoices, where a total price (sum of all the prices of all the products) has to be calculated.
16.3.2 Nested pseudo-fields
You can use pseudo-fields in other pseudo-fields, allowing you to set up a tree structure. The following example explains this:
You want to make an invoice . Your data set contains a recurring element Product , which has the fields
Unit price and Quantity .
User manual XperiDo template design add-in for Microsoft Word 134
Your documents. Automated.
Master your data flows. Boost your output streams.
You set up pseudo-field A under Product (so each product has its own pseudo-field A) that calculates
Unit price * Quantity (unit price multiplied by quantity) .
You set up pseudo-field B on the same level as Product (so there is only one pseudo-field B) that calculates sum(pseudo-field A) .
Now you can use pseudo-field A in a loop over Product , to show each product's subtotal . Then, outside of the loop, you can map pseudo-field B to show the full total .
16.3.3 Concatenation
You can use the concat() function to put text fields together, so that you only have to map the pseudo-field instead of having to map the fields separately. For instance, you can put the FirstName and LastName fields together.
This also saves time on formatting, as you only have to format one mapping.
16.3.4 Splitting text
One particular use of pseudo-fields is the split() function. To illustrate this, we'll work with the following example:
This dataset contains a texts parent node, with textA and textB as child elements. TextA contains a single line of text while textB contains 3 lines of text.
If we map these as basic fields, without changing any settings...
User manual XperiDo template design add-in for Microsoft Word 135
Your documents. Automated.
Master your data flows. Boost your output streams.
...then we get the following result:
While the Field Inspector shows the content of textB as 3 separate lines, in the output this isn't the case. To split these correctly, we can use a pseudo-field.
Select the parent node and click add pseudo-field :
Give it a name and select Text as the type. In the middle text box, type splitLines() , select and drag textB from the right and drop it in between the brackets:
Now we have a new pseudo-field:
Select the pseudo-field and click the loop icon:
User manual XperiDo template design add-in for Microsoft Word 136
Your documents. Automated.
Master your data flows. Boost your output streams.
A loop box will now appear:
Inside the loop box , insert the pseudo-field:
Note that you can't simply map the pseudo-field as we've splitted the content into 3 lines, meaning that you need to loop over these 3 lines in order to show them all. If you just map the pseudo-field, only the first line will be shown.
This is the template with 4 different mappings: 2 basic fields , 1 pseudo-field and 1 loop around a pseudo-field :
And this is the resulting output:
User manual XperiDo template design add-in for Microsoft Word 137
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 138
Your documents. Automated.
Master your data flows. Boost your output streams.
17 Formulas
Formulas are an easy way of quickly inserting an expression in your template. They don't offer the same flexibility as pseudo-fields, but they make up for it in ease-of-use.
17.1 Concept
Here's how you use formulas in XperiDo:
1) Place the cursor where you want to insert to formula.
2) Click the Formula button.
3) Define the formula's value .
In step 2, you can use other fields' values so that your formula is actually a modification of other fields' values .
For instance, you can use a formula for:
Calculating totals, subtotals and percentages.
Editing names in full caps (JOHN) to make them less shouty (John).
Defining a new constant value for use in your templates.
The possibilities are endless as you can combine all fields and all functions the XperiDo template design add-in has to offer.
17.2 Creating a formula
To create a formula, follow these steps:
1) Place the cursor where you want the formula to appear in the template.
2) Click the Formula button in the XperiDo ribbon.
3) Define your formula's value by editing the expression . For more information on how to edit
expressions, please read this chapter .
User manual XperiDo template design add-in for Microsoft Word 139
Your documents. Automated.
Master your data flows. Boost your output streams.
4) Click OK to confirm the expression.
5) The XperiDo mapping window for this formula opens, asking you to define the formula's formatting.
Change the settings if you want and click OK .
Your formula is now defined and mapped. By default, it will be named {Formula} .
17.3 Editing a formula
After you've created a formula, you can edit its expression or formatting by following these steps:
1) In the data set tab of the XperiDo pane, select your formula and click Settings :
User manual XperiDo template design add-in for Microsoft Word 140
Your documents. Automated.
Master your data flows. Boost your output streams.
2) In the XperiDo mapping window that opens, you can change the formatting. To change the formula's value, click the pencil under Value in the Field Selection part.
3) This opens a window where you can change the formula's expression.
4) Click OK to confirm the expression, and then click OK to close the XperiDo mapping window.
17.4 Differences with pseudo-fields
While similar, pseudo-fields and formulas have a few distinct differences. You can read about those differences here .
User manual XperiDo template design add-in for Microsoft Word 141
Your documents. Automated.
Master your data flows. Boost your output streams.
18 Expressions
An expression is a combination of functions, fields and values that produces another output. They are very useful for calculations, textual changes and logical operations.
18.1 Concept
Typically, you use expressions for one of the following purposes:
Defining values that aren't present in your data set.
Manipulating existing values so that the output is different.
Creating more complex conditions than the wizard allows.
18.1.1 Defining values
The simplest way to use an expression is to define a value that is not present in your data set. For instance, here we define the string Mr :
This will simply output the string Mr .
On its own, defining a value isn't that useful. In combination with functions , however, it becomes more powerful. For instance, here we check whether the type field's value is equal to the string black marker :
18.1.2 Manipulating existing values
Changing an existing value so that it outputs something different is done by using functions . For instance, here's a table that shows the effect of a few functions on some fields' values:
Value of field A: 3
Value of field B: 6
Value of field C: 'XperiDo'
Value of field D: ' John'
Function
sum
Description
Returns the sum of the fields.
Input fields
field A & B
Outcome
9
User manual XperiDo template design add-in for Microsoft Word 142
Your documents. Automated.
Master your data flows. Boost your output streams.
Function
max
Description
Returns the largest number. toUpper Makes all characters uppercase. concat Puts two strings together.
This chapter shows all of the available functions.
Input fields
field A & B field C field C & D
Outcome
6
XPERIDO
XperiDo John
18.1.3 Complex conditions
Instead of using the wizard to define your conditions, you may also use expressions. We always encourage you to use the wizard as much as possible, but there are a few things the wizard won't let you do. For instance, you can't insert multiple conditions in a condition through the wizard.
There are a few functions that return 1 (true) or 0 (false); these are called logical functions . The eq function (to check whether a value is equal to another value) is a good example:
This expression will return 1 if the type field's value is equal to black marker . This expression can also be defined through the wizard:
User manual XperiDo template design add-in for Microsoft Word 143
Your documents. Automated.
Master your data flows. Boost your output streams.
But, more complex conditions require expressions. Here is an example of a condition that checks whether the type field's value is equal to either black marker or red marker :
Here, we use the or function that checks whether one of the arguments is true (which means that it returns 1).
So, if either of the eq functions is true, the entire expression is true and the condition is thus true.
18.2 Elements of an expression
An expression can contain the following elements:
Functions
Fields
Numbers
Strings
Let's go over each of them.
18.2.1 Functions
Functions are shown in pink (although they may appear in black the second time you open the expression):
Adding a function to an expression can be done in 2 ways: either you type it in or you use the function wizard .
To use the function wizard, follow these steps:
1) Click the Insert Function button:
2) A window will pop up, asking you which function you want to include.
User manual XperiDo template design add-in for Microsoft Word 144
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Choose your function (you can search for it or browse by category) and click OK . This opens a new window where you can choose the function's arguments:
4) You can type in your argument, use the expression button to bring up another expression editor
(which you can then use for inserting fields if you like), or you can click the green plus to add another
User manual XperiDo template design add-in for Microsoft Word 145
Your documents. Automated.
Master your data flows. Boost your output streams.
argument (if the functions allows a variable number of arguments). Click the red cross to remove an argument.
5) Click OK and your function, with all the arguments you provided, will be inserted into the expression:
The faster way is just to type avg(,3) and insert your field before the comma. But the wizard is helpful when you're not used to working with expressions.
18.2.2 Fields
Fields are shown with ${} around them:
To insert a field, follow these steps:
1) Find your field in the data set tree to the right:
User manual XperiDo template design add-in for Microsoft Word 146
2) Click your field and hold down the mouse button.
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Drag the field to the spot in the expression where you want to insert it:
This expression will now output the value of the field.
18.2.3 Numbers
Numbers are shown in brown (when used in a function):
To insert a number, simply type it. To use a decimal separator, use a dot , like this:
18.2.4 Strings
Strings are shown in green:
Strings will only be recognized as such when they are put in between apostrophes . Otherwise, the text won't be green and thus it won't be a valid string.
User manual XperiDo template design add-in for Microsoft Word 147
Your documents. Automated.
Master your data flows. Boost your output streams.
18.3 Good to know
A few things that are good to know when using expressions:
A function that takes multiple arguments as its input will work with only one argument when that argument is recurring. For instance, the sum function can be used to return the sum of all the quantity fields, like this:
This is often used in quotes and invoices, where each line item has its own subtotal. You can then just use the sum function on the subtotal field.
You can use the Validate button to check whether you made syntax errors. It's always a good idea to click Validate before clicking OK .
When using pseudo-fields, be sure to select the right type . Some functions won't work on text and some won't work on numbers.
0 will always be considered false , but everything else is true. So if your condition returns 2, or 5.4, it will be considered true .
User manual XperiDo template design add-in for Microsoft Word 148
Your documents. Automated.
Master your data flows. Boost your output streams.
19 List of functions
The XperiDo add-in for Microsoft Word offers a large number of functions that you can use in your expressions.
19.1 Good to know
19.1.1 Regular expressions
Some of the functions that you can use allow you to make use of regular expressions. To learn more about regular expressions, visit http://docs.oracle.com/javase/tutorial/essential/regex/ .
19.1.2 Extended characters
Some of the functions that you can use allow you to make use of extended characters. To learn more about extended characters, visit http://en.wikipedia.org/wiki/Control_characters .
\n is a newline.
\r is a carriage return.
\t is a tab.
\\ is a backslash.
\x## is a hexadecimal value (between 00 and FF).
\u#### is an extended hexadecimal value meant for Unicode characters (between 0000 and FFFF).
\d### is a decimal value (between 000 and 255).
19.2 Mathematical functions
19.2.1 Elementary arithmetic
add
Returns the sum of c and b. (c + b) add(c, b) add('1.2','2.3') = 3.5
add('1.2',2.3) = 3.5
add(1.2,2.3) = 3.5
uadd
Returns the sum of c and 1. (c + 1) uadd(c) uadd(10) = 11
User manual XperiDo template design add-in for Microsoft Word 149
Your documents. Automated.
Master your data flows. Boost your output streams.
sub
Returns the result of subtracting b from c. (c - b) sub(c, b) sub(9,3) = 6 sub(3,9) = -6
div
Returns the result of dividing c by b. (c / b) div(c, b) div(9,2) = 4.5
div(-9,2) = -4.5
div(2,4) = 0.5
mod
Returns the remainder of the division of c and b.
mod(c, b) mod(9,2) = 1 mod(9,3) = 0 mod(8,3) = 2 mod(-9,-2) = -1
mult
Returns the multiplication of c with b. (c x b) mult(c, b) mult(2,6.5) = 13 mult(-2,8) = -16
sum
Returns the sum of all arguments. (a + b + c + d...) sum(a, b, c, d...) sum(1,6.5,2) = 9.5
sum(1,0,0,0,6) = 7
prod
Returns the product of all arguments. (a x b x c x d...) prod(a, b, c, d...) prod(2,3,4) = 24
User manual XperiDo template design add-in for Microsoft Word 150
Your documents. Automated.
Master your data flows. Boost your output streams.
prod(-2,1,-3.5,2) = 14
19.2.2 Basic
rnd
Returns a new random number between 0.0 and 1.0. Seed is the number used to initialize a pseudorandom number generator.
rnd(seed) rnd(25) = 0.645
abs
Returns the absolute value of c. ( |c| ) abs(c) abs(123) = 123 abs(-123) = 123
max
Returns the largest number of c and b.
max(c, b) max(5,2) = 5 max(-3,7) = 7 max(-3,-5) = -3
min
Returns the smallest number of c and b.
min(c,b) min(5,2) = 2 min(-3,7) = -3 min(-3,-5) = -5
negate
Returns c multiplied with -1.
negate(c) negate(63) = -63 negate(-63) = 63
User manual XperiDo template design add-in for Microsoft Word 151
sign
Returns -1 if c is negative, 1 if c is positive and 0 if c is 0.
sign(c) sign(0) = 0 sign(-4) = -1 sign(7) = 1
val
Converts c to a floating point value.
val(c) val(1.2) = 1.2
19.2.3 Power
sqrt
Returns the square root of c.
sqrt(c) sqrt(121) = 11 sqrt(499849) = 707
sqr
Returns the square of c. (c²) sqr(c) sqr(11) = 121 sqr(707) = 499849
exp
Returns e raised to the power c.
exp(c) exp(2) = 7.389
pow
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 152
Your documents. Automated.
Master your data flows. Boost your output streams.
Returns c raised to the power b. (c ^ b) pow(c, b) pow(10,3) = 1000 pow(2,8) = 256 pow(3,3) = 27
19.2.4 Logarithms
ln
Returns the natural logarithm of c. (base e) ln(c) ln(10) = 2.303
log
Returns the logarithm of c in base 10.
log(c) log(1000) = 3 log(100) = 2
log2
Returns the logarithm of c in base 2.
log2(c) log2(1024) = 10 log2(256) = 8
logn
Returns the logarithm of c in base n.
logn(c, n) logn(343,7) = 3 logn(64,4) = 3 logn(100,10) = 2
19.2.5 Rounding
ceil
Returns the smallest integer higher than or equal to c. (rounding up) ceil(c) ceil(1.0) = 1
User manual XperiDo template design add-in for Microsoft Word 153
Your documents. Automated.
Master your data flows. Boost your output streams.
ceil(1.1) = 2 ceil(1.8) = 2 ceil(-1.0) = -1 ceil(-1.1) = -1
floor
Returns the largest integer lower than or equal to c. (rounding down) floor(c) floor(1.0) = 1 floor(1.1) = 1 floor(2.5) = 2 floor(-1.0) = -1 floor(-1.3) = -2
trunc
Returns c without the decimal part.
trunc(c) trunc(1.0) = 1 trunc(1.6) = 1 trunc(2.5) = 2 trunc(-3.6) = -3
19.2.6 Trigonometrical
sin
Returns the sine of c. (c in degrees) sin(c) sin(0) = 0 sin(30) = 0.5
sin(45) = 0.707
sin(90) = 1
cos
Returns the cosine of c. (c in degrees) cos(c) cos(0) = 1 cos(45) = 0.707
User manual XperiDo template design add-in for Microsoft Word 154
Your documents. Automated.
Master your data flows. Boost your output streams.
cos(60) = 0.5
cos(90) = 0
tan
Returns the tangent of c. (c in degrees) tan(c) tan(0) = 0 tan(45) = 1 tan(60) = 1.732
19.2.7 Statistical
avg
Returns the average of all the arguments. Blank values are not included. avg(a,b,c...)
avga
Returns the average of all the arguments. Blank values are included and considered to be zero. avga(a,b,c...)
count
Counts the number of values. Blank values are not included. count(a,b,c...)
counta
Counts the number of values. Blank values are included. counta(a,b,c...)
countb
Counts the number of blank values. countb(a,b,c...)
19.3 Text functions
19.3.1 Basic
str
Converts c to a string.
str(c)
User manual XperiDo template design add-in for Microsoft Word 155
str(1.2) = 1.2
strlen
Returns the length of c.
strlen(c) strlen('Hello world!') = 12 strlen('XperiDo') = 7
concat
Returns the string that results from concatenating c and b.
concat(c, b) concat('Hello ', 'world') = 'Hello world'
substr
Returns the substring of s starting from c with length b.
substr(s, c, b) substr('Hello World!', 1, 4) = 'ello' substr('Hello World!', 3, 2) = 'lo' substr('Hello World!', 3, -2) = 'el' substr('Hello World!', 100, -4) = 'rld!'
chr
Returns the nth character of c.
chr(c, n) chr('XperiDo', 2) = 'p' chr('XperiDo', 150) = ''
19.3.2 Trim
trim
Removes all leading and trailing whitespaces from c.
trim(c) trim(' some text ') = 'some text'
rtrim
Removes all trailing whitespaces from c.
rtrim(c) rtrim(' some text ') = ' some text'
ltrim
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 156
Your documents. Automated.
Master your data flows. Boost your output streams.
Removes all leading whitespaces from c.
ltrim(c) ltrim(' some text ') = 'some text '
19.3.3 Case
toLower
Returns c with all characters in lowercase.
toLower(c) toLower('XperiDo') = 'xperido'
Please note that the function lowercase
has the same effect.
toUpper
Returns c with all characters in uppercase.
toUpper(c) toUpper('XperiDo') = 'XPERIDO'
Please note that the function uppercase
has the same effect.
19.3.4 Replace
replaceText
Returns a string where each occurence of d in c has been replaced with e. Case is ignored.
replaceText(c, d, e) replaceText('The quick brown fox jumps over the lazy dog', 'brown', 'orange') = 'The quick orange fox jumps over the lazy dog' replaceText('The quick brown fox jumps over the lazy dog', 'BROWN', 'ORANGE') = 'The quick ORANGE fox jumps over the lazy dog' replaceText('The quick BROWN fox jumps over the lazy dog', 'brown', 'orange') = 'The quick orange fox jumps over the lazy dog' replaceText('The quick brown fox jumps over the lazy dog', 'brown', '') = 'The quick fox jumps over the lazy dog'
replaceTextC
Returns a string where each occurence of d in c has been replaced with e. Case-sensitive.
replaceTextC(c, d, e) replaceTextC('The quick brown fox jumps over the lazy dog', 'brown', 'orange') = 'The quick orange fox jumps over the lazy dog' replaceTextC('The quick brown fox jumps over the lazy dog', 'BROWN', 'ORANGE') = 'The quick brown fox jumps over the lazy dog' replaceTextC('The quick BROWN fox jumps over the lazy dog', 'brown', 'orange') = 'The quick BROWN fox jumps over the lazy dog'
User manual XperiDo template design add-in for Microsoft Word 157
Your documents. Automated.
Master your data flows. Boost your output streams.
replaceTextC('The quick brown fox jumps over the lazy dog', 'brown', '') = 'The quick fox jumps over the lazy dog'
replaceExtended
Returns a string where each occurence of d in c has been replaced with e. d and e are considerd to be texts with extended characters. Case is ignored.
replaceExtended(c, d, e) replaceExtended('"Ā"', '\u0100', 'Latin capital letter A with macron') = '"Latin capital letter A with macron"'
replaceExtendedC
Returns a string where each occurence of d in c has been replaced with e. d and e are considerd to be texts with extended characters. Case-sensitive.
replaceExtendedC(c, d, e) replaceExtendedC('"Ā"', '\u0100', 'Latin capital letter A with macron') = '"Latin capital letter A with macron"'
replaceRegEx
Returns a string where each occurence of d in c has been replaced with e. d and e are considered to be regular expressions.
replaceRegEx(c, d, e) replaceRegEx('The quick brown fox jumps over the lazy dog', '(dog|fox)', '\[animal\]$1\[animal\]') = 'The quick brown [animal]fox[animal] jumps over the lazy [animal]dog[animal]'
19.3.5 Split
split
Splits a field into separate parts, which can be stored as an array in a pseudo-field. These can then be accessed by mapping the pseudo-field.
split(text, separator, isRegex, removeEmpty, trimParts) text - the text to be split into pieces (text) separator - the value to split on (text) isRegex - whether separator is a regular expression or not (1 = true, 0 = false) removeEmpty - whether to remove empty pieces from the result (1 = true, 0 = false) trimParts - whether to trim the pieces (1 = true, 0 = false)
Example: split on lines
split(${./Content}, '\\\\r?\\\\n', 1, 1, 1)
Splits the value of element <Content> into pieces separated by the regular expression \r?\n. empty parts are removed and the separate parts are trimmed.
The reason that you need to place all the backslashes here is that the regular expression is translated two times before it is fed to the regular expression matcher. The expression is translated to a java-string before it is
evaluated; \\\\r -> \\r -> \r.
User manual XperiDo template design add-in for Microsoft Word 158
Your documents. Automated.
Master your data flows. Boost your output streams.
Example: split on , or ;
split(${./Content}, '[,]|[;]', 1, 0, 0)
Splits the value of element <Content> into pieces separated by the regular expression [,]|[;].This means either a comma or a semi-colon. Empty parts are kept and the separate parts are not trimmed.
Example: split on space
split(${./Content}, ' ', 0, 0, 0)
Splits the value of element <Content> into pieces separated by one space. empty parts are kept and the separate parts are not trimmed.
splitLines
Splits a field into separate parts, splitting on newlines.
splitLines(text)
This function is equivalent to split(text, '\\\\r?\\\\n', 1, 1, 1)
and will split text into pieces separated by a newline.
splitWords
Splits a field into separate parts, splitting on whitespaces.
splitWords(text)
This function is equivalent to split(text, '\\\\s+', 1, 1, 1)
and will split text into pieces separated by whitespaces.
19.4 Logical functions
19.4.1 Logic
if
Returns d if c equates to true, e if c equates to false.
if(c, d, e) if(1, yes, no) = yes if(0, yes, no) = no if(2, yes, no) = yes if(-1, yes, no) = yes
and
Returns the logical AND of c and d.
and(c, d) and(1, 1) = 1 and(1, 0) = 0 and(0, 1) = 0 and(0, 0) = 0
or
User manual XperiDo template design add-in for Microsoft Word 159
Your documents. Automated.
Master your data flows. Boost your output streams.
Returns the logical OR of c and d.
or(c, d) or(1, 1) = 1 or(1, 0) = 1 or(0, 1) = 1 or(0, 0) = 0
not
Returns 1 if c is 0, 0 otherwise.
not(c) not(0) = 1 not(1) = 0 not(2) = 0 not(-1) = 0
19.4.2 Comparision
eq
Returns 1 if c is equal to d, 0 otherwise. When used with text, the values are trimmed (trailing and leading whitespaces are removed), and case is ignored.
eq(c, d) eq(2, 2) = 1 eq(2, 5) = 0 eq(2.0, 2) = 0 eq(' AbC ','abc') = 1
neq
Returns 1 if c is not equal to d, 0 otherwise. When used with text, the values are trimmed (trailing and leading whitespaces are removed), and case is ignored.
neq(c, d) eq(2, 2) = 0 eq(2, 5) = 1 eq(2.0, 2) = 1 eq(' AbC ','abc') = 0
Extensions of eq and neq
The eq and neq functions can be extended for use with text: eqc - the same as eq, but case-sensitive.
eqt - the same as eq, but the values aren't trimmed.
eqct - the same as eq, but case-sensitive and the values aren't trimmed.
neqc - the same as neq, but case-sensitive.
User manual XperiDo template design add-in for Microsoft Word 160
Your documents. Automated.
Master your data flows. Boost your output streams.
neqt - the same as neq, but the values aren't trimmed.
neqct - the same as neq, but case-sensitive and the values aren't trimmed.
gt
Returns 1 if c is bigger than d, 0 otherwise.
gt(c, d) gt(2, 1) = 1 gt(2, 5) = 0 gt(2, 2) = 0
geq
Returns 1 if c is bigger than or equal to d, 0 otherwise.
geq(c, d) geq(2, 1) = 1 geq(2, 5) = 0 geq(2, 2) = 1
lt
Returns 1 if c is lower than d, 0 otherwise.
lt(c, d) lt(2, 1) = 0 lt(2, 5) = 1 lt(2, 2) = 0
leq
Returns 1 if c is lower than or equal to d, 0 otherwise.
leq(c, d) leq(2, 1) = 0 leq(2, 5) = 1 leq(2, 2) = 1
isNull
Returns 1 when c is unspecified (null).
isNull(c)
isNullOrBlank
Returns 1 when c is unspecified (null) or blank (empty or only whitespaces).
isNullOrBlank(c)
19.4.3 Check text
contains
User manual XperiDo template design add-in for Microsoft Word 161
Your documents. Automated.
Master your data flows. Boost your output streams.
Returns 1 if c contains s, 0 if it doesn't. Case is ignored.
contains(c, s) contains('XperiDo', 'Xp') = 1 contains('XperiDo', 'xP') = 1 contains('XperiDo', 'Xu') = 0 contains('XperiDo', 'u') = 0
containsc
Returns 1 if c contains s, 0 if it doesn't. Case-sensitive.
containsc(c, s) containsc('XperiDo', 'Xp') = 1 containsc('XperiDo', 'xP') = 0 containsc('XperiDo', 'Xu') = 0 containsc('XperiDo', 'u') = 0
startsWith
Returns 1 if c starts with s, 0 if it doesn't. Case is ignored.
startsWith(c, s) startsWith('XperiDo', 'xp') = 1 startsWith('XperiDo', 'X') = 1 startsWith('XperiDo', 'do') = 0 startsWith('XperiDo', 'Do') = 0
startsWithC
Returns 1 if c starts with s, 0 if it doesn't. Case-sensitive.
startsWithC(c, s) startsWithC('XperiDo', 'xp') = 0 startsWithC('XperiDo', 'X') = 1 startsWithC('XperiDo', 'do') = 0 startsWithC('XperiDo', 'Do') = 0
endsWith
Returns 1 if c ends with s, 0 if it doesn't. Case is ignored.
endsWith(c, s) endsWith('XperiDo', 'xp') = 0 endsWith('XperiDo', 'X') = 0 endsWith('XperiDo', 'do') = 1 endsWith('XperiDo', 'Do') = 1
endsWithC
Returns 1 if c ends with s, 0 if it doesn't. Case-sensitive.
endsWithC(c, s)
User manual XperiDo template design add-in for Microsoft Word 162
endsWithC('XperiDo', 'xp') = 0 endsWithC('XperiDo', 'X') = 0 endsWithC('XperiDo', 'do') = 0 endsWithC('XperiDo', 'Do') = 1
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 163
Your documents. Automated.
Master your data flows. Boost your output streams.
20 Resultsets
Resultsets are groups of fields that have a filter applied to them. This makes them ideal for situations in which you only want to show a subset of all items.
20.1 Concept
Here's how you use resultsets in XperiDo:
1) Add a new resultset .
2) Choose which fields to include by selecting the parent element of those fields.
3) Define conditions to apply as a filter.
4) Loop over the resultset.
5) Map fields inside the loop.
Now only the fields that adhere to the conditions are looped over, giving you a filtered list of items.
20.2 Configuring resultsets
20.2.1 Creating a resultset
To create a resultset, follow these steps:
1) Add a pseudo-field :
2) For the type, choose Resultset . Give your resultset a name that makes sense.
User manual XperiDo template design add-in for Microsoft Word 164
Your documents. Automated.
Master your data flows. Boost your output streams.
3) Choose the field on which to base the resultset. All the child elements of this field will be included in the resultset.
4) Click the Add Condition button.
5) A default condition will be added. You can now choose whether to use a field in your condition, or an expression .
6) You can now define your condition. For instance, here we define the condition to check whether the description field contains the word marker .
7) Next, click the Apply Changes to Condition button to finalize your condition.
User manual XperiDo template design add-in for Microsoft Word 165
Your documents. Automated.
Master your data flows. Boost your output streams.
8) The condition is now in place. Click OK to save the resultset.
You'll now see your resultset, and all of the underlying fields, in a separate part of your data set:
20.2.2 Editing a resultset
You can change your resultset after you've created it. To do that, select the resultset in the data set tab of the
XperiDo pane and click Edit pseudo-field .
User manual XperiDo template design add-in for Microsoft Word 166
Your documents. Automated.
Master your data flows. Boost your output streams.
This brings up the resultset window again, where you can change the settings.
20.2.3 Adding further conditions
It is possible to add multiple conditions to the same resultset. This allows you to create complex filters.
When using multiple conditions in a resultset, you need to define how they behave in relation to each other.
This is done by grouping them in a condition group .
There are two types of condition groups:
In an AND group , every condition must be met in order for the group condition to be met. For instance, the following picture shows an AND group that requires that every product is a marker and that it needs to be restocked:
User manual XperiDo template design add-in for Microsoft Word 167
Your documents. Automated.
Master your data flows. Boost your output streams.
In an OR group , at least one condition must be met in order for the group condition to be met. For instance, the following picture shows an OR group that combines all markers and paperclips:
To add another condition to your resultset after you've created it, follow these steps:
1) Open your resultset again by selecting it and clicking Edit pseudo-field in the data set tab of the
XperiDo pane.
2) Click the Add Condition button. This will add a default condition.
3) Select the new condition and change its condition, then click Apply Changes to Condition .
User manual XperiDo template design add-in for Microsoft Word 168
Your documents. Automated.
Master your data flows. Boost your output streams.
4) Now the second condition has been added. The two conditions now have to be grouped in an OR or an AND group. If you leave them, the default behaviour is AND.
5) To create a group, select them both by checking the boxes and clicking Group AND or Group OR .
6) This will add them in a group, which is visualized as such:
7) You can then add even more conditions and group them further.
User manual XperiDo template design add-in for Microsoft Word 169
Your documents. Automated.
Master your data flows. Boost your output streams.
8) If you want to remove a group, select the group and click Ungroup :
9) You can also change a group from OR to AND or vice versa by selecting the group and clicking the
Change to button :
10) Once you're happy with your resultset's conditions, click OK to save it.
20.3 Using resultsets
Now that the resultset is fully configured, you can use it in your template. This implies that you use your resultset in a loop. Unlike a regular loop, you won't be looping over a field, but over a resultset. The difference is that the fields inside the loop will only be shown if, for that iteration, the conditions of the resultset are true.
Follow these steps:
1) Select the zone you want to loop over.
User manual XperiDo template design add-in for Microsoft Word 170
2) Select your resultset and click Loop .
Your documents. Automated.
Master your data flows. Boost your output streams.
3) This inserts a loop over the resultset. Note that this loop behaves like a regular loop, so you can go into the loop's settings for additional options, such as sorting the loop.
4) Now, every field you put in the loop will only be shown in the final document if that iteration adheres to the conditions of the resultset.
User manual XperiDo template design add-in for Microsoft Word 171
Your documents. Automated.
Master your data flows. Boost your output streams.
Note that you can map either the field from inside the resultset or the field from the data set - it doesn't make a difference.
20.4 Further reading
There's actually a lot you can do with resultsets, such as using them as condition checks. Or using them in combination with groups. Before this chapter in the manual was written, a very thorough series of articles about resultsets was written, which explains everything there is to know by starting with a very basic example and growing more and more complex along the way. It's a good read, and there's a template, data set and sample included so that you can follow the articles along the way.
Here are the articles:
Working with resultsets
Basic examples of resultsets
Advanced examples of resultsets
Groups and resultsets
Resultsets in expressions
Common mistakes with resultsets
We believe this series covers all aspects of resultsets, so we highly recommend you take a look if you're interested in getting the most out of resultsets.
User manual XperiDo template design add-in for Microsoft Word 172
Your documents. Automated.
Master your data flows. Boost your output streams.
21 Dynamic fields
Dynamic Fields are fields of which the value is determined at the time of document generation, unlike regular fields that pull their value from a database. The template designer sets the type of value to enter, while the user generating the document decides the value. This provides the user with some degree of flexibility towards the final document.
21.1 Concept
Most of the work involving dynamic fields is done with an other XperiDo product - the XperiDo add-in for Word is only used to map these fields in your template.
If you've defined dynamic fields for your template, you'll see them appear in your data set in a new section:
Now that these fields appear in your data set, you can map them like you map a regular field.
21.1.1 Limitations
When previewing your template in Word, you'll notice that your mapped dynamic fields are gone. This is normal, since they do not contain a value until you create an actual document.
If you want to see how your dynamic fields behave in your template, we advise you to head over to your other
XperiDo product and generate a document. There, you'll be able to enter values into the dynamic field boxes.
21.2 Preserve formatting of text box dynamic fields
When using dynamic fields of the text box type, the formatting of the content may be lost in the transition to the Word add-in. You can make sure that the formatting is kept intact by following these steps:
User manual XperiDo template design add-in for Microsoft Word 173
Your documents. Automated.
Master your data flows. Boost your output streams.
1) Select the mapping in the Mapping tab of the XperiDo pane and click Settings .
2) In the window that pops up, go to the Rules tab.
3) There, check the box next to Preserve formatted text . This brings up new settings.
4) Set these settings like in the below screenshot:
User manual XperiDo template design add-in for Microsoft Word 174
Your documents. Automated.
Master your data flows. Boost your output streams.
5) Click OK to save the settings.
Note that these settings will overwritten by the settings of an XperiDo Style , should you decide to assign it to the mapping. Unless, of course, you apply these settings to the XperiDo Style itself.
21.2.1 Automatic settings
The add-in has a setting that allows you to make the above steps the default setting for all text box dynamic fields. You can set this in the XperiDo options, which you can find by clicking Properties in the XperiDo ribbon:
User manual XperiDo template design add-in for Microsoft Word 175
Your documents. Automated.
Master your data flows. Boost your output streams.
Please note that this setting is not retroactive, meaning that turning this on will only affect future mappings. If you want to enable this for existing mappings, you need to re-map these.
User manual XperiDo template design add-in for Microsoft Word 176
Your documents. Automated.
Master your data flows. Boost your output streams.
22 Electronic signatures
The XperiDo 6.6 template design add-in introduces electronic signatures for digitally signing your document. To accomplish this, XperiDo uses the DocuSign® platform.
22.1 Concept
When you generate a document that contains an electronic signature, one of two things will happen:
Either you get a link that redirects you to the signing procedure. This is called sign in person , where the person that needs to sign is there with you.
Either an e-mail is sent to the party that needs to sign the document. This is called sign by e-mail .
You can insert multiple signatures in the same document, but you cannot mix sign in person with sign by e-mail signatures.
22.2 Inserting an e-signature
To insert an e-signature, click E-Signature in the XperiDo ribbon:
This creates an empty mapping with the digital signature option activated:
To use this signature, you'll need to configure it properly.
22.3 E-signature settings
22.3.1 Type
There are 4 types of signatures.
User manual XperiDo template design add-in for Microsoft Word 177
Your documents. Automated.
Master your data flows. Boost your output streams.
Signature , where the signer signs with his/her full name/full signature.
Initial , where the signer signs with his/her initials.
Optional signature , which is a non-mandatory signature.
Optional initial , which is a non-mandatory initial.
DocuSign® uses the following symbols for this:
A signature looks like this:
And this is what an initial looks like:
22.3.2 Recipient
The Recipient part shows who is the recipient of the signature. If no recipient has yet been set, the message Not configured is shown.
Click Configure to open a window where you can set the options for the recipient. In here, you can choose whether to sign by e-mail (sign) or sign in person (sign in person).
User manual XperiDo template design add-in for Microsoft Word 178
22.3.2.1 Sign by e-mail (sign)
Your documents. Automated.
Master your data flows. Boost your output streams.
When choosing Sign , you have to input an Email and a Name .
The Email field should contain the e-mail address of the receiver.
The Name field should contain the name of the receiver.
You can also assign a field from your dataset to these fields, by clicking the buttons at the right of the text boxes.
User manual XperiDo template design add-in for Microsoft Word 179
22.3.2.2 Sign in person (sign in person)
Your documents. Automated.
Master your data flows. Boost your output streams.
When choosing Sign in person , you have to input a Host email , Host name and Recipient name .
The Host email field should contain the e-mail address of the DocuSign® account that you wish to use.
The Host name field should contain the name of the account associated with the host e-mail address that you have provided.
The Recipient name field should contain the name of the person that is to sign the document.
You can also assign a field from your dataset to these fields, by clicking the buttons at the right of the text boxes.
22.3.2.3 Advanced
The advanced tab contains more options:
User manual XperiDo template design add-in for Microsoft Word 180
Your documents. Automated.
Master your data flows. Boost your output streams.
You can add an access code by typing the code in the text box next to Access Code . You can also assign a field from your dataset to this code, by clicking the button at the right of the text box. Checking the box Add the access code to the email that is sent to the recipient includes the access code in the mail that is sent to the recipient.
Under routing order you can assign a routing order to each recipient. The routing order defines the order in which the recipients get asked the question to sign the document. This allows you to define who should sign first, then second etc. The person with the lowest routing order gets the document first, after which (after signing) it is sent to the person with the second-lowest routing order etc.
Recipients that have the same routing order get the document at the same time.
22.3.2.4 Routing order scenario
The following scenario may happen:
You have multiple signatures with routing order X
You have at least one signature with a routing order greater than X
In this scenario, the document will first be sent to all the recipients whose signatures have the routing order X.
After ALL of them sign the document, only then will the recipient from the other signature get the document to sign.
User manual XperiDo template design add-in for Microsoft Word 181
Your documents. Automated.
Master your data flows. Boost your output streams.
22.3.3 Formatting
When you insert a signature, it is always placed where your cursor is in the template at that time. However, a
DocuSign® signature can take up some space, so you need to define in which direction it can expand.
This is best explained with an example. The following images shows how we set up a part of our document, with the red dot representing the position where we add our signature:
Depending on how you choose the alignment of your signature, it will end up differently:
Top left:
Bottom left:
User manual XperiDo template design add-in for Microsoft Word 182
Your documents. Automated.
Master your data flows. Boost your output streams.
Top right:
Bottom right:
By selecting the right alignment, you can make sure that there's room for your signature.
User manual XperiDo template design add-in for Microsoft Word 183
Your documents. Automated.
Master your data flows. Boost your output streams.
23 Multi-language
XperiDo comes with a multi-language feature that you can use to choose a document's language, either manually or automatically.
23.1 Concept
The multi-language feature works with multiple variants of the same template, bundled together. Every template can contain one variant per language.
Multi-language can be used in 2 scenarios:
23.1.1 Automatic
Automatic language selection happens when you designate a field that determines the language of the document. For instance, the Country field of an Account can be a deciding factor in whether to create a German or English invoice. In a country with multiple languages, you can use an other field that determines the language.
You decide which values are linked to each language. For instance, you can choose to link Germany and Austria to German . If your account is then in either Germany or Austria, the document will be created from the German variant of the template.
23.1.2 Manual
In a manual language selection scenario, you decide the language of the document at document generation time. You select which language to use, and that variant of the template will be chosen to generate the document.
23.2 Set up
Before you can access a language variant of your template, that language needs to be activated for your project. This article describes how to set up your languages.
23.3 Changes
Once you've set up your languages, you will see the following changes:
23.3.1 In the connect window
In the Connect window, where you select your template, you'll notice an additional tab, called Language .
User manual XperiDo template design add-in for Microsoft Word 184
Your documents. Automated.
Master your data flows. Boost your output streams.
You can then choose which language variant for that template to open. You can also remove a language variant here.
23.3.2 In the XperiDo ribbon
In the XperiDo ribbon, you'll see an additional part where you can switch language variants for that template, as well as set Auto Settings .
23.4 Controls
When you open a template, it will open the default language variant. This is defined in your project.
23.4.1 Switching language variants
When you are working on one variant, you can switch to another by clicking the Language button in the
XperiDo ribbon and confirming that you want to switch.
This will open the other variant in a new window.
User manual XperiDo template design add-in for Microsoft Word 185
Your documents. Automated.
Master your data flows. Boost your output streams.
23.4.2 Copying content from one variant to another
You can copy content from one variant to another. This allows you to fully design one variant, then copy everything to the others and then make your translations.
Click the Copy From button, then select the variant you wish to copy the content from. You'll need to confirm your action, as you will overwrite the content of your current variant.
23.4.3 Saving a language variant
Saving a language variant is done like any other template: check it back in to the server. Beware though, as you need to check in every variant separately.
23.5 Auto settings
If you want your template to use the automatic language selection feature, you need to configure a table that links values to languages.
Click Auto Settings in the XperiDo ribbon to bring up the Language tab in the XperiDo options.
Check the box that says Enable automatic language selection for this template . Additional options now appear.
Now, click the field button to select the field which will be used for the automatic language selection.
User manual XperiDo template design add-in for Microsoft Word 186
Your documents. Automated.
Master your data flows. Boost your output streams.
Finally, you need to set up the Language lookup table . Click the button to bring up another window.
This window shows which value-language pairs have been defined. To add another value-language pair, click the green plus . To remove a pair, select it and click the red cross .
Click OK to finalize the table.
With the field defined and your language lookup table set, you have configured this template for automatic language selection. All that's left to do now, is to select Auto for the language when creating the document in another XperiDo product.
User manual XperiDo template design add-in for Microsoft Word 187
Your documents. Automated.
Master your data flows. Boost your output streams.
24 Settings
The XperiDo add-in has quite a few settings you can change. You can access these by clicking Properties in the
XperiDo ribbon:
In the XperiDo Options window that opens, you'll find many tabs:
This chapter goes over the settings found in these tabs.
24.1 General
24.1.1 Show namespaces of fields
Activate this setting if you want to show the namespace of a field. The namespace will then appear in the data set tab of the XperiDo pane after the field's name.
This will generally only be useful if you use XSD's or database connections to build your data sets, which is the case if you are using XperiDo Nucleus.
24.1.2 Use alternate names for fields
Data set fields can have multiple names. Usually, CRM systems have some sort of system name and display name for their fields. The display name is then formatted in a more human-friendly way, while the system name is more logical for computers.
User manual XperiDo template design add-in for Microsoft Word 188
Your documents. Automated.
Master your data flows. Boost your output streams.
Activate this setting if you want to show the display name for your data set's fields.
24.1.3 Force reset of XperiDo Ribbon-tab
Click this button if your XperiDo Ribbon is missing buttons or looks strange - a force reset should take care of that.
24.1.4 Use large icons in XperiDo Styles Overview
Activate this to show large icons:
Deactivate it to to small icons:
24.1.5 Show templates when connecting (else only data sets are shown)
Activate this setting if you want to show the templates when connecting to your project, which is default behaviour.
If you deactivate this setting, only the data sets are shown. You can then open your template by selecting the data set, after which you'll see the available templates for that data set:
User manual XperiDo template design add-in for Microsoft Word 189
Your documents. Automated.
Master your data flows. Boost your output streams.
The advantage of deactivating this setting is that your project opens faster, since loading the templates from the server is a slow operation. Note that this isn't an issue unless you have a very large number of templates.
24.1.6 Sort fields in data set tree
Activate this setting to sort your data set's fields alphabetically.
24.1.7 Display the full path of fields
Activate this setting if you want your mappings to show the full path instead of just the field's name:
This setting can also be activated from the XperiDo pane:
User manual XperiDo template design add-in for Microsoft Word 190
Your documents. Automated.
Master your data flows. Boost your output streams.
24.1.8 Prefix and suffix for datamap-content-text
By default, all mappings are put in between curly brackets, like {this}. You can change that here.
24.1.9 Ask confirmation to connect to server when opening an XperiDo document
Activate this if you want XperiDo to ask for your confirmation to connect to the server.
24.1.10 Local workspace
While you can access template on the server, these are stored locally during the design process. The place where these are stored on your computer is called the local workspace . The default location of the local workspace is <My Documents>\XperiDo .
This setting only applies to current users on the computer. When changing this location, please note the following:
When a template is checked out, it is checked out to the local workspace. When you change the location of the local workspace, the template stays checked out in the old folder. Therefore, before changing the location of the local workspace, it is advised to check in all templates that you've checked out.
In order for the location of the local workspace to effectively change, you need to restart all instances of Word.
24.1.11 Open generated documents (previews) as read-only
Activate this if you want to make all previews read-only files.
24.2 Sample values
Use this tab to change the sample values, which are used to preview the formatting of a mapping.
24.3 Server instances
connections.
User manual XperiDo template design add-in for Microsoft Word 191
Your documents. Automated.
Master your data flows. Boost your output streams.
24.4 Options
24.4.1 Confirm certain actions
XperiDo will often ask you something or warn you about something - but you can turn those notifications and questions off. Here's the list:
24.4.2 Support settings
These settings affect the export of templates:
Include diagnostics information by default when exporting - it's a good idea to leave this activated when exporting a template for our support team, as your system information may provide us with additional information towards a solution for your problem.
Remove temporary files after exporting a template - let XperiDo take care of those temporary files, although you can deactivate that if you like.
24.4.3 Documentation generation settings
Here, you can choose which file format will be used when clicking the preview button without choosing a file format:
24.4.4 Mapping settings
There's one setting you can change here: whether to automatically check the preserve formatted text option on dynamic fields of the text box type.
User manual XperiDo template design add-in for Microsoft Word 192
Your documents. Automated.
Master your data flows. Boost your output streams.
Text box dynamic fields generally benefit from having this option activated as their formatting is ignored.
24.5 Support
This section is about importing and exporting
templates. This chapter explains how to do that.
24.6 Live ID
You can use your Windows Live ID
for connecting to the add-in. This chapter explains how to do that.
24.7 Data formatting
Here, you can change the document locale for both numbers and dates. The document locale determines how input data (of which the type is unknown) is converted to usable numbers/dates. Setting your document locale correctly is very important, as this effectively tells the add-in how it should treat (for instance) a comma or a dot. Some languages use a comma as a 1000 separator and a dot as a decimal separator, while other languages do it the other way around.
This article has more information about locale settings.
24.8 Runtime
XperiDo offers a few options for optimization and validation settings. The following settings are available:
24.8.1 Optimize access to grouped fields
By turning this setting on, variables are introduced behind the scenes that keep track of the used conditions and their evaluated results. By doing this, less evaluations need to be performed which reduces the loading times of grouped fields.
User manual XperiDo template design add-in for Microsoft Word 193
Your documents. Automated.
Master your data flows. Boost your output streams.
24.8.2 Schema-object cache size
This setting specifies the size of the schema-object cache. This cache keeps track of the types of fields that are used. Setting this value to 125 means that for the first 125 fields, the type is stored and so the lookup is less
CPU-intensive the second time around.
Unless you are looping over blocks which contain over 125 fields, we recommend leaving it at 125.
24.8.3 Skip validation of empty table cells
By turning this setting on, XperiDo will skip a validation step at document generation time. This step checks for invalid tables, which can be produced as a result of a combination of settings.
Turning on this settings speeds up the document generation but introduces a small chance of the resulting docx file (if you export to docs) being unreadable by Word. If you use tables in your document, it is advised to test docx document generation with this setting turned on and see whether the resulting docx file can be opened by Word.
Due to the large potential difference between data used in documents, some records might generate a valid docx while others may not.
24.8.4 Validate whether all dynamically created columns are configured correctly
Activating this setting will prevent some errors with column configuration, which may happen as a result of a combination of factors. If you are experiencing problems with columns, you can turn this setting on and see whether it makes a difference in your case.
24.9 Metadata
This tab shows various information about the currently opened template.
User manual XperiDo template design add-in for Microsoft Word 194
Your documents. Automated.
Master your data flows. Boost your output streams.
24.10 Properties
This tab shows a few extended properties about the currently opened template.
24.11 E-signature
This tab shows the e-signature properties of your template.
24.12 Language
This tab explains how to use the multi-language feature in your template. This feature makes it possible to
create language variants of your template. This chapter explains this concept in detail.
24.13 Error handling
This tab gives you some options regarding error handling. Currently, there's only one setting you can change: what XperiDo should do when something goes wrong inserting an image. These are the options:
Stop document generation with an error - this throws an error and you won't get your document.
Insert the message below - provide a message that will be put in the document at the place where the image should have been.
Insert the error message - the error message itself will be inserted in the document.
Insert the image below - add an image that will be inserted at the place where the original image should have been.
Ignore errors - don't insert anything in the document.
User manual XperiDo template design add-in for Microsoft Word 195
Your documents. Automated.
Master your data flows. Boost your output streams.
User manual XperiDo template design add-in for Microsoft Word 196
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project