Quickstart - Exercise 1: Creating your first template

Outline

This exercise will show you how to create a template using the most relevant placeholder: ValueOf. You will also learn how to connect to the Docati-service and test the template.

Setup

The prerequisites for these exercises are listed on the Quick-Start introduction-page.

The template you’re about to create in this exercise is, will show order data. This order data is located inside a data-file. You will need this data-file to test the template. You can download it here: http://static.docati.com/samples/order-basic.xml (you must save it to a local folder on your computer, you need it later).

Steps

1. Open Microsoft Word and navigate to the Docati-ribbon.
   
   * The Docati-ribbon was added to Word by the Docati Word Add-In.
   * In Word 2013 and later, you need to open a new (blank) document first for the ribbon to appear.
   * You may be prompted to accept the End User License Agreement
   * If you haven't loaded your (trial) license, you must now do so to be able to use the Word add-in
2. We’re creating a new template. However, instead of starting with a blank document, we start with very basic ready-made starter/template. You can open it directly by clicking this link: http://static.docati.com/samples/Order-Starter.docx
3. Since this document originated from an internet location, it’s most likely opened in read-only mode or Protected View.

   

   To overcome this problem, you must enable editing first.
4. Now we're giving it a proper (file)name. To do so, simply Save-As the document and name it "Order1.docx".
   

The document represents a template that could have been designed by your own financial department. It looks great, but finance guys don’t know much about document automation, so they did not add any Docati-placeholders and therefore it’s not ready for use yet. And that’s where you come in!

5. To add Docati-placeholders, make sure the Docati-ribbon is activated. In the document you will find the text ‘-exercise 1 comes here-’. This is were we want the company information to be displayed.
   Remove this text and add a ValueOf-placeholder by clicking the corresponding button on the Docati-ribbon. Since you just removed the text, the cursor-position was in the exact position where the ValueOf-placeholder had to be placed.
6. Once the placeholder is added to the document, a taskpane will be automatically displayed. This taskpane must be used to configure the placeholder. Configure like this:

   

   When the ValueOf-placeholder is selected in the document, it will appear like this:

   

   * Query specifies the location inside the data that specifies the company name. The format of this notation is either regular or advanced (XPath). For now we stick to regular queries. More information on queries can be found here.
   * Word 2013 and later will show an orange tab, in older versions the tab will be coloured blue.
7. Save the document now. You just created your first Docati template!

8. There is only one way to find out if the template works correctly: by generating a document based on the template! We can do this by using the Generate button on the Docati-ribbon.

   The Generate Document-dialog will pop up and requires you to specify an XML data-file to use. Select the order-basic.xml you downloaded earlier. You can set the output format as desired, however you must have the proper license to use a different format than Word (.docx).

   

   You can now click on Generate document to have the service generate the document. The Docati-addin will generate the resulting document. Word will then display the document in read-only mode so you can check the results. It should look like this:

   

   * As you can see, the ValueOf-placeholder has been replace by the actual name of the company in the data-file (“Docati”).
   * Once the test succeeds, the settings of the Test-dialog are stored, so you don't have to configure them next time.
   
   

   Besides the generated document, another window has popped up. This is the Processing Result Log. For each Docati-placeholder in the template that was processed, it displays information on the results, like the number of nodes matches in the data-XML. This will help you creating the correct queries for you template.

   

   * On the Generate-dialog you can enable/disable the processing result log.

You created a new template, inserted and configured a Docati-placeholder, connected to the Docati-service and tested it. The resulting document may look far from impressive, but these are just the basics. In the next exercises we will explore more advanced scenarios.

Continue with the next exercise >