Event Handlers (Profile)

Event handlers define validation rules or other scripts to run when an event occurs on an object. The logic of the event handler is defined using VBScript. Criteria do not support event handlers.

  1. Right-click a metaclass or a stereotype and select New > Event Handler to open a selection box, listing the available types of event handlers:

    Event handler

    Description

    CanCreate

    Implements a validation rule to prevent objects from being created in an invalid context. For example, in a BPM for ebXML, a process with a Business Transactions stereotype can only be created under a process with a Binary Collaboration stereotype. The script of the CanCreate event handler associated with the Business Transaction process stereotype is the following:

    Function %CanCreate%(parent)
  if parent is Nothing or 
  parent.IsKindOf(PdBpm.Cls_Process) then
  %CanCreate% = False
  else
  %CanCreate% = True
  end if
End Function

    If the event handler returns True on a stereotype, then you can use the custom tool to create the stereotyped object and the stereotype is available in the Stereotype list on the object property sheet. If it returns True on a metaclass, then you can create the object from the Toolbox, from the Browser or in a list.

    Note: CanCreate event handlers are ignored during model import or reverse-engineering, since they could modify the model and make it diverge from the source.

    Initialize
    Instantiates objects with a predefined template. For example, in a BPM, a Business Transaction must be a composite process with a predefined sub-graph. The script of the Initialize event handler associated with the Business Transaction process stereotype contains all the functions needed to create the sub-graph. The following script fragment is from the Initialize event handler for a Business Transaction.
    ...
' Search for an existing requesting activity 
     symbol
 Dim ReqSym  
 Set ReqSym = Nothing  
 If Not ReqBizAct is Nothing Then
  If ReqBizAct.Symbols.Count > 0 Then
   Set ReqSym = ReqBizAct.Symbols.Item(0)
  End If
 End If
 
 ' Create a requesting activity if not found
 If ReqBizAct is Nothing Then
   Set ReqBizAct =
      BizTrans.Processes.CreateNew 
   ReqBizAct.Stereotype =
     "RequestingBusinessActivity"
   ReqBizAct.Name = "Request"
 End If
...

    If the event handler returns True on a stereotype, then the initialization script will be launched whenever the stereotype is assigned, either with a custom tool in the Toolbox, or from the object property sheet. If it returns True on a metaclass, then it will be launched when you create a new object from the Toolbox, from the Browser, in a list or in a property sheet. If it returns true on a model, then it will be launched when you assign a target (DBMS or object, process, or schema language) to the model at creation time, when you change the target of the model, or when you attach an extension to the model.

    Validate

    Validates changes to object properties or triggers cascade updates when you change tabs or click OK or Apply in an object property sheet. You can define an error message to appear when the condition is not satisfied by filling the message variable and setting the %Validate% variable to False.

    In this example, the event handler verifies that a comment is added to the definition of an object:
    Function %Validate%(obj, ByRef message)
 if obj.comment = "" then 
  %Validate% = False
  message = "Comment cannot be empty"
 else
  %Validate% = True
 end if
End Function

    CanLinkKind

    [link objects] Validates the kind and stereotype of the objects that can be linked together as the source and destination extremities when you create a link with a Toolbox tool or modify link ends in a property sheet. The sourceStereotype and destinationStereotype parameters are optional.

    In this example, the source of the extended link must be a start object:

    Function %CanLinkKind%(sourceKind, sourceStereotype, 
                       destinationKind, destinationStereotype)
 if sourceKind = cls_Start Then
 %CanLinkKind% = True
 end if
End Function

    OnModelOpen, OnModelSave, and OnModelClose

    [models] Run immediately after a model is opened, saved, or closed.

    OnLanguageChangeRequest, OnLanguageChanging, and OnLanguageChanged
    [models] Run immediately:
    • Before the model's DBMS or language definition file is changed. If the event handler returns false, then the language change is canceled.
    • After the language change, but before any transformations are applied to objects to make them conform with the new language definition.
    • After the model's DBMS or language definition file is changed and the object transformations are applied.

    OnNewFromTemplate

    [models] Runs immediately after a model or a project is created from a model or project template.

    BeforeDatabaseGenerate, AfterDatabaseGenerate, BeforeDatabaseReverseEngineer, and AfterDatabaseReverseEngineer

    [PDM models] Run immediately before or after generating or reverse-engineering a database (see Adding Scripts Before or After Generation and Reverse Engineering).

    GetEstimatedSize

    [PDM only] Runs when the Estimate Database Size mechanic is called (see Modifying the Estimate Database Size Mechanism).
  2. Select one or more event handlers and click OK to add them.
  3. Enter a name and comment to identify and document the event handler.
  4. Click the Event Handler Script tab and enter a script to define the event handler. You can access shared library functions and static attributes defined for reuse in the resource file from the Global Script tab (see Global Script (Profile)).


  5. Click Apply to save your changes.
Parent topic: Extension Files