How to Generate Documents from Word Templates in ServiceDesk

Version 4

    Purpose

    Document Generation can be used to produce ‘Word format’ reports containing data from any process object at any point in the process.  It is similar to the use of the Print button which generates a Crystal report but is preferable in circumstances where:

     

    1. A standard letter or document needs to be generated.
    2. The ServiceDesk database is stored on Oracle so in order to print Crystal reports the workstation must also have the Oracle client installed.  This may not be convenient.
    3. A report containing specific information at a certain point in the process may be required.  This does not contain the same general information that is displayed in the Crystal report generated by printing.
    4. No one has Crystal skills sufficient to modify the OOTB reports to display required data.

     

    Requirements

    Document Generation is not difficult, however, before you begin you should ensure you have the following:

    • The ability to add Document templates is not automatic, it is a licensable feature so if the option is not available a new licence may be required.
    • A copy of Microsoft Word will be required to generate the XML template.
    • &An understanding of the way in which objects and attributes are related in the database.
    • Users who can generate a document must have the appropriate privileges.

      E.g. For Incident: Modules | Incident Management | Process Related Objects | Incident Document | Generate – Execute
      Modules | Incident Management | Process Related Objects | Incident | Incident Document | Create Document – Create, Read Update

     

    Overview

    In order to create documents containing data relating to your Incident/ Problem/ Change/ Calls (IPCC) you need to complete a series of actions.  Firstly, you will have to create the template in Word using merge fields to represent the object/attributes.  You will then need to add the template in Administration to make it available on your IPC’s and finally you will need to change your process and windows to make sure the action is available and the collection is visible.  These steps are described in detail in the following sections.

     

    Template Creation

    The first step is to create a Template in Word that will be populated with details from the Incident when the ‘Create Document’ action is used.  To define where the ServiceDesk data will appear in the document you must add merge fields to the file.

     

    NOTE: This only works with Word 2003 or Word 2007.  Attempting to use Word 2010 or higher will fail because it does not correctly save to "Word 2003 XML" format.  You can take a document created in 2010 or 2013, open it in 2003 or 2007, then "Save As" to a new file and this will be in the correct format.

     

    To do this in Word 2003:

    1. From the ‘Insert’ menu choose ‘Field’
    2. In the ‘Category’ drop-down list select ‘Mail Merge’
    3. In the field names list choose ‘MergeField’
    4. In the ‘Field Name’ field type the name of the placeholder you want to use (see below screenshot)
    5. Once all the fields have been added save the document as an XML file

     

    To make a merge template in Word 2007:

     

    1. From the ‘Insert’ menu choose ‘Quick Parts’ and select ‘Field’
    2. In the ’Category’ drop-down list select ‘Mail Merge’
    3. In the field names list choose ‘MergeField’
    4. In the ‘Field Name’ field type the name of the placeholder you want to use (see below screenshot)
    5. Once all the fields have been added save the document as a Word 2003 XML file (this will not work as a Word 2008 XML file)

     

     

    WordAddFields.JPG

     

    Attached is a sample template called Incident Summary.xml.

     

    When choosing your placeholders for the merge fields you must be careful to always use the name of the Object/attribute exactly as it is named in Object Designer.  For example, if you are adding the reference number to the template only “Id” will merge correctly, “id”, “reference number”, “ref” etc will not be replaced with the required data.  For more information about placeholders please contact Support or search our Community for further advice.

     

    The biggest limitation of the templates is that when displaying data from a collection, only the latest collection object will be displayed.  This means that unlike a Crystal Report it is not possible to display all Notes on an Incident, only the one most recently added

     

    Adding the Template to ServiceDesk

    In versions prior to 7.2.6 the out-of-the-box database included a Document window.  If your database was not upgraded from a version earlier than 7.2.6 then you will need to create a window.  On launching the Window Manager component navigate to ‘Metadata | Document Template’ and create a new Window here.  The only attributes you must add are ‘Title’ and ‘Template Data’ though it is advisable to also include ‘Description’ and the Creation/Update attributes.

     

     

    CreateWindow.JPG

     

    Once you have a window, launch the ‘Administration’ component, then choose the ‘Document Templates’ tree.  You can now create a document template in any of the IPCC modules for use in your processes.

     

     

    CreateDocument.JPG

    Adding the functionality to Create a Document from an IPCC

    You may find that you will also need to create a window in the appropriate IPCC module(s) to display the Document window.  This window must have the ‘Title’, ‘Template’ and ‘Document’ attributes displayed on it.  In version 7.2.6 and later you must also include the ‘Show On Screen?’ attribute too.  The ‘Show On Screen?’ attribute means that on saving a Document object the Document will be generated and immediately opened for review and printing.

     

    DocumentWindow.JPG

     

    You will also need to edit your appropriate IPCC window(s) to show the ‘Documents’ collection either on a tab or in the tree else, having created a Document your Users will be unable to access it to open it.

     

    The action required to generate a Document is called ‘Create Document’, like most actions this can be added as an Optional action at a status, as a manual action that alters the process in some way or as an Automatic Action within the process.  Depending on how you want the Document to be used you may want this as an Optional action so that anyone can generate and print a document or you may want to automatically generate a document when an Incident is passed to a third party so that this can be sent to them to complete a work order.

     

     

    DocumentActionInProcess.JPG