Using Custom Events
This section explains, using an example, how to use Custom Events within EVA Netmodeler. Also refer to the Events section for more information on the events API.
Users will from time to time have a need to execute event-driven code that is not specifically covered by the EVA Netmodeler Event API. For this reason, the EVA Netmodeler Custom Event feature was developed.
The custom event feature works in very much the same manner as the event API, except that a user-written custom code snippet is executed instead of a predefined API method.
This section covers the following topics:
Introduction
The illustration below shows a simplified model of the EVA Netmodeler Event Architecture. Basically, events can occur either as a result of user activity (Creating, Editing, Linking or Deleting a knowledge item), or as a result
of a time trigger.
As soon as an event occurs, EVA Netmodeler determines whether there is an Event Subscription linked to that Type/Event combination. If EVA Netmodeler finds a valid subscription, it executes the Event Actions attached to the
subscription in sequential order (an event may have several actions attached to it).
Each event action specifies an API method to be executed, together with a list of keywords appropriate to the specific outcome desired.
In the case of Custom Events, the user also supplies a Smalltalk Code snippet that is executed as if it was an event API.
The remainder of this section is a step by step example that will guide you through the process of setting up a Custom Event in EVA Netmodeler.
Workflow History Example
By linking to the EVA Netmodeler Portal site, you will see that we manage all Archi issues within the portal using the "Archi Issue" knowledge type. The status of an issue is indicated by the "Archi Issue Status" knowledge type.
As an example, if we look at the "Submitted" issues, you will see a list of all EVA Netmodeler Issues currently related to the "Submitted" instance of type EVA Netmodeler Issue Status".
When we change the status of an issue from Submitted to Moderated, we are in essence saying that the Issue has
been verified and prioritized and is available for development. This is done by relating the issue to the Moderated instance of type "Archi Issue Status" and breaking the relationship to the Submitted instance of type "Archi Issue Status".
For management purposes, however, we would like to be able to tell how long an Issue has been in a particular status,
which statuses it has moved through and so on. In order to do this, we obviously need to keep some sort of history that can be used for this analysis.
If we could cause EVA Netmodeler to create a history item every time an instance of type "Archi Issue" is linked to an
instance of "Archi Issue Status" and indicate when this activity occurred by using some sort of time stamp, we have essentially solved our problem.
Having come this far in our thinking, it becomes clear that we have to use the Link event on knowledge type "Archi Issue"
to fire off an additional activity. The functionality of the desired activity can be broken up in the following steps:
- Create a new instance of type "LinkHistory" (this is the new knowledge type we will create and will be used to store all our history instances.
- Name the new history instance with a name that indicates the timestamp of the event, as well as some description of the event that took place.
- Link this new history item to the "Archi Issue" item that caused the event in the first place via the "history" relationship.
By looking at the above requirement, it becomes clear that none of the current API methods will satisfy it exactly, so we decide to set up a Custom Event that will satisfy the requirement.
Step 1 - Create the History Type and Relationship
Firstly, we will need a new knowledge type to store our history instances, for the sake of simplicity, we will not add any properties to the type.
In the Type Maintenance Browser, create a new relationship called "history" with an Inverse name of "history item of",
then create a new type called "LinkHistory" and, within this type, create a legal relationship of "history item of an "Archi Issue".
When you have completed this step, your new "Linkhistory" type should look as follows:
Step 2 - Create the Event Action
Now that we have the type that will store our history, and we have established a relationship between it and our "Archi Issue" type, we need to create the event action that will create our history items.
On the Item Browser, create a new instance of type "EventAction", and complete the property values as follows:
1. Instance Name: Type the following name
2. Perform This Action (Action Type) : Select this value from the drop down
3. Event Code: (Type the following Smalltalk code snippet)
[|aBTC aTargetType aNewNode aNewDescr aTargetRel|
(aTargetNode nodeType description = 'Archi Issue Status')
ifTrue: [
aTargetRel := A2RelTypeHome singleton findByDescr: 'history'.
aTargetType := A2NodeTypeHome singleton findByDescr: 'LinkHistory'.
aBTC := Archie2BusinessTransactionClass new.
aNewDescr := ((Archie2TimeStamp now printString), ' moved to: ', aTargetNode description).
aNewNode := (aBTC createNewTargetNodeAndReturn: aNewDescr nodeType: aTargetType
relType: aTargetRel sourceNode: aSourceNode).
].
] value
The event code is quite straightforward and essentially does the following:
IF the target type of the link that has just occurred and that caused this event is of type "Archi Issue Status"
THEN Find a relationship type with the name "history"
Find an item type with the name "LinkHistory"
Create and Link to the Source Item of the link that has just occurred
END IF
Once you have completed the creation of your new Event Action instance, it should look like the illustration below:
Step 3 - Create the Event Subscription
By creating the event action, we have described what we want EVA Netmodeler to do every time this event takes place. Now we have to create the event subscription to link this action to the actual event
In the item browser, go to "EventSubscription" and create a new item with the name "Create History", complete the property values as follows:
1`. Subscribe to event type: Select the following from the dropdown list:
2. On Node Type, select "Archi Issue"
Finally, link your new event action instance to this event subscription. This will effectively tell EVA Netmodeler to perform your event action every time a link event occurs on an instance of type "Archi Issue".
The illustration below show what your completed Event Subscription should look like:
Step 4 – Testing your event
We are now ready to test our event. This is done simply by linking any instance of "Archi Issue" to an instance of "Archi Issue Status". Once this has been done, you will notice that EVA Netmodeler
has automatically created a new instance of "LinkHistory" and linked it to the "Archi Issue" instance that was changed.
Finally, try to create a new instance of "Archi Issue", you will notice that EVA Netmodeler automatically creates a history item.
Why does this happen, since we haven't subscribed to the create event?
It is because the default instance of "Archi Issue" has a relationship to the "0. Moderated" instance of "Archi Issue
Status", which means that whenever a new instance of "Archi Issue" is created, if is automatically linked to the default relationships, thereby triggering the link event.
The illustration below shows an "Archi Issue" that has been moved through several statuses. From this illustration the usefulness of the history can be clearly seen:
Conclusion
By following the example given in this section, you should be in a position to create your own Custom Events in EVA Netmodeler.
|
