VERIFIED SOLUTION i

Setting up Custom Indexes in EngageOne Vault

Overview
The data in Vault can be broken down into several parts:

A common pool of:
  • compressed pages or other content
  • document records

One or more databases consisting of:
  • a set of customer records
  • a set of indexes that link to customer records
  • a set of indexes that link to document records

A database is a logical view of the common pool of document data. A database may link to all document data or just a subset of it. Each database has a customer table that maintains properties common to all documents associated with an account number.

Databases are used as a way to organize broad sets of documents. For example, you might group documents by type of customer (e.g. “residential” and “commercial”) or by type of document (for example “invoices”, “credits”).

Indexes play an important role in Vault. They are used to enable clients to search for customer and document records in various ways. They are also used internally for a number of housekeeping purposes such as linking documents to account numbers.

Default Indexes
Vault defines a default set of indexes that will be created automatically if not otherwise configured. These are useful for simple installations and test environments. For more complex needs, the indexes used by Vault can be customized. For example, removing indexes that are not needed can save space and time during loads. Adding new indexes can enable searches for data in ways important for specific business needs.

Vault creates the following indexes by default:
Account numbers
Names
Addresses
Dates under this account
 
All the index entries must be defined in an initialization file, and the label changed as required. Use the database initialization file for system wide changes or the profiles initialization file for a particular profile(s) only. You must ensure that all the index entries are defined, as when indexes are defined in the initialization file, no defaults are assumed; otherwise the default settings are used exclusively. Note that there are also some extra internal index entries that must also be included.  Note that in older versions of Vault, it may be necessary to add the CustomIndexing=1 parameter to the profile for additional indexes.

Index Settings
The index related settings can be broken down into two groups:
  • database settings that define the available searches and their properties
  • profile settings that define how index entries for each document record are to be created
If you customize the index settings in an installation, you normally need both types of settings. Database settings are configured in database.ini in sections representing each database. The profile settings are configured in profiles.ini in sections corresponding to the profile assigned to the job.

The following is a sample index configuration showing some of the more common settings. It sets up 4 indexes (account, name, address and date) in a single database called “statements”. The meaning of each key is documented in detail in the following sections.

Profiles.ini
[st201204]
Database=statements
Index1=account,cust.account,wjctul,Account Numbers
Index2=name,cust.name,jcrtul,Names
Index3=address,cust.address,jcrtul,Addresses
Index4=invlink,doc.date,xdhasb,Dates under this account

Database.ini
[statements]
Description=Statements
Index1=account,cust.account,wjctul,Account Numbers
Index2=name,cust.name,jcrtul,Names
Index3=address,cust.address,jcrtul,Addresses
Index4=invlink,doc.date,xdhasb,Dates under this account
Render1=Account;Name;Address,int.match;cust.name;cust.address
Render2=Name;Account;Address,int.match;cust.account;cust.address
Render3=Address;Account;Name,int.match;cust.account;cust.name
Render4=Date,doc.date

Profiles.ini Settings Reference
Database

Set the list of databases to which the index entries should be added.
  • The parameter is a comma separated list of database names.
  • Database names are typically short words in lowercase without punctuation. This name will
    be used to create a subdirectory containing index files and other data. The default database
    is simply called “default” and is stored by under server\index.
One of the names in the database setting can be * which tells Vault to retrieve the attribute DATABASE from the document record and add it to the list of databases.

Format
Database=<dblist>

Default
Database=default

Examples
Database=invoices
Database=statements,credits,requests
Database=*
Database=all,*

Index<N>
Define the index entries to be added for the document records using the profile. The Index<N> settings need to be numbered from 1 to N without gaps. Each Index<N> parameter consists of 4 parts separated by commas.
  • The first is the name of the index. Index names are typically short words in lowercase
    without punctuation.
  • For standard indexes, this will refer to a .dri file with the same base name in the database
    subdirectory (e.g. the “invlink” index in the “invoices” database will refer to the file
    server\index\invoices\invlink.dri).
  • For Unicode indexes the extension will be .dru. For indexerd indexes, the data is stored in a
    common file, server\index\index.dr2.
  • The second is a list of fields used to construct the index key. This can be a single field or
    multiple fields separated with "+". Index fields can refer to data from the customer and
    document records or can be special fields used to access internal information. For details on
    the list of fields available during index creation, see the “Index Key Fields” section below
  • The third is a list of that control the behavior of the index. Normally the are single lower case
    letters. These control the behavior of the index and how keys are created. For details on
    each flag, see the “Index Flag” section below.
  • The fourth is a text description of the index. This is the text description of the index that gets
    presented to users.
The profiles.ini Index<N> entry format is the same as the format used in the database.ini file. In some cases you can cut and paste the Index<N> settings from one to the other. However, the fields are used differently in the two locations. For example, the text description is used in the database.ini but ignored in the profiles.ini. The reverse is true of the list of fields used to construct keys.

NOTE: The numbering in the profiles.ini does not have to match the order in the database.ini.

By default, when a field is used in a custom index configuration, the index entry will not be added unless the field exists and contains a value other than the empty string. You can make the field optional by prefixing the field name with a “?” character. If so, the index entry will be added even if the field is missing or blank. The only exception to this is that if all fields in an index entry configuration are missing or blank. When an optional field is missing, the empty string will be used as its value.

Format
Index<N>=<indexfilename>,<keyfield>,<>,<description>

Examples
Index<N>=<indexfilename>,<keyfield>,<flags>,<label>
Index1=account,cust.account,wjctul,Account Numbers
Index2=name,cust.name,jcrtul,Names
Index3=invlink,doc.date,xdhasb,Dates under this account
Index4=guid,doc.guid+int.null+doc.type,dhi,GUID
Index5=invoice,doc.invoice,dh,Invoice
Index6=info,doc.date+int.space+?SRCCODE+int.space+?ORGUNIT,dhas,Document
Information
 
Render entry format example:
Render<N>=<title1>;<title2>;<title3>,<field1>;<field2>;<field3>
 
Example database.ini entries:
Index1=account,cust.account,jctul,Accounts
Index2=name,cust.name,jcrtul,Names
Index3=address,cust.address,jcrtul,Addresses
Index4=guid,hint.guid+int.null+int.format,dhi,GUID
Index5=contract,hint.invoice,dh,Invoice Numbers
Index6=wayg,WAY,dh,Way Bills
Index7=invlink,hint.date,dhasb,Dates under this account
Index8=pol,PO,sadh,Purchase Order under this account
Index9=ordl,ORD,sadh,Order Number under this account
Render1=Customer;Name;Location,cust.account;cust.name;cust.address
Render2=Name;Customer;Location,cust.name;cust.account;cust.address
Render3=Location;Customer;Name,int.match;cust.account;cust.name
Render4=GUID;Customer;Date,hint.guid;hint.account;hint.date
Render5=Invoice Number;Customer;Date,hint.invoice;hint.account;hint.date
Render6=Way Bill;Customer;Date,WAY;hint.account;hint.date
Render7=Date;Invoice,hint.date;hint.invoice
Render8=Purchase Order;Date,PO;hint.date
Render9=Order Number;Date,ORD;hint.date
 
Index Flag Descriptions
Flags Internal Variable Description
a PrefixAccount Prefixes the user's search key with [account][0]. This index is used to search for data associated with a particular account (document names, and purchaseorders).
m MultipleValues Add multiple keys if more than one copy of the attribute is present. When adding keys based on custom attributes, look for multiple copies of that attribute and add each one separately. NOTE: The maximum number of multiple instances is limited by the following profile setting (default is 8):
 
[profilename]
MaxInstances=4
 
s AccountMustBeSelected This flag tells the client that an account must be selected in order for the search to appear in the list of available searches.
h LinkByHintRecord Match ends with [0][hintfile name][0][hintfile offset].The keys in this index point to documents.
c LinkByCustomerRecord The keys in this index point to accounts. Match ends with [account.drr offset].
p DisplayPage If the index points to a document using a custom attribute, switch to the page associated with that attribute.
d DisplayDocument When selected, display the first page of the specified document.
t DisplayNewestDocument Displays the most recent document for the account (whether the index points to a document or account
r RotateStrings Adds multiple “rotations” of the key field to the index, each version starting at a new word within the value. For example field:
“JOHN SMITH” would add versions
“JOHN SMITH” and “SMITH JOHN”.
This can be used to search within a key field which is useful for names and addresses. In a name index for example you could search for first or last name. NOTE: The maximum number of rotated values (option r) is limited by the following profile setting (the default is 8):
 
[profilename]
MaxRotations=4
 
b SearchBackwards Shows the search results in reverse order (helpful for the date index - it will show most recent first).
i InvisibleToUser Sets the index as invisible to the user.
u UpdateOnCustomer Add this key only if the customer record changes. This is an optimization for fields that use the customer record, it avoids the effort if it did not change).
l LeaveOnUnindex Do not remove this key when the print file removed from the Vault (fields that point to the customer record should still be usable when a single print file is removed).
j JumpOnSingleMatch If a single search value was returned, automatically select it (if you enter a unique matching search, that result will immediately pop up, otherwise it will wait for the user to click on the single result listed).
w WebAccountIndex Web scripts can use this index to check the existence of accounts (this is used sometimes by custom web scripts that need to know which index will tell them whether an account number is valid).
 
Flag Scenarios
Below is an example of possible scenarios that can be created with the use of multiple flags: Top level index that points to an account (name, account, and address):
 
ctul
• points to a customer
• shows the most recent document when selected
• add only if the customer record changed
• leave this key when documents are removed
• use only cust.xxx fields
 
Top level index that points to a document (invoice number and purchase order)
hd
• points to a document
• shows this document when selected
• uses only doc.xxx fields or custom attributes
 
An index that points to documents under an account (dates under this account, invoice numbers for this account)
hdsa
• points to document
• shows this document when selected
• an account must be selected before the search should be available
• the key's value is associated with a specific account
• uses only doc.xxx fields or custom attributes
 
Common Options
Below are examples of options that are commonly used for indexing.
b – List backwards: shows the results in backwards order.
j – Autoselect: automatically select the match when only one matching result is found.
r – Search within the field: add “rotated” versions (e.g. JOHN SMITH would add “JOHN SMITH” and “SMITH JOHN”).

Uncommon Options
Below are examples of options that are not commonly used for indexing but can be used if deemed necessary.
i – Do not show this to the user: this index is invisible to the user.
m – Multiple values of a custom attribute: add each specified copy of the custom attribute to the index.
w – Mark this as the account index for web scripts: marks the index that can be used by web scripts to validate account numbers.

For full information about indexing, please refer to the Vault Customizing Guide.
UPDATED:  October 30, 2019