Filter phases

Actions within filters are carried out in one of three phases. All Phase 1 actions are carried out immediately. Phase 2 and Phase 3 actions are queued to be carried out later. See Filter-processing-example.

Using a phased approach to filter processing helps to make sure the following actions occur:

  • Notifications are sent and that processes are run only after the database operations are successful. If any database operation fails, all subsequent actions are suppressed, and database changes are rolled back. So, the system defers to a final phase the operations that should not run until database transactions have been committed and there is no chance that a rollback occurs.
    For example, you can create a filter to notify Shipping that a purchase order is ready to be fulfilled. If, during the filter processing, an error occurs, the chain of events are rolled back, and the transaction is not committed to the database. Without phases in filter processing, Shipping would be notified and the equipment would be sent, but no record of the task would be committed to the database.
  • All data values are complete and available to the notification that is sent as well as to Push Fields operations that create related records.
  • Obtaining a write lock (which is an exclusive lock) for a Push Fields operation is delayed until the point at which a write is performed to the main data table. This shortens the duration of the exclusive portion of the transaction, and improves throughput.

Related topic

Filter-processing

Phase 1 actions

The following Phase 1 actions are always performed as soon as they can be:

  • Call Guide
  • Exit Guide
  • GoTo
  • Go To Guide Label
  • Log to File
  • Message
  • Set Fields
  • Service

Phase 2 actions

Phase 2 actions are queued when they are encountered and performed after all Phase 1 actions from all filters execute. If a Phase 2 action triggers more Phase 1 actions, then those Phase 1 actions are performed before the next Phase 2 action. If a Phase 2 action triggers more Phase 2 actions, then they are added to the end of the Phase 2 queue.

Each request with a filter executing against it has its own Phase 2 queue. So if a Push Fields action triggers the execution of a nested filter against the target request, the Phase 2 action in that filter that apply to that request are queued separately in the Phase 2 queue for that request. Those Phase 2 actions are run after the Phase 1 action in the nested filter are complete. The remaining Phase 2 actions in the outer filter are run after the nested filter Phase 2 actions.

Phase 2 actions include:

  • Push Fields
  • Direct SQL

Phase 3 actions

Phase 3 actions do not include any database interaction. All Phase 3 actions encountered are queued and performed after all Phase 1 and Phase 2 actions.

Unlike the separate Phase 2 queues, there is one Phase 3 queue for the request against which filter execution is originally triggered and any other requests which have filters

Phase 3 actions include:

  • Notify
  • Run Process
  • DSO

Phase 3 actions are presumed successful, but can fail and not affect the operation's success.

Filter phasing exceptions

There are exceptions to the phasing process:

  • For get actions (filters with Execute On set to Get Entry) and delete actions, Phase 1 and Phase 3 actions occur together.
  • For get operations, there is generally no database change, so the actions need not be phased. However, there might be database changes as the result of Push Fields actions that the get operation triggers.
  • For delete operations, you cannot defer actions because the delete action removes the current record, so the record would not be available for the actions later. The subsequent actions need to run when the data is still present.

The following tables further describe when certain operations are processed.

Filter phasing for Create and Merge operations

1 Filters run (including Phase 1 actions).


2 Create operation. (Entry ID is created.)

Database transaction occurs.

3 Phase 2 actions occur.

4 Phase 3 actions occur.



Filter phasing for Set operations

1 Filters run (including Phase 1 actions).


2 Phase 2 actions occur.

Database transaction occurs.

3 Entry is modified in the database.

4 Phase 3 actions occur.



Filter phasing for Get operations

1 Data is retrieved from the database.


2 Filters run (including all Phase 1 and 3 actions).


3 Phase 2 actions occur.

Database transaction occurs.

Filter phasing for Delete operations

1 Filters run (including all Phase 1 and 3 actions).


2 Phase 2 actions occur.

Database transaction occurs.

3 Entry is deleted in the database.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*