Adding Event Trigger Scripts: Background Information

Before you can create an event trigger script for the General callback event, you must create an orphan of the GeneralCallbackScripts object, located in WFMain:WFRoot:CallbackEventsScripts, into your custom module. The GeneralCallbackScripts object contains the scripts that can be attached to general workflow events.

For each general event trigger script that you create, you can set the following features:

• fEnabled, which contains a Boolean value. When set to TRUE, the fEnabled feature lets you register the object in WFMain:WFCBGeneralSubsystem.
  
  
• fScriptName, which contains a String value. This feature stores the name that you want to represent the event trigger script on the Event Scripts tab in the Content Server interface. By default, the name that you give to the script is used to name the option on the Event Scripts tab in the Content Server interface; however, you can customize the name that is displayed by creating this String feature.

If the names of the scripts that you add to the GeneralCallbackScripts object do not begin with a 0 or an underscore (_), they are displayed on the Event Scripts tab in the Content Server interface as options for Content Server users to attach to general workflow events. If the names of your scripts begin with a 0 or an underscore (_), they are not displayed in the Content Server interface, but can be used as utility scripts that are referenced by the event trigger scripts.

If you attach a general event trigger script to a Step Ready event and the event trigger script returns a value of TRUE, the step is automatically completed.

After you set the features associated with the GeneralCallbackScripts object, you can create the general event trigger scripts. A prototype for the general event trigger scripts is stored in the ODocumentation() script in the GeneralCallbackScripts object. General event trigger scripts must return a Boolean value -- TRUE for success or FALSE for failure.

After you orphan the general event trigger object, set the fEnabled feature, and create the general event trigger scripts, you run the BuildOSpace() script in the Globals object of your custom OSpace and restart the Content Server Builder to register your changes. The BuildOSpace() script registers the GeneralCallbackScripts object in WFMain:WFCBGeneralSubsystem and exposes the Event Scripts tab in the Content Server interface.

When you install the custom module in which the general event trigger functionality is contained, you can view your changes in the Content Server interface. The names that you specified in the fScriptName features of the GeneralCallbackScripts object are displayed as options in the lists associated with general workflow events on the Event Scripts tab.

For GeneralCallbackScripts attached to Before Send On events in the Event Scripts tab:

• Before Send On events are designed for validation purposes, for example to check if an attachment is reserved or not. For scalability reasons the Before Send event scripts are executed without locking the process instance. They are executed even if parallel paths or sub workflows are executed at the same time.
  
  
• Only read-only operations are allowed, no modifications are possible (e.g. on the work package) in GeneralCallbackScripts referenced in the Before Send On callback.
  
  
• It is possible to set a specific error message. Use the fErrorMsg feature of the WSession to set the desired error message in the general event script. For example:
  
  prgCtx.WSession().fErrorMsg = Str.Format( "The document %1 is reserved", documentName )
  
  This error message is displayed in case the GeneralCallbackScripts returns FALSE for failure.

Before you can create the event trigger scripts for the Performer callback event, you must create an orphan of the PerformerCallbackScripts object in your custom module. You can find the PerformerCallbackScripts object in WFMain:WFRoot:CallbackEventScripts. The PerformerCallbackScripts object will contain the scripts that can be attached to the Assign Step Performer workflow event.

For each performer event trigger script that you create, you can set the following features.

• fEnabled contains a Boolean value. When set to TRUE, the fEnabled feature lets you register the object with WFMain:WFCBPerformerSubsystem.



• fScriptName  contains a String value. This feature stores the name that you want to represent the event trigger script on the Event Scripts tab in the Content Server interface. By default, the name that you give to the script is used to name the option on the Event Scripts tab in the Content Server interface; however, you can customize the name that is displayed by creating this String feature.

After you set the features associated with the PerformerCallbackScripts object, you can create the performer event trigger scripts. A prototype for the performer event trigger scripts is stored in the ODocumentation() script, which is contained in the PerformerCallbackScripts object. If successful, these scripts return the ID of a Content Server user or group to which the workflow step is assigned when it becomes ready; otherwise, these scripts return errors.

After you create and edit the performer event trigger scripts, you must run the BuildOSpace() script in the Globals object of your custom OSpace and restart the Livelink Builder to register your changes. The BuildOspace() script registers the PerformerCallbackScripts object in WFMain:WFCBPerformerSubsystem and exposes the Event Scripts tab in the Content Server interface.

When you install the custom module in which the performer event trigger functionality is contained, you can view your changes in the Content Server interface. The names that you specified in the fScriptName  features of the PerformerCallbackScripts object are displayed as options in the Assign Step Performer list on the Events Script tab. This lets you add performer event trigger scripts to Assign Step Performer workflow events.

Before you can create the event trigger scripts for the Submap callback event, you must create an orphan of the SubmapCallbackScripts object in your custom module. You can find the SubmapCallbackScripts object in WFMain:WFRoot:CallbackEventScripts. The SubmapCallbackScripts object will contain the scripts that can be attached to the Determine Sub-Map To Use workflow event.

For each submap event trigger script that you create, you can set the following features:

• fEnabled contains a Boolean value. When set to TRUE, the fEnabled feature lets you register the object with the WFMain:WFCBSubmapSubsystem.
  
  
• fScriptName  contains a String value. This feature stores the name that you want to represent the event trigger script on the Event Scripts tab in the Content Server interface.

By default, the name that you give to the script is used to name the option on the Event Scripts tab in the Content Server interface; however, you can customize the name that is displayed by creating this String feature.

After you set the features associated with the SubmapCallbackScripts object, you can create the submap event trigger scripts. A prototype for the submap event trigger scripts is stored in the ODocumentation() script associated with the SubmapCallbackScripts object. If successful, these scripts return an integer representing the MapID of a workflow map definition (as stored in WAPI) that is initiated as a Sub-workflow when the corresponding step becomes ready; otherwise these scripts return errors.

After you create and edit the submap event trigger scripts, you must run the BuildOSpace() script in the Globals object of your custom OSpace, and restart the Livelink Builder to register your changes. The BuildOSpace() script registers the GeneralCallbackScripts object in WFMain:WFCBSubmapSubsystem and exposes the Event Scripts tab in the Content Server interface.

When you install the custom module in which the submap event trigger functionality is contained, you can view your changes in the Content Server interface.The names that you specified in the fScriptName  features of the SubmapCallbackScripts object are displayed as options in the Determine Sub-Map To Use list on the Event Scripts tab. This lets you add submap event trigger scripts to Determine Sub-Map To Use workflow events.

Creating event trigger scripts lets the creators of workflows access the Event Scripts tab in the Content Server interface, where they can add custom operations to specific workflow events. This means that the creators of workflows can determine which operation to perform when a specific workflow event occurs in the execution of a workflow.

If you want to restrict access to an event trigger script that you add to Content Server so that only certain Content Server users can attach the event trigger script to specific workflow events, you can modify the fObjectFactory feature and the FactoryName() script associated with the corresponding event trigger object. For example, if you want to specify which Content Server users can attach a general event script to specific workflow events, you can modify the fObjectFactory feature and the FactoryName() script contained in the general event trigger object in your custom module. Similarly, if you want to specify which Content Server users can attach a performer event trigger script to the Assign Step Performer workflow event, you can modify the fObjectFactory feature and the FactoryName() script contained in the performer event trigger object in your custom module. If you want to specify which Content Server users can attach a submap event trigger script to the Determine Sub-Map To Use workflow event, you can modify the fObjectFactory feature and the FactoryName() script contained in the submap event trigger object.

• fObjectFactory contains a Boolean value. When set to TRUE, this feature works with the FactoryName() script to allow the Admin user (Content Server Administrator) to restrict access to event trigger scripts.
  
  
• FactoryName() returns a string that identifies the event trigger scripts to which you want to restrict access.

You can restrict access to general event trigger scripts, performer event trigger scripts, and submap event trigger scripts individually by setting different return values for the FactoryName() scripts for each event trigger object. You can restrict access to all general event trigger scripts, performer event trigger scripts, and submap event trigger scripts together by setting the same return values for the FactoryName() scripts for each event trigger object.

After you modify the fObjectFactory features and the FactoryName() scripts contained in the event trigger objects for the event trigger scripts to which you want to restrict access, you must run the BuildOSpace() script in the Globals object of your custom OSpace. Then, the Admin user can go to the Administer Object and Usage Privileges section of the Content Server Administration page and specify which Content Server users can attach the event trigger scripts to workflow events.

Suppose that you create general, performer, and submap event trigger scripts in your custom module and you want to restrict access to the performer and submap event trigger scripts. You can set the fObjectFactory feature to TRUE and modify the FactoryName() script to return the same string value in the performer and submap event trigger objects. This means that the Admin user can specify which Content Server users can attach the performer and submap event trigger scripts to workflow events. In this case, certain Content Server users can attach the performer and submap event trigger scripts to workflow events and all Content Server users can attach the general event trigger scripts to workflow events.