Acorel Document Service: Template editing

With the ongoing growth of our ADS (Acorel Document Service), I would like to share some tips and tricks to make it easier to create a template. Specifically Word templates, because it is the most used template format. If you don’t know what Acorel Document service is. You could refer to this blog written by my colleague. This blog will also demonstrate the flexibility of our ADS solution.

Basics

When creating a document on ADS you need to set up data connections to SAP Cloud for Customer. A connection to SAP Cloud for Customer uses API calls to fetch JSON data from your tenant. Each document can have multiple connections to SAP Cloud for Customer to combine data of several different objects.

Every resource above contains JSON data. These resources will be linked to your Word Template.

When ADS fetches data from SAP Cloud for Customer, it will fetch OData converted to JSON.

To import data to word templates, ADS uses the popular Freemarker engine to import SAP Cloud for Customer JSON data into your word template.

Create MergeField

To add data from a connection to the document you need to create a merge field in Word. To insert a merge field you go to:  “Insert” tab -> “Quick Parts” -> “Field”. In a new window you can choose “MergeField”, fill the needed data and press “OK” to create a mergefield.

Turn on Word Field Code

When creating a template in Word, you need to turn on the ‘word field code’ option. To be able to do that press alt+f9
Inside the word field code, you can use Freemarker script
Sample with no word field code
«${Customer.Name}»

Sample with word field code turned on
{MERGEFIELD ${Customer.Name} \* MERGEFORMAT}

With this turned on you are able to use advanced Freemarker script language to script inside

Filtering and dates

When fetching dates with API calls to SAP Cloud for Customer, fields with date value are displayed in Unix Epoch numbers. To get the right date value you can use the dates converting option. To change the date display to your liking you can adjust the date/time format explained on the date Freemarker page.

{MERGEFIELD ${ Customer.ChangedOn?date?string(\”dd-MM-yyyy\”) } \* MERGEFORMAT}

Like in scripting, you can also use if-else statements. This is especially useful if you are going through a lot of data. For example:

• Filter data only when a particular field is filled
• Only see data if a field has a particular value.

Example when Rolecode needs to be filled
{MERGEFIELD [#if Customer.RoleCode?has_content ] \* MERGEFORMAT}

Always close the “if” when you start one.
{MERGEFIELD [/#if] \* MERGEFORMAT}


Only show rolecode with “CRM000”

{MERGEFIELD [#if Customer.RoleCode?contains("CRM000"?string)] \* MERGEFORMAT}
{MERGEFIELD [#else] \* MERGEFORMAT}
{MERGEFIELD [/#if] \* MERGEFORMAT}


“else” is only needed if you want to show something else  in case the “if” condition does not match.

Tables and Aligning text

When creating a report it is really nice to adjust the right alignment.
The recommended method of working is to always use tables to put text inside when making a report. If you don’t like the table lining you can always make it invisible.

Looping through data when using tables will be a hassle if you don’t know where to place the word field code.
When looping through data you need to make sure to place the code correctly. In the following picture, you can see how one can loop through a data list while making sure the tables are built correctly.
You need to keep in mind that if you loop through the table you also add cells and rows when placing them inside the table.

Like the picture above you use #list when looping through a list of data with the header intact.

You can do many things with Freemarker language script inside Word template like sorting data or assigning variables. In this blog, I have yet to explain everything, there is much more that you can do. What I explained above also works with XHTML but the syntax works a bit different than Word.