Zetadocs for Microsoft Dynamics NAV Advanced Configuration Guide

Transcription

1 Zetadocs for Microsoft Dynamics NAV Advanced Configuration Guide Version history Version: 09/12/2008 Equisys plc Equisys House 32 Southwark Bridge Road London SE1 9EU United Kingdom Tel + 44 (0) Fax +44 (0) Equisys Inc 30,000 Mill Creek Avenue Suite 335 Alpharetta GA USA Tel +1 (770) Fax +1 (770) Contact: Equisys Technical Support, support@equisys.com Copyright Notice Copyright 2008 Equisys plc, London All rights reserved. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the prior written permission of Equisys plc. All trademarks are acknowledged.

2 Zetadocs for NAV Advanced Configuration: The Advanced Configuration Process Contents 1. Zetadocs for NAV Advanced Configuration The Advanced Configuration Process Creating Document Templates Standard Document Templates Creating New Document Templates Creating Zetadocs for NAV Reports Backup Reports Import the Zetadocs for NAV Report Template Global, Local and Text Constants Code Segments Version Code Configuring Zetadocs for NAV Basic Configuration Advanced Configuration Testing the Zetadocs for NAV Solution Full Cycle Test Scenario Detailed Component Testing Introduction to NAV Customization Microsoft Dynamics NAV Compatibility Glossary of Terms Overview of Zetadocs for NAV Architecture Overview Typeless Public and Private Code Data Processing Flow Summary Send Any Report Permissions Simply Send Configured Send Custom Send Bespoke Contacts and Company Types Company Types Contacts Zetadocs-Customize codeunit OverrideSendResult GetAdditionalEmbComms Advanced Zetadocs for NAV Report Writing Zetadocs Report Code Overview Types of Reports Import the Zetadocs for NAV Report Template Global, Local and Text Constants Modifying the reports Copy Loop Modifications Necessary for the Role Tailored Client Reports APPENDIX Creating and Troubleshooting Zetadocs for NAV Reports...62 Step by Step Optional Zetadocs Report Format...68 This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 2

3 Zetadocs for NAV Advanced Configuration: The Advanced Configuration Process 1. Zetadocs for NAV Advanced Configuration Due to the customizable nature of NAV it is clearly a challenge to ensure the Zetadocs integrates well with all system setups. For those systems which are not compatible the use of the Zetadocs for NAV Standard data import the Advanced Configuration guide provides a detailed description of how to configure your system. Even for those systems which can utilize the standard data import reading this guide may still prove useful as the standard configuration has been created with compatibility to a variety of circumstances in mind as such this guide will show you how to refine Zetadocs for NAV to mesh with your system requirements. Further the Customization section will also shown you how to adapt Zetadocs for NAV to a variety of other purposes. 1.1 The Advanced Configuration Process 1. Creating the Default Document Template o Create stationery that will be overlaid onto printed NAV documents, standard attachments and Zetadocs template. 2. Creating Zetadocs for NAV Reports o Setting up the reports. 3. Configuring Zetadocs for NAV o Setup of system wide rules for archiving (Fileplan), default delivery methods and default templates. 4. Testing the Zetadocs for NAV Solution o Verify the functionality end to end and gain customer acceptance. 2. Creating Document Templates Typically each document sent from NAV using Zetadocs will use a Zetadocs Template to apply a format to the report. This can include putting a company logo on each page of the document, appending additional pages to each document, adding additional addressing, and customizing the message. At this point it is recommended that you create an initial Zetadocs template, to not only have a default sending format, but also to grasp the power and flexibility of the Zetadocs system, so that when you come to design greater customizations later in the installation process you will have a good understanding of what is possible and how to achieve it. 2.1 Standard Document Templates Zetadocs for NAV includes as part of the standard configuration a series of Zetadocs Templates, these can be adjusted to match your needs and come complete with sample stationery for you to replace and a generic message. You may find it quicker and easier to modify these than to create your own from the beginning, these templates should be located in the shared folder setup earlier in the install. For further details on adjusting the standard document templates please see the Standard Configuration guide located on your product CD. 2.2 Creating New Document Templates Actions: 1. Select the Create Document Template option from the Tools menu at the top of your program window. 2. The first edit screen of the document template wizard allows you to choose the attachments you would like to include in your document template. This allows you to add either single or multiple attachments. When you are happy with your selection, select the Next button to continue. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 3

4 Creating Document Templates: Creating New Document Templates Figure 1 - Document Template Wizard Choose Attachments 3. The second edit screen that is displayed allows you to choose any stationery that you would like to automatically apply to any documents sent with this document template. You can choose a stationery type, or opt not to apply stationery to your main document. To add stationery, select the type you wish to apply and select the add option. When you are happy with your selection, select the Next button to continue. Figure 2 - Document Template Wizard Choose Stationery This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 4

5 Creating Document Templates: Creating New Document Templates 4. The third screen allows you to add addresses to the template. This may be useful in situations where other members of staff will need to be notified of certain types of documents, for example invoices sent out by the accounts department that need to be seen by the Sales team. Figure 3 - Document Template Wizard Enter Properties NOTE: Zetadocs for NAV passes a number of metadata fields as Zetadocs dynamic fields which can be used to customize the message specified in a template. More fields can be passed from NAV by purchasing the Zetadocs Customization granule for NAV and implementing these fields in NAV. For more information see section Advanced Configuration. 5. Having ensured that you have added all the items that you wish to enclose in your template, use this screen to check the items are correct, leave class type empty as you will manage document typing from NAV. Figure 4 - Document Template Wizard Choose Name This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 5

6 Creating Zetadocs for NAV Reports: Backup Reports 6. Your template is now ready to import into NAV. 3. Creating Zetadocs for NAV Reports This section details the changes required to enable a typical NAV report to be sent using Zetadocs. If you are using the Zetadocs sample templates then you may not need to perform these steps unless you have reports which are not covered in the samples provided or have specific amendments to make to them. To make the process simpler and faster there is a template report in the Zetadocs for NAV installation pack which contains only the elements that are to be added to an existing report to enable it for sending. It is recommended that you complete the previous sections of this installation document before attempting to create a Zetadocs for NAV report, because much of the code to be added to an existing report depends upon other Zetadocs for NAV objects. Please follow each of the steps listed in the section below in the order they appear. Note: This method works for most reports; however, due to the customizable nature of reports it may not fit all reports exactly. Therefore, the location of where to insert the code below may need to vary but the code will remain the same. For additional printing options in reports and troubleshooting the building of a report see the section on report building in the Appendix. 3.1 Backup Reports In order to be able to uninstall the Zetadocs for NAV software it is necessary to backup the Navision reports you are editing before installing the Zetadocs for NAV objects. Alternatively, reports can be duplicated and saved with new report ID s before adding the Zetadocs for NAV changes. Either way it is important to add the Version List EQ2.0 after saving the completed report. Open the Navision client and connect to/open the Navision database. Open the Object Designer (ToolObject Designer). Click on Report button in the designer menu. Select all the reports that you are going to edit for Zetadocs for NAV. Select Export objects in file menu (FileExport). Export objects to a Backup of Reports before Zetadocs for NAV2.0.fob file. Keep the Backup of Objects before Zetadocs for NAV2.0.fob in a safe place. 3.2 Import the Zetadocs for NAV Report Template Ensure that the Zetadocs for NAV report template has been imported into the object designer. Report <CD Drive>:\Zetadocs NAV Server Components\ Zetadocs for NAV V2.0 Additions Report We will refer to this report from now on as the template and to the report you are editing as the report. NOTE: The template is based on the Sales Header table. 3.3 Global, Local and Text Constants Open the template in the Report Designer and view the C/AL Globals (ViewCA/L Globals). Select all global variables (Ctrl + A), right-click and select Copy. Open the report and view the C/AL Globals. Scroll to the bottom of any existing Globals in your report and select the blank global variable row, right-click and select Paste to paste the additional Zetadocs Globals into the report. You must now repeat the above steps to copy and paste all the Text Constants from the template into your report. 3.4 Code Segments Next you need to add code to your report. The code is provided here and is also available in the Zetadocs Additions Report as an example of its completed form to assist you. Some of the code requires you to insert This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 6

7 Creating Zetadocs for NAV Reports: Code Segments the main data item name and the number of your report. These are indicated by <param description> in the pasted code. (i) Create Zetadocs Embedded Commands Data Item In the report designer select an empty row and create a new data item of type Integer called Zetadocs Embedded Commands. Move the data item up to just below your main data item and indent once so that it will be the first page of output in your report and set the properties and code as below. Open the template in the Report Designer and view the sections (ViewSections) Select the three textboxes located in the Zetadocs Embedded Commands, Body(1) section Copy and Paste the three textboxes to the same section in your report. (ii) Code Report - OnPreReport //--EQ2.0 ZetadocsSend := TRUE; noerror := TRUE; IF NOT ZetadocsSendResultGen.Initialize(<Report No.>) THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END ELSE BEGIN IF <Main DataItem Name>.FIND('-') THEN REPEAT BEGIN // Get the RecordID IF noerror THEN BEGIN RecRef.GETTABLE(<Main DataItem Name>); IF NOT ZetadocsSendResultGen.AddRecord(RecRef.RECORDID) THEN BEGIN noerror := FALSE; CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; END; UNTIL <Main DataItem Name>.NEXT = 0; IF noerror THEN IF NOT ZetadocsSendResultGen.ResolveSendInfo() THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; //--EQ2.0 Report OnPostReport //--EQ2.0-- CLEAR(ZetadocsUtilities); This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 7

8 Creating Zetadocs for NAV Reports: Code Segments CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); //--EQ2.0 Primary Data Item OnAfterGetRecord (E.g. Sales Invoice Header data item as shown in Figure 5.) //--EQ2.0-- RecRef.GETTABLE(<Main DataItem Name>); IF ZetadocsSendResultGen.IsToBeSkipped(RecRef.RECORDID) THEN BEGIN CurrReport.SKIP; END; //--EQ2.0-- Zetadocs Embedded Commands OnPreDataItem //--EQ2.0-- SETRANGE(Number,1,1); //--EQ2.0-- Zetadocs Embedded Commands OnAfterGetRecord //--EQ2.0-- RecRef.GETTABLE(<Main DataItem Name>); ZetadocsEmbComms:= ZetadocsSendResultGen.GetRecordEmbComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsCustComms := ZetadocsSendResultGen.GetRecordCustComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsMultRecComms := ZetadocsSendResultGen.GetRecordMultRecComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE //--EQ2.0-- This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 8

9 Creating Zetadocs for NAV Reports: Code Segments Zetadocs Embedded Commands OnPostDataItem //--EQ2.0-- CurrReport.NEWPAGE; //--EQ2.0-- Zetadocs Embedded Commands, Body (1) - OnPreSection //--EQ2.0 CurrReport.PAGENO := CurrReport.PAGENO - 1; //--EQ2.0 (iii) Properties (Data Item) Zetadocs Embedded Commands DataItemTableView: SORTING(Number) (Report) Report ShowPrintStatus: No Figure 5 Adding Zetadocs Embedded Commands DataItem (iv) CopyLoop If your report contains a copy loop data item that outputs more than one copy of the report per print, then you must edit the loop to only output one copy when sending using Zetadocs. An example of the standard copy loop with the additional logic is in the template. NOTE: THIS IS NOT THE EXACT CODE TO PASTE. YOU MUST EDIT YOUR COPY LOOP TO ONLY RUN ONCE WHEN (ZetadocsSend = TRUE) IF (NoOfLoops <= 0) THEN NoOfLoops := 1; IF (ZetadocsSend) THEN NoOfLoops := 1; SETRANGE(Number,1,NoOfLoops); (v) Modifications Necessary for the Role Tailored Client Reports To enable Role Tailored Client reports to be sent successfully using Zetadocs for NAV you will need to adjust the reports using the following steps. Open the Navision client and connect to/open the Navision database. Open the Object Designer (ToolObject Designer). Click on Report button in the designer menu. Select the reports that you are going to edit for Zetadocs for NAV. Select Export in file menu (FileExport). Export the report as a.txt file. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 9

10 Configuring Zetadocs for NAV: Version Code Open the file using a notepad.exe or another suitable program. Scroll down through the file until you reach the RDLDATA. Delete everything contained within the curly brackets {}. Save the changes to the file. Go to NAV and open the Object Designer (ToolObject Designer). Click on Report button in the designer menu. Select (FileImport) and re-import the modified report. Repeat the process for any remaining reports you intend to use in conjunction with Zetadocs for NAV. 3.5 Version Code Once you have saved the report add EQ2.0 to the Version List column in the Object Designer. Adding this value is essential to ensure easy identification of reports modified for Zetadocs for NAV, in particular, for uninstalling Zetadocs for NAV at a later point. 4. Configuring Zetadocs for NAV Configuration of Zetadocs for NAV has two phases, basic default settings to enable the system for document sending and archiving (specific settings), followed by the development of customized rules based on your business logic (requires planning and design). In this section there are instructions on setting the default configuration of Zetadocs for NAV. The following sections take you through the Zetadocs Setup forms in order. If you have already installed or intend to install the Zetadocs SharePoint Site Template then remember to use the archive settings detailed in the Zetadocs for Microsoft Dynamics NAV SharePoint Components Installation Guide included on the product CD, if not please ignore any SharePoint related settings detailed below. 4.1 Basic Configuration In this section the minimum required settings are presented and explained. They are listed in order and each sub section details the actions to be completed by the installer. It is recommended that the basic configuration is completed and verified as working before progressing to the Advanced Configuration section. (i) Zetadocs No. Series Zetadocs for NAV has tables which use auto generated series numbers as well as allowing the use of custom numbering. It is required that the installer create the no. series for use in these tables. The Zetadocs No. Series Card has two series which need creation. Figure 6 - Zetadocs No. Series Form It is suggested that two number series are created with the following settings and selected from the Zetadocs No. Series Form. However, it is at the installer s discretion to specify other number series as suits their client. Actions: 1. Create and assign 2 number series for Zetadocs Document Sets and Templates. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 10

11 Configuring Zetadocs for NAV: Basic Configuration Code Description Start No End No Default Nos. Manual Nos. ZDDOCSET Zetadocs ZD00000 ZD99999 YES YES Document Sets Series ZDTEMP Zetadocs Template Series ZT00000 ZT99999 YES YES (ii) Zetadocs System Settings The Zetadocs System Settings contains settings for enabling key Zetadocs for NAV features. Depending on the system that was purchased you should enable or disable the settings in NAV. Actions: 1. Set the system settings which match your installation environment and purchased Zetadocs for NAV package. Properties: Archiving Enabled o Fax Enabled o Enables archiving to Microsoft SharePoint (MOSS/WSS). When disabled, standard network folder archiving can be enabled via the Zetadocs Administration Configuration, however, this does not support any of the Zetadocs for NAV search features. Requires the installation of a Zetafax system. For instructions on Zetafax installation please refer to the Zetafax Setup guide located on the product CD. NOTE: When faxing is disabled on the Zetadocs System Settings form the system does not prevent the creation of rules including fax, however, attempts to use fax addressing may prompt warnings and during sending any documents that attempt to use fax addressing will be displayed in the Zetadocs Batch Delivery Settings Dialog as an error. Logging Enabled o To be used for troubleshooting installations and support issues. Enabling logging causes a text based log to be written to each NAV user Windows %Temp% folder (ZetadocsNAV.log). The Log Level specifies the amount of detail in the log. Log Level o ERROR Only writes error information to the log o WARNING Writes any potentially problematic and error information to the log o DEBUG- Writes all levels of detail for troubleshooting difficult problems. Recommended only when obtaining support or during installation and configuration. SharePoint Site o To be used in conjunction with Archiving Enabled, this setting should be the base URL address of your SharePoint installation should you be utilizing one. Figure 7 - Zetadocs System Settings This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 11

12 Configuring Zetadocs for NAV: Basic Configuration (iii) Zetadocs Templates Zetadocs Templates combine stationery overlays and attachment documents as well as supplementary addressing for any document sent using that template from the Zetadocs Client. The templates can be created in the Zetadocs Client and saved to a shared network location. For more information on creating Zetadocs Templates and setting up Zetadocs Shared Network folders please consult the Zetadocs Client help. There is also an introduction to Zetadocs Templates in the previous section on document templates. Any Zetadocs Templates to be applied to documents sent from NAV have to have their location imported into NAV. Please note that any local drive templates that are referenced will not be available to all users and therefore it is strongly recommended that all templates are referenced from a shared network folder to which all NAV users have access. This is done automatically when using the standard configuration data. Actions: Create a shared network folder for storing Zetadocs Templates for use with Zetadocs for NAV. All Zetadocs for NAV templates should be saved here including the stationery and attachments they use as they are referenced from a template not embedded in a template. Create the required templates using the Zetadocs Client (See Zetadocs Client help for more information) Import the template paths into NAV using this form. Properties: Template ID uses the Template No. Series created earlier. Custom ID s can also be assigned for convenient grouping of templates. Paths are browsed to and file existence is validated to complete a successful reference import. Name is taken from the template file name (minus the extension). This is in line with how templates can be referenced in embedded commands sent to Zetadocs (however, full paths are used from Zetadocs for NAV). You cannot import the same file from the same location more than once. That is to say that the Path of imported templates must be exclusive. Figure 8 - Zetadocs Template Card (iv) Zetadocs Company Type The Zetadocs Company Type provides the ability to define a relationship between a company reference and a table or some custom logic. This is primarily used on customized systems or for setting up the sending of reports to other recipients besides Customer and Vendors. For more information see Chapter 9 Bespoke Contacts and Company Types. For the standard configuration: Actions: 1. Create the Customer and Vendor Company Types Open the Zetadocs Company Types form and enter the following information NOTE: Code is Case sensitive This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 12

13 Configuring Zetadocs for NAV: Basic Configuration Code CUST VEND Description Sales & Marketing Customer recipients Purchase Vendor recipient (v) Zetadocs Document Sets A document set is the joining reference between NAV reports and a Zetadocs rule definition. A document set is essentially a display name and archive document type for a rule which is defined in the Zetadocs System Rule card. The Zetadocs Document Sets form displays the list of all registered document sets, their names and Archive Document Types. Use this window to register a new document set. Then set the criteria for this rule on the Zetadocs System Rule card. Once a document set is registered and then defined in the system rule table a set of documents (NAV reports) can be instructed to use that document set rule definition when sending via Zetadocs. Hence a Zetadocs Document Set. Actions: 2. Create the default document set No. = 0 (zero) Name = Default (or the localized equivalent) Archive Document Type = (blank) Properties: There must always exist a document set with No. = 0. This is the default rule. No. o The No. field uses the ZDDOCSET number series we created earlier. Custom ID s can also be assigned for convenient grouping of templates. Name o This is the display name for a document set as it is more descriptive for users. Archive Document Type o All documents sent and archived from NAV using Zetadocs have a default document type of Zetadocs. Specifying an Archive Document Type overrides the default and means that any document which uses that document set will be archived as that document type and has the Zetadocs document type as a parent document type. This means that the new document type will inherit all the columns from its parent document type Zetadocs Document types are useful for filtering views of documents in a SharePoint document library. For more information on using this property see the section on Archive Document Types in the SharePoint Components Installation Guide included on your product CD. (vi) Zetadocs System Rules The Zetadocs System Rule card is where the Zetadocs Document Set rule is defined. It brings together the format (templates), delivery method (contact addressing) and archiving options (SharePoint document library, Archive Document Type and document library subfolder structuring). Actions: 1. Define the default Zetadocs Document Set. Select the default document set using the Document Set property lookup on the General tab. Specify the desired delivery method failover order (remember to only specify Fax if you have Zetafax Server installed). Choose a Template from your imported template references. Enter an address that reports using this rule will be sent from. On the Archiving tab enable archiving (remember only if you have SharePoint). Complete the remaining archive options if applicable. On the Additional Recipients section, enter the contact information of any additional contacts that will receive a copy of the reports using this rule. Properties: Once you have selected the document set to define, it cannot be changed for that record. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 13

14 Configuring Zetadocs for NAV: Basic Configuration Figure 9 - Zetadocs System Rule Card General Tab General Tab Delivery Method Priority: Implies that if the contact information being used during the sending of a document that uses this rule is missing addressing information, the next highest priority method will be used. For example, if the Delivery Method Priority was , Fax, Hard-copy and the contact information being used had no information but did have fax information, then fax addressing would be used. Similarly, if there was neither or fax information, then the document would be printed from Zetadocs to the local system default printer. Template: Optional. From: Optional. The user must have access to send s using the address entered. If left blank the user s default account will be used. Comments: Field for any additional information you may wish to add. Additional Recipients: Optional. This field is available on both the general and archiving tabs. Enter additional recipients either by selecting a contact or by entering the information manually. The delivery methods available are (To, CC or BCC) and Fax. You can enter a maximum of 5 additional recipients for a system rule. distribution lists are supported but they must be entered as their full address and not an alias (E.g. support@equisys.com) Figure 10 - Zetadocs System Rule Card Archiving Tab This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 14

15 Configuring Zetadocs for NAV: Basic Configuration Archiving Tab Archive Sent Documents: Determines whether Zetadocs for NAV will attempt to archive sent documents. Archive Library: Only specify the SharePoint document library name, not the full URL. Archive URL: Displays the full target archive library by concatenating the SharePoint Site from the Zetadocs System Settings and the Archive Library property. Folder Name Structure: Subdivides archived documents into subfolders of the SharePoint document library based on information from the sent record. The Custom radio button allows you to specify new folder structuring values. Currently, no others have been implemented. o COMPANY The recipient NAV Customer name o DATE The Date with a format specified by the Date Folder Naming property o DOCTYPE The Archive Document Type as specified for the current Zetadocs Document Set, or its override in the Zetadocs Report Settings Date Folder Naming Allows you to specify the format of the date folder structure in the SharePoint archive. E.g. YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY etc. (vii) Zetadocs Customer Rules and Zetadocs Vendor Rules The Zetadocs Customer and Vendor Rules are generally accessed from the NAV Customer or Vendor card to setup the sending rules. They are made available from the Administration settings primarily for management of existing rules, such as deleting or modifying invalid rules. For the basic setup, it is not necessary to add anything here at this point. We will look more at this table in section 4.2 Advanced Configuration. (viii) Zetadocs Report Settings The Zetadocs Report Settings is where Zetadocs enabled reports can be associated with a particular Zetadocs Document Set and therefore a rule definition for sending (template, delivery method, archiving settings, additional recipients). It is also where recipient information settings are specified. For the basic setup, it is necessary to add the correct field no. s for the company and contact fields to this table. Figure 11 - Zetadocs Report Settings Card General Tab Properties: o A report can only be associated with one Zetadocs Document Set. o Many reports can be associated with one Zetadocs Document Set. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 15

16 Configuring Zetadocs for NAV: Basic Configuration General Tab Report ID: The Report ID is unique value given to identify each report. Report Name: This field is populated when the Report ID is selected. Document Set No.: The Document Set No. corresponds to the key field of the Zetadocs System Rule Table linking the report to rules for its distribution. Document Set Name: Contains the name of the rule that is being applied to the report, it is determined via the Document Set No. selection. Archive Document Type: this Archive Document Type overrides the Archive Document Type specified in the Zetadocs Document Set for a particular report. Default Batch Name: When a report prints a number of records to Zetadocs they are held in a batch in the Zetadocs Client. This field allows you to specify a name for the batch that will be visible in the Zetadocs Client document explorer. Comments: Field for any additional information you may wish to add. Figure 12 - Zetadocs Report Settings Card Table Mapping Tab Table Mapping Tab Company Type Code: This specifies a table relation between the report record and the recipient. For example, the standard Sales Quote report is to be sent to a Customer. Therefore, we select CUST for the Company Type Code from the Company Type Code List. Company No. Field No.: Specifies the field no. of the field in the table the report is based on where the Company No. should be taken from. For example, the standard Sales Quote report is based on the Sales Header table. The Customer No. in the Sales Header table is the field Sell-to Customer No. field no. 2. Contact No. Field No.: Specifies the field no. of the field in the table the report is based on where the Contact No. should be taken from. For example, the standard Sales Quote report is based on the Sales Header table. The Contact No. in the Sales Header table is field Sell-to Contact No. field no Record No. Field No.: Specifies the field no. of the field in the table the report is based on where the records No. should be taken from. This can be used as a dynamic field for writing the record no. into a template message as a reference to the recipient and also as a searchable field in the Zetadocs SharePoint archive. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 16

17 Configuring Zetadocs for NAV: Basic Configuration Figure 13 - Zetadocs Report Settings Card Options Tab Options Tab Show Delivery Dialog: Controls the display of the delivery dialogs which allow run-time user overriding of send results. Show Batch Delivery Dialog: Controls the display of the delivery dialog which allows the user to view and fix any send result errors. Preview in Zetadocs Client: Controls the default value of previewing the Zetadocs documents in the Zetadocs Client before sending. If the delivery dialog is shown the default can be overridden by the user. Test Mode: This field allows the administrator to prevent the report from printing the report results to Zetadocs. It is useful when troubleshooting problems on a live system. When the report is run it will run as normal up to the point of printing the report documents to Zetadocs. The table shown below gives the standard field no. values to use for reports based on the following tables and the figure shows some example report settings. Table No. Table Name Company Type Company No. Field No. Contact No. Field No. Record No. Field No. 18 Customer CUST Sales Header CUST Sales Invoice CUST Header 114 Sales Cr.Memo CUST Header 110 Sales Shipment CUST Header 6660 Return Receipt CUST Header 23 Vendor VEND Purchase VEND Header 120 Purch. Rcpt. VEND 2 N/A leave as 0 3 Header 122 Purch. Inv. VEND Header 124 Purch. Cr. VEND 2 N/A leave as 0 3 Memo Hdr Return Shipment Header VEND 2 N/A leave as 0 3 This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 17

18 Configuring Zetadocs for NAV: Basic Configuration (ix) Zetadocs Sales Doc. Queue Setup As explained before the Zetadocs Document Queue is a centralized location for processing inbound sales documents from, in essence a virtual in tray. This form specifies where to find the document queue files and where to archive them to once processed. Actions: 1. Create a shared network folder with full control access for any users that will process sales documents using the Zetadocs Sales Document Queue. 2. Enter the network folder UNC Path to the shared network folder. 3. Specify the archive library and a subfolder on your SharePoint Site where copies of the processed documents should be archived after processing (e.g. Original Order Documents/2007). Figure 14 - Zetadocs Sales Doc Queue Setup Card Properties: Name: The name of the document queue. Name has little significance in this version as there is currently only one sales document queue allowed. Location: Path to network accessible folder that will contain inbound sales documents. Archive Library: The SharePoint document library name only. NOTE: Unless you create the document library in SharePoint before hand, the document library will be created the first time you archive from the document queue. The document queue has a default document type of Document Queue which has the Zetadocs document type as a parent. It is therefore crucial that the Zetadocs document type is fully configured before archiving from the Zetadocs Document Queue. Archive Metadata Mapping This table shows how NAV data items are mapped to SharePoint properties. SharePoint Column Name Type NAV Value ZetadocsRecipientName Text Contact Name ZetadocsOrganization Text Customer Name ZetadocsArchiveID Text Zetadocs Archive ID from the generated record ZetadocsRecordType Text In Sales Order process only: Choice of {Order, Quote, Invoice, Credit Memo, Blanket Order, Return Order} or Posted Sales Invoice ZetadocsRecordNo Text Record No. ZetadocsCompanyNo Text Customer No. ZetadocsDateReceived Date Contains the file s last modified Date i.e. the date that the item was stored in the document queue (x) Zetadocs Purch. Doc. Queue Setup The Zetadocs purchase document queue is very similar to the sales document queue. It is used as a central location for all the inbound purchase documents. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 18

19 Configuring Zetadocs for NAV: Basic Configuration Actions: 1. Create a shared network folder with full control access for any users that will process purchase documents using the Zetadocs Document Queue. Note that the shared network folder used for the purchase document queue must be different from the folder used for the sales document queue. 2. Enter the network folder UNC Path to the shared network folder. 3. Specify the archive library and a subfolder on your SharePoint Site where copies of the processed documents should be archived after processing (e.g. Archive/Documents/2007). (xi) Report Selections To have any Zetadocs enabled report, see section Creating Zetadocs for NAV Reports, operate from the Print button on the appropriate NAV card form, the report selections table must be updated. This is only applicable if you have created new versions of reports for Zetadocs with different ID s to the normal versions. Actions: 1. Set Zetadocs for NAV Reports for the appropriate usage in NAV: In the NAV Navigation Pane, go to Administration\Sales & Marketing\Report Selections (for sales order process related reports). For each usage that you want to enable for sending via Zetadocs, select the appropriate Zetadocs enabled version of the report. Repeat the procedure for purchase order process related reports. In the NAV Navigation Pane, go to Administrator\Purchase\Report Selections Figure 15 - Report Selection Sales (xii) Printer Selections Any reports that have been Zetadocs enabled (see section Creating Zetadocs for NAV Reports) must have the Zetadocs printer selected in the printer selections to ensure that it is the default printer when sending a print job using Zetadocs. Actions: 1. Set Zetadocs for NAV Reports printer selection to Zetadocs PDF : In the NAV Navigation Pane, go to Administration\General\Printer Selections Select the Zetadocs enabled reports. Set the printer name to Zetadocs PDF. (You must have the Zetadocs for NAV Client installed on the local machine to do this). This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 19

20 Configuring Zetadocs for NAV: Advanced Configuration Figure 16 - Printer Selections 4.2 Advanced Configuration In this section the advanced settings are presented and explained. It is recommended that the basic configuration is completed and verified as working before progressing to the Advanced Configuration section. (i) Zetadocs Document Sets Once you have configured the basic Zetadocs for NAV system you can begin to consider designing more specific rules and templates to format specific types of sent documents. The Zetadocs Document Sets should be the starting point for your design. A document set identifies NAV reports (documents) which you want to send via Zetadocs with the same settings such as template formatting, delivery method ( , fax, hard-copy), archiving (location, grouping) and additional recipients. Quite often this set of documents will mirror the NAV table upon which the reports are based. For example, take the Sales Order Process in NAV. The Sales Header table can represent Quotes, Orders, Invoices etc. However, we may like to send all reports based on these with the company logo and an attached terms and conditions page. This would represent a document set. The Quote report and Order Confirmation report would be 2 documents which we would then set up to use that document set. Conversely, reports based on Quotes, Orders and Invoices may be considered positive sales and Credit-Memo s and Return Order reports viewed as negative sales and therefore they may constitute 2 document sets with different criteria for sending. The Zetadocs Document Set gives you this report level formatting control and offers convenient re-use capabilities. Actions: From your business requirements establish the reports which will be sent using Zetadocs Identify the commonalities between these reports and identify Zetadocs Document Sets Register these document sets Proceed to create and import the Zetadocs Templates for each document set (Zetadocs Templates) Define the rule for the Document Set (Zetadocs System Settings) Associate the reports with the respective document set (Zetadocs Report Settings) (ii) Zetadocs Templates The templates are a key part in customizing your sent document sets. As you will know by now it is possible to add stationery and attachments in a template. We will now look at customizing the subject and message text. Zetadocs for NAV passes a number of database values from the record being sent as a Zetadocs document. These are passed as dynamic fields, which, means that their value can be used in subject and message body text. Below is the list of available dynamic fields and an example of their use in a Zetadocs Template. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 20

21 Configuring Zetadocs for NAV: Advanced Configuration Name Name Organization ZetadocsRecordNo ZetadocsCompanyNo FirstName Surname Value Full name of the contact being sent to The NAV Company name being sent to The ID of the record on which the report was printed The ID of the company the report is being sent to. I.e. the Customer or Vendor No. The contact first name, or if blank our best attempt at the first name from the full name. (All the names except the last which is presumed to be the surname. E.g. James T. Kirk, first name would be James T. ) The contact surname name, or if blank our best attempt at the surname name from the full name. (The last word of the full name. E.g. James T. Kirk, surname name would be Kirk ) In Zetadocs dynamic fields are replaced in the subject and message text where they appear. Dynamic fields take the following format: %%[<field name>] Here is an example of setting the template subject and message and the resulting message that will be sent by Zetadocs: Figure 17 - Zetadocs Template Customized Message Design This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 21

22 Configuring Zetadocs for NAV: Advanced Configuration Result: Figure 18 - Zetadocs Template Customized Message Result (iii) Archive Document Types As discussed earlier, archive document types allow sent documents to be classified and grouped together in the SharePoint archive. The document type from Zetadocs for NAV maps onto the SharePoint content type. This means that if you are using the Zetadocs SharePoint site template you must ensure that the content types match those used with the site template. For an introduction to content types in SharePoint visit for details on the site template see the SharePoint Components Installation Guide included on the product CD. Zetadocs for NAV allows you to classify your document types in two ways, by document set or by individual report. In the Zetadocs Document Sets form you can override the default document type Zetadocs by specifying a value in the Archive Document Type column. Figure 19 - Document Set Archive Type This means that any NAV report which has been set up to use that document set will be archived with that document type. It may be advantageous to have a different Archive Document Types within one Zetadocs Document Set. This is achievable by specifying a value in the Archive Document Type in the Zetadocs Report This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 22

23 Configuring Zetadocs for NAV: Advanced Configuration Settings. This value overrides the archive document type specified by the Zetadocs Document Set the report is associated with. Figure 20 - Report Specific Archive Type (iv) Zetadocs System and Company Rules The Zetadocs System Rules were explained in the Basic Configuration section as the ability to define how a message being sent is delivered ( , Fax or Hard-Copy), how it is formatted (Zetadocs Templates), from which address the message is sent and where it is archived. By now you should realize each Zetadocs Document Set can have a separate definition of these sending settings. Zetadocs for NAV also has Company Rules, these are the Zetadocs Customer Rules and the Zetadocs Vendor Rules which add another level of control. The sending rules are best explained as a set of override rule definitions. It can be viewed as a 4 level system which overrides particular rule settings dependent upon the document set, the company or a combination of both. LEVELS: 1. The Default Rule Allows you to specify a basic rule that can be used by any Zetadocs enabled report. 2. Per Document Set Allows you to specify more specific settings for Zetadocs enabled documents by type. 3. Per Company All Zetadocs enabled documents being sent to a particular company can have the following rule settings overridden (This includes documents which are being sent using either the Level 1 or a Level 2 rule settings): i. The contact information to which the document will be sent ii. The method of delivery by which the document will be sent ( , Fax, Hard- Copy) 4. Per Company, per Document Set All Zetadocs enabled documents being sent to a particular company and that are part of a particular document set can have the following rule settings overridden (this includes documents which are being sent using either the Level 1 or a Level 2 rule settings and has had some settings already overridden by a Level 3 rule settings) i. The Zetadocs Template that will be applied to the document ii. The contact information to which the document will be sent iii. The method of delivery by which the document will be sent ( , Fax, Hard- Copy) To visualize this, let s look at the forms below to describe a use case. In this example the NAV Administrator has set up a document set for order confirmations. It has been set so that Order confirmations are sent via with the order confirmation template. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 23

24 Configuring Zetadocs for NAV: Advanced Configuration The Zetadocs System Rule card shows the level 1 rule that will apply to all documents by default unless overridden by a higher level rule. In this case documents are sent using with the default template. We can also set the archiving options on the Archiving Tab, in this example we will set the system not to archive. Figure 21 Level 1 Zetadocs System Rule Card The level 2 rule details shown below apply to all documents with the document set Order Confirmation, meaning that any Order Confirmation document will be sent using the ZD- Order Confirmation Template whilst the others will use the level 1 rule and thus the default template. Figure 22 - Level 2 Zetadocs System Rule Card During discussions with the staff at the company in our example the sales staff have requested that all correspondence between us and them be sent to Mindy Martin, with the exception of Order Confirmations. So the Default document set has the contact details adjusted to contain the contact details of Mindy Martin. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 24

25 Configuring Zetadocs for NAV: Advanced Configuration Figure 23 - Level 3 rule shown on Customer Rule Card They have requested that Order Confirmations should instead go to John Emory by fax. The figure below shows how this would be set up. This is done by adjusting the Order Confirmation rule set up for level 2 and adding that it should use the alternate contact John Emory and to deliver it by fax. Figure 24 - Level 4 rule shown in the Customer Rule List Starting from the top then, the internal processing determines the send settings by building the results from the lower level rules up. Assume we are sending an order confirmation and it uses the document set ZD00006 Orders Confirmations. This will determine from Level 1 & 2 above: Delivery Method: Template: ZT Order Archiving Settings: Do not archive Contact: Use Default contact This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 25

26 Testing the Zetadocs for NAV Solution: Full Cycle Test Scenario When we consult the Level 3 Rules we see that any document being sent to The Canon Group PLC (from the Level 3 figure above) will be sent to Mindy Martin instead of the contact specified in the record we are printing from. This would mean Delivery Method: Template: ZD Default Archiving Settings: Do not archive Contact: Mindy Martin However, the Order Confirmation document has been made part of ZD00006, therefore the Level 4 settings will be applied and it will be sent to John Emory and by fax. So the final settings will be Delivery Method: Fax Template: ZD0006 Order Confirmation Archiving Settings: Do not archive Contact: John Emory Additional Recipients The additional recipients define in the system and company rules do not override those from the lower level rule as the other settings do. They are additive. If additional recipients are added for a document set (ZD00006 Order Confirmations for example), any document sent using that document set will be addressed to these additional recipients, along with the additional recipients set at a higher level. (v) Zetadocs Report Settings There are a number of fields in the Zetadocs Report Settings which can be left set to default but will then require that additional C/AL code be written to integrate a report with sending using Zetadocs. 5. Testing the Zetadocs for NAV Solution This section shows how to test all the components of the Zetadocs for NAV product are installed and configured correctly. First it covers a full cycle scenario to test the product as a whole and then some tests for individual components. As a minimum we recommend that you carry out the full cycle scenario testing to confirm that the system is correctly installed and configured. 5.1 Full Cycle Test Scenario Before running through this test, please ensure that all the prerequisites have been met. (i) Prerequisites Create a No. Series for the Document Sets and for the Templates and assign them through the Zetadocs No. Series form: Figure 25 - Zetadocs No. Series This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 26

27 Testing the Zetadocs for NAV Solution: Full Cycle Test Scenario Create a Zetadocs Template from the Zetadocs Client. The template should have some recipient information, an attachment, stationery and some text in the body text. Name it Order Confirmation. Create another Zetadocs Template and name it Invoice. Create two custom Sales reports, one of Order Confirmations and one for Invoices Add those two reports to the Zetadocs Report Settings list: Figure 26 - Zetadocs Report Settings Set up some network folders to store and access the templates, the documents for the Document Queues etc. (ii) Test For a full end-to-end scenario follow the steps below: 1. Set up a definition of the Document Set for a Sales Order by going to the Zetadocs Document Set Card form: Figure 27 - Zetadocs Document Set Card 2. Add a Zetadocs Template using the Zetadocs Template Card: This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 27

28 Testing the Zetadocs for NAV Solution: Full Cycle Test Scenario Figure 28 - Zetadocs Template Card 3. Set up both the sales and purchase Document Queue locations using the Zetadocs Sales Doc Queue Setup / Zetadocs Purch. Doc. Queue Setup: Figure 29 - Zetadocs Document Queue Setup 4. Set up a System Rule in the Zetadocs System Rule list using the System Rule Card the default System Rule should cover the minimum information necessary and should include the as the delivery method and should have a template selected. On the Archive tab the Archive Sent Documents option should be checked and you should also add a contact in the additional recipients tab: This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 28

29 Testing the Zetadocs for NAV Solution: Full Cycle Test Scenario Figure 30 - Default System Rule Card 5. Create an original document in Microsoft Word that would represent an example Sales Order and place it into a shared network folder that the Sales Document Queue is setup to monitor. 6. View that original document from the Zetadocs Sales Document Queue form: Figure 31 Zetadocs Sales Document Queue 7. Create a NAV Sales Order based on the original document using the Create menu button on the Zetadocs Sales Document Queue form. 8. Archive the original document to SharePoint by closing down the Sales Order form (it will archive the document automatically). 9. Open the just created NAV Sales Order and add any further info needed. 10. Send the NAV Sales Order to the Zetadocs Client by printing it. 11. Confirm in the Zetadocs Client that the correct template has been applied to the printed Order. 12. Send the Order to the recipient. 13. Confirm that the sent document has been archived in SharePoint and can be associated with the original document. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 29

30 Testing the Zetadocs for NAV Solution: Detailed Component Testing 5.2 Detailed Component Testing This section contains instructions for how to test specific components of the Zetadocs for NAV system. (i) Document Queue This section details how to test that the Document Queue is functioning correctly. The following tests are valid for both the Sales Document Queue and the Purchase Document Queue. The terminology Zetadocs Document Queue in this section is used to describe both document queues. Check Scanning (Optional) If a scanning device is connected, perform the following checks to ensure correct operation. 1. Click the Queue Scan... button to initiate scanning which uses the Zetadocs client settings. 2. Scan a document; once scan is complete the user should be prompted to name the document. Figure 32 Enter Scanned Document Name 3. Upon Save, the scanned document name should appear in the Zetadocs Document Queue as the latest entry. The file (typically filename.pdf ) should also be in the Zetadocs Document Queue shared folder location. Check Shared Location Updating 1. Create an with an attachment and save it as a.msg file into the Zetadocs Document Queue s shared folder location. 2. Press the QueueRefresh menu button and ensure that the saved .msg file is now in the Document Queue. 3. Select the.msg entry in the Zetadocs Document Queue and click ItemView, ensure that the item is viewable in the native application. Repeat for the scanned.pdf file also. Check Printing 1. Select the scanned.pdf file and click ItemPrint, when prompted select a physical printer and click print. Ensure that the document prints to the printer. 2. Select the recently added.msg file with attachment(s) and click ItemPrint, when prompted select a physical printer and click print. Ensure that the document prints to the printer and that the attachments are printed out also. Check Delete 1. Select an entry in the Zetadocs Document Queue and click ItemDelete. Ensure that the document is removed from the Queue and also that it successfully deletes the file from the Zetadocs Document Queue network folder location. (ii) Send to Zetadocs Client The Zetadocs Client can deliver your NAV documents by or fax and it can also send them to a physical printer. You can setup the NAV Client to do that per Document Set and/or per Company (Customer or Vendor). Setting up the Zetadocs System Rules for each Document Set or setting up the Zetadocs Customer/Vendor Rules for each Document Set you can test where each Document Set will be delivered and how. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 30

31 Testing the Zetadocs for NAV Solution: Detailed Component Testing Change the Delivery Address of the Default System Rule to Fax to test sending to a recipient by fax or change the Delivery Address to Hard Copy to test printing a hard copy through the Zetadocs Client where the template will be applied. Zetadocs for NAV can send a batch of NAV documents to independent recipients. To test this feature create a number of Sales Orders and print them like in the previous example described in the Full Cycle Scenario section. This time you will see the batch document in the Zetadocs Client which it will include the Sales Orders from NAV Client with the templates applied. If you have the Preview Documents in Zetadocs Client Before Sending option unchecked the Zetadocs Client will begin sending all the documents in the batch automatically after loading the batch. It is suggested you leave it checked until familiar with the printing and sending. (iii) Zetadocs Rules Zetadocs for NAV has the ability to create rules to determine the way a NAV document will be send and to whom depending on certain circumstances. Zetadocs System Rules are the Level 1 and 2 rules. Zetadocs Customer/Vendor Rules are the Level 3 and 4 rules. The Default System Rule set up for the Full Cycle Scenario section is Level 1 rule. Let s test the rest of the rule levels. Level 2 Rule Test 1. Create a Document Set and name it Invoice. 2. Add the Invoice template you created earlier in the Zetadocs Template List. 3. Create a Zetadocs System Rule and select the Document Set to be the new Invoice and set the Template to be the Invoice template: Figure 33 - System Rule Invoice 4. Print a NAV Invoice and check in the Zetadocs Client that the Template Invoice has been applied. Level 3 Rule Test 1. Go to the Customer Card with whom you have made an order. 2. Click the Customer Button and select Zetadocs Rules. 3. The Zetadocs Customer Rule Card will open. 4. Select the Delivery Tab and select a sending option other than Use Default and/or change the delivery address (by changing any of those settings on that page you create a Level 3 Rule for that customer). This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 31

32 Introduction to NAV Customization: Microsoft Dynamics NAV Compatibility Figure 34 - Customer Card - Zetadocs Tab page 5. Send an Order to this customer and check that the NAV document has been delivered to the correct recipient. Level 4 Rule Test 1. Go to the Customer Card whose Customer you have made an order. 2. Click the Customer Button and select Zetadocs Rules. 3. The Zetadocs Customer Rule Card will open. 4. Create a Customer Rule (Level 4 rule) for this particular customer. 5. Print a NAV document and check in the Zetadocs Client that the appropriate settings from that Customer Rule have been applied. 6. Introduction to NAV Customization In the Zetadocs for Microsoft Dynamics NAV Installation Guide you were guided through setting up the product for Sales and Purchase Order processes. However, the Zetadocs for NAV architecture is such that it can be adapted to be used in a multitude of situations. Understanding how Zetadocs for NAV works is paramount to unlocking the true potential of the product. The aim of this document is to guide you through the development and integration of Zetadocs for NAV with highly customized systems, as well as guiding you through the use of the Zetadocs for NAV SDK granule. The document contains an overview of the Zetadocs for NAV objects architecture, provides some concrete examples of how to use the SDK granule to implement custom business logic and also gives some examples of how to integrate with some typical NAV customizations. It is recommended that you read the entire installation guide and are familiar with the Zetadocs for NAV Addin before continuing. 6.1 Microsoft Dynamics NAV Compatibility This product has been developed and tested against Microsoft Dynamics NAV 4.0, 5.0 and 6.0. It cannot be guaranteed that the NAV objects and NAV code in Zetadocs for NAV will be supported on other NAV versions. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 32

33 Introduction to NAV Customization: Glossary of Terms 6.2 Glossary of Terms Term Company Contact Address Object Report Document Description An object in NAV which stores information about an organization that your organization deals with. This can also be your organization. Example: Customer A person in a Company with whom your organization has correspondence. This can also be a person in your organization. Example: Contact Information a Contact has about how and where correspondence should be sent. Example: jackjones@company.com An NAV object which defines data or UI or processing units. Examples: Table, Form, Codeunit A document which displays information from NAV Tables. Any printable document that can be printed to the Zetadocs printer. Typically refers to an NAV Report in this document. 6.3 Overview of Zetadocs for NAV This diagram shows the main applications and components of Zetadocs for NAV and the flow of data from NAV to Document Recipients and SharePoint. The dashed line represents launching a SharePoint search for documents previously archived to SharePoint when sending a document from NAV using Zetadocs. Microsoft Dynamics NAV Zetadocs API Zetadocs Client Document Recipients SharePoint Service Figure 35 - Zetadocs for NAV Architectural Overview This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 33

34 Introduction to NAV Customization: Overview of Zetadocs for NAV To supplement this diagram we have provided a typical real world example of the data and its flow through the system. Typical Send Use-Case 1. From within NAV, the user views a queue of documents to be processed. 2. One by one they view each order and input the details into NAV. 3. On finishing the order entry the original order document is copied to a persistent document library in SharePoint with associated metadata to bind it to the created record in NAV. This uses the Zetadocs API. 4. The user then sends an order confirmation document from NAV to the customer. The Order Confirmation report in NAV is modified to contain formatting and delivery information ( address of customer) as well as metadata to bind the document to the NAV record. Zetadocs Client loads the printed report, applies the formatting, converts the completed document to PDF and sends to customer. 5. A copy of the sent document is archived in SharePoint. The Zetadocs Client passes a copy of the PDF to the SharePoint Service with the metadata for persistent storage. (i) Document Queue, Order Entry and Archiving Currently focused on both the Sales Order Process and the Purchase Process in NAV, it allows the user to view documents for data entry and archives these documents, with metadata from the associated record that is created, to a SharePoint document library. It also sets up a reference for monitoring correspondence associated with the record over the course of the order process. This means that at any point during or after the sales or purchase process all documents associated with an order can be quickly found and reviewed on screen. The Zetadocs Document Queue provides a simple user friendly interface for document processing. It displays a list of documents currently waiting to be processed from a centralized folder. The list shows you the name of the document, the date it was saved to the network folder, and the source which tells you whether the document was scanned in, or received by fax or (based on file extension). The document queue form allows you to quickly identify any document you are searching for. It also allows you to: View, print and delete the item using the Item button. Create a quote, an order, an invoice, a credit memo, a blanket order, a return order or link the document to an existing record (posted or otherwise). Scan a newly received document. (ii) Sending Reports using Zetadocs Any NAV Report can be printed to the Zetadocs printer, addressed in the Zetadocs Client and sent to that recipient. To take advantage of the automated addressing, formatting and archiving of Zetadocs for NAV the report must be edited to link in Zetadocs for NAV rules and output addressing, formatting and archiving data during the printing of the report. The Zetadocs Client then uses that information to format, send and archive the document. Zetadocs for NAV maintains a set of company-wide sending rules which determine the format, addressing and archiving settings for particular reports and customers. With very little work, Zetadocs for NAV makes the sending batches of fully formatted, customer specific documents with personalized messaging easy and manageable. (iii) Archiving to SharePoint In a SharePoint enabled company, Zetadocs for NAV offers the ability to archive backup copies of correspondence documents in a highly customizable archive. It does this by storing metadata against the archived document that make it easy to locate record or customer related documents, or to simply search based on your own criteria. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 34

35 Architecture Overview: Typeless Public and Private Code 7. Architecture Overview The Zetadocs for NAV Addin can be split into 2 main areas, data and processing. The installation guide dealt primarily with setting up the data that would determine our report formatting and send information when sent to the Zetadocs Client. We saw how reports could be grouped into Document Sets which share a common rule for formatting and archiving and we saw how rules can be stored which alter formatting and send information dependant on who we were sending to. It is assumed then that we have a good understanding of the information involved in sending a report using Zetadocs for NAV. In this architectural overview the process of collating the sending information, which we refer to as the Send Results, is explained. This includes a breakdown of the main processing areas and their use in integrating with NAV as well as an insight into the customization potential and extensibility of Zetadocs for NAV. 7.1 Typeless Public and Private Code The Zetadocs for NAV processing code is split into two categories, public and private. Public being NAV objects that we have installed which are editable by a VAR, and private, the objects that are not editable. This is more commonly known in NAV as having Modify rights on the codeunit or not. The code is also written so that it is typeless, meaning it is not compiled against specific tables in NAV, all data access is done using table and field references and therefore the code is adaptable to work with any data set. This concept will become clearer as we progress through the examples in this document. The core processing codeunits of Zetadocs for NAV are private as this allows us to be able to provide upgradable object versions of our core processing engine without additional work necessary from a VAR to copy and reconfigure customization they have made. To ensure that we still remain a highly customizable solution we ensure that all our processing data is typeless and all interactions with existing NAV data and objects remain public, and are therefore editable by a VAR. 7.2 Data Processing Flow Now let s look at the flow of data that occurs when sending a report. The following diagram helps to visualize the process and will aid us in discussing the relevant parts of the product. As you can see from the diagram it starts with a NAV report that has been modified for Zetadocs for NAV. A report is generally based on a set of records that are used to produce some report output, a document for each record. The records contain information that relates to a contact and possibly a company, to whom the report should be sent (i.e. the recipient). Sometimes that information can be a direct table reference to an existing table that represents a contact or company for example, or it may contain some other form of references which can be used to find the contact information from another source. This could be a look up table of some sort based on some bespoke logic. The Zetadocs Send Results Gen codeunit is the central processing controller and builds a runtime list of send results in a temporary table of type Zetadocs Send Result for each record in the report. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 35

36 Architecture Overview: Data Processing Flow Zetadocs Send Results Gen 2. Zetadocs Settings Tables Initialize Add Record ResolveSendInfo GetEmbComms 1. Zetadocs Send Results NAV Report Zetadocs Integration Zetadocs Customization Records Integration Functions 3. Override Functions Table Table Table NAV Tables Data Query Temporary Table Codeunit Table Records (Filtered Table) Private Public Notation Figure 36 - Zetadocs for NAV Architecture Diagram (i) Interfacing with the Zetadocs Send Results Gen codeunit (1.) A report modified for Zetadocs for NAV will call the four trigger functions on the Zetadocs Send Results Gen codeunit. Firstly, Initialize (1.) is called to set the report that is being printed. The initialization information allows us to determine what report settings, if any, have been specified (2.). After initialization we start to process individual record specifics. Each record reference is passed to the send results codeunit by calling AddRecord (1.). Each record is then processed to extract the contact information (3.). Depending on who the company is we may apply specific rules covering how the contact or the template is determined. When all rules and settings have been applied the Zetadocs Customize codeunit is called to offer overriding of the result (4.) (This requires the Zetadocs for NAV SDK Granule). Once all the records have been added ResolveSendInfo (1.) is called which will offer run-time user override and error resolution dialogs. The final This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 36

37 Architecture Overview: Summary step is for the report to request the formatted embedded commands text to print for each report by calling GetEmbComms (1.). Once again a call is made to offer the ability to add additional embedded commands in the Zetadocs-Customize codeunit (4.) before returning the full text of embedded commands to the report. These embedded commands are then extracted by the Zetadocs Client after printing to the Zetadocs printer. (ii) Querying the Zetadocs Settings (2.) Based on the ID of the report that is being printed we can determine what template and archiving settings to use for the report and potentially how to automatically find the company and contact references from the report records. Internally the Zetadocs Send Results Gen codeunit will query the Zetadocs Report Settings using the report ID. These settings control the flow of processing from this point on. Figure 37 - Zetadocs Report Settings (iii) Resolving the Company and Contact Information (3.) This can happen in a number of ways depending on the Zetadocs Report Settings for that report. The report settings control whether the Zetadocs Send Results Gen codeunit can copy the company and contact references from a field in the record or whether it should call out to the Zetadocs-Integration codeunit for the information. It is in this public codeunit that a VAR will implement their custom integration code for their system. This is explained in more detail in a later section of this guide; however, this should highlight the main purpose of the Zetadocs-Integration codeunit and the Zetadocs Send Result table being public. It means that when we need to access data from typed NAV tables this code is exposed to the VAR developer to allow them to integrate or customize successfully. The private Zetadocs Send Results Gen codeunit only correlates and manages the data, unaware of its meaning (typelessly). (iv) Overriding in Customize Codeunit (4.) There is the ability to alter the Zetadocs Send Results record directly in this codeunit before continuing with sending of a report. Each send result is passed to this codeunit by calling OverrideSendResult internally in the Zetadocs Send Results Gen codeunit. This gives the VAR a great opportunity to implement customized business logic above that offered by Zetadocs for NAV. An example would be altering the recipient (contact) depending on the value of an order. The second potential customization is to add additional embedded commands for tailoring messages using dynamic fields in Zetadocs Templates or adding extra metadata to be archived with the document. 7.3 Summary Now that we have been introduced to the architectural overview of Zetadocs for NAV it should be easier for us to understand the sections which follow and begin to allow us to imagine the potential customizations and workflow that could be created with the Zetadocs for NAV Addin. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 37

38 Send Any Report: Permissions 8. Send Any Report In the installation guide we saw how to configure Zetadocs for NAV to send reports from the Sales Order and Purchasing processes. We edited the NAV reports for Zetadocs for NAV and set the report settings to point at the Customer or Vendor reference for that report and the respective Contact reference. With this information Zetadocs for NAV was able to extract the references and query the names, addresses and fax addresses of the contact, as well as, cross reference the company (Customer or Vendor) reference with the associated Zetadocs Customer or Vendor rules tables to apply per company formatting and addressing logic. This however is not the limit of Zetadocs for NAV functionality. This principle of field reference and related information resolution can be applied to almost any report. In this section we will see how small changes in the report settings can control and alter the information used to address, format, send and archive a report using Zetadocs for NAV. 8.1 Permissions Before we enable more reports for sending there are some permission considerations to consider. The Zetadocs-Integration codeunit has a function that is called by the Zetadocs Send Results Gen codeunit to set the Zetadocs Archive ID for any record being archived. This is here to allow a VAR to add to the permissions of this public codeunit any tables they wish to send and archive using Zetadocs for NAV. For this reason please follow these instructions for each report you wish to enable for archiving. 1. Determine the table type (<TableName>) of the record you are sending in the AddRecord command in your report. (This is the record which will have the Zetadocs Archive ID set in it.) 2. Modify the table is the table designer. Add the Zetadocs Archive ID field (case sensitive, type GUID) 3. Ensure that the field no. you choose for this field is the same as other tables in the posting line to ensure correct copying of the archive id across the tables during posting. 4. Modify the permissions on the Zetadocs-Integration codeunit ( ) to include TableData <TableName> =rm 8.2 Simply Send Perhaps you have no requirement for the power of the rules support provided by Zetadocs for NAV for a particular report or number of reports. You simply want to give your users the ability to manually address a report at runtime using contact information in NAV and send using Zetadocs. For example you need to send the Warehouse Shipping Status report to someone who does not have access to that report in NAV. This is simply done by not associating the Zetadocs edited version of the report with any Zetadocs Document Set in the Zetadocs Report Settings. The following instructions explain how to set this up. 1. Edit the desired report for Zetadocs for NAV (See the Single Recipient report style in section 11.) 2. Do not enter any report settings in the Zetadocs Report Settings for your modified report. 3. Set the printer selection for your modified report to Zetadocs (Administration\General\Printer Selections in NAV). Now when the report is run you should see the Zetadocs Delivery Dialog where you can select your addressing and template information. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 38

39 Send Any Report: Configured Send Figure 38 - Zetadocs Delivery Dialog 8.3 Configured Send It should be clear by now from the installation guide that by setting the Company Type Code, Company No. Field No. and Contact No. Field No. fields in the Zetadocs Report Settings that you can configure Zetadocs for NAV to automatically resolve your contact information and apply company specific rules if they exist. In this way it is possible to reference any fields which contain the right type of reference (i.e. customer/vendor or contact etc). There is some logic to the application of these settings that is important to know to help decide what settings to enter but it also gives the opportunity for some variations in configuration. (i) Zetadocs Report Settings Field No. s Reference Logic (Pseudo Code) IF Company Type Code <> NULL THEN IF Company No. Field No. <> NULL THEN Get the Company No. from Record using Field No. ELSE CALL Integration codeunit GetCompanyForReport for VAR to get Company No. END END Send Result.VALIDATE(Company No., Company No. Value) IF Contact No. Field No. <> NULL THEN Get the Contact No. from Record using Field No. ELSE CALL Integration codeunit GetContactForReport for VAR to get Contact No. END Send Result.VALIDATE(Contact No., Contact No. Value) From this it is important to notice the order that validation happens in as this coordinates with the Zetadocs Send Result table OnValidate trigger code for Company No. and Contact No.. Since the company information is validated first no contact reference will be set yet. We can check for this and default to using This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 39

40 Send Any Report: Custom Send the company s communication information, later when the contact reference is validated we can override the addressing information ( , fax). This provides the fallback addressing logic of Zetadocs for NAV so that if a record has a blank reference for a contact we will still end up with the company correspondence information. This means that we can deliberately control what information is used by altering the settings. It also means that this behavior can be customized by the VAR by implementing the get trigger functions in the Zetadocs-Integration codeunit and/or changing the OnValidate triggers in the Zetadocs Send Result table. Company Type Code Company No. Field No. Contact No. Field No. Resulting Addressing Info Used SET SET SET Contact Info unless the reference in record is blank THEN Company Info SET NULL SET Contact Info unless the reference in record is blank THEN Company Info using Company Reference implemented by VAR SET NULL NULL Contact Info using Contact Reference Implemented by VAR unless that reference is blank THEN Company Info using Company Reference implemented by VAR NULL NULL SET Contact Info NULL SET SET/NULL Invalid You must specify a company type to enable use of company field. Table - Zetadocs Report Settings Addressing Information Control Options To get a strong understanding of this it is recommended that you review the OnValidate triggers for Company No. and Contact No. in the Zetadocs Send Result table and familiarize yourself with the trigger functions in the Zetadocs-Integration codeunit. These are explained in detail in the next section. 8.4 Custom Send We saw in the last section how selecting certain report settings can control the flow of the operation of the Zetadocs processing codeunits. By exploiting these settings and implementing the trigger functions in the Zetadocs-Integration codeunit we can highly customize our report sending. In this section we will focus on the trigger functions in the Zetadocs-Integration codeunit and explain how they can be used. (i) GetZetadocsArchiveID WARNING: This function should be left unchanged. It is only exposed in this codeunit to allow a VAR to add additional permissions to the codeunit for reading and writing the Zetadocs Archive ID value to and from additional tables! (ii) OverrideSendSettings Apart from setting up the company and contact field number references in the Zetadocs Report Settings there are a number of other options that control the display options and the report batch information settings. During the Initialize function (See Section 7 Architecture Overview) these settings are copied in to a temporary table called the Zetadocs Send Settings. This gives us the ability to adjust these settings at This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 40

41 Send Any Report: Custom Send runtime. Once the report settings have been copied into the temporary send settings table described, the Zetadocs Send Results Gen codeunit calls the OverrideSendSettings trigger function in the Zetadocs- Integration codeunit. Here you can modify the settings based on some logic for that send instance. Let s have a look at the Zetadocs Send Settings table. Figure 39 - Zetadocs Send Settings 1. Report ID WARNING: This is not for editing. It is here to allow the developer to determine which report is being printed in the trigger and to branch CASE or IF statements depending on its value. 2. Batch Name In the Zetadocs Report Settings you have the ability to specify a Default Batch Name. This is the name that will be displayed in the Zetadocs Client for the report records printed to Zetadocs. This default value can be overridden in this function. 3. Show Delivery Dialog, Show batch Delivery Dialogs, Preview in Zetadocs Client and Test Mode All these can be dynamically overridden in this trigger at runtime. For more information on their meaning please see the Zetadocs for Microsoft Dynamics NAV Installation Guide.pdf on your CD. 4. Company Type Code Similar to the Report ID, this value is not for editing but is present to allow the developer to determine the target company type configured for this report without having to query the Zetadocs Report Settings Table. A good example of when you might use this function is if you wish to have a report run uninterrupted by UI dialogs and previewing in the Zetadocs Client if it is being sent during the night. All previews could be turned off. (iii) GetContactForReport As explained in the previous section, not specifying a Contact No. Field No. means that this function will be called for you to return the value. This means that you are not restricted to extracting the reference directly from the record being reported. The report id, record id and send settings are passed as parameters into this function and therefore you can implement your own custom logic for each report and record type to determine a contact. Note that the return value Code is not typed and is extra long. This means that the code is not tied to a specific NAV type. This will be covered more in the next chapter. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 41

42 Send Any Report: Custom Send (iv) GetCompanyForReport Similar to GetContactForReport this function allows you to implement custom logic for determining the Company No. value. The report id, record id and send settings are passed as parameters to this function and therefore you can implement your own custom logic for each report and record type to determine a contact. Note that the return value Code is no typed and is extra long. This means that the code is not tied to a specific NAV type. This will be covered more in the next chapter. (v) GetHardCopyPrinter This function is always called to get the printer to use for the current user when the delivery method is set to Hard Copy. It defaults to using the NAV Printer Selections setting for that user for that report otherwise it uses the user s system default printer. It is provided here to allow you to change this logic. (vi) GetOutputFileName When a report is printed to Zetadocs, converted to a pdf and sent to a recipient it is desirable to be able to name that pdf file something relevant. This function is called from the AddRecord function in the Zetadocs Send Results Gen codeunit (i.e. once per report record) to allow you to specify independent file names. (vii) GetRecordNoForReport Similar to the Company No. Field No. and Contact No. Field No. settings in the Zetadocs Report Settings there is an option to specify the Record No. Field No. This fields purpose is primarily for customizing Zetadocs message content. For example it is often desirable to include a Ref. number in the subject of correspondence. This can be set by adding %%[ZetadocsRecordNo] into the subject of a Zetadocs Template. Figure 40 - Zetadocs Template Wizard Once again this field no. reference setting operates similar to Contact No. Field No. such that if the field is left blank in the Zetadocs Report Settings then this function will be called from the AddRecord function in the Zetadocs Send Results Gen codeunit. This may be necessary if your reference number is composed of more than one field value. If so these field values could be concatenated and returned from this function. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 42

43 Bespoke Contacts and Company Types: Company Types (viii) GetCompanyRule This function is exposed here for a number of reasons. Firstly it allows the customization of rules dynamically at runtime but primarily it can used in conjunction with the Company Type Code to provide company rules for bespoke company types (i.e. types other than Customer and Vendor). This is explained in more detail in the next chapter. The important thing to note about this function is the parameter that is passed. The Zetadocs Company Rule is another temporary table maintained in the Zetadocs Send Results Gen codeunit. This is used to get the rule override information irrespective of the company type. This will become clearer in the next chapter. It is recommended that you review the implementation of this trigger function in the Zetadocs-Integration codeunit to further your understanding. 9. Bespoke Contacts and Company Types Due to the nature of NAV system installations and the hugely customizable potential it is acceptable that some systems may or may not use the company tables 18 Customer and 23 Vendor. Similarly some systems may not use the Contact Management Module or the native NAV 5050 Contact table. These entities may have bespoke tables, this section details how Zetadocs for NAV can be integrated into such systems. This section focuses on the abstract relationship between the Zetadocs Company Types table and the tables that represent these types. We will also see how Zetadocs for NAV can be extended to integrate with other existing native company types. 9.1 Company Types Zetadocs for NAV integrates with two native company types in its initial configuration, Customer and Vendor. However, the code which directly accesses these tables is kept in 2 locations that are public to a NAV VAR. As an example of how one could implement a new bespoke company type or in fact edit one of the existing company types CUST and VEND the following example is presented. NOTE: the Zetadocs Sales Document Queue form ( ) operates for the Sales process only and uses direct references to the Customer and Contact names field in the Sales Header table. If you have modified the Sales Header table (36) to work with your bespoke Customer and/or Contact implementations then you may need to alter the references to Sell-to Customer.. and Sell-to Contact... field references. (i) BANK Example Consider the business relation BANK. To integrate Zetadocs for NAV with reports that are sent to BANK contacts you would follow these instructions. 1. Create a Zetadocs Company Type BANK Figure 41 - Zetadocs Company Types 2. Implement the BANK IF case to get the bank name and addressing information from your bank table in the Zetadocs Send Result table ( ) similar to the CUST case. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 43

44 Bespoke Contacts and Company Types: Company Types Figure 42 - Zetadocs Send Result Table Code 3. Also update the Company No. - OnLookup trigger and Contact No. - OnLookup trigger to include the IF case for your BANK type. 4. Update the tbcontname OnLookup trigger in the Zetadocs Delivery Form ( ) to use the correct ContactBusinessRelation information if necessary. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 44

45 Bespoke Contacts and Company Types: Contacts Figure 43 - Zetadocs Delivery Form tbcontname textbox 5. Then in the Zetadocs Report Settings set the BANK Company Type for the report that has BANK recipients and set the respective Company No. Field No. and Contact No. Field No. references for the report source table. 6. If you have implemented a bespoke Customer table for use with Sales and Marketing then you may need to update the Zetadocs Sales Document Queue Form ( ) to use your bespoke Customer record type references where necessary. 9.2 Contacts Similar to Company it is possible that there may be a bespoke implementation of Contact information or there may be a requirement to change the default contact address resolution logic of Zetadocs for NAV. (i) Validating As has been explained the Zetadocs Report Settings the Contact No. Field No. determines whether the contact reference can be extracted from a field in the record that is passed to the Zetadocs Send Results Gen codeunit or whether this is implemented by the VAR and called from the codeunit. Once the reference has been set in the Contact No. field in the Zetadocs Send Result table the OnValidate trigger is called. Therefore to modify the contact addressing resolution or to change the code to use a bespoke contact table you must follow these instructions: 1. Modify the Contact No. OnValidate trigger in the Zetadocs Send Result table ( ) to get the name and addressing information from your bespoke contact. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 45

46 Zetadocs-Customize codeunit: OverrideSendResult Figure 44 - Zetadocs Send Result table - Contact No. code 2. Modify the Contact No. OnLookup trigger in the Zetadocs Send Result table ( ) to use the correct ContactBusinessRelation information dependant on the Company Type Code. 3. Update the Zetadocs Delivery Form ( ) references to contact information to use your bespoke contact record type and correct ContactBusinessRelation information if necessary. 4. If you have implemented a bespoke Customer table for use with Sales and Marketing then you may need to update the Zetadocs Sales Document Queue Form ( ) to use your bespoke contact record type references where necessary. 10. Zetadocs-Customize codeunit By now you should have a good idea of what this codeunit is for. Up until now we have been exploring the internal processing and control flow of the Zetadocs for NAV Addin. By using specific settings and writing some code in the Zetadocs-Integration codeunit and the Zetadocs Send Result table triggers it is possible to completely integrate and customize Zetadocs for NAV into an NAV system. We have also seen the potential to implement business specific logic into the sending mechanism and expand on the Zetadocs for NAV product functionality. There is still however room to take it further. This section details the two basic functions in the Zetadocs-Customize codeunit ( ) that allow the implementation of more business specific send logic as well as document formatting and archiving customizations OverrideSendResult As the name suggests this function gives you the whole send result. At this point the result has been completely resolved by Zetadocs and any custom code that has been implemented by you in the various areas explained earlier in this document. This then allows you to modify the completed record as a whole. The only place the results can be edited after this are in the Zetadocs Delivery Dialogs or the Zetadocs Errors Dialogs depending on your display settings for these dialogs, as specified in the Zetadocs Report Settings (potentially overridden by the OverrideSendSettings in the Zetadocs-Integration codeunit). Let s examine the Zetadocs Send Result table a little more closely now for the first time. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 46

47 Zetadocs-Customize codeunit: OverrideSendResult Figure 45 - Zetadocs Send Result Some of these fields will be familiar from having worked with the Zetadocs Company Rule used in the GetCompanyRule trigger function in the Zetadocs-Integration codeunit. Let s break them up into their respective parts and get familiar with their use and how we can exploit this to implement our specific business logic and workflow. (i) Record Fields (1 2) The Record ID and Record No. represent the typeless and typed references to the record we are sending. Record ID is used by the core processing of Zetadocs for NAV to tie the send results and records together. Record No. is what will ultimately be passed to Zetadocs for use as an external reference by either the recipient or in archiving to SharePoint. For more information on Record No. see section 8.4.iii. Example Usage: Having the Record ID of what you are sending means you can get that record and query or use values from that record to implement logic for changing other fields in the Zetadocs Send Result. (ii) Company Fields (10 12) These fields and their use should be extremely clear by now. The Company Type Code allows us to integrate with native and bespoke company tables such as Customer, Vendor and one of your own design. Company No. and Company Name are then obvious references to the id and display name of the company. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 47

48 Zetadocs-Customize codeunit: OverrideSendResult (iii) Delivery Method (20) This controls the addressing that is selected for sending, , Fax or Hard Copy. Some obvious customization possibilities include implementing a company policy such as Any company sensitive information should not be ed under any circumstance and should be faxed or printed only. Depending on particular reports or recipients the delivery method could be checked or changed to uphold company policy. (iv) Contact Fields (30 31) In collaboration with the Company fields these fields can integrate with native and bespoke systems for contact addressing information resolution. By setting and validating this field is it possible to pull the information from the contact based on the logic that is implemented in the Zetadocs Send Result table triggers as discussed previously. (v) Addressing Fields (40 60) Provides the ability to set additional recipients in the Cc and Bcc fields, these fields are without relationships to the contact and company references that may or may not be present in the send result record. This means that addressing information can be taken from anywhere for the respective , cc, bcc, fax and print addressing fields. Care should be taken to clear the company and contact no. fields before setting these values manually. (vi) Archiving Fields (70 72) Set in the Zetadocs System Rule that you have associated with a report via the Zetadocs Report Settings, the archiving settings are available for per record modification. This can be used for example in deciding whether or not the document is archived depending on its content or changing the archiving location to a limited permissions document library in SharePoint, or sub categorizing documents using the Zetadocs Archive Document Type. Properties: Archiving Enabled per document archiving Archive Location the archive connection string takes the following format o sharepoint: <site>, <archive library>[/subfolder[/subfolder ]] Archive Document Type for an in-depth explanation of this please refer to the Zetadocs for Microsoft Dynamics NAV SharePoint Components Installation Guide.pdf on your CD. Customization Examples: (vii) Zetadocs Archive ID (80) WARNING: This field will contain data which contains a reference for an NAV record to archived documents. It should not be edited or you risk breaking the archive search functionality of Zetadocs for NAV. (viii) Zetadocs Template Fields The Zd Template Name field is set automatically as the Zd Template ID field has a table relation with the Zetadocs Template table. The uses of this field are fairly obvious, change the Zetadocs template being used depending on some custom business logic. (ix) Error Fields The Zetadocs Send Result table ( ) has a trigger function CheckErrors. This function is called for each results record in the Zetadocs Send Results Gen codeunit during the ResolveSendInfo function. This happens after all possible modifications of the send result values have taken place in the Zetadocs- Integration trigger functions and Zetadocs-Customize codeunit override function OverrideSendResult. This function checks the addressing information ( , fax, printer) against the specified Delivery Method ( , Fax, Hard Copy) to pre-empt potential send failures in the Zetadocs Client. If an error is found in a Zetadocs Send Result record the Error field is set to TRUE and a description of the error written in Error description. It is possible to implement your own error checks by editing the code in the CheckErrors function in the Zetadocs Send Result table. Note that the presence of an just 1 error record in the Zetadocs This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 48

49 Zetadocs-Customize codeunit: GetAdditionalEmbComms Send Result record for a particular send will cause the Zetadocs Batch Delivery Dialog to display IF the Zetadocs Send Settings for that send has Show Batch Delivery Dialog set to TRUE otherwise all errors will be marked as Skip = TRUE. (x) Skip When Skip = TRUE this will cause the report to use CurrReport.Skip for the associated record. For example if your report contains 3 reports and one is marked to skip then only 2 will be printed to Zetadocs. If the Zetadocs Batch Delivery Dialog is displayed either by there being errors in the send results or by the user choosing to preview the send results, they can manually set a report to skip particular report records. Figure 46 - Zetadocs Batch Delivery Dialog (xi) Output File Name When a report is printed to Zetadocs and split into the addressable documents each document is given a name. It is desirable to be able to control the name of these documents as it will be the name of the PDF file produced and attached to s as well as archived to SharePoint. This field allows you to set that document name. A good example of its use would be to generate the name based on the type of report and the record no. For example: Order Confirmation: Using the RecordID you can retrieve any information about the record for generating the output file name GetAdditionalEmbComms In the final stage of the reporting process for Zetadocs for NAV the GetRecordCustComms function is called from the report on the Zetadocs Send Results Gen codeunit to retrieve the formatted embedded commands which represent the send result for each report record. Internally in the Zetadocs Send Results Gen codeunit we create the Zetadocs embedded commands but before we return it we call this trigger function GetAdditionalEmbComms in the Zetadocs-Customize codeunit. This allows you to return additional embedded commands which can be used to customize your document message subject and body text as well as additional archive metadata to associate with the document when it is archive. (i) Dynamic Fields Dynamic Fields are name/value pairs that can be used to pass any information to Zetadocs. The format of the command is: For Example: %%[field: <name>, <value>] This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 49

50 Zetadocs-Customize codeunit: GetAdditionalEmbComms %%[field: salutation, Mr.] By using this in conjunction with a Zetadocs Templates you can personalize the message as follows. %%[field: salutation, Mr.] %%[field:name, McCarthy] %%[field: company, Widgets Inc.] %%[field: quote_number, 1234] %%[field: myname, Sam] Document Template When merged to a document template containing the following text: Dear %%[salutation] %%[name] I'm pleased to attach your quotation as discussed along with our conditions of sale and product brochure. Our quotation number for your reference is %%[quote_number], please include this on your sales order. Regards, %%[myname] Expected Output Zetadocs creates the following message body: Dear Mr. McCarthy I'm pleased to attach your quotation as discussed along with our conditions of sale and product brochure. Our quotation number for your reference is 1234, please include this on your sales order. Regards, Sam (ii) Archiving Metadata It is also possible to archive any of the dynamic fields as metadata. To do this the embedded command should include the ARCHIVE flag at the end. Here is the format: For Example: %%[field: <name>, <value>, ARCHIVE] %%[field: Postcode, N7 0JE, ARCHIVE] Whether the dynamic field is used in personalizing the message or not its value name pair will be passed to the SharePoint archive as a content type column. There are a couple of things to note about this. If the column name does not exist already in SharePoint it will need to be created, as a column of the content type specified this needs to be done in SharePoint in advance. Zetadocs documents default to using a Zetadocs content type. If you have specified an Archive Document Type in either the Zetadocs Document Sets table or the Zetadocs Report Settings table then the content type will be a child type of the Zetadocs content type. NOTE: It is recommended that the SharePoint columns are created before archiving a document and that it is well tested before roll out. These fields can then be used to search on SharePoint. The Zetadocs-Utilities codeunit exposes a search function which can perform a column search in SharePoint. SharePointSearch This command in the Zetadocs utilities will launch your web browser and search the specified field for the specified value. For Example: SharePointSearch(Text <fieldname>, Text <fieldvalue>, Boolean <ShowSearchPage>) SharePointSearch( Postcode, N7 0JE,FALSE) This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 50

51 Advanced Zetadocs for NAV Report Writing: Zetadocs Report Code Overview When <ShowSearchPage> is false you will be directed to the search results. When it is true you will be taken to the Zetadocs Search page with the Postcode pre-populated in the search form. This does however require modifying the search page as per the instructions in the Zetadocs for Microsoft Dynamics NAV SharePoint Components Installation Guide. 11. Advanced Zetadocs for NAV Report Writing The different reports available in NAV can be modified to enable them to be sent using Zetadocs. The modifications that need to be made to a report depend on how that report is structured. A report modified by the operations described in this section will output one page of embedded commands at the beginning of each one of the report documents. The embedded commands will contain information related to the automated addressing, formatting and archiving of the report document. This section describes how to modify different types of reports to enable them to be sent using Zetadocs. For easier understanding, we will refer to each part of a report as a report document. For example, in the case of a report that outputs five invoices, each one of these invoices is called a report document Zetadocs Report Code Overview As mentioned above, the modifications made to a NAV report will allow us to insert one page of embedded commands before each one of the report documents. This is done by adding three text boxes in the report, as well as making calls to the methods offered by the code units. There are four method calls that need to be made by a modified report to ensure the printing of the embedded commands. We will now explain the role of these calls and where in the report they should be located. (i) Initialization The initialize method is the first one that needs to be called by a modified report and it s where the specific settings for a report will be fetched from the rules. The tables that contain the embedded commands and the contact information will also be cleared of any content remaining from previous operations. Typically, the call to the initialize method is located in the OnPreReport section of the code, which allows the code to be executed before any of the records are processed. (ii) Add Record The AddRecord method is called to add the content of the embedded commands for a particular report document to the Zetadocs Send Results table. Therefore, the method needs to be called once for every report document that will be created. For example, in the case of a report that will create a report document for every record in the customer table like the Statement report, the AddRecord method needs to be called for every record in the customer table. In most cases, the calls to the AddRecord method can be made in the OnPreReport section, after the initialization is made. (iii) Resolve Send Info The role of the ResolveSendInfo method is to find the contact information related to every record that has been added to the Zetadocs Send Result table. By the process described in section 8.3, this function will allow each report document to be addressed properly. The call to the ResolveSendInfo is only made once, and all the records are treated at the same time. Therefore, it is important that all the records have already been added to the Zetadocs Send Results object when the call is made. (iv) Get Embedded Commands The role of the GetRecordEmbComms method is to return the embedded commands related to a particular report document. The method needs to be called for every report document that is to be created. Typically, the method call will be located in the OnAfterGetRecord trigger of the data item where the embedded commands text boxes are located. The first textbox created will contain the standard set of embedded commands recognized by Zetadocs. The second textbox will contain any custom commands that have been This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 51

52 Advanced Zetadocs for NAV Report Writing: Types of Reports created for a specific system, and the third textbox will contain addressing information for the any additional recipients. The GetRecordEmbComms function will fill the first text box with the standard set of embedded commands The GetRecordCustComms function will fill the second text box with the custom commands added by a VAR The GetRecordMultRecComms function will fill the third text box with the additional recipients addressing commands Types of Reports The reports in NAV are all meant for different purposes which is why they are all structured in a different way. There are three general categories of reports and most reports can be associated with one of them: 1. One report document is created for each record 2. Only one report document is created 3. One report document is created for a group of records (i) One report document per record This is the most common type of report in which a report document will be created for every record of the table the report is based on. For example, a report of that type based on the Customer table would detail every transaction made by one customer in a report document. The next report document would detail the transactions made by another customer and so on. Typically, every report document created will be sent to a different recipient. Examples of that type of report are the Statement report and the Blanket Sales Order report. Figure 47 - One report document per record report (ii) Only one report document These reports are only creating one report document, regardless of the number of records in the table. The content of a report of that type will generally be a list and the recipient will receive the entire report. In the case of a report based on the customer table for example, this report would print a list of customer, rather than details of transactions made by that customer. Examples of this type or report are the Customer List report and the Vendor List report. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 52

53 Advanced Zetadocs for NAV Report Writing: Import the Zetadocs for NAV Report Template Figure 48 - Only one report document (iii) One report document per group of records This type of report is very similar to the first type of report (i) but instead of creating a report document for each record of the table it is based on, a report document is created for a group of records from the table it is based on. Records are grouped together when they share a similar value in one of the fields from the table the report is based on. For example, all the records from the Vendor Ledger Entry table that have the same value under the Vendor No. field would be grouped together in a section of the report. Examples of this type of report are the Remittance Advice Entries and Remittance Advice - Journal report. Figure 49 - One report document per group of records 11.3 Import the Zetadocs for NAV Report Template Before you start modifying a report, ensure that the Zetadocs for NAV template has been imported into the object designer. Report <CD Drive>:\Zetadocs NAV Server Components\ Zetadocs Additions Report.txt We will refer to this report from now on as the template and to the report you are editing as the report. NOTE: The template will not compile. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 53

54 Advanced Zetadocs for NAV Report Writing: Global, Local and Text Constants 11.4 Global, Local and Text Constants Open the template in the Report Designer and view the C/AL Globals (ViewCA/L Globals) Select all Global variables (Ctrl + A), right-click and select Copy Open the report and view the C/AL Globals Scroll to the bottom of any existing Globals in your report and select the blank global variable row, right-click and select Paste to paste the additional Zetadocs Globals into the report. You must now repeat the above steps to copy and paste all the Text Constants from the template into your report Modifying the reports The code that you need to add to your report varies depending on the report type. This section will guide you through the modifications that need to be made. NOTE: Due to the customizable nature of the reports in NAV, the steps described below may not fit all reports exactly. Therefore, the location of where to insert the code below may need to vary but the code will remain similar. Also, the placement and sizing of the Zetadocs embedded commands text box may need to be tailored to ensure that the first page of each report is dedicated to the embedded commands only and that subsequent page numbers are decremented accordingly. For additional printing options in reports and troubleshooting the building of a report see the section 12 on report building in the appendices. (i) One report document per record To modify that type of report, follow the instructions described in Section 3.3. (ii) Only one report document This type of report prints information extracted directly from the table it is based on (rather than information related to the table it is based on) which makes the structure of the report different: the content of the report is created in the main data item s section. To describe the differences in the process, we will use the Customer List report as an example. If you open the report designer and then select ViewSections for the Customer List report, you will see that all the sections of the report are created under in the main data item. Since the Zetadocs embedded commands need to appear before anything else in a report, we need to create a data item and locate it above the main data item. Step 1: Create Zetadocs Embedded Commands Data Item In the report designer select an empty row and create a new data item of type Integer called Zetadocs Embedded Commands. Move the data item up above the main data item and do not indent it. View the sections of your report (View Sections) and you should see a section called Zetadocs Embedded Commands, Body (1) Select the Zetadocs Embedded Commands, Body (1) section, insert a new section (F3) and select the Header section type. You should now have a Zetadocs Embedded Commands, Header (1) above the Zetadocs Embedded Commands, Body (2) section. Select the Zetadocs Embedded Commands, Body(2) section and delete it (Edit Delete) Open the template in the Report Designer and view the sections (View Sections) Select the three textboxes in the Zetadocs Embedded Commands, Body(1) section Copy and Paste the textboxes to the Zetadocs Embedded Commands, Header (1) section in your report. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 54

55 Advanced Zetadocs for NAV Report Writing: Modifying the reports Figure 50 - Customer - List Report A report like the Customer List report is generally meant for internal use and the intended recipient is not determined by the content of the report. Instead of creating a rule associated with the report and changing it every time the report is printed, the following steps will allow the information to be entered by the user at runtime. Step 2: Create a temporary contact variable In the report designer select an empty line and select View C/AL Code (F9) From the code windows, select View C/AL Globals and navigate to the Variables tab. On an empty line, create a new variable called TempContact. The type of the variable should be Record and the subtype should be Contact. Select the TempContact variable in the list and go to View Properties (Shift+F4) Change the Temporary value to Yes. Save and close the C/AL Globals window. Step 3: Code Report OnPreReport The OnPreSection section of the code is where the initialization of the Zetadocs Send Result objects takes place. Once the initialization is done and has succeeded, we create an empty contact record and add it to the content of the embedded commands. The contact variable is created empty because the information will be entered at runtime. There is only one report document associated with a report like the Customer List. Therefore, only one set of embedded commands needs to be created, which is why the AddRecord method is only called once. Finally, the last section of the code is where we will call the ResolveSendInfo method, as the only record that needed to be added to the Zetadocs Send Result object has already been added. //--EQ2.0 ZetadocsSend := TRUE noerror := TRUE; IF NOT ZetadocsSendResultGen.Initialize(<Report No.>) THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT END This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 55

56 Advanced Zetadocs for NAV Report Writing: Modifying the reports ELSE BEGIN TempContact.INIT; TempContact.INSERT; RecRef.GETTABLE(TempContact); IF NOT ZetadocsSendResultGen.AddRecord(RecRef.RECORDID) THEN BEGIN noerror := FALSE; CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; IF noerror THEN IF NOT ZetadocsSendResultGen.ResolveSendInfo() THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; //--EQ2.0 Report OnPostReport The code here clears automation variables used during sending. Copy and paste the code below for the Report OnPostReport function into the top of the same function in your report. //--EQ2.0-- CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); //--EQ2.0 Zetadocs Embedded Commands OnAfterGetRecord In this part of the code, we will get the set of embedded commands that will be printed on the first page of the report document. //--EQ2.0-- RecRef.GETTABLE(TempContact); //Get the standard set of embedded commands ZetadocsEmbComms:= ZetadocsSendResultGen.GetRecordEmbComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE //Get the custom embedded commands, added by the VAR ZetadocsCustComms := ZetadocsSendResultGen.GetRecordCustComms(RecRef.RECORDID, ZetadocsEmbCommsAction); This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 56

57 Advanced Zetadocs for NAV Report Writing: Modifying the reports CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE //Get the multiple recipients embedded commands ZetadocsMultRecComms := ZetadocsSendResultGen.GetRecordMultRecComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE RecRef.GETTABLE(TempContact); IF ZetadocsSendResultGen.IsToBeSkipped(RecRef.RECORDID) THEN BEGIN CurrReport.SKIP; END; //--EQ2.0-- Zetadocs Embedded Commands OnPostDataItem The following line of code is added to ensure that nothing but the embedded commands gets printed on the first page of the report document. //--EQ2.0-- CurrReport.NEWPAGE; //--EQ2.0-- Zetadocs Embedded Commands, Header (1) OnPreSection When printing a report, adding this line of code will allow your report to keep a valid page count (i.e. the embedded commands will be located on page 0 and the beginning of the report document is located on page 1). //--EQ2.0 CurrReport.PAGENO := CurrReport.PAGENO - 1; //--EQ2.0 (iii) One report document created for a group of records The modification of a report where the records are grouped before they are printed requires a few more operations, as the embedded commands will be created for a group of records instead of a single record. We will use the Remittance Advice Entries as an example of such a report. If you open the report designer and then select View Sections, you will notice that some of the sections of the report are created in the main data item. Since the Zetadocs embedded commands need to appear before anything else in a report, we need to insert the embedded commands text box and locate it above the other sections. This will ensure that nothing appears before the embedded commands when the report is printed. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 57

58 Advanced Zetadocs for NAV Report Writing: Modifying the reports Step 1: Create Zetadocs Embedded Commands Data Item In the report designer select an empty row and create a new data item. The type of that new data item needs to be the same as the main data item. Call it Zetadocs Embedded Commands. Move the data item up above the main data item and do not indent it. View the sections of your report (View Sections) and you should see a section called Zetadocs Embedded Commands, Body (1) Select the section directly below Zetadocs Embedded Commands, Body (1). Insert a new section (F3) and select the Group Header section type. Select the section called Zetadocs Embedded Commands, Body (1) and delete it (Edit Delete). The newly created section should be called <main data item name>, GroupHeader (1) and should be empty. It should be located above all the other sections of your report. Open the template in the Report Designer and view the sections (View Sections) Select the three textboxes in the Zetadocs Embedded Commands, Body (1) section Copy and Paste the textboxes to the <main data item name>, GroupHeader (1) section in your report. Figure 51 - Remittance Advice Entries Report Because the records treated by the report are grouped, we need to reproduce the conditions under which the records are grouped to be able to know how many sets of embedded commands will be created. Creating a temporary table in which we keep track of the groups of records will allow us to do that. Step 2: Create a temporary record variable In the report designer select the main data item (which is now the second one in the list, directly below the Zetadocs Embedded Commands data item) Select View C/AL Code (F9) and navigate to the OnAfterGetRecord function. You should be able to see how the records are grouped together (i.e. which field is used to group the records together). For example, a report in which the records are grouped together when they use the same <Field Name>, you would see code like : <variable>.get(<field Name>); NOTE : For this section, this variable will be referred to as <variable>, a variable of type Record and the field name will be referred to as <Field Name>. View C/AL Globals and navigate to the Variables tab. You will find the <variable> in that list and it will be of type Record. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 58

59 Advanced Zetadocs for NAV Report Writing: Modifying the reports Navigate to an empty line and create a new variable called Temp. The type of the variable should be Record and the Subtype should be the same as the Subtype from the <variable> mentioned above. Select the Temp variable in the list and go to View Properties (Shift+F4) Change the Temporary value to Yes. Save and close the C/AL Globals window. In the OnAfterGetRecord function, under the code <variable>.get(<field Name>), add the code: Temp.GET(<Field Name>); Figure 52 - The records are grouped by Vendor No. in the Remittance Advice Entries report Step 3: Code Report OnPreReport At this point in the code, the records cannot be grouped together because the records that will be processed by the report are still unknown. For that reason, the initialization is the only thing done in this section: noerror := TRUE; IF NOT ZetadocsSendResultGen.Initialize(<Report No.>) THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; Report OnPostReport Don t forget the clean up code in the OnPostReport, otherwise successfully ran reports may become locked. CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); Zetadocs Embedded Commands OnAfterGetRecord The following section of code is where we will group the records and store them in a temporary table. It is important to understand that only one set of embedded commands is created for a group of records, which is why the record is only added when the <Field Name> is not already present in the table. IF NOT Temp.GET(<Field Name>) THEN BEGIN <variable>.get(<field Name>); Temp := <variable>; Temp.INSERT; RecRef.GETTABLE(Temp); IF NOT ZetadocsSendResultGen.AddRecord(RecRef.RECORDID) THEN BEGIN noerror := FALSE; CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 59

60 Advanced Zetadocs for NAV Report Writing: Modifying the reports CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; CurrReport.SKIP; Zetadocs Embedded Commands OnPostDataItem By the time the OnPostDataItem trigger is executed, the records have all been added. The ResolveSendInfo method will fetch the contact information from the different groups of records. IF noerror THEN IF NOT ZetadocsSendResultGen.ResolveSendInfo() THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; Main Data Item OnAfterGetRecord The records have already been grouped at this point so the content of the embedded commands can be fetched. This code must be added at the end of the OnAfterGetRecord. //--EQ2.0-- RecRef.GETTABLE(<Main DataItem Name>); ZetadocsEmbComms:= ZetadocsSendResultGen.GetRecordEmbComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsCustComms := ZetadocsSendResultGen.GetRecordCustComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsMultRecComms := ZetadocsSendResultGen.GetRecordMultRecComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 60

61 Advanced Zetadocs for NAV Report Writing: Copy Loop END; //CASE RecRef.GETTABLE(<Main Data Item Name>); IF ZetadocsSendResultGen.IsToBeSkipped(RecRef.RECORDID) THEN BEGIN CurrReport.SKIP; END; //--EQ2.0-- Zetadocs Embedded Commands, Header (1) - OnPreSection //--EQ2.0 CurrReport.PAGENO := CurrReport.PAGENO - 1; //--EQ Copy Loop If your report contains a copy loop data item that outputs more than one copy of the report per print, then you must edit the loop to only output one copy when sending using Zetadocs. An example of the standard copy loop with the additional logic is in the template. NOTE: THIS IS NOT THE EXACT CODE TO PASTE. YOU MUST EDIT YOUR COPY LOOP TO ONLY RUN ONCE WHEN (ZetadocsSend = TRUE) IF (NoOfLoops <= 0) THEN NoOfLoops := 1; IF (ZetadocsSend) THEN NoOfLoops := 1; SETRANGE(Number,1,NoOfLoops); 11.7 Modifications Necessary for the Role Tailored Client Reports To enable Role Tailored Client reports to be sent successfully using Zetadocs for NAV you will need to adjust the reports using the following steps. Open the Navision client and connect to/open the Navision database. Open the Object Designer (ToolObject Designer). Click on Report button in the designer menu. Select the reports that you are going to edit for Zetadocs for NAV. Select Export in file menu (FileExport). Export the report as a.txt file. Open the file using a notepad.exe or another suitable program. Scroll down through the file until you reach the RDLDATA. Delete everything contained within the curly brackets {}. Save the changes to the file. Go to NAV and open the Object Designer (ToolObject Designer). Click on Report button in the designer menu. Select (FileImport) and re-import the modified report. Repeat the process for any remaining reports you intend to use in conjunction with Zetadocs for NAV. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 61

62 APPENDIX: Creating and Troubleshooting Zetadocs for NAV Reports 12. APPENDIX 12.1 Creating and Troubleshooting Zetadocs for NAV Reports Step by Step This section provides a detailed description of the changes required to enable a report for sending using Zetadocs. Understanding how it works will make it much easier when trying to enable a report which is in an unusual format. An explanation as to the function of each piece of code that needs to be added to a report is given to help understanding. To make the process simpler and faster there is also the template report in the Zetadocs for NAV installation pack which contains the elements that are to be added to an existing report to enable it for sending. It is recommended that you complete the previous sections of this installation document before attempting to create a Zetadocs for NAV report, because much of the code to be added to an existing report depends upon other Zetadocs for NAV objects. Please note that these instructions appear long and are written to accommodate people with little NAV development experience. Once understood, modifying a report should only take a matter of minutes. (i) Report Overview The goal in editing a report to enable it for Zetadocs is to build a list of embedded commands to be written on a separate page at the start of each record report. So for a report which is run for 4 records there will be 1 page inserted before each record output totaling 4 pages in all. There are a number of options for where the code provided is added into a report, what follows is our suggestion as it will work with most of the reports supported. Required Code Overview: Send Results Generation call o All records passed to Zetadocs codeunit to resolve Document Set rules for sending settings and recipient information. Error and user specified record skipping o Code to skip records which have a send results error or records marked by the user to be explicitly skipped. Embedded Command Generation call o For each record generating the required embedded commands from the send results. Zetadocs Embedded Commands Section o An area in the report to put textboxes where the embedded commands will be written. Optional code Overview: Print for Zetadocs option o Request Form radio buttons. Report option to allow user to choose output format of the report, normal or Zetadocs. o Additional code to suppress output of embedded commands when printing report normally. (ii) Import the Template Zetadocs for NAV Report Ensure that the Zetadocs for NAV report template has been imported into the object designer. Report <CD Drive>:\Zetadocs NAV Server Components\Zetadocs for NAV V2.0 Additions Report txt We will refer to this report from now on as the template and to the report you are editing as the report. NOTE: The template is based on the Sales Header table as an example. You must edit the code to use the table your report is based on as instructed. (iii) Global, Local and Text Constants Open the template in the Report Designer and view the C/AL Globals (View CA/L Globals) This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 62

63 APPENDIX: Step by Step Select all global variables (Ctrl + A), right-click and select Copy Open the report and view the C/AL Globals Scroll to the bottom of any existing globals in your report and select the blank global variable row, right-click and select Paste to paste the additional Zetadocs Globals into the report. You must now repeat the above steps for the Text Constants: (iv) Code Segments Next you need to copy the code from the template to your report Open the template in the Report Designer again and select an empty data item row. Figure 53 Zetadocs Template Report in Report Designer Press F9 or View C/AL Code to view the PreReport Triggers. Report OnPreReport The code here initializes the Zetadocs codeunit and passes each record being sent to query the rules tables and sets the appropriate send information for each record. Copy and paste the code below for the Report OnPreReport function into the top of the same function in your report. Now edit the function parameters and function calls in place. These are signified by <param description> in the code below. o <Report No.> - The ID of your report. o <Main DataItem Name> - This is the name of the first DataItem in your report. Typically it is the name of the table upon which your report is based. Code: ZetadocsSend := TRUE; noerror := TRUE; IF NOT ZetadocsSendResultGen.Initialize(<Report No.>) THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 63

64 APPENDIX: Step by Step END ELSE BEGIN IF <Main DataItem Name>.FIND('-') THEN REPEAT BEGIN // Get the RecordID IF noerror THEN BEGIN RecRef.GETTABLE(<Main DataItem Name>); IF NOT ZetadocsSendResultGen.AddRecord(RecRef.RECORDID) THEN BEGIN noerror := FALSE; CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; END; UNTIL <Main DataItem Name>.NEXT = 0; IF noerror THEN IF NOT ZetadocsSendResultGen.ResolveSendInfo() THEN BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END; END; Report OnPostReport The code here clears automation variables used during sending. Copy and paste the code below for the Report OnPostReport function into the top of the same function in your report. Code: CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); Zetadocs Embedded Commands Data Item This data item is added to provide a location to put the Zetadocs Embedded commands text box. The goal is to insert a page before each record report which will contain the embedded commands to be read by the Zetadocs Client. This page will then be removed from the resulting document and therefore should not contain any report data. For some reports such as the Statement report, where each page has a recurring header which contains the customer address information then placement of the Zetadocs embedded command text box may need to be different and resized to force all report data to be printed from page 2 onwards. Action: 1. In the report designer select an empty row and create a new data item of type Integer called Zetadocs Embedded Commands. Move the data item up to just below your main data item and indent once so that it will be the first page of output in your report. Select the Zetadocs Embedded Commands data item in your report and press Shift + F4 or View Properties. Set the properties DataItemTableView to SORTING(Number) or alternatively cut and paste this property value from the equivalent in the template. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 64

65 APPENDIX: Step by Step Return to the template report designer select View Sections. Select the three textboxes called ZetadocsEmbComms, ZetadocsCustComms and ZetadocsMultRecComms in the Zetadocs Embedded Commands section and copy to clipboard (Ctrl + C). View the sections on your report and paste (Ctrl + V) the textbox into the Zetadocs Embedded Command section. Zetadocs Embedded Commands, Body(1) OnPreSection As we are adding an additional page which will be removed from the final document we need to decrement the page numbers. This must be done in this section trigger OnPreSection Open the report designer for the template. Select View Sections from the main menu. Select the Zetadocs Embedded Commands, Body(1) section and press F9 to view the code. Copy the code below for the Zetadocs Embedded Commands, Body(1) OnPreSection function. Paste the code into the top of the same function in your report. Code: CurrReport.PAGENO := CurrReport.PAGENO 1; Zetadocs Embedded Commands OnPreDataItem Figure 54 Adding Zetadocs Embedded Commands DataItem Ensures we only write one set of embedded commands per record. Return to the report designer for the template. Select the DataItem Zetadocs Embedded Commands and press F9 to view the code. Copy the code below for the Zetadocs Embedded Commands OnPreDataItem function. Paste the code into the top of the same function in your report. Code: SETRANGE(Number,1,1); Zetadocs Embedded Commands OnAfterGetRecord The code here queries the Zetadocs Send Results Gen codeunit for the embedded commands to be written onto the report page in the Zetadocs Embedded Commands textboxes. The first textbox created will contain the standard set of embedded commands recognized by Zetadocs. The second textbox will contain any custom commands that have been created for a specific system, and the third textbox will contain addressing information for the any additional recipients. Copy the code below for the Zetadocs Embedded Commands - OnAfterGetRecord function. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 65

66 APPENDIX: Step by Step Paste the code into the top of the same function in your report. Now edit the function parameters and function calls in place. These are signified by <param description> in the code below. o <Main DataItem Name> - This is the name of the first DataItem in your report. Typically it is the name of the table upon which your report is based. Code: RecRef.GETTABLE(<Main DataItem Name>); ZetadocsEmbComms:= ZetadocsSendResultGen.GetRecordEmbComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsCustComms := ZetadocsSendResultGen.GetRecordCustComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE ZetadocsMultRecComms := ZetadocsSendResultGen.GetRecordMultRecComms(RecRef.RECORDID, ZetadocsEmbCommsAction); CASE ZetadocsEmbCommsAction OF ZetadocsEmbCommsAction::Error: BEGIN CLEAR(ZetadocsUtilities); CLEAR(ZetadocsSendResultGen); CLEAR(ZetadocsPrnRem); CurrReport.QUIT; END END; //CASE Zetadocs Embedded Commands OnPostDataItem Copy the code below for the Zetadocs Embedded Commands OnPostDataItem function. Paste the code into the top of the same function in your report. Code: CurrReport.NEWPAGE; CopyLoop If your report contains a copy loop data item that outputs more than one copy of the report per print, then you must edit the loop to only output one copy when sending using Zetadocs. An example of the standard copy loop with the additional logic is in the template. The easiest way is to ensure IF ZetadocsSend THEN NoOfLoop = 1; This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 66

67 APPENDIX: Step by Step Sample Code: IF (NoOfLoops <= 0) THEN NoOfLoops := 1; IF (ZetadocsSend) THEN NoOfLoops := 1; SETRANGE(Number,1,NoOfLoops); Main DataItem OnAfterGetRecord The code here controls whether or not to output the current records report based on errors or skip commands from the Zetadocs Send Results Gen codeunit. Select the main section in the template. This is the first data item in the report designer view, for example Sales Header. Press F9 or View C/AL Code. Copy the code below for the OnAfterGetRecord function. Paste the code into the top of the same function in your report. Now edit the function parameters and function calls in place. These are signified by <param description> in the pasted code. o <Main DataItem Name> - This is the name of the first DataItem in your report. Typically it is the name of the table upon which your report is based. Code: RecRef.GETTABLE(<Main DataItem Name>); IF ZetadocsSendResultGen.IsToBeSkipped(RecRef.RECORDID) THEN BEGIN CurrReport.SKIP; END; Figure 55 Report Designer (v) Report Properties This prevents our send errors dialog and the printer status dialog being shown at the same time. Zetadocs also has its own printing progress dialog. Open the report designer for your report. Select the empty section row at the bottom of the section list. Press Shift + F4 or click View Properties. Set the ShowPrinterStatus to No. (vi) Completed Report Shown here is a working report of three records. Note the inserted pages with the Zetadocs embedded commands at pages 1,3 and 5. This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 67

68 APPENDIX: Optional Zetadocs Report Format Figure 56 - Zetadocs Enabled Report Preview 12.2 Optional Zetadocs Report Format There may be a situation where you want the ability to print the report as you used to and also to be able to print it with the embedded commands to Zetadocs without having to duplicate the report in the system. The follow instruction allows you to add some additional code to your reports to make this possible. To decide between the output formats they desire the user selects the Printing Action option on the request form of the report. Figure 57 - Optional Zetadocs Report Format Request Form (i) Already Added Zetadocs Code All the code that you have added to the Zetadocs report must be optionally run. This means we must only perform the code if we want to output the printed report in Zetadocs format to the Zetadocs Printer. Go back and locate the code that was pasted into the following triggers. o Report OnPreReport o Zetadocs Embedded Commands OnAfterGetRecord o Zetadocs Embedded Commands OnPostDataItem o Main DataItem OnAfterGetRecord Add the following red code around the already added code to ensure it only gets run when the Zetadocs option is selected This edition 09/12/2008 Copyright Equisys plc 2008 All trademarks acknowledged All rights reserved Page 68