Pre- and Post-Action Event Dispatching and Validation
Whenever a create, update, or delete action is initiated, the pre-action validator Thing (PTC.SCA.SCO.PreActionValidator) is called before the database update occurs. If the validation succeeds, the database is updated and the action completes. After a successful database update, the post-action handler Thing (PTC.SCA.SCO.PostActionHandler) is called in another thread, without impacting the execution of the action. The following diagram shows the dispatcher sequence of the pre-action validator 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.SCA.SCO.PreActionValidator) inherits the pre-action validator Thing Template (PTC.SCA.SCO.PreActionValidatorThingTemplate). Similarly, the post-action handler Thing (PTC.SCA.SCO.PostActionHandler) inherits the post-action handler Thing Template (PTC.SCA.SCO.PostActionHandlerThingTemplate). These Thing Templates implement the necessary Thing Shapes for triggering the pre- 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 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.
Example
For example, the work definition pre-action and post-action services work as follows:
• On the pre-action validator Thing: WorkDefinitionPreCreate, WorkDefinitionPreUpdate, ValidateWorkDefinitionExecutionStatus, and EnumerationValidation
When a work definition is created or updated, and an execution state is specified, the execution state is validated before allowing the action to proceed. The WorkDefinitionPreCreate or WorkDefinitionPreUpdate service is called depending on the action being performed. That action in turn calls the ValidateWorkDefinitionExecutionStatus service, which calls the EnumerationValidation service. If multiple work definitions 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 EnumerationValidation service for an example of how to issue an exception when a validation fails.
• On the default post-action handler 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 and Post-Action Services
The PTC.SCA.SCO.PreActionValidator Thing and PTC.SCA.SCO.PostActionHandler Thing are not editable.
To add additional pre- or post-action services:
1. For additional pre-action services, duplicate the PTC.SCA.SCO.PreActionValidator Thing. For additional post-action handler services, duplicate the PTC.SCA.SCO.PostActionHandler Thing. For this procedure, these duplicate Things will be referred to as the PTC.SCA.SCO.PreActionValidator_Duplicate Thing, and PTC.SCA.SCO.PostActionHandler_Duplicate Thing, respectively.
2. Create your pre-action services on the PTC.SCA.SCO.PreActionValidator_Duplicate Thing. Create post-action services on the PTC.SCA.SCO.PostActionHandler_Duplicate Thing.
3. Add a new entry to the ActionConfigurationSettings configuration table on the Configuration page for the PTC.SCA.SCO.PreActionValidator_Duplicate Thing or PTC.SCA.SCO.PostActionHandler_Duplicate Thing, as appropriate:
◦ DataShapeName—Search for and select the name of the Data Shape for which this pre- 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 on which your service resides, such as PTC.SCA.SCO.PreActionValidator_Duplicate or PTC.SCA.SCO.PostActionHandler_Duplicate.
◦ 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.SCA.SCO.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.SCA.SCO.PostgresDatabase or PTC.SCA.SCO.MSSQLDatabase.
 | You an find the database Thing configured for your system on the Configuration page of the launch point configuration Thing (PTC.Factory.C_LaunchPointConfigurationThing_[ReleaseVersion]). |
6. On the Configuration page for the database Thing, under DatabaseValidationConfigurationTable, update the PreActionValidator and PostActionHandler fields to point to duplicate Things created in step 1.
7. Click Save to save the database Thing configuration changes.