Effector 6.4 developer manual

XML Reference 6.4

Effector Studio 6.4 summary

Effector Studio 6.4 manual

Effector WebAPI 6.4 manual

Effector 6.3 developer manual

XML reference 6.3

Effector Studio 6.3 summary

Effector Studio 6.3 manual

Effector 6.2 developer manual

XML reference 6.0

Effector Studio 3.2 manual

Effector Studio 3.2 summary

Business objects

General overview


As understood in computer science, an object is a unit endowed with characteristics and behaviors modelled on reality, which unit encompasses a collection of variables and sub-programs needed to represent relevant real-life objects or notions using a computer language.

In the realm of business, an object is a structure or storage, where data can be stored/displayed and exchanged among the components and users of the application. The data represent individual business units (such as invoices or other data records).

What does it mean? In practice, everything can be described as a closed unit containing coherent data and characteristic behavior patterns. Each of these units may form relationships and interdependencies with other units.

Let's take a look at some simple examples:

  • Passenger car: its basic properties are: brand, model, registration plate, color, engine capacity, etc.
  • Invoice : an invoice must contain a unique identifier, various data concerning the issuance and payment (date of issue, payment method, payment type, etc.), the data concerning the vendor and the buyer, as well as the items (products, services) being sold/purchased.

Modelling in the system

In the Effector system, a business object should be seen the same way. It is used when we would like to represent a data set consistent with reality, forming a unit.

How to represent the properties of the above mentioned passenger car?

For the properties we will need:

  • Registration plate : free text
  • Brand: A value to be selected from a list. For now, let the list contain the following only: Seat, Skoda, Mercedes Benz.
  • Model: This could be practically anything but now we can select a model from an existing list, just like in case of the brand. The list contains the following: Ibiza_, Cordoba, Fabia, Octavia, A-Class, C-Class .
  • We will also need an identifier, that will make a distinction between items having identical properties. Let the property of the identifier be an integer.

In keeping with the object-oriented approach, the Effector system allows for the inheritance/derivation of objects. This means that we have the ability to append the properties and behaviors of the individual business objects.

Let us add the group of motorcycles to the passenger cars now: We would like to store the following data on motorcycles: brand, model, registration plate and possible crash bar.

It is practical to use an OOP approach, and collected the common properties to the base class, which will be the vehicle in our case. Thus, we will get the following objects:


We keep the brand and model in case of both objects since their datasources are completely independent of each other.

The individual objects, just like in reality, are not independent and isolated units in the system, but are interrelated and form a graph. The nodes of the graph represent the objects, while the edges stand for the relationships.


These relationships – or in other words, logical associations - connecting the individual objects are easy to model. Through these associations, we can define the relation of connected objects. We can define the numerosity of the relationship or the row of events taking place if a unit is deleted from the system. Should the system delete other related units or leave ignore them? If an invoice is deleted from the system, it is sensible to have the rows of that invoice removed as well.

The relationships defined in the system correspond with relations formed between tables in a relational database.

Our example on vehicles can be appended as follows: Each passenger cars must be supplied with a tracking device; therefore, we should add a tracking object to our system and create associations that define which passenger car gets which tracking device. This relationship will be a 1-1 type relationship.


There are, however, types of data which do not necessarily need to be represented as objects, as they do not appear directly in the model system but play an auxiliary role. For example lists.


BusinessObjects are used in various ways. The figures below illustrate their location and relationships in the system.

Relationship with other components


Objects modelled on reality can be introduced into Effector, which can be done using the BusinessObject(BO) XML-schema. This XML-schema features a functionality similar to the DataDefinition: it can be used for the configuration of services facilitating data entry, inheritance and display.

Available features

  • Defining data
  • Setting inheritance
  • Handling connections/relationships
  • Defining virtual fields
  • Defining the individual states and transitory states of business processes
  • Verifying data
  • Setting and enforcing rights
  • Performing extra procedures
  • Automatically set task to done

Prerequisites, conventions

  • Database: There must be a data table representing the BusinessObject and it must have a
    • Deleted TINYINT field, which plays a role in the system’s transaction management.
    • The presence of the ObjectType VARHCAR(60) is needed when we you want to define a subtype to the business object, that is, we would like to use inheritance in the definition.
  • Conventions:
    • The name of the business objects must be unique.
    • The files must be saved to directory called BusinessObject.
    • The name of the file must follow one of the patterns below:
      • In case of a simple object: BusinessObject{0}.xml, where {0} is the name of the BusinessObject.
      • In case of a derived subject: BusinessObject{0}{1}.xml, where {0} is the value of ParentBusinessObject node of the BusinessObject, and {1} is the name of the BusinessObject. (For instance: BusinessObjectEventInfo.xml)


Available references:

  • Filter: The values of filters defined at the user interface.
  • Field: The fields of a business object.
  • Special: Special constants.
  • Session: Particular parameters of the given session.

Defining data

Data can be defined by properly defining the XML schema and the database table representing the business object. For this, a BusinessObject has to be created, and the /BusinessObject/DataTable, /BusinessObject/UniqueIDColumn and /BusinessObject/Fields/Field node must be configured properly. The database fields defined here will contain the data of the object. There is no need to use all the fields from the database table. It is a common mistake that the field set in the /BusinessObject/UniqueIDColumn node cannot be found in any of the /BusinessObject/Fields/Field nodes.

        <Field name="PeopleID" />
        <Field name="Name"/>
        <Field name="Jobtitle"/>

Elements used:

  • The /BusinessObject/DataTable node Contains the name of the database table associated with the object. In case of simple objects, it is a mandatory element, however, in case of derivations, in certain instances, it can be omitted. See: inheritance.
  • The unique identifier of the business object is represented by the /BusinessObject/UniqueIDColumn node. In case of simple objects, it is a mandatory element. In case of derivations, in certain instances, it can be omitted. See: inheritance.
  • Node SetDoneAutomatically is used to automatically set task to done.
  • The definition of the database fields is done using the Field node of the /BusinessObject/Fields collection: the name attribute contains the name of the column in the database.
  • Optionally, encryption type of field can be set. The system will save the data to databased based on this setting.

Later we will see that the Name attribute may define the name of such a column, that physically isn't present in the table of the business object, but it appears in a different table. This can be achieved by creating connections and defining virtual fields. In such cases, a 1-1 relationship is needed between the two tables, and the aliascolumn and foreignField attributes must also be defined. More on this in the following section.

Exercise: Define the passenger car business object in its basic state without inheritance.

A default value rule (RuleValueType) can also be specified for the fields, which gets evaluated and sets the values of the fields during this generation of the object.

<DefaultValue type="Constant" default="false" return="boolean">false</DefaultValue>

Important: The rule defined in the Editform overwrites this default value rule. Also, in the BusinessObjects there can be constant rules only!

For more information on default values see Rules.

Inheritance and defining relationships

As it has been mentioned above, inheritance among objects is allowed in the system. This can be done using the nodes of the BusinessObject node.

<!-- base BusinessObject (BusinessObjectProject.xml) -->

<!-- derived BusinessObject (BusinessObjectProjectSzamlaigazolas.xml) -->    

As shown in the example, we will need to define a base and a derived object. The derived object contains the reference, which is done by means of the ParentBusinessObject node pointing to the base object. This value is identical to the name of the base object. Between the two objects a 1-1 type relationship is formed, which means that if we create an object instance, then in the database exactly one data record will be generated in both tables. The relationship is created by the unique IDs: ProjectID and U_ProjectID.

If the derived object will not carry extra information - it has no associated data table and there are technical reasons for the inheritance - the setting of the the DataTable and the UniqueIDColumn is unnecessary.

Relationships are defined not only in case of inheritance but also for representing relationships discovered during modelling. The degree of relationships can be the same as that of the database relations. Their operation is similar to what is known from there. They play a significant role primarily in saving, deleting and occasionally in query processes.

  • 0-1: Such a connection is optional; the maximum number of related objects is 1. Typically used in objects where the value set of the given field is a complex set of data (object) and it comprises a variable set. We can represent it by defining the newly generated field as a foreign key, thus creating a reference to another object instance. For example: Invoice and approving person, where the need of an approving person depends on a value limit, therefore, it is optional.
  • 1-1: It is very similar to the previous one, however, here one and only one association must be defined. For example: inheritance.
  • 0-N: Again, an optional assignment, but here more than one object may be associated with one.
  • 1-N: The only difference between this and the previous one is this being mandatory. For example: Invoice and the partner on it. A partner can have more invoices.
  • N-M: This relationship represents the multiple-to-multiple association. Each N-M association can be broken down to two 0-1 types. It is employed in the system using a connection table.

Inheritance of value of field

Type of inheritance, possible values:

- `NearestSameBusinessObject`: Same type of business object which was created before the current one. If there is more than one, then it will be the last one.
- `NearestSelectedBusinessObject`: Same type of the selected step (with attributes businessObject and objectType) which was created before the current one. If there is more than one, then it will be the last one.
- `FurthestSameBusinessObject`: Same type of business object which was created before the current one. If there is more than one, then it will be the earliest one.
- `FurthestSelectedBusinessObject`: Same type of the selected step (with attributes businessObject and objectType) which was created before the current one. If there is more than one, then it will be the earliest one.

    <FieldInheritance name="Basedata">

At the field of the business object it can be referred which field value of which object have to be inherited. Optionally it also can have conditions.

<Field name="RequestId">
    <InheritedValue fieldInheritanceName="Basedata" fieldName="NameOfPreviousField"></InheritedValue>
    <Condition type="SQL" return="string" default="">...</Condition>

Defining relationships

Relationships can be defined by configuring the RoleConnection elements of the BusinessObject/RoleConnections collection of the object.

The following example includes all the elements available for defining relationships.

    <RoleConnection type="Relation" deletingmode="AllowIfEmpty" direction="Child" RoleName="ProjectDocument">

        <!-- mandatory section

        <!--    in case of 0/1-1/N relationships

        <!—to be used in case of N-M relationships
        <ConnectionTableID name="ProjectID">ProjectID</ConnectionTableID>
        <ConnectionTableID name="DocumentID">DocumentID</ConnectionTableID>


Nodes used:

  • The type attribute indicates the type of the connection definition. Its possible values:
    • Relation: It indicates a classic relational connection between two objects. Typically, the objects are not related through inheritance. The degree of the relationship may be any of the following or their inverses: 0-1, 1-1, 0-N, 1-N, N-M.
    • Descent: Used for representing a descendant relationship. In this case the ConnectionIDField is used only to specify the IDs participating in the connection, just like a foreign key definition. It is mandatory in the base object. The degree of the relationships defined in such a way is 1-1 due to inheritance.
  • direction It indicates the direction of the relationship, showing where the current and the connected objects are in the relationship. The relationship can be of Parent or Child direction.
    • Parent: The relationship points toward the Parent so the unique ID of the business object defined by the relationship appears as a foreign key in the object at hand.
    • Child: It is a relationship pointing toward the Child object. Here the business object’s own ID appears in the field of the connected object.
  • RoleName: The name of the relationship. Each relationship defined in a particular object must have a unique name.

  • deletingmode: It defines the behavior of the relationship in case of deletion.
    • AllowIfEmpty : The current object can be deleted only if there is no database record associated with the relationship.
    • Cascade : When deleting the object, the rows of the connected tables pointing to this business object will also be deleted.
  • Nodes affecting the numerosity/degree of the relationship are as follows: FromMinimum, ToMinimum, FromMaximum, ToMaximum. Possible values: 0 (not interpreted in case of ToMaximum), 1, N.

Defining 0/1-1/N relationships: In this case we need to do nothing more than defining the degree of the relationship, the business object on the other end and the unique ID thereof by setting the BusinessObject and the ConnectionIDField nodes. The setting of the BusinessObject is done by entering the name of the file without extension.

    <RoleConnection direction="Child" RoleName="Users">

Inheritance: A special 1-1 relationship. The type of the relationship is Descent and the ConnectionIDField does not need to be specified as it can be clearly determined from the connected objects. The relationship will be brought about by the unique ID on both sides.

In case of N-M connections, we have to set the "From/To" nodes responsible for the numerosity, as well as the connected business object using the BusinessObject, and we also need to set the data of the connection table carrying out the relation conversion. We can do this in the ConnectionTableName and the ConnectionTableID nodes.

    <RoleConnection type="Relation" direction="Parent" RoleName="ProjectPeople">
        <ConnectionTableID name="ProjectID">ProjectID</ConnectionTableID>
        <ConnectionTableID name="PeopleID">PeopleID</ConnectionTableID>
        <ConnectionTableID name="ProjectRoleID">ProjectRoleID</ConnectionTableID>

The name of the connection table is defined by the ConnectionTableName, while the ConnectionTableID-s specify the columns and fields of the table which will connect the individual business objects to the connection table. The data structure of the example above is illustrated by the figure below:


Defining virtual fields

Data not associated with particular business objects, but represent the characteristics of other connected objects, yet are visible and editable on the user interface are called virtual fields. When using the given object, the system reaches through the defined relation and maintains the fields in the connected object as well.

Nodes participating in the configuration of the virtual fields:

<RoleConnection type="Relation" deletingmode="Cascade" direction="Child" RoleName="EventPeople">
    <ConnectionTableID name="EventID">EventID</ConnectionTableID>
    <ConnectionTableID name="PeopleID">Responsible</ConnectionTableID>
        <AliasValue name="EventRoleID" type="SQL" default="1" return="int">1</AliasValue>

<Field name="Owner" aliascolumn="PeopleID" aliasrolename="EventPeople">
    <DefaultValue type="Simple" return="int">`[##Session.UserID##]`</DefaultValue>

Connection: A proper connection descriptor must be supplemented by an AliasValues collection. The elements of the collection, the AliasValue nodes essentially describe rule definitions, that define how the field specified in the name attribute be filled. For more information see Rules.

Field definition: The aliasrolename defines which relationship be used to fill or modify the given field. The aliascolumn attribute is responsible for the definition of the exact data field, whether it is a connection table or an object.

The example allows for setting the owner associated with the event. Among the participants (EventPeople), there can be exactly one record where the role (EventRoleID) is “Owner”. The role (a mendatory field) in this case is contained by the connection table responsible for the N-M relationship; therefore, when we associate a new person with the event, this field should also be filled. In an average case, we could enter this piece of data recorded for the association in a separate maintenance window, but since only one record is allowed, we can use the virtual fields to accomplish this task. This is a simpler way to define the owner.

NOTE: This is an outdated method, this relationship can be set in a simpler/more clear way with ForeignFields

ForeignFields We have the option to reference and save data to a field of an external (foreign) table connected via a 1-1 relationship defined in the DataTable setting. Such a field is called foreign field.


    <ForeignField name="EventPeople">
            <Mapping> <!—no. 1 roleid is the owner -->
            <Mapping> <!-- az EventPeople.EventID = Event.EventID -->
            <Mapping> <!—the value of the EventPeople.PeopleID field can be found under Owner -->
  • ForeignField: This node gathers the foreign field definition settings. Within a definition, several foreign fields can be defined (if placed in the same table). The name attribute should include the name of the definition, which can be referenced in the Field setting.
  • TableName: The name of the table connected through a 1-1 relationship with the original table.
  • TableField: The name of the field in the table set in the TableName setting.
  • BusinessObjectField: The name of the column set in the Fields section of the BusinessObject. If setting a fixed value is needed to establish the 1-1 relationship, then that value should be specified in this setting. From the Value and the BusinessObjectField settings, only one should be specified. In the example, a table named EventPeople is used to store the Owner for the Event table. Since data can be recorded with a 1-N relationship in this table, the data of the Owner is identified by using the value 1in the EventRoleID column. The relationship is defined by the EventID.

Defining the individual states and transitory states of business processes

While modelling and configuring the business processes, we can add here, at the business objects the logic forwarding the given process from one state to the next. These settings can be done using Triggers. To configure triggers, we need to think backwards.

What does it mean? Why do we have to think backwards?

It is necessary simply because in a system we do not specify the outcome of an action, rather, the other way around, what actions may result in said outcome. It gives us greater freedom in designing and organizing our processes with a slighter chance of making definition mistakes. By the time the process engine is started, all the possible combinations of the process steps are available, complete with the referenced objects.

So, looking ahead, if event “A” must be followed by event “B”, we need to insert a rule in the triggers of event “B” that prompts the generation of object “B”. In our case it will be an event triggered by object “A”. (A change in a property of object “A”).

Being familiar with configuration processes facilitates a deeper understanding of more complex triggers. To learn more about this topic, please read Workflows. As the two chapters are closely related, it is advised to carry on with said chapter and then return to the subject of configuration.

Configuring triggers

Aa a result of the operation of the process engine (that is based on the process descriptors) in case of objects that do not take part in processes (not part of any process definitions), the triggers will not be evaluated.

The triggers can be set using the Trigger element of the Triggers collection. These triggers control the process state transitions, define the action prompted by an event in the business object, regulate whether a new object be created, or a piece of data be refreshed. The triggers also define the business objects the changes of which prompt the generation of the given business object. For instance, if an event is set to ready, that can trigger the generation of a new process step or the configuration of a different process step, or the process engine can run an arbitrary SQL statement.

<Trigger sourceBusinessObject="Event" sourceObjectType="Iktatas02" action="Create" event="Done">
    <Condition type="Simple" return="boolean" default="false"><![CDATA[`[##Field.FolyamatVezerlo##]`==30]]></Condition>

The Trigger nodes have numerous attributes, some of which are independent, while others contain interdependent logical associations.

Independent attributes:

  • The sourceBusinessObject and the sourceObjectType attributes together define the business object that activates the trigger. This object may be the Project/Event object or one of its descendants, the type of the object is to be set in the sourceBusinessObject attribute, while the type of the derived object is to be defined in the sourceObjectType attribute. Sticking with the example above, the trigger of the transition will be the BusinssObjectEventIktatas02 object.
  • action: it defines the type of the triggered event, that is, what to be done when this trigger gets activated. The value of the type may be:
    • Create: It creates a new business object of the type where the trigger is defined.
    • Modify: The object will be modified where the trigger is defined. During modification special variables can be used. But the given expression can be a constant value only.
    • RunSQL: The system runs an arbitrary SQL statement. The statement may contain special valiables.
  • isAttachedWorkflow: It shows whether an attached workflow is specified.
  • attachedWFTemplate: It contains the reference of the attached workflow, if there is one.
  • event: It is a node applicable to all triggers, it contains the event that sets off the activation of the trigger. Its value can be:
    • Done: The trigger gets activated once an action is reported done.
    • Created: The trigger is activated once an object is created. It is the TriggerEvent used for the creation of the first step of the process. For instance, once the creation of the business object (“Project”) launching the workflow is created, the first step of the workflow (Event object) is to be created automatically.

Available sub-nodes:

  • Condition: It defines a condition that will be evaluated once the trigger is activated. It executes the operation specified in the action setting depending upon the result.
  • SQL: It is the SQL statement to be run in case of the RunSQL trigger type.
  • ForeignKey: In case of Modify or RunSQL trigger types, this node specifies the name of the field that connects the business object that being created with the other object.
  • value

It may contain several SetValue nodes. In this case, all modifications will be carried out. The fieldName attribute of the SetValue node contains the name of the field to be modified. The new value will be the content of the node, which cannot be a statement.

It is possible to create multiple, parallel instances of the same type of object. For example if there is need for multiple approvals for the same task. Moreover it is possible to assign roles to task not only exact assignees. It will be dynamically evaluated based on the roles (and persons in roles) assigned to the specific run of the process. The next step will be created when all parallel branches have been run.

Verifying data

Data validation is carried out before saving. Setting such validations is possible using the /BusinessObject/Methods collection. This collection is multifunctional, business logics can also be run with its help.

To do the validation, a special element, the OnValidate node is used, which may contain a rule. For further information on rules, please read Rules.

Performing extra procedures

Using the /BusinessObject/Methods collection, we can react to various events of the business object and run business logics using SQL or a module. The events are as follows:

  • BeforeSave: It runs before saving the business object.
  • AfterSave: It can be used directly after saving.
  • AfterDelete It may contain a logic to be run when the object is deleted.
  • AfterCreate: This runs some kind of business logic after a business object is created.
  • `AfterLoad': This runs some kind of business logic after a business object is loaded.

Each node may contain the following:

  • Module: The Module discussed in the section on action buttons. It is the DLL implementing the business logic.
  • [##LocalProgramPath##]\orn_ReleaseTest.dll
  • The value of the Module node is the name of the .dll file with its path. Effector replaces the string [##LocalProgramPath##] included in the path with the bin folder of the actual website, so the translated .dll file can be copied directly to the Effector program files.
  • The name of the class realizing the desired unique function should be specified in the className attribute.
  • With the action attribute, we can select the action we want to be executed within the function (it is not a systemic setting, the developers have to work out and handle them).

Since the triggers defined in the business object do not run in case of ad-hoc events, the best place for an SQL execution after saving and okaying is the Methods/AfterSave node.

This example has been taken from a document business object. Its task is to insert a row in the DocumentConnection table after saving the document business object, if a new document has been saved.

    IF '[##Filter.JumpType##]' = 'New' BEGIN
        INSERT INTO DocumentConnection (BoType, BoId, DocumentID, Deleted, Created, CreatedByID)
        SELECT 'Event', '[##Field.EventID##]', '[##Field.U_DocumentID##]', 0, GETDATE(), '[##Session.UserID##]'

Setting and enforcing rights

Effector is capable of managing rights on the level of BusinessObject. Basically, access rights can be configured to the individual business objects. With the help of the /BusinessObject/Rights collection, we can define user rights by specifying rules therein. These rules are of RuleValueType, so they can be used the usual way. They get evaluated when an object is being handled. For more on rules, see Rules. The following rules are available for setting rights:

  • Create: Its evaluation indicates whether the business object can be generated with the given conditions.
  • Delete: It shows whether deletion is allowed on the object at hand.
  • Modify: It indicates whether the modification of the object is allowed.
  • View: It indicates whether the display of the object data is allowed.

In the example below the user right validation is executed centrally via a stored procedure called osp_wrk_ValidateUserRights. Its stored parameters in order are: ID of the signed-in user, name of the BusinessObject, sub-type of the BusinessObject, name of the right.


    <Create type="SQL" return="boolean" default="false">
        execute osp_wrk_ValidateUserRights '[##Session.UserID##]', 'Document', 'RoleDetails', 'Create'
    <View type="SQL" return="boolean" default="false">
        execute osp_wrk_ValidateUserRights '[##Session.UserID##]', 'Document', 'RoleDetails', 'View'
    <Modify type="SQL" return="boolean" default="false">
        execute osp_wrk_ValidateUserRights '[##Session.UserID##]', 'Document', 'RoleDetails', 'Modify'
    <Delete type="SQL" return="boolean" default="false">
        execute osp_wrk_ValidateUserRights '[##Session.UserID##]', 'Document', 'RoleDetails', 'Delete'

  • Last update: 41 weeks 2 days ago
  • Effector