Skip to end of metadata
Go to start of metadata

With the iteraplan Plugin API scripts (so called "Reactions") might be created to manipulate the data in iteraplan. 

Example use cases

Setting of attribute default values, distributing costs, working with seals for elements, various validations of the data model, data synchronisation with other systems, input validation, numerical calculations, hierarchy editing, automatically relating elements, creating individual workflows, sending HTTP requests, e-mail notifications, querying information about users, LDAP queries ... and much more!

Scope

  • Metamodel: Query and Edit Attributes
  • Data model: Query, create and delete elements and relations; Information about individual types
  • Elements and relations: Query, create and delete attribute values
  • Users: Query, create and modify
  • Historization: Queries both for element and type
  • HTTP requests with parameters
  • Send e-mails
  • LDAP Queries

See Plugin API Usage for details.

Things to consider

  • There is no customer support for user created Reactions. Reactions are written by the customer. The syntax has to be correct JavaScript. Moreover, the user has to ensure that data are consistent and correct, e.g. all mandatory properties are set in a newly created object.
  • Via Reactions it is possible to access all data in iteraplan. A plugin containing a bug might inadvertently modify all data. You might want to test your plugins within a test installation of iteraplan.
  • Depending on the concrete implementation, Reactions (especially subscription scripts) might have an negative impact on the performance of every write operation in iteraplan. 
  • Changes made by the plugins themselves do not trigger any further change events. 
  • Changes to the iteraplan metamodel (assigning attributes to building blocks, changing literals of an enumeration attribute etc.) do not trigger any Reactions.
  • The Plugin API has supervisor permissions. Hence potential restrictions of an user do not influence the changes made by the plugin after the changes made by the user.
  • Sometimes a change for a single building block via the Single Element API implicitly contains more than one change. This is for example the case when parents are set to a newly created building block or attributable relations are created by connecting two building blocks. These different changes are treated separately. For Example: When creating an element and setting a parent this is done in two transactions. The new parent is not contained in the "INSERT"-Event, but in an "UPDATE"-Event that follows the "INSERT"-Event.

  • The scripts are executed in arbitrary order. In case you have more than one script reacting on a change make sure that your scripts work in any order.

  • Functions that are called within a script have to be defined in the same file as the script. Functions can either be defined within another function or outside (on top level). The definition of the function can be done the same way as for the registered functions.

Reactions are powerful

Be careful when using Reactions, we warned you!

Procedure

The Plugin API works with JavaScript code snippets, which are maintained and uploaded by the customer.

Decide what you need

There are two types of Plugin API scripts: One type registers for changes of building blocks of a certain type (subscription script). The other type waits until it is executed, either by the user via the GUI or by a schedule (direct execution script). Both types work with callback functions.

Write a script

A callback function needs to be registered within the script. It's either a subscription callback - in this case iteraplan provides a change event with data detailing the change - or it's a direct execution callback. Within the script, there are different api calls available to work with the iteraplan data, for example functions to read from the model or to write to the model. Sending mails or making http calls is also supported.

Add the scripts

Add the scripts to the application from the Plugin Api list page using Upload Script dialog or script editor. More information of adding new scripts can be found in Plugin API List View.

Schedule / run scripts

Only for direct execution scripts: After creating or uploading the script its execution can be scheduled by time interval or the script can be directly executed from Plugin API List View.

Scripts react on events

Only for subscription scripts: When data are changed, an event is created for each affected building block. All functions that are subscribed for the corresponding building block type receive this event and can work with the information.


Detailed syntax, available api calls and general guidelines how to write and use scripts can be found in Plugin API Usage page. For some script examples, please visit the Plugin API Example Scripts page.

  • No labels