Daniel Becker Bighelini

SPEL API: Domain Server - Attached Events

Blog Post created by Daniel Becker Bighelini on Jun 13, 2016

Chapter 5

Domain Server - Attached Events

 

Table of Contents

 

Attached Events - Overview                                                                

Major Object Classes:                                                                         

ENSEMBLE - macro                                                                                                                                

ENSEMBLE - macro_type                                                                         

ENSEMBLE - evt                                                                                         

Attributes:                                                                                                                                                      

Methods on the Dob                                                                                                                                     

Methods on the Factory:                                                                                                                             

ENSEMBLE - atevt                                                                                     

Methods on the Dob:                                                                                                                                   

Methods on the Factory:                                                                                                                             

 

 
 

Attached Events - Overview

 

The domsrvr has some built in ensembles to handle attached events. This document describes the salient features about these ensembles.  It also attempts to serve as a stake in the groud re how to document the objects.

 

Purpose:

Consider a specific call request which for some reason we want to check after 3 days to see if it is still open.  If it is open we want to do some procedure such as mail the assignee.  We have chosen to implement this kind of functionality by providing the ability to define an event and to attach that event to any dob in the system.  The event has a  'when to fire' associated with it.  When the time comes, the object that is that event will be instantiated by the system, will checkout any items needed to be checked out (for example the dob the event is attached to), and will execute the event.  The event has built in rules to first check a condition, and then to execute a series of actions for either a true or false result from the

 

Files:

   bopevt.maj - majic files

    bopevt.spl - spel files

 
 

Major Object Classes:

macro             Holds code fragments that are either  a condition to test or action to perform on the dob

macro_type     Private class to define the types of code fragments  (condition or action)

evt                   An event template.  Defines the interesting stuff about an event such as what the condition is, what actions to fire, if the attached event should repeat, etc.

atevt                The attached event.  An instance of this is what wakes up in three days and notifies if the call request is still open.

wrkshft            A way to define when the 'clock is running' on events.

ENSEMBLE - macro

A holder for a code fragment.  It is best not to make these except in the GUI.

Attributes:

ob_type SREL            the type of the object the macro is to be used for.  This Srel is pointing to a special factory.  To enable a new entry in this factory define a DISPLAY_NAME for the type of object you want to add.

type SREL                  the type of macro.  This defines the arguments that will be passed to the macro.

lock_object INTEGER                         a flag to say if the dob this macro is executing on should be locked prior to calling the macro.  Typically this should be set to yes.

sym STRING              another way to define the macro.  Don't modify symbol on a running system.

ENSEMBLE - macro_type

Don't mess with this.

ENSEMBLE - evt

This defines info about an event.  The atevt has the evt as an SREL so it can find out what script to execute, etc. This implies that if the evt changes between the time the atevt is created and it fires, you may not get what you expect to get.

It is not recommended to attempt to make these by hand.  Use the GUI.

Attributes:

sym STRING              Used to uniquely identify the event.  We can use this string to find / the evt.  Don't change these in a production        system.

obj_type SREL           As in macro.  Defines the type of object we are used for.

condition SREL macro - What macro should we use for the condition.  We will allow you to choose only those that match the object type.

work_shift SREL wrkshft - Defines the work hours to figure out the fire time against.

delay_time DURATION - The default time to wait before you fire an atevt created from this template.  This time may be overidden at the time of the atevt creation depending on the user_settime flag.

module_time DURATION  A way to round times.  If you want triggers to fire on a time boundry (say once an hour) you set the modulo_time to one hour.

user_settime INTEGER                        if 0, the delay_time can't be modified on the attached event.

on_done_flag INTEGER Says what the attached event should do when it has fired.  0 = delete, 1 = stay around for history, 2 = recycle        and fire again later.

user_smag STRING    stuff that can be defined that the actions in the attached event can choose to use in deciding what to do.

 
 

Methods on the Dob

 

make_attached_event( object group_leader, string attach_to_persid)

Create an attached event for us.  The new attached event will be made using the passed in group leader, and it will be attached to the persid passed in.  We return the new event so you can make further modifications.

Arguments:

object group_leader,

string attach_to_persid

Error Reply:

      Misc problem

          -1                                                 - string error_text

Success Reply:

      Object_Ref                                     atevt_object

Methods on the Factory:

 

make_attached_event( Object_Ref | nil group_leader,

         string attach_to_persid, string evt_symbol,

         duration | nil vberide-duration, string | nil group_name)

The interface we expect you to really use.  This creates the attached event and sets the commonly changed paramagers in it for you.

If no group leader is provided, and we have no errors, we will     check in the atevt for you.  If you provide a group leader, we will use it but not do any check in.

If we are not allowed to change the duration, we just ignore what you pass in.

The group_name is used to make it easier to delete selected events later. For example if you decide to use the group_name  'xyz_escalation' for a number of atevt's, you can later delete all 'xyz_escalation' type events on a specific dob, leaving any other        events alone.

Arguments

Object_Ref | nil group_leader,             Group leader to use for new.

string attach_to_persid,                        Who to attache the atevt to

string evt_symbol,                                The template name to use

duration | nil overide_duration  change duration to this

string | nil  group_name

Error Reply:

misc error                                                 -1  - String errro_text

Success Reply:  Object_Ref atevt        // The new attached event

string attach_to_persid)                                ???

Create an attached event for us.  The new attached event will be    made using the passed in group leader, and it will be attached to the persid passed in. We return the new event so you can make further modifications.

Arguments:

      object group_leader,

 
 

ENSEMBLE - atevt

 

The attached event.  This defines an object that will be animated at some time in the future, will test the condition in it's template, if it passes, it will execute the appropriate actions defined in the template.

 

Do NOT attempt to make one of these yourself.  Use the methods in evt.

Do NOT attempt to simply delete this.  Appropriate clean up's will not happen.  (This is a bug and may be fixed in future releases)

 

The user_smag string is un-obvious.  When the action is executing, it has available to it the atevt, and therefore the smag string.  You can stuff into the smag string information the actions script can use to perform it's funcitons.

Attributes:

obj_id STRING           Who we are attached to.

wait_time DURATION                        How long to wait befor firing.  If the  template does not allow changes, this will fail.  Setting this value also sets the 'fire-time' attribute.

fire_time DATE - When to fire.  Allows you to set this explicitely.  As a side effect, clears the wait_time.

user_smag STRING    A way to add some strings that can be interpreted by the actions at run time.

user_smag STRING The only thing you should attem

 
 

Methods on the Dob:

 

cancel_me(void)

Do the appropriate cancel operation.  This cleares the animator so the event will not fire in the future, and make delete the object or just change it's status.  The object must be checked out before this is called.

Error Reply:

      Misc error as passed from underlying calls

Success Reply

      Varies - error code set to 0

    Methods on the Factory:

 

nuke_by_id( string attach_to_id, string | nil group_name)

Delete the atevt's for the attach_to_id.  If you pass in a group  name it will not delete all, only those that are ' LIKE' the  group_name.  This method gets a group leader for it's own use and does the checkin before you return.

 

Arguements:

      string attach_to_id       The persistant id to delete from

      string | nil group_name The group name to nuke for.

Error Reply:

      Misc errors

          ??                              - string error text

Success Reply:

      (void)                               Just replies with no data

Outcomes