Documents Module

The main mission of the Documents module is to provide you with a unique possibility to 'merge' documents through a built-in integration with Microsoft Word.

Additionally, the Documents module is designed to be a simple and efficient solution to store scanned copies of documents and any other types of files to which you want to have quick access from the Adonis Personnel Manager.

For the Word documents merge, you can export/send any kind of personal information using templates in Word format to a big number of crew members instead of working with every document separately (for example invitation letters, contracts, visa letters, etc.). You need only have a word template with common text (hardcoded) and the system will fetch various kinds of personal/employment data for every crewmember from Adonis.

Housekeeping

Defining Document Codes

First, you need to create various merge group codes to organize your work in the way you like, for example, to distinguish between Licenses, Invitations, Contracts, and so on.
Each of these codes will be as a separate folder/group on the Documents screen, where you'll be able to attach/link files.
For example:

Open

This is done under Setup > General Codes > Enclosed Documents > Enclosed Documents Codes.
Click the button to add a code:

Open

1. Input Code - is a unique alphanumeric code for a document to be in use. 

   Type Name/Text.
   Sort is used for ordering folders in the module.

   '0' means the very first.
   
   Is Passive the option defines if the code is passive or not. Passive codes are shown grey and you will not be able to work with this group.
   Security Code is used for giving restricted access to the use of this code for separate users.
   When a security code other than '0' is defined, it is possible to set up access rights (Write/Read/None) to this very type in Adonis Control Centre > General Codes > Enclosed Documents > Enclosed Documents Codes:

   Enclosed are Documents types with Security Code = '0' that is available for all users.

2. Available In the section defines if: 

   a document is displayed in the Documents module as a group of Merge documents – Documents Module option;
   
   
   

   a document is used only for/in Enclosed Documents data group (to add scan of passport or visa) – Enclosed Documents Datagroup option;
   
   
   

   but if you want not only to merge and send the document but also distribute it (attach to persons enclosed documents) – you need Both options.
   
   For example:
   
   
   As a result, this merged document will be added to the person's Enclosed data group with TEST code.

How to Filter Codes for Organization

It is possible to filter certain codes for an organization using the diagram icon near the Code field :

The organization structure tree will be displayed from the Concern to Company level.
You can clear the checkbox for the level where you want the selected general code to be unavailable.
You can use the search field as well as Tag/Untag All buttons to simplify the procedure.
Click OK to save the settings.

The same filtering possibility exists in Setup > Organization Structure > Org. Properties > General Codes > Enclosed Document Codes:

A document code that does not have a tick near its name, is not shown/hidden for the organization.
Click Apply when you are finished.

Method of Storing Documents

It is necessary to define the method of storing enclosed documents.
Adonis represents two main ways:

• Link - to store a path to the document in the database;

• Attach - to store the file itself in the database.

We prefer and suggest you use the store in database option. This way the documents are replicated and can easily be scheduled to replicate or not to replicate. 

To choose between these two functionalities, go to Global Options > Datagroups > Enclosed Documents:

1. Attach

   There are several advantages to storing the documents in the database.
   The documents are then protected by the database security and consistency tools.
   The way of attaching documents is necessary for companies that use Replicator. Only using this way of storing documents, the files are added to the database and will be sent to the other sites via Replicator.

   The only disadvantage with the attach method is that the size of the database will grow when byte-consuming documents are stored inside.
   
   So, as mentioned above, Adonis recommends users to use the attach method, but to put a size limit for attached documents (define how much 'place' a single scan can take).

   About 500 KB should be enough to get a good scan.

   The bigger the files are the quicker the database size will be growing.
   
   
   

   This setting module's main working area looks like below one:
   
   
   

1. A list of all available documents groups is given in the tree structure to the left. 

   
   By clicking one of the groups, only the documents belonging/added to that particular group will appear on the right.
   When you select All Documents, all records will be displayed in one big list.

   When All Documents mode is selected, it is not possible to create a new document or modify an existing one.
   So, for your convenience, we recommend creating separate groups for contracts, visa letters, travel letters, medical documents, etc
   
   
   
   

2. Manage commands: 

   New button - to create a new record/document.

   New Merge documents may be added to each group at any time.

   There is no limit to the number of documents that can be added to a documents group.
   
   
   Use the Open button or double-click a documented record to view its properties.
   The delete button removes only the attachment, not the whole tagged document.
   Click the Merge button to merge a document (see Functionality section).

   Described above commands are available only when you choose a certain group.

   When All Documents mode is selected, it is not possible to create a new document or modify an existing one.
   
   Click the Find icon and the Find Panel will appear for you to search for a special record, start typing and the system prompts variants.
   Click it again and the Find Panel will disappear.
   By clicking icon, you will be switched to The Documents Module help manual.

Functionality

The Documents module allows you to organize all types of scanned documents, create groups, and link them to individual data records (e.g. such as a passport/certificates).
It also allows you to scan other image files and attach them to each person (to the Enclosed data group) using Distribute option.
There are advanced tools to pick up scans directly from e-mail or a folder and preview, before selecting the record it will be attached to.
With this module, it is also possible to create and add merge templates in MS Word, bookmark and add fields for automatic report generation in MS Word.
Merging is done automatically for all tagged persons in the current crew list, one or many.
You can open the Documents module either by selecting the icon on the Modules ribbon or pressing Ctrl+Alt+D hotkeys.

The standard work-flow for merging:

1. Create a Word template with needed bookmarks.

2. Link it to the record in the Documents module.

3. Use Merge Properties and Fast Query Builder to choose view/table, select fields, generate script, and define aliases for the merge document.

4. Tag some persons in the Crew List whose data you want to merge into the Word document. 

5. Go to the Documents module > select needed group and record > click Merge button under Manage menu > set options. 

 Let's consider these steps in detail below.

Creating Record, Adding Word Template

To start merge, please open the Documents module. A list of all available documents for merge will appear.
By clicking one of the groups in the tree structure to the left, only the documents belonging to that particular group will appear.

• Various document groups are defined by the company administrator in General Codes (see Housekeeping section).

New Merge documents may be added to each group at any time. There is no limit to the number of documents that can be added.
Click the New button under the Manage menu to create a new record/document.

• It's available only when you choose a certain group.

When All Documents mode is selected, it is not possible to create a new document or modify an existing one.
A Document window appears:

The Document type corresponds to the selected group name.

You may add a Description to easily distinguish between a large number of templates.

Keywords field can be used for various notes.
To create a note put the cursor on the field, in the right-click menu choose New, a window where you can type any comment will appear. Type the comments & click OK to save.
Several lines of comments can be added.
It's possible to delete or edit them. You need to select a comment and choose the necessary option from the right-click menu.

Click and locate the word template that was prepared for this record beforehand (see How to Prepare Bookmarks in a Word Document in the section below).

 Options:

Merge Properties (see Define Merge Properties by Fast Query Builder section).

Attachment Properties, click to see the file name, size, location, time of creation, etc.

Mail Properties – from ver. 2018.3, we introduce a new option that allows you to customize email subject & email text when a merged document is generated using Email Merge Output.

Bookmark Setup (see Pre-Editing of Bookmarks section).

Click to edit the template.
This will open Microsoft Word and load the template automatically. Now you may change the content of the template to what is required. When you are done, save the changes.

• You cannot edit records under the All Documents folder if you are using Attach option for storing documents.
  
  The records are read-only in this case.
  Save To File allows you to save the linked document to your hard drive

Click OK to save the new document record.

How to Prepare Bookmarks in Word Document

When working with a Merge Word template, we advise you to turn on the Show bookmarks option (File > Options > Advanced > Show document content > Show bookmarks):

In our example, we will create a new Word document with proper bookmarks.
The document will contain basic information about a person (Name, Rank, Address, and Phone).

1. Step 1: Create a new Word document:
   
   
   

2. Create some text in it, for example, we need to prepare an invitation to the annual officers meeting without variable information like name, address, rank. This information will be merged into the document automatically.

3. Place bookmarks for each separate piece of information 

   We advise you to type a needed field name, then double-click it and select the Insert > Bookmark.
   Under Bookmark name, you should type a field/bookmark name (e.g.: Address2), then click Add.
   
   
   

   Bookmark names should begin with a letter and can contain numbers.
   
   You can't include spaces in a bookmark name. But, you can use the underscore to separate words (e.g.: First_Name).

   It is not necessary to use the same bookmark names as the field names in APM, you may use Aliases.
   
   Later you just need to type your alias under the Bookmark column in front of the correct field name In Query Builder (see Defining Merge Properties by Fast Query Builder section).

   It is possible to define the same predefined bookmark several times in the output document. For example, if you need to define a user's first name several times in the document, then you should add bookmarks into the output document as bkUserFirstName_1, bkUserFirstName_2, bkUserFirstName_N, etc., and then add them to the script manually during setting Merge Properties (see Defining Merge Properties by Fast Query Builder section).

   The text enclosed in grey brackets represents bookmarks.

Create other bookmarks in the same way. You need to add a bookmark for each data field you want to merge into the document.
If you are using three fields for the addresses, you need to define three bookmarks, one for each address field (as in our example).
If there is no information to be placed into a corresponding bookmark, a space will be put.

Defining Merge Properties by Fast Query Builder

You need to check the Merge Document box to indicate that your document is a merged one.
Click Options > Merge Properties to add an SQL statement/script:

You can write the script yourself or use Query Builder Designer.
By clicking the Query Builder button, you may easily generate the SQL query statement to use for merging:

1. The tables appearing on the right are sorted alphabetically. You should move down to find the needed table/view and double-click it. 

   For our case, we need to find the SRV views.

   We are using a database table (view) called PW001SRV0, which corresponds to the content of the Standard Crew List. A view is a virtual table that usually contains data from several database tables. It may be easier to use one of the crew list views than use a standard table, making it much easier to select numerous fields from one view.
   e.g.: PW001SRV1 corresponds to Current Activity view, PW001SRV2 - Last Appraisal view.
   
   
   
   

2. The fields of the selected table or view will appear in a small box to the left. 

   You should tag the corresponding fields you will use for Merge.
   
   
   

   
   
   

   
   
   

3. 
   
   

   As soon as you tag a field, it will appear in the left column of the grid.
   The last step is to type the Alias for each field in the Bookmark column, exactly as it is written as a bookmark in your Word document if they differ.
   Currently, you are at the Model tab.
   You may check the script by choosing the SQL tab:
   
   And the result of the SQL statement by choosing the Result tab.
   To save your merge properties, click button.
   The menu also allows:
   - to load from file.
   - to save to file.
   - to clear the selections.
   - to cancel script building.
   
   

For example, if you need to define a crew member's name several times in the document, then you should add bookmarks into the Word template as Name_1, Name_2, etc.
And then add them to the script manually during setting Merge Properties:

When a Word template is loaded to the Merge record, you can at any time open it and make any changes in the text.

If you change the bookmarks in any way, you need to make sure that the merge properties are changed accordingly.

Pre-Editing of Bookmarks

It is possible to check existing bookmarks & manually modify them before merging a document.
This gives to end-user more flexibility compared to a static set of data that is returned by the SQL query.
It is very useful for situations when some information is not stored inside the Adonis database but should be added to a merged document.
It cannot be extracted but you want to add it manually, e.g. your company's comments for a certain position (when offering vacancy) or others.
Open ready merge document, click Options > Bookmark Setup, Bookmark Setup Form appears.
Setup
You can select to upload all bookmarks that exist in the enclosed document or you can add them one by one as per necessity, using Insert/Delete buttons:

Bookmark displays the name of the bookmark as it exists in a merged document.
Label. Type the name of a bookmark to be shown on the Pre-edit screen.
Editable. The state of this checkbox defines whether the label will be available on the pre-editing screen or it will be ignored & the value will be fetched from the database.
The order defines the order of appearance for bookmarks on the Pre-edit screen.
The hint is the text that will be displayed for a tagged bookmark on the Pre-edit screen.

Please note that some bookmarks are mandatory. They can be also uploaded to the list, but they are shown grey & cannot be set Editable as this will break the logic of the query.

Pre-Editing
Once you've set up all the necessary bookmarks, you can close the dialog window & start merging a document.
The box will display all bookmarks with the corresponding setup:

1. Bookmarks list defined for pre-editing.
   Labels are shown instead of bookmark names.
   
   
   

2. The default value is fetched by the query.
   You can input a value to any editable empty bookmark.
   Or you can modify the value fetched by the query & this will override the result shown in the merged document.

3. Hint for the tagged bookmark.

You can set up bookmarks for every person tagged in the list, just click the Next/Previous Person buttons.

These buttons are enabled if you selected several needed persons in the Crew List and choose any selection option except Selected Person in Merge Output Form.

• Predefined bookmarks (bkUserPhone, bkUserEMail, bkUserSignature, bkUserPosition, bkFirstname, bkLastname) are disabled in Setup form.

It's not possible to redefine the value for such bookmarks when merging (see Predefined Bookmarks section).
After you're are done, you can follow by merging the document.

Document Merging

The result can look like this:

Tag person(s) in the Crew List whose data you want to export.
Locate the correct merge document in the Documents module and click the button:

In the window that appears, choose one of the Selection options:

•  

  • Selected Person;

  • Entire Crew Selection;

  • Tagged Persons (you need to tag the persons you want to merge the doc. in Crew List before merging);

  • UnTagged Persons (all persons who are not tagged in the crew list).
    
    
    

Choose a Merge Output option:

• Send to the default printer - the merged document is sent directly to the printer without previewing it in MS Word;
  
  
  

• Send to common Word document- the document appears as an open document in MS Word, from where it may be printed later;
  
  
  

• Save to separate file(s) - the document will be saved as a .doc file.
  
  In this case, please specify a file name and select a directory on your hard drive you want to save the document in;
  
  
  

• E-mail - the doc. will be sent to the selected crew member(s) using his e-mail address in the Personal Details data group (see Mail Properties the section below).

Distribute the option is separated from Merge output and can be selected in addition.
When this option is checked, the merged document is added to the Enclosed documents of a person with the Test code.

• Depending on the state of the global option Merge: E-mail and distribute word documents as pdf (office 2010 only) the document can be saved as an MS Word document or as a pdf file.
  
  
  

• When the option is selected, merge documents can be sent as pdf files, and the distributed file is added to Enclosed documents as .pdf, too (if the user has Microsoft Office 2010 installed). If the option is not set, the document is sent as word documents (doc., Docx files).

When you are ready, click OK.
The pre-merge form will appear if the merged document contains any Bookmark Setup (see Pre-Editing of Bookmarks section).

Mail Properties

From ver. 2018.3, We introduce a new option for Mail Properties which allows you to customize email subject & email text when a merged document is generated using Email Merge Output:

1. Open a merge document Options > Mail Properties
   
   
   

2. Input customized text for email subject & body.
   Note that you can use any of the fields which are returned by Merge SQL, wrapping them into [] symbols, e.g. [PIN], [FIRSNTAME] & those will be fetched accordingly.
   
   
   

3. Merge a document with the Email Merge Output option.
   Customized subject & body will be used for the generated & sent email.

Predefined Bookmarks

Adding User Data to Merge Document

There is a possibility to fetch any of the following user-related information from the user account properties to the merged document:

• First/Last Name;

• Position;

• Office address;

• Phone;

• E-mail;

• Signature.

The result can look like below:

First, the corresponding data should be added to the user profile in the ACCESS > Defining User Profile > More section.

OR
In APM > Backstage View > View Profile:

When creating a Word template, any of the following predefined bookmarks can be added per your wish:

• bkUserPhone;

• bkUserEMail;

• bkUserSignature;

• bkUserOffice;

• bkUserPosition;

• bkFirstname;

• bkLastname.

There is no need to include the above-mentioned fields (predefined bookmarks) in the SQL script in Merge Properties.

Save the template and merge the document.

For example, if you need to define user's first name several times in the document, then you should add bookmarks into output document as: bkUserFirstName_1, bkUserFirstName_2, bkUserFirstName_N, etc.
And then add them to the script manually during setting Merge Properties (see Defining Merge Properties by Fast Query Builder section).

Fetching Organization Information: Header, Footer, Logo

The situation when various organizational units within a company should have different headers, footers, and logos can be treated.
So, in addition to the user's data, it is possible to fetch the Logo, Header and Footer defined in Setup > Organization properties > Reports - Documents tab.
The result can look like this:

Steps:

Insert/check needed information and logo for the company:

The data to be merged depends on the organization unit that is the current open client.

The following predefined bookmarks should be added to the Word template: BBK header, bkFooter, bkLogo.

There is no need to include the above-mentioned fields in the SQL script in Merge Properties, too.

Save the ready template and merge the document.