Difficulty: novice

Parameters in templates

In the previous article /wiki/spaces/KB/pages/105971749, you have learned how to find, create and refer to parameters. Parameters are frequently used when generating content from document templates or when sending out emails from Workplace. A template that is set up to be highly dynamic, can be used to tackle multiple different scenarios. In this article, you will learn the basic functionalities to create a template using parameters from Workplace.

Rules for creating (HTML and docx) templates

The basic principles when creating a template applies to all modules in Workplace. The example that we follow in this article will help you to set up your own template. However, before creating a template it is important to know the basic rules:

• Workplace templates used to generate documents and email have the format “.docx” or “.html”.

  • The creation of HTML templates is not discussed in this article. However, the same rules apply as when creating .docx templates

• When exporting the results, a template can be formatted to docx, pdf, or html.

• A parameter is used by placing it between {curly_brackets}.

  • start with Capital letter: The Parameter will return the label of the field.

    • Example: {SystemUserContact} returns “Contact”

  • start with small letter: The Parameter will return the value of the field.

    • Example: {systemUserContact} returns “CON-20001”

• Make sure there that the parameter is an exact copy. Any spaces or wrong use of capital letters inside the brackets will cause a malfunction.

• It is possible to specify your parameter using bold, italic, underlining, color etc. To do so simply apply the desired layout to the parameter. For example:

  • {reference} will result in REQ-230001

  • {reference} will result in REQ-230001

• If translation strings are specified for parameters, the labels and values of a parameter will reflect the specified language of the receiver (assuming the correct settings are applied and translation strings are available).

• If a parameter originates from a list, it is possible to switch on “Auto-expansion”. By adding “1” to the parameter, it will auto-expand based on the values in the list. Note: This only works for parameters situated inside a tabel!

• The use of if-statements is allowed.

Good to know when testing templates

• When you link a template to a page (navigate to instance page > open page definition > PDF tab > New) it can be tested by choosing the ‘Export PDF” or “Export Word” button when you open a reservation. This process is described in more detail in the example below.

• If more than one template is linked to a page definition, the user needs to select what template should be used when pressing 'Export PDF” or “Export Word”.

• Templates are inherited from parent page. However, as soon as one template is linked to a child page, the templates from parent pages can no longer be used on this child page.

• When implementing an email template always make sure to also test it by going through the workflow proces. So actually create and process a reservation/ reservation/ work order/ etc. before putting the template in Production.

Example: create a template for reservations

In this example, we will show you step-by-step, how to create a template for the reservation module in Workplace.

Step 1: When creating a template for reservations, the first step is to check which parameters are available on the page. To check the available parameters for reservations:

1. Navigate to the Reservations via your navigation menu;

2. Click on Reservations;

3. Open a reservation;

   1. Alternatively, create a new reservation;

4. Navigate to parameters (behind the gear symbol).

5. You will now see all the available parameters for reservations that can be referred to in a template.

Step 2: Create a template using a program that can save your file as “.docx” or “.html”. In this example we’re creating a template in .docx using Microsoft Word.

The example below uses a mix between hard coded text, parameters, translation strings, if-statements, and various style elements (bold, italic, underline, colour) to showcase the most used options for a Workplace template.

• Point 1: Hard coded text and a parameter addressing the contact that will receive the letter.

• Point 2: The parameter is a translation string. Translation strings allow the use of paragraphs, spaces, numeration, etc.

  • A big advantage of using translation string is that once the template has been setup. The text can be managed by editing the translation string. This is often easier than downloading an existing template, editing it, and uploading the new version.

• Point 3: Various style elements incorporated for the parameters.

• Point 4: An if-statement is a conditional statement that takes on different values depending on its specifications.

  • An if-statement always open with a curly bracket. Everything inside the statement is enclosed by normal brackets. The if-stament is closed by a curly bracket.

  • Hard coded text must be enclosed by double quotes. Note: the double quotes must be straight, not angular.

  • If the double quotes are next to each other without any content, as such: ““. We are effectively telling it to show nothing.

  • Commas are separating the values in the if-statement.

  • There must be two equal signs when referring to “equal”.

    • The if-statement in the example below is read as follows: If the parameter item1 is equal to empty, then show the text No reservable items have been selected, else show the parameter item1.

• Point 5: a parameter that ends with the number “1”, is auto-expanded. This is useful when the length of the items in a list varies. To activate the auto-expansion function, the parameter must be in a table format. When you’re using MS Word you can hide the borders of the tabled by using the ‘No border’ option.

  

• Point 6: Logos and other pictures can also be added to the template. To control the size and position these are often places in hidden tables. Pictures can also be added to the header and footnote of the document. This functionality is not shown in the example below, but self explanatory.

Example of input (template) and output (template exported to PDF)

Step 3: Testing the template by linking it to the page definition (the reservation page in this example)

1. Navigate to the Reservations via your navigation menu;

2. Click on reservations;

3. Open a reservations that is filled in and contains all the information needed for the parameters you defined.

4. Navigate to the back-end of the page using the page definition;

5. Click on the PDF tab;

6. Click on “new”;

7. Press the “three dots” and upload the template using drag- and drop;

8. You can leave the field ‘PDF parameter’ empty. It will then use the PDF-parameter page that is linked on the ‘General’ tab of the page definition.

9. Note: write down the document number. We need it for later when you’re linking this document as a template for the workflow email.

10. Navigate back to the instance page;

11. Test the template by exporting it as a PDF. If more than one template is linked to the page you have to select the correct template.

Example: link the email template to a workflow connector

Step 4: Linking the template to a workflow connector.

An email can be set up to be sent via the reservations workflow. For most workflow objects standard email templates are applied (See section “Editing the default email templates” below). However, it is also possible to link our own template that we have created in the example above. In this example, we will link our own email template to a workflow connector for reservations.

The template that we have created in the steps above, can be linked to the email by following these steps:

1. Navigate to the Reservations via your navigation menu.

2. Click on Reservations.

3. Open a reservation, or create a new reservation.

4. Click on the workflow tab.

5. Click on the workflow definition button.

   

6. Click on the magnifying glass to enter the workflow graphics.

   

7. Click on the connector that the email should be sent via.

   1. Emails can only be linked to connectors going from a task to a status (square to a circle);

   2. Emails can also be linked to a status combined with a trigger (e.g. send an email when the status of a workflow has been ‘awaiting approval’ for 3 work days)
      

8. 

   Click on the Email button.

9. Click on the plus sign to generate a new email.

10. Choose a ‘From’ or 'From group' contact by:

    1. Click on the ‘…' behind the 'From’ field.

    2. Select if your looking for a person or organization.

    3. Type a keyword.

    4. OK.

    5. Selecting a contact.

    6. OK.

11. To determine who received the email set the field “To”:

    1. Click on the '…'.

    2. Click the ‘To systemgroup’ button. It is also possible to send an email to a specific contact or organization. The front desk could for example be put in the Cc for reservation all emails.

    3. Type a keyword.

    4. OK.

    5. select one or more groups by clicking the checkbox.

    6. OK.

    7. Press OK a second time to return to the email definition.

12. Cc and Bcc in the same manner (optional).

13. Fill in the subject of the email. This can contain a translation string.

14. Change the setting for ‘Expand recipients’ if needed.

15. Upload the template using the drag and drop function. Alternatively, if the template already exists in the environment (because you already tested it):

    1. Click on the Add button in the document include.

    2. Click on Advanced search.

    3. Empty all the filters and search for the document number (generated earlier in step 3).

    4. Select the document and click OK.

Settings on the email definition

Hovering over the settings will show a help text. The most common settings are explained in the table below.

Editing the default email templates

When implementing a module using the SBRs, the default email templates are applied to that Workplace environment. When the default mail templates need to be modified and the email do not exist in the client environment, the steps below can be followed.

1. Navigate to the Reservations via your navigation menu.

2. Click on Reservations.

3. Open a reservation, or create a new reservation.

4. Click on the workflow tab.

5. Click the workflow case icon (top right)

6. Click on the workflow definition button.

7. Click on Generate standard emails button on the bottom of the page.

   

8. The email can now be accesses by pressing the envelop icon on the top right OR by navigating to the graphical workflow view > opening the corresponding workflow connector > press the ‘Email’ button.

Summary

Search