In addition to synchronous and asynchronous event actions,
you can create a user-implemented action called a change preprocessor.
A change preprocessor runs synchronously during a transaction before
database updates have occurred. Using this feature you can make source
object modifications that are difficult or impossible to achieve with
synchronous or asynchronous event actions.
The following list contains examples of object modifications
that change preprocessors can make:
- A change preprocessor must be used to alter properties that are
settable only during object creation. The reason for this requirement
is that when committed to the database, this type of property cannot
be changed.
- A change preprocessor can be used to synchronously modify a source
object. The only other method of modifying a source object is by using
an asynchronous event action. However, for high-volume operations,
asynchronous event actions reduce throughput due to the increased
processor usage inherent in using them.
- A change preprocessor can be used in cases when the action must
complete in time to satisfy dependencies of other applications. With
asynchronous actions, there is a brief time period between object
persistence in one transaction and action changes in a separate transaction.
Therefore, avoid an asynchronous event action if a dependent client
cannot tolerate a time period when required action changes have not
been applied.
For more information about the differences
between change preprocessors, synchronous event actions, and asynchronous
event actions, see Action
Handlers: Restrictions and Best Practices.
A change preprocessor
consists of three components:
- A change preprocessor definition that associates
a change preprocessor action to a class. A class can have one or more
change preprocessor definitions associated with it.
- A change preprocessor action that references the JavaScript or code module
that is used to perform the action.
- A Java™ or JavaScript action handler that
performs the action. A Java-implemented action handler can be placed
in a code module. In addition, it can coexist with other action handler
types, such as event action, lifecycle action, and document classifier.
When you work with change preprocessors, note the following
characteristics:
- A change preprocessor is triggered by the following types of events:
create, update, and delete.
- A change preprocessor runs synchronously, so an exception rolls
back the entire transaction.
- If auditing is enabled, the audit log entry shows the changes
that are made by change preprocessors.
- Unless disabled, change preprocessors are invoked unconditionally.
- Changes made by a preprocessor can be saved only if the user making
the request has the required permissions, and if property constraints
are not violated.