docCustomDefinitions.xml file

The document properties configuration file (docCustomDefinitions.xml) defines properties that are used to manage documents. The installation process places a sample file in /aiw/aiw1/samples/config on UNIX-based operating systems, and in C:\aiw\aiw1\samples\config on Windows.

    Note:
  • If you change the docCustomDefinitions.xml file after installing Advanced Document Pool, AFP Support, or PDF Document Support:
    • Run the docCustom utility and install or upgrade the Custom Document Properties feature.
    • For the PDF Document Support feature, load the document properties to RICOH ProcessDirector Plug-in for Adobe Acrobat.
    • For the AFP Support feature, access RICOH Visual Workbench from the RICOH ProcessDirector user interface. New document properties are loaded to RICOH Visual Workbench when it opens on your workstation.

Database properties and limited properties

You can define two types of document properties:

  • Database properties
  • Limited properties

You can store and manipulate both types of properties in a document properties file, but only database properties are stored in the database.

You can work with both types of properties in these ways:

  • You can use them with steps in a workflow to group or sort documents (for example, with the SortDocuments step template).
  • You can link them to AFP index tags using the RICOH Visual Workbench Document Property Designer.
  • You can map document data in PDF jobs to them using RICOH ProcessDirector Plug-in for Adobe Acrobat.
  • If you have the Archive feature, you can store them in a repository. After you store them, you can use them to search the repository and retrieve jobs, documents, and history information. The values of the properties appear on the Properties tab when you click Show details on the Results table.
  • If you have the Preference Management feature, you can use an external preferences file to set the values of the properties.

You can work with database properties, but not limited properties, in these ways:

  • You can use them to search for documents on the Documents portlet on the Main page of the user interface.
  • When you select a document on the Documents portlet, the values of database properties are displayed.
  • You can use them to search for documents to display in the viewer.
  • You can determine their values in one job, update their values in another job, and use the updated values in the original job.
  • If you have the Automated Verification or Inserter feature, you can use database properties to search for documents to reconcile or reprint.
  • If you have the Advanced Document Pool extended feature, you can use selectors to manipulate documents based on their property values.

Limited properties offer these advantages:

  • You can use them to avoid displaying sensitive property values in the user interface, such as Social Security numbers or check amounts.
  • They maximize system performance. Database property manipulation can degrade performance if you process a significant number of documents.

Work with your support representative to determine your needs for database and limited document properties.

Sections in sample file

The sample docCustomDefinitions.xml file contains several sections. This table summarizes them.

Sections in the docCustomDefinitions.xml file

Section Purpose
Schema The schema section identifies the schema and the unique character string for the custom document properties. Only the support representative should edit this section.
Database properties This section defines database document properties.
Limited properties This section defines limited document properties.
User authorization properties This section is optional. User authorization properties specify custom authority groups for access to database properties.

Schema section

The Schema section contains one docCustomDefinitions element and one schema element. Only support representatives should edit the schema section.

Database properties section

The Database properties section contains the docProperty element.

    Note:
  • Do not define a property as both a database property and a limited property. Unexpected behavior might occur.
  • Do not define a document property with the same name as a property that RICOH ProcessDirector defines automatically. For a list, see Automatically defined document properties.
<docProperty>
Defines document properties that are in the database.

Attributes for the docProperty element

docProperty attribute Required? Notes
name Yes The database name (internal name) for the property. Programs that read or write properties use this name. We recommend that you use a consistent naming convention for your custom property names, so they are unique across the entire system. For example, the sample docCustomDefinitions.xml file uses the prefix Doc.Custom to make its properties unique from those of the base product.

Do not use any special characters (such as @, #, $, %, or - (dash)) or spaces in the property name. You can use periods and underscores.

Do not use a number immediately after the period (.) in the property database name. For example, the property Doc.3rdLineAddress is not valid.
access No The user access level for the property. You can use an access level that is already defined in the product, or you can create a custom access level if an existing one does not meet your needs. See the Access section for more information.
datatype Yes The data type to use for the property. See the next table.
dbType No A database parameter that specifies the type of data.
    Note:
  • The dbType property has been deprecated and is no longer used. Use the datatype property instead.
caption Yes The user interface name (default caption) for the property. If you are setting up captions in only one language, define them in this file. If you are setting up user interface names in more than one language, create additional document properties names files (docCustomDefinitions_language.properties) for the other languages.
shortCaption Yes The default short caption displayed for this property where required, such as in table column headings. If you are setting up short captions in only one language, define them in this file. If you are setting up short captions in more than one language, create additional document properties names files (docCustomDefinitions_language.properties) for the other languages.
description Yes The default description of the document property, which displays in the user interface as help text. If you are setting up descriptions in only one language, define them in this file. If you are setting up descriptions in more than one language, create additional document properties names files (docCustomDefinitions_language.properties) for the other languages.

You can use these data types and database types in database property definitions. Keep in mind that the database definition might further restrict the values that can be stored, in addition to the validation rules shown in this table. For example, a SMALLINT can store integers from 0 to 32,767. Database type values are not case-sensitive.

Data types and database types for docProperty definitions

Data type Database type (used in SQL) Validation for data type
String VARCHAR(128) VARCHAR: variable length, 1–128 characters
IntegerNonNeg SMALLINTBIGINTINTEGER SMALLINT: 2 bytesBIGINT: 4 bytesINTEGER: 8 bytesMinimum=0
Timestamp TIMESTAMP TIMESTAMP: Must contain values for day (D), month (M), and year (Y).Those components can appear in one of these formats:MM DD YYYYDD MM YYYYYYYY MM DDDay and month must be represented by a two-digit number.You can add a time of day in this format:hh:mm:ss
XdkString10 VARCHAR(10) VARCHAR: variable length, 1–10 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.
XdkString20 VARCHAR(20) VARCHAR: variable length, 1–20 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.
XdkString30 VARCHAR(30) VARCHAR: variable length, 1–30 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.
XdkString40 VARCHAR(40) VARCHAR: variable length, 1–40 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.
XdkString50 VARCHAR(50) VARCHAR: variable length, 1–50 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.
XdkString128 VARCHAR(128) VARCHAR: variable length, 1–128 characters

    Note:
  • These values are variations of the String data type that can be used instead of String to reduce the amount of space reserved in the database for property values.

Limited properties section

The Limited properties section contains one or more docProperty elements.

    Note:
  • Do not define a property as both a database property and a limited property. Unexpected behavior might occur.
  • Do not define a document property with the same name as a property that RICOH ProcessDirector defines automatically. For a list, see Automatically defined document properties.
<docProperty>
Defines document properties that are manipulated only in the document properties file and not in the database.

Attributes for the docProperty element

docProperty attribute Required? Notes
name Yes We recommend that you use a consistent naming convention for your custom property names, so that they are unique across the entire system. For example, the sample docCustomDefinitions.xml file uses the prefix Doc.Custom to make its properties unique from the base product.

Do not use any special characters (such as @, #, $, %, or - (dash)) or spaces in the property name. You can use periods and underscores.

Do not use a number immediately after the period (.) in the property database name. For example, the property Doc.3rdLineAddress is not valid.
datatype No See the next table.
caption No The caption displayed in lists