Document template management

Management in the administration console

You manage document templates in the administration console via the Document template management. You can edit complex searches via the node Search /Search container management.

The dialog consists of two tabs: a list of templates and a mask for editing the loaded template.

Button

	After you have loaded a template from the templates area via the Load button, all templates from this area are available. You can navigate the templates with the navigation button. Alternatively, you can switch to the “List” tab and select the template there.
New	New creation of a document template. This button is used to create a new dataset. To do this, you must select an already existing document template via the displayed file browser. The application then checks this template and transfers all fields found in it into the mapping table. In many cases, required templates are created based on the copy of an existing template. This saves a few steps.
Load	Loading the document templates. Use the drop-down button to restrict the list of displayed document templates to the selected document type.
Save	Only when this button is pressed will the changes in the document template be saved in the database. This process is often forgotten at the beginning. Before you save the template in CRM, you must save the document template in Word. The most recently saved version of the document template file is always saved in CRM.
Delete	The document template is permanently deleted after a security inquiry. Instead of deleting a template in this way, you can also set it to Inactive.
Edit	This button opens the document template in Word and can be edited. Via the menu items Convert and Edit the document can be updated before opening. Missing bookmarks are automatically inserted in the document in the form of SET fields and the corresponding REF fields. Bookmarks removed from the assignment table are also removed from the document template. For the serial letter, serial mail and email, the conversion functionality is irrelevant and should therefore not be used.
Import mapping	The assignment table of the current template can be completely replaced by the assignment table of another template. This helps to make changes in the assignment table quickly available for other templates. However, the complex search must match: either the concerned templates refer to the same complex search, or the searches are largely identical to the aliases and fields. Otherwise, gaps occur in the search field column, which then have to be processed.
Copy template	The existing document template is copied under a new name with its properties (mapping, assignment to the complex search, description, link key for documents and/or activities, etc.). The user is asked to enter the name. The uniqueness of the name is checked after the entry.
migration tools	For the migration tools the following section on the use of these processes should be noted! For the “Find and Replace”, “Templates Review”, “Optimization Mapping” and “Convert to Native”, it is important to check when the tool starts if it is the list or detail view: Detail view In the detail view of a document template, the operation is performed only for this template. The changes are only made in the local file. The administrator thus has the option of rechecking the document template before the final saving. List view In the list view, the operation is performed for all selected entries of the list view. Changed document templates are saved automatically. For details see: Chapter Migration tools
Find & replace	Enables the replacement of text as well as adding and changing file properties for single or multiple documents. The text and/or file properties concerned are specified in the text replacement file. For the behavior in the details and list view, see the explanation in Migration Tools. After the process is complete, a detailed summary of the modified document templates is displayed.
Open replacement file	The path of the text replacement file is stored in the user options in the integration area. When working with multiple text replacement files, this entry must be filled with the currently active text replacement file. If there still is no text replacement file in the user options, a text replacement file will be generated with sample data upon request when opened for the first time. To do this, the user must first specify the file name of the text substitution file.
Import new templates by copy	Enables the mass import of similar document templates in one process step.
Check templates	As part of the validation, the following conditions are examined: Checking the mapping (search fields still available, validity assignment text marker type vs. search field) Checking link fields (document and activity, if available in template) link fields in search still available Checking availability of complex search At the end, a detailed log of all checked templates appears, allowing the administrator to see if individual templates need to be processed. Detail view: In the detail view of a document template, the validation is performed on this template only. List view: In the list view, the validity check is performed for all selected entries of the list view.
Optimize mapping	With this action, the administrator can optimize the performance of generating single letters, quotes and contracts by reducing the number of fields to be transferred to the Word template. For the behavior in the details and list view, see the explanation in Migration Tools. After the process is complete, a detailed log of all edited templates will be displayed with details of the fields removed per template.
Distribute mapping	Assistance to the administrator when adding new fields in any templates in the field of single letters, offers, contracts or individual document types.
Updating the template format	To support the replacement of the old Microsoft Office formats, a migration option is offered in the template management to facilitate the conversion of document templates with the old format (e.g. dot or xlt) to the current format (dotm or xltm). This entry is available for the following cases: Document template from the area of single letters, serial letters or Excel templates The format of the document template is outdated The layer of the document template corresponds to the current layer During the conversion, both the template format and the output format of the document template are changed to the new format. Template format before → after dot/doc → dotm xlt/xls → xltm Output format before/after doc → docm xls → xlsm Variants of the conversion Conversion in the detail view The conversion is carried out – recognizable by the changed format and, if applicable, the output format. The template is not saved automatically and must be executed manually. This allows you to view the document template in advance. Conversion in the list view The conversion in the list view enables the conversion for all selected document templates. If there are non-convertible templates among the selected entries, e.g. due to the template type, these are skipped. At the end, a detailed log file appears with a list of all selected document templates and their conversion result. The changes to the document templates are saved automatically. In principle, it is advisable to make a backup of the document templates to be changed before the conversion or to assign the changes to a new package. If problems are detected during the subsequent test, the old templates can be restored.
Change to NATIVE	This entry is available if the optional module ‘Native document generation’ is enabled. Further information can be found above in the explanation of the document generation variants. This button facilitates the button to the generation variant ‘NATIVE’. This triggers the actions described above in the selected template (s) “Changing of the generation variant field to ‘NATIVE’” and “Import of the macro module ‘NATIVE’ into the Word document template”: For the behavior in the details and list view, see the explanation in Migration Tools. After completion of the conversion process, a detailed log of all edited templates appears.
Read document	Document template can be opened for reading from another layer.

Tabs ‘List’ and ‘Details’

Switch to the 'List' tab to see the available templates. This list shows all existing templates. However, it may be that only a subset of the templates is seen, and if filters had been placed when loading the template of the document type (single letter, offer, etc.). In such a case you only see the templates of this type.

The list representation is used for a quicker selection of the template to be edited. In addition, you can quickly get an overview of the displayed columns: which templates are active or inactive? Which templates are linked to a specific search?

Double-clicking on an entry in this list loads the selected dataset and displays it on the tab ‘Detail’. The following explains the fields in this dialog.

Document type

This entry specifies the purpose of the template. Currently the following document types are supported:

1. Single letter

2. Quote

3. Serial letter

4. Mass Data

5. Email

6. Serial email

7. Contracts

8. Process template

This list can be extended by more types for individual documents. To do this, you must make these entities capable of documenting by setting a check in the system setting. This is true for C1 and for C2 entities. Then these entities appear in the list. Documents for these entities are then created in a manner similar to the procedure for contract and offer documents: the button for document generation is active directly in the respective entity. Please make sure to set the type of complex search, tat should be available for these templates to ‘ILetter’ (for ‘Individual Single Letter’).

Document range

Via the entry in this field you can assign the template to an area. Areas are managed in key maintenance via the entry ‘Document Area’. With these areas one can simulate a hierarchical structure similar to the main and subdirectories in the file system. An area can be assigned any number of document templates. This hierarchical structure is displayed to the user during template selection in the left-hand window of the selection dialog. He can use this to navigate faster to the required template.

Document category

Document categories can be used to systematically organize your document templates and their created documents. The user is shown the document category when selecting the template in a column of the selection dialog. Categories have another advantage: since they are stored in the dataset of the created document, they can be used to later select letters based on their category. The categories are also stored in the area of​key maintenance.

Name

The name of the document template is displayed to the user during the document creation in the selection dialog. It must be unique. Special characters such as quotes, periods or commas are not allowed.

Description

The description is also displayed when selecting the templates. Short explanations of the template can be entered in this field.

Search container (Complex search)

Each template is assigned a complex search. This selects the data that is displayed in the document.

By clicking on the label ‘Complex search’ you can jump directly to the displayed complex search to edit it. (By switching to the management of complex searches, you may be prompted to save the currently loaded complex search.)

Searches in the ‘CURSOR Standard’ checkbox with the check set were created by CURSOR and can therefore be adjusted during an update. You should therefore not use them. If you would like to use such a search, create a copy of this search and use this copy (even if you do not change the content of these copies).

Data source

This setting determines the connection in which a template can be selected by the user. You can only do this for single letter templates, for the other document types the system will specify the appropriate value and cannot be changed. This is explained by looking at the function of this setting for the single letter templates: the default entry #Default# does not restrict the availability, so the template is always available. Any value other than #Default# results in the single letter template being available for selection only if the user has created the activity from this selected entity (or has switched to an existing activity).

The use of the template is thus restricted to the activity by the path selected via certain parent entities. For templates with a setting other than #Default#, one therefore speaks of an ‘entity-specific single letter’.

A disadvantage of a setting other than #Default# is that this template is not available for single letter creation via the main activity window.

The values​’Activity’, ‘Document’ or ‘Offer’ must not be used.

Link activity with

This button is only available for offers, serial letters and serial emails. Here you can specify which entities are linked to the activity that can be created in the course of document creation. The entries in the selection list come from the complex search: only the entities addressed there can appear in the list. In addition, the ‘Primary key’ field must be selected and marked with a check for ‘Include in selection result’.

Changes to this list should be carefully tested, as inappropriate entries may result in duplicates of the letter/email.

Figure: Link activity with

The created document is automatically linked to the specified entities during the document creation. In this functionality, as with the setting “Link Activity to”, the entity to be displayed in the list must include the ‘Primary Key’ field in the search.

Collector Activity

(Only for serial letters)

During the serial letter creation, a completed and an open activity can be created for each selected dataset. This refers to this setting. It influences the amount of generated activities as follows:

1. Collective activity is active: Only one completed and/or open activity is generated. All datasets are assigned to these two activities. They are “collected” under these activities.

2. Collective activity is not active: One completed and one open activity is created per dataset. This can result in a significant number of activities.

3. Start macro (only with individual documents)

Start macro

If this checkbox is activated, after creating the document in the used template it is checked if there is a macro named StartMacro. If so, it will start automatically.

Optimize dissolving of field links

(Only for single letters)

During creation of documents, the field links for the fields in the document are automatically resolved following the data transfer. As a result, the SET and REF fields are removed from the finished letter, so the transferred data remains as a now fixed text. If you enable this option, the field links for all fields in the main document area will not be resolved individually, but in one step. This speeds up the action considerably. However, resolving the links only affects the fields in the main part of the document (in the so-called body). The fields in the header and footer areas are further resolved one at a time. Thus fields such as e.g. page number can be used easily.
If the option is disabled, or if form fields or control elements are found in the main document area, the fields will be resolved one by one as before. Only the fields transferred by the application (that is, the bookmarks listed in the mapping table) are resolved.

Active

Via the checkbox 'Active' you can deactivate the document template. As a result, the template is no longer available to users during document template selection.

Generation variant

(Only for individual documents)

There are a total of 3 variants of document generation:

• COM

• NATIVE

• MIXED

You can use the native document generation ‘NATIVE’ in the area of ​​single letters, offers, contracts and entity-specific documents. It is an extension of the existing document generation via the 'COM' variant and is available if the optional module 'Native document generation' is activated. ‘NATIVE' offers several advantages: significantly increased performance and greater stability. So the runtime behavior is independent of the installed virus scanner software. In a later expansion stage, no Office installation is required to generate the document.

The following list contains further explanations of the different procedures.

The following restrictions are currently known when using the native generation type

• The usage of item frames in combination with IncludeText leads to moved texts. In other words, after document generation, the text inserted by IncludeText is located below the position frame.
  Recommendation: Use text fields instead of the position frames in the document template.

• When using PDF as save format, several points must be observed (see below "Note on generating PDF")

• The documents are generated on the application server. It is therefore necessary that subsequently installed fonts are also available on the computer of the application server. It is important to ensure that the fonts are not installed for one user, but system-wide. After installing a font on the server, it may be necessary to restart the application server.
  An alternative is to embed the font in the document template. However, this significantly increases the memory size of the document template.
  

  

After the switch of generation type, a function test is required!

Default output formats

• For new creation of document templates of the type single letters, quotes or contracts DOCM is used as default output format.

• For new creation of document templates of the type serial letter and mass data PDF is used as default output format.

• For the new creation of an Excel template, XLSM (instead of XLS) is always suggested as the default output format, since macros are usually used. The template administrator can still change the output format.

Detailed information on Excel templates

Changes in the output format area of native Excel templates (output format is not available in COM based Excel templates):

• Output formats with macros xlsm, xlsb, xls
  Before saving, the program checks whether the NATIVE VBA module is present in the Excel template. This is necessary for the execution of the native Excel template. Saving without NATIVE VBA module is no longer possible.
  

  

• Output format xlsx
  In addition to xlsm, xlsb and xls, the output format xlsx is now also available. This output format has the consequence that the generated Excel file no longer contains macros and is consequently classified as trustworthy.
  When using the xlsx output format, the program checks whether macros are present in the Excel template before saving it. If this is the case, a message appears to inform the administrator that existing macros will no longer be executed. Thus, accidental use of the xlsx output format should be avoided.

  

  
  
  When checking for potentially executable macros, the following properties are checked

  • In the CONFIG tab of the Excel template the configuration parameter 'Start Macro' (cell name: CONF_MACRO_RUN) is activated (entry "Yes")
    

    

  • In the VBA project of the Excel template (ALT+F11) are macro procedures (Sub ... End Sub or Function ... End Function) stored.
    These procedures can be assigned to a worksheet or a module.
    

    

    
    
    After deactivating the configuration parameter and removing all macros, the message no longer appears.

Save as

(Only for single letters)

You can use this setting to specify the output format of the single letter to be generated. However, the document template must be based on the generation variant NATIVE. In the variants COM and MIXED, the output format is always doc.

The following output formats are currently supported.

• doc (Standard)

• docm

• pdf

• odt

• rtf

• txt

• epub

• xps

• svg

The use of non-Word output formats, such as pdf, is subject to restrictions and conditions. The following points must be noted:

In Word, a complete spelling of REF fields is not always necessary. This shorthand notation, e.g. {COMPANY} instead of {REF COMPANY} will produce erroneous results when generating other output formats.

• When using REF fields, the field function should always be written out, e.g. {REF COMPANY} instead of {COMPANY}

• When using a field (REF field or similar) as an expression in an IF field, then the field name must be stated in full.

RIGHT

VB

{ IF {REF Firma}<>"" "A" "B" }

WRONG

VB

{ IF Firma<>"" "A" "B" }
 { IF { Firma } <>"" "A" "B" }

• IncludeText or IncludePicture have limited functionality

The fields within the field result are updated correctly. However, there is no update of the field result of includetext, i.e. the old field result is used. If a change is made in the text block file, this change does not affect the document, since the field result is not updated here.

• The execution of customer-independent macros is not supported.

• No update of OCX or ACTIVEX components.

• Further restrictions are not excluded.

Mask scripting: the definition of the output format of individual documents is available to you as an optional parameter 'Output format' in the script command 'generateDocument':

JAVA

generateDocument("Blanko (Beispiel Non-Word)", true, "Besuch", "pdf");

In the admin console, when changing from NATIVE to COM or MIXED, the output format is automatically changed to “doc” and can no longer be changed. In the mask script command ‘generateDocument’, the entered output format is not considered in this case.

Figure: Document generation on the client computer

Assignment Table (Mapping Bookmarks)

This assignment table differs in its function and meaning depending on whether a single or a serial letter template exists:

• For Single documents, this table is used to associate a bookmark with either a field or a table search from the complex search. In addition, the Type column defines how the value of a field is passed to the document.

• In the case of Form letter templates, this table can only link the document to specific employees. As a bookmark type, the value TEXT must always be selected. Field assignments as with the single documents are not required and also not possible. This also applies to the attempt to store a table search using an entry of type ‘Table’ and then to receive one output table per serial letter dataset according to the procedure for single documents. For such requirements, the only way is via a report, which is laid out like a serial mail template.

The following explains individual columns in the assignment table.

Text

This information applies only to single document templates.

Bookmark type

The bookmark type decides how to treat the value of a field in the text document. The following bookmark types are available.

• Text

This entry is the default for newly created bookmarks. It is to be used if you want to transfer the contents of the field. The value of the field is then available as a REF field in the template.

If the field to be edited is a lookup field, the entry ‘TEXT’ is not allowed. In this case, one of the two values ​​'KEY VALUE' or 'DESCRIPTION' must be selected

• Key value

This bookmark type can only be used for lookup fields. The key of the lookup value is provided as a REF field in the text document. Example: In the case of the business partner type “Company”, the key UU is output.

• Description

This bookmark type can only be used for lookup fields. The description (the 'long text') of the lookup value is provided as a REF field in the text document. In the case of business partner type ‘Company’, the description ‘Company’ is output.

• Document

The referenced text block (document object) is inserted at the position of the bookmark. This type of bookmark is only available for lookup fields that access the entity DOCOBJECT. The entity DOCOBJECT contains document objects, such as text modules and graphics.

The administrator must ensure that the lookup field only accesses text modules in the entity DOCOBJECT - not graphics of the entity DOCOBJECT.

List formatting

When importing document objects via lookup fields in the entity, e.g. Suffixtext1 in the quote, list formatting will not be applied correctly. For example, list numbering is not continued for numeric lists, but is always 1.
Alternative solution: Use of an individual format template with activated numbering.

• Graph

Graphics can be inserted at the position of the bookmark. Two options for providing graphics are supported here.

1. The graphic is provided by a document object. Access is done via a lookup field to the entity DOCOBJECT. The entity DOCOBJECT contains document objects - both text modules and graphics.
   The administrator must ensure that the lookup field only accesses graphics in the entity DOCOBJECT - not text modules of the entity DOCOBJECT.

2. The graphic is provided as an image file directly in the entity, for example, the Logo field in the business partner or the employee image in the employee tree.

• Hyperlink

A hyperlink is inserted at the position of the bookmark. This is not a bookmark transferred and displayed via the SET and REF fields, but a bookmark that is set as a jumpmark. The field can therefore only be output once in the document under this bookmark. Email and www addresses are automatically converted into the appropriate structure.

mailto:<user>@<domain> bzw. mailto:Cornelia.Altenhain@cursor.de

• Table

At the position of the bookmark, a table is inserted during the document creation. Like the type HYPERLINK, this bookmark is also a jump mark, not a REF field. Therefore, a table with this name can only be transferred to the document once.

Table searches can be recognized by the extension TABLEDATA in the column Search field. The table layout will be stored in the table definition column for this search. An explanation of the syntax of this definition can be found below.

Bookmark

Bookmark the names for fields that you use directly in the template.

Search field

Contains the field associated with the bookmark from the complex search. Since a complex search can consist of several individual searches, the aliases of the respective search are prefixed to the field. Examples of how to display the names of fields in the search fields column:

• Simple search box

the search field GP - Short Name (Business Partner) corresponds to the field short name from the entity business partner, which is determined in the partial search with the alias GP. If additional entities are accessed in an advanced search, the relations used are displayed in parenthesized expression. The search field ADR - Location (address - contact person) thus corresponds to the field location from the entity address of the contact person, which is determined in the partial search with the alias ADR.

• Search box based on a table lookup

The name of the field for a table search consists of the alias of the table search and the extension TABLEDATA. Example: Product data.TABLEDATA This corresponds to the table lookup with the alias ‘Product data’.

Global Variables in document templates (Single letters)

The current value of a global variable can be output via an assigned bookmark in the document (single letter).

All global variables are available in the Search field column along with the search fields. The method is analogous to the search fields, i.e. the global variable is assigned to a bookmark. Only the bookmark type TEXT is available.

As part of the implementation, the maintenance of the mapping table has been optimized.

• Depending on the document type and the currently selected search field, only the permitted bookmark types are available
  e.g. TEXT for global variables or KEY and DESCRIPTION for lookup fields.

• Global variables are only available in the document templates single letters, offers, contracts, and entities enabled for document creation. In all other areas, the global variables are not offered in the Search fields column.

Process template - individual processing of a template

In the context of single letter generation, it is possible to jump to a BPM process by selecting a process template. Based on the selected template and the source entity, individual processing within the BPM process is now possible.
For example, it would be conceivable to provide the data required for writing in the process and send it to the third-party system for generating the document. In case of success, the document is further processed by print line or mail. The document could then be archived and made available in CRM as an external document.

Process template administration

In the template management area of the administration console, process templates can be newly created and loaded for maintenance.

Figure: New creation of a process template

The selection of the data source (entity) determines availability of the process template in the application.
Example:

• Activity → Exclusive display of the template in the context of single letter generation in the activity

• #default# → Display of the template within the single letter generation for all entities

When selecting the process, only the published processes with "Document template" start event are available. The selection of a valid process is necessary to save the document template.

Figure: BPM process with a document template as a start event

If a process template is loaded and its assigned process has been deactivated in the meantime, this is indicated accordingly in the selection field. Changes to the template can now be saved. The process must be published beforehand.

Using process templates in the application

The user starts the document creation via the known way by changing to the desired entity (usually 'Activity') and clicking the button "Create new single letter". The template selection opens. Here, both the internal CRM templates and the provided templates of the external DMS system (process templates) are offered for selection.

With the selection of an internal template, further processing takes place as before. The user is guided through the wizard, the document is generated and opened for further processing. With selection of a process template, further processing is controlled by a BPM process. The wizard is thus closed and the stored process is started. The process is called with the following parameters:

• documentTemplate: Name of the document template

• entityName: Name of the entity from the opened mask

• container: IContainer of the currently displayed entry from the opened mask

Replacing existing documents is only possible with internal CRM templates. Therefore, no process templates of documents are offered during the replacement in the template selection.

In case of undeployed processes, a hint message appears with reference to undeployed process.

In scripting, the use of process templates is not supported initially. When determining the single letter templates on the script side, the process templates are consequently not offered in the template selection.

• DocumentUtils.getDocTemplateNames(String)

• DocumentUtils.getDocTemplateNamesWithFilter(ScriptDocTemplateFilter)