Pre-, On-, and Post-Action Event Dispatching and Validation
Whenever a create, update, or delete action is initiated, the pre-action validator Thing (PTC.DBConnection.PreActionValidator) is called before the database update occurs. If the validation succeeds, the database is updated and the on-action processor Thing (PTC.DBConnection.OnActionProcessor) is called. After a successful database update, the post-action handler Thing (PTC.DBConnection.PostActionHandler) is called in another thread, without impacting the execution of the action.
The following diagram shows the high-level design of the pre-action validator, on-action processor, and post action handler:
The following diagram shows the dispatcher sequence of the pre-action validator, on-action processor, and post-action handler when the pre-action validation succeeds.
If the validation fails, the action does not complete, and the database is not updated. The following diagram shows the dispatcher sequence when the pre-action validation fails.
The pre-action validator Thing (PTC.DBConnection.PreActionValidator) inherits the pre-action validator Thing Template (PTC.DBConnection.PreActionValidator_TT). The on-action processor Thing (PTC.DBConnection.OnActionProcessor) inherits the on-action processor Thing Template (PTC.DBConnection.OnActionProcessor_TT). Similarly, the post-action handler Thing (PTC.DBConnection.PostActionHandler) inherits the post-action handler Thing Template (PTC.DBConnection.PostActionHandler_TT). These Thing Templates implement the necessary Thing Shapes for triggering the pre-, on-, and post-action event dispatches.
When a create, update, or delete action is initiated, the appropriate pre-action service on the pre-action validator is triggered (PreCreateAction, PreUpdateAction, or PreDeleteAction). The pre-action service, in turn, executes the CallServices service, which reviews the data changes and reads the configuration on the pre-action validator. If there is a service configured for that action and Data Shape, CallServices dispatches the appropriate validation services. If any part of the validation fails, the entire action does not succeed.
If the pre-action validation succeeds, the database is updated and the on-action services are triggered (OnCreateAction, OnDeleteAction, OnUpdateAction). The on-action service then executes the CallServices service, which reads the configuration on the on-action processor, If a service is configured for that Data Shape and action, that on-action service is dispatched.
If a create, update, or delete action completes, the post-action handler is triggered (PostCreateAction, PostUpdateAction, or PostDeleteAction). The post-action service then executes the CallServices service, which reads the configuration on the default post-action handler. If a service is configured for that Data Shape and action, that post-action service is dispatched.
Services are provided on the pre-action validator and on the post-action handler which are run whenever a work definition, shift, or site is created or updated. These implementations can be used as models for implementing your own pre- and post-action services.
Pre-Action Services Example
This section describes how the pre-action services work, using job order actions as the example.
The following services are found on the PTC.JobOrderImpl.Manager Thing: JobOrderPreCreate, JobOrderPreUpdate, ValidateDispatchStatus, and ValidateJobOrderSite.
When a job order is created or updated, and an execution state is specified, the execution state is validated before allowing the action to proceed. The JobOrderPreCreate or JobOrderPreUpdate service is called depending on the action being performed. That action in turn calls the ValidateDispatchStatus and ValidateJobOrderSite services. If multiple job orders are being created or updated in a single action, and one of them has an invalid execution state specified, then the entire action does not succeed. Set the Log Level to Debug to view the details of the validation services and any errors in > . Refer to the ValidateJobOrderSite service for an example of how to issue an exception when a validation fails.
On-Action Services Example
The following services are found on the PTC.JobOrderImpl.Manager Thing: OnCreateJobOrder, OnUpdateJobOrder, UpdateJobOrderExecutionResponsesForJobOrders
When a job order is created or updated, the OnCreateJobOrder or OnUpdateJobOrder service is called depending on the action being performed. That action in turn calls the UpdateJobOrderExecutionResponsesForJobOrders service.
Post-Action Services Example
The following services are found on the PTC.SCA.SCO.DefaultProductionOrderManager Thing: WorkDefinitionPostCreate, WorkDefinitionPostUpdate, LogWorkDefinitionExecutionStatusChange
After a work definition is successfully created or updated, the WorkDefinitionPostCreate or WorkDefinitionPostUpdate service is called, depending on the action being performed. That action, in turn, calls the LogWorkDefinitionExecutionStatusChange service, which logs the following details about the action: the responsible agent for the action, the UID of the work definition that was created or updated, and the execution state UID and value. These details can be viewed in > , after the Log Level is set to Debug.
Adding Pre-Action, On-Action, and Post-Action Services
The PTC.DBConnection.PreActionValidator Thing, PTC.DBConnection.OnActionProcessor Thing, and PTC.DBConnection.PostActionHandler Thing are not editable.
To add additional pre-, on-, or post-action services:
1. For additional pre-action services, duplicate the PTC.DBConnection.PreActionValidator Thing. For additional on-action services, duplicate the PTC.DBConnection.OnActionProcessor. For additional post-action handler services, duplicate the PTC.DBConnection.PostActionHandler Thing. For this procedure, these duplicate Things will be referred to as the PTC.DBConnection.PreActionValidator_Duplicate Thing, the PTC.DBConnection.OnActionProcessor_Duplicate Thing, and the PTC.DBConnection.PostActionHandler_Duplicate Thing, respectively. For more information, see Duplicating Building Block Entities.
2. Create your pre-action, on-action, and post-action services on the manager Thing for the building block to which the Data Shape belongs. For example, create pre-action, on-action, and post-action services for job orders on the PTC.JobOrderImpl.Manager Thing.
3. Add a new entry to the ActionConfigurationSettings configuration table on the Configuration page for the PTC.DBConnection.PreActionValidator_Duplicate Thing, the PTC.DBConnection.OnActionProcessor_Duplicate Thing, or PTC.DBConnection.PostActionHandler_Duplicate Thing, as appropriate:
◦ DataShapeName—Search for and select the name of the Data Shape for which this pre, on-, or post-action service applies.
◦ Action—Enter the action: Create, Update, or Delete. The value is case-sensitive and must be entered exactly as presented here.
◦ ThingName—Search for and select the Thing name of the manager Thing on which your service resides, such as PTC.JobOrderImpl.Manager.
◦ ServiceName—Enter the name of the service to be dispatched by CallServices. If your implementation consists of multiple services, enter the initial service that calls the others. The value is case-sensitive and must exactly match the name of the service.
 | While your implementation can include a series of services, the service specified on the ActionConfigurationSettings configuration table and dispatched by CallServices must include an input parameter named DataChanges. This input parameter is an infotable of the Data Shape PTC.DBConnection.DataChange. |
4. Click Add, then click Save to save your configuration changes.
5. Navigate to the database Thing configured for your system, such as PTC.DBConnection.SQLThingDatabase.
 | You can find the database Thing configured for your system in the DefaultDatabaseConfiguration configuration table on the Configuration page of the PTC.DBConnection.Manager. |
6. On the Configuration page for the database Thing, under DatabaseValidationConfigurationTable, update the PreActionValidator , PostActionHandler, and OnActionProcessor fields to point to duplicate Things created in step 1.
7. Click Save to save the database Thing configuration changes.