With the iteraplan Plugin API the user can upload scripts (so called "Reactions") to manipulate the data in iteraplan. Reactions subscribe for changes on building blocks of a certain type. Whenever a building block is changed, the function is called and obtains an event, which contains all changes. The Reaction can use these changes to manipulate values in any building block, modify relations and also create new objects or remove existing ones.
Things to consider
- 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 subcription 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 (assinging attributes to building blocks, changing literals of an enumaration 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.
Reactions are powerful
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.
Please note: All scripts have a common scope.
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.