Example of the agent definition language

The following example shows a complete agent definition, based on the ADOxx BPMS Application Library. The example contains a single agent which calculates four different results during the simulation.

If you wish (and if you work with the ADOxx BPMS Application Library), you can just copy this agent definition into the attribute "Agent definition". In this way, you will have your first predefined agent which you can then employ in the ADOxx Modelling Toolkit.

After the agent definition, every expression used in the example is explained. The reasons why certain expressions have not been used are also explained.

AGENT "ExampleAgent" volume-analysis lock-select-results hide-extremum auto-buildsum hide-buildsum infotext: "This agent is an ExampleAgent." modeltype-1: "businessprocessmodel" FORMULA name: "Totalcosts" expression: " \"PersonnelCosts\" + \"ResourceCosts\" + \"ProcessCosts\" " lock-expression OBSERVED "PersonnelCosts" OBSERVED "ResourceCosts" OBSERVED "ProcessCosts" WWECOST name: "PersonnelCosts" lock-name resultscope: process hide-history-mem hide-history-disk class: "Performer" lock-class attribute: "Hourly wages" lock-attribute WWECOST name: "ResourceCosts" lock-name resultscope: process hide-history-mem hide-history-disk class: "Resource" lock-class attribute: "Hourly wages" lock-attribute AVGSUM name: "ProcessCosts" lock-name resultscope: process hide-history-mem hide-history-disk class: "Activity" lock-class attribute: "Costs" attribute-type: numeric lock-attribute

In the following all the expressions used in the example above are explained in the order of their occurrence:

AGENT "ExampleAgent" An agent definition is always introduced by the expression AGENT. This expression must therefore be in the first position. In addition, a name must be assigned to the agent type defined. The name can be chosen according to your preferences. In the example above the name chosen is "ExampleAgent".

volume-analysis This expression specifies that this agent is only active during the simulation algorithm "Capacity Analysis".

As defined below in the agent definition, this agent contains among others the result function "Costs of execution" (see expression WWECOST). This result can only be calculated during a capacity analysis. If the agent is employed in any other simulation algorithm, it will not be able to calculate this result function.

The result of the result function "Special formula" (see expression FORMULA) is based on the "Costs of execution" and thus could also not be calculated within a path or workload simulation. Only the result function "Sum over attribute" (see expression AVGSUM) could be calculated in this case.

The agent's area of application is restricted to the capacity analysis by the expression volume-analysis. This prevents the agent from being employed in simulation algorithms where its functionality could not be fully used.

lock-select-results This expression specifies that the ADOxx user can neither remove result functions from nor add result functions to the agent.

In the case of predefined agents it is in general sensible to specify this expression, since the predefined agent usually contains all the result functions desired. If an ADOxx user wants an agent with other result functions, he should create a new agent and configure it according to his wishes rather than carry out extensive changes to an existing predefined agent.

However, in the example above the expression lock-select-results has been specified for a further reason. This agent contains the result function "Special formula" (see expression FORMULA). This is based on other result functions of this agent. If ADOxx users were allowed to remove result functions from this agent, they might accidentally remove result functions which are needed to calculate the "Special formula". To prevent this from happening, the expression lock-select-results is specified.

hide-extremum In addition to an agent's results, the minimum and maximum values of the results can also be displayed, if desired. The expression hide-extremum specifies that the control elements which control the display of the minimum and maximum values are hidden from the ADOxx user.

The expression auto-showextremum causes the extreme values to be shown by default. In our example, extreme values are - by default - not shown.

auto-buildsum This expression specifies that for every result of this agent the total sum is also shown by default. However, only a default value is specified here which can be changed by the ADOxx user at any time. To prevent the ADOxx user from changing the default settings the following expression can be specified:

hide-buildsum This expression causes the control elements controlling the display of the sums to be hidden from the ADOxx user. So the ADOxx user no longer has the possibility to change the default value specified above.

infotext: "This agent is an ExampleAgent." An information text is specified here. We recommend that you enter a short but meaningful information text for each predefined agent as this helps the ADOxx user to select the agent he desires - especially useful when there are many predefined agents.

modeltype-1: "Businessprocessmodel" This expression ensure that this type of agent may only be created in dynamic models.

The specification of model type is not necessarily required in this example. The agent defined contains the result function "Sum over attribute (see below; expression "AVGSum"), which can only be assigned to agents in dynamic models. This result function already restricts this agent to dynamic models. Nevertheless to give a complete picture, this expression has been specified in this example.

FORMULA This expression assigns the "Special formula" result function to the agent. All the following expressions (up to the definition of the next result function) refer to this result function.

name: "TotalCosts" This expression names the "Special formula" result function. The name can be freely chosen but must be unique within the agent.

expression: " \"PersonnelCosts\" + \"ResourceCosts\" + \"ProcessCosts\" " This expression defines the calculation formula for the result. Since the calculation formula itself has to contain inverted commas, all other inverted commas inside the calculation formula are masked, i.e. instead of " \" has to be written.

Hint

The elements "PersonnelCosts", "ResourceCosts" and "ProcessCosts" are the names of the other result functions in this agent (see below).

lock-expression This expression prevents the ADOxx user from changing the calculation formula on his own. However, he may still view the calculation formula.

Hint

The expression hide-expression would in addition hide the calculation formula from the ADOxx user. However in order to understand a certain result it can be useful when the corresponding calculation formula is displayed.

When the ADOxx user may not change the calculation formula, it might also be important, to prevent him from removing result functions from this agent. Otherwise, the calculation formula could refer to results which this agent cannot calculate any longer. The ADOxx user would have no possibility to adjust the calculation formula accordingly. For this reason, the expression lock-select-results (see above) has been included in this agent's definition.

OBSERVED "PersonnelCosts"OBSERVED "ResourceCosts"OBSERVED "ProcessCosts" These expressions specify all those result functions on which the "Special formula" is based. It is in any case required that the names of all result types which occur in the calculation formula are specified.

WWECOST This expression assigns the result function "Costs of execution" to the agent. All the following expressions (up to the definition of the next result function) refer to this result function.

name: "PersonnelCosts" The name of this result. The name can be chosen freely, but must be unique within the agent.

In this example the result function "Special formula" (see expression FORMULA) refers to the name of this result. If the result's name is changed, the definition of the formula must be adjusted accordingly.

lock-name This expression specifies that the ADOxx user may not change the result name of this result function.

This is necessary because the special formula result function (see expression FORMULA) refers to the name of this result function ("PersonnelCosts"). If the ADOxx user changed the name of the result, the calculation formula of the "Formula" would have to be adjusted accordingly. In the definition of the "Formula", however, it has been specified that the ADOxx user may not change the calculation formula (see above; expression lock-expression). Thus, he cannot adjust this formula. Therefore, it is necessary to specify that he also cannot change the current name of the result ("PersonnelCosts").

resultscope: process This expression specifies that the result function calculates a single number by default as result with regard to the whole process evaluated.

Hint

Since neither the expression lock-resultscope nor the expression hide-resultscope were specified, the ADOxx user may, if necessary, change the degree of detail of the result calculation.

hide-history-memhide-history-disk These expressions cause all control elements in the configuration window of the result function to be hidden. Therefore the ADOxx user has no access to these elements. Since the default setting is that the development of results is not stored (and nothing to the contrary has been specified in this ExampleAgent definition), the development of results for this specific result will not be recorded.

class: "Performer" This expression causes the execution costs to be calculated with regard to the class "Performer". This means, the personnel costs will be calculated.

lock-class This expression prevents the ADOxx user from changing the class selection. Since the expression lock-class but not the expression hide-class has been specified, the ADOxx user still has the possibility to see for which class the execution costs are being calculated.

attribute: "Hourly wages" This expression specifies the attribute which contains the hourly wages based on which the execution costs are to be calculated. The attribute "Hourly wages" is defined in the class "Performer" in the ADOxx BPMS Application Library.

lock-attribute This expression prevents the ADOxx user from changing the attribute selected. Since the expression lock-attribute but not hide-attribute has been specified, the ADOxx user may still see on which attribute the calculation is based.

WWECOST This expression assigns the result function "Costs of execution" a second time to the agent. This time, however, the result function is configured differently so that this time the "ResourceCosts" can be calculated (see below).

Hint

All the following expressions (up to the definition of the next result function) refer to this result function.

name: "ResourceCosts" Definition of a further result name.

lock-name The explanations made under "PersonnelCosts" (see above) also apply here.

resultscope: process The explanations made under "PersonnelCosts" (see above) also apply here.

hide-history-memhide-history-disk The explanations made under "PersonnelCosts" (see above) also apply here.

class: "Resource" This expression determines that the execution costs are calculated with regard to the class "Resource" . Thus it is the resource costs which are calculated here (which is why the result has been named that way).

lock-class The explanations made under "PersonnelCosts" (see above) also apply here.

attribute: "Hourly wages" This expression specifies the attribute containing the hourly wages based on which the resource costs are calculated. The attribute "Hourly wages" is defined in the class "Resource" of the ADOxx BPMS Application Library.

lock-attribute The explanations made under "PersonnelCosts" (see above) also apply here.

AVGSUM This expression assigns the result function "Sum over Attributes" to the agent. All the following expressions now refer to this result function.

name: "ProcessCosts" The explanations made under "PersonnelCosts" (see above) also apply here.

lock-name The explanations made under "PersonnelCosts" (see above) also apply here.

resultscope: process The explanations made under "PersonnelCosts" (see above) also apply here.

hide-history-memhide-history-disk The explanations made under "PersonnelCosts" (see above) also apply here.

class: "Activity This expression defines in which class the attribute to be summed up is defined. It must be a class that can be instantiated and which has been derived from the meta-model activity class. In the ADOxx BPMS Application Library this is the class "Activity".

lock-class This expression prevents the ADOxx user from changing the class selection.

attribute: "Costs" attribute-type: numeric This expression specifies that the expected value of the sum of the attribute "Costs" is to be calculated. Since this attribute is numerical, the expression numeric must be specified for "attribute-type:".

lock-attribute This expression prevents the ADOxx user from changing the attribute selection.