Skip to end of metadata
Go to start of metadata

The scripts can have one of the following forms:

Subscription Scripts listen for an event to happen and react to that event

'use strict';
 
api.subscribeFor('ExampleBuildingBlockType', onBuildingBlockChange);
 
function onBuildingBlockChange(buildingblocktype, event) {
	// React on the event
}

Direct Execution Scripts are executed on schedule or on manual execution

'use strict';
 
api.registerExecution(onDirectExecute);
 
function onDirectExecute() {
	// Do something when the execution was triggered
}

Be advised

In any reaction script, do not use any direct statements other than api.registerExecution or api.subscribeFor. All functionality has to be placed within functions.
Scripts are executed arbitrarily by the Plugin system, so direct statements in the scripts will have unintended effects.

Functions to work with the model

The variable api is available in the common scope. It has the following functions:

Function (of api)Description
subscribeFor(string buildingBlockType, JSFunction yourFunction)With this function the new script subscribes for changes at a Building Block Type. More than one function can subscribe for a certain Building Block Type. The system will call the function for each of these subscriptions.

registerExecution(JSFunction yourFunction)


printLog(string message)

Prints message to database as log message. It is possible to retrieve all logs of a specific script by sending a GET request to /api/administration/reactions/log/<id>.

Note

Using function printLog(string message) without 'api.' will print to console


datamodelGives access to a model that contains the iteraplan data.

getPropertyInfo(String buildingBlockType, string property)

Gets inner properties of Building Block attribute by its persistent name (mandatory, multiple and type attribute properties are available)

executeLdapQuery(String extendedBase, String ldapQuery, String[] fields)

Execute LDAP query. Result based on search criteria. This function can throw exception. To get detailing information about exception use message field.

parameters:

  • extendedBase - extend Distinguished Name for search criteria. Base DN is setting when configuring LDAP connection for Iteraplan application. For example: need execute search for next DN: "ou=People,dc=example,dc=com", and Iteraplan LDAP connection use "dc=example,dc=com" as BasDN, for this case extendedBase parameter has value: "ou=People".
  • ldapQuery - string that represent LDAP query. As example: "(&(objectCategory=user)(objectClass=user))"
  • fields - optional parameter that define list of fields than will include in result. Can be omitted. When this parameter not set result will contains all available fields that return LDAP server.

result:

  • result - array of objects. Each object represents one row of LDAP server response.

createDate(number milliseconds)

createDate(string dateValue)

createDate(number  year, number monthindex, number day, number hour, number minutes, number seconds, number milliseconds)

Returns a date value that can be set as attribute value or can be used within date intervals. For more information see the section "Date" on this page.


The api.datamodel supplies different methods to work with iteraplan data:

Function (of api.datamodel)Description
getAllTypeNames()returns the names of all Building Block Types in the metamodel.

getAllPropertyNamesByType(string typePersistentName)

returns the names of all properties of a Building Block Type.
getAllRelationNamesByType(string typePersistentName)returns the names of all relation ends connected to the Building Block Type.
findByType(string typePersistentName)returns an array containing all Building Block objects of the given type in the model.
findByTypeAndId(string typePersistentName, number id)returns a Building Block object with the given type and id. Null if there is no such object.
findByTypeAndName(string typePersistentName, string name)

returns a Building Block object with the given type and name. Null if there is no such object.

create(string typePersistentName)creates a new object of the given type in the model and returns it.


Set functions to work with attribute:

Function (of api.metamodel)Description
getAttributes() returns list of attribute objects
getAttributesAssignedToBuildingBlockType(string persistentTypeName)returns list of attribute objects
getAttribute(string persistentName)returns attribute object
createResponsibilityLiteral(string attributePersistentName, number userId, string literalColorRGB)Create new literal for existing responsibility attribute. Function returns boolean value, where true mean that new literal successfully added and false otherwise.
createEnumerationLiteral(string attributePersistentName, string literalName, string literalDescription, string literalColorRGB)Create new literal for existing enumeration attribute. Function returns boolean value, where true mean that new literal successfully added and false otherwise.

removeResponsibilityLiteral(string attributePersistentName, number userId)

Remove literal from responsibility attribute. Function returns boolean value, where true mean that literal successfully removed and false otherwise.
removeEnumerationLiteral(string attributePersistentName, string literalName)Remove literal from enumeration attribute. Function returns boolean value, where true mean that literal successfully removed and false otherwise.

The attribute object describes next fields:

Attribute object
String name;
String type;

String description;

Boolean mandatory;
String attributeGroup;
String lastModificationUser;
String lastModificationTime;
Array<String> buildingBlocks

For responsibility type attribute exists additional fields and functions:

Responsibility type additional functions and fields
createResponsibilityLiteral(number userId, String color)Create literal for existing attribute
removeResponsibilityLiteral(number userId)Remove literal for existing attribute
boolean multiassignmenttype;
boolean includeAllUsers;
Array<User> users;

Type "User" for responsibility attribute contains next fields:

User
String login;
String fullIdentity;
String color;

For enumeration type attribute exists additional fields and functions:

Enumeration type additional functions and fields
createEnumerationLiteral(String name, String description, String color)Create literal for existing attribute
removeEnumerationLiteral(String name)Remove literal for existing attribute
boolean multiassignmenttype;
Array<Literal> literals

Type "Literal" for enumeration attribute contains next fields:

Literal
String name;
String description;
number position;
String color;


The objects that represent a Building Block in the model have the following properties:

FunctionDescription
getId()returns the id.
getValue(string propertyPersistentName)

returns the value for a property that can have only a single value. Does not work for multi value properties.

getValues(string propertyPersistentName)returns an array of values for a property that can have more than one value. Returns empty array if no values are assigned. Does not work for single value properties.
getRelatedObject(string relationEndPersistentName)returns the assigned object for a single assignment relation, does not work for multi assignment relations.
getRelatedObjects(string relationEndPersistentName)returns an array of objects for a multi assignment relation, does not work for single assignment relations.
setValue(string propertyPersistentName, Object value)for single value properties, replaces the current value with the new value, returns whether the operation was successful.
setValues(string propertyPersistentName, Array values)for multi value properties, replaces the current value array with a new array of values, returns whether the operation was successful.
addValue(string propertyPersistentName, Object value)for multi value properties, adds the value to the value array, works only if the value is not already contained, returns whether the operation was successful.
removeValue(string propertyPersistentName, Object value)for multi value properties, removes the value from the value array, works only if the value is contained, returns whether the operation was successful.
clearValues(string propertyPersistentName)unsets the value and returns whether the operation was successful.
connect(Object object2, string relationendPersistentName)connects an object to the other object via a relation of the given type, if an object can have only one relation an earlier relation is replaced. The objects are connected in both directions, returns whether the operation was successful.
disconnect(Object object2, string relationendPersistentName)disconnects an object from the other object, returns whether the operation was successful.
remove()

Removes the corresponding Object from the model.

getPropertyInfo(string propertyPersistentName)Gets inner properties of Building Block attribute by its persistent name (mandatory, multiple and type attribute properties are available)

Attribute values are expressed in simple javascript types

  • Enum attribute value -> string
  • Responsibility attribute value -> string
  • Numeric attribute value -> number
  • Text attribute value -> string
  • Date attribute value -> Date
  • Date interval value - > Object o with o.from (Date) and o.to (Date)
  • Boolean attribute value -> boolean

    Start and end dates of date intervals can depend on date attributes. If a plugin changes such a start or end date the change is ignored. The value can only be changed via the corresponding date attribute.

Working with arrays

The setValues()-function expects an array 'values' which has to be a string array. Although the reaction script is JavaScript, how this array needs to be created depends on the version of the used JRE/JDK (Java Runtime Environment).

JDK 1.7

The array must be created as shown in this code-snippet:

Example
var complexitySet = ["low"];
changedObject.setValues("Complexity", complexitySet);
JDK 1.8

The array must be created as shown in this code-snippet:

Example
var StringArrayType = Java.type("java.lang.String[]");
var complexitySet = new StringArrayType(1);
complexitySet[0] = "low";
changedObject.setValues("Complexity", complexitySet);

Helper Functions

HTTP

From reaction scripts it is possible to perform Http(s)-calls to third-party REST APIs. Using "http" with various commands will provide such functionality. 

Function (of api.http)Description
setURL(string URL)Sets URL to which http call will be performed
setMethod(string method)Sets request method type. There are four possible options: GET, PUT, POST, DELETE.
addUserName(string password)Sets username to credentials within rest request.
addPassword(string password)Sets password to credentials within rest request.
setContentType(string contentType)Sets content type for the request. By default it is "application/json".
setBody(string body)Sets body for the request. By default it is JSON body.
addParameter(string name, string value)Adds parameter for the request.
addHeader(string name, string value)Adds header for the request.
performRequest()If all needed data is set, performs http request. Returns response as String.
toJsonObject(string stringInJson)Converts string if it is in json format to JSON object. Helping function to convert response to json if needed.
toJsonArray(string stringinJson)Converts string if it is in json format to JSON array. Helping function to convert response to json if needed.
setProxyURL(string proxyURL)Sets proxy URL
setProxyUser(string proxyUser)Sets username to proxy credentials.
setProxyPassword(string proxyPassword)Sets password to proxy credentials.

Send EMail

It's possible to send emails from within a script:

Function (of api)Description
sendEmail(string recipient, string subject, string content)

With this function it is possible to send emails as a plain text. Returns an integer value of 1 if email was sent successfully, -1 if not.

Please see the Subscriptions for more information on how to configure mail Mail-notifications.

User

There is a function to get information about user by username:

Function (of api)Description

getUserDetails(string userName)

Note: This function is deprecated and will not be supported in future versions of iteraplan!

With this function it is possible to get simple information about any user. Returns an object with 3 properties: firstName, lastName and eMail.

Function (of api.user)Description

getAll()

Returns all Users entities of iteraplan.

get(Integer userId)

Returns User entity with given Id.

get(String loginName)

Returns User object with given login name.

create(String loginName)

Creates and returns new User entity with given login name. When loginName parameter is empty or user with given loginName already exist will throw exception with appropriate message.

The objects that represent User entity have following functions:

FunctionDescription

getId()

Returns id.
getLoginName()Returns login name.
getFirstName()Returns first name.
getLastName()Returns last name.
getEmail()Return email address.
setLoginName(String loginName)Sets new login name and returns true if operation was successful and false if not.
setFirstName(String firstName)Sets new first name and returns true if operation was successful and false if not.
setLastName(String lastName)Sets new last name and returns true if operation was successful and false if not.
setEmail(String email)Sets new email address and returns true if operation was successful and false if not.


History

To work with the history there are two available functions:

Function (of api)Description
getHistoryForType(String typePersistentName)returns history for Building Block Type
getHistoryForBuildingBlock(Integer buildingBlockId, String typePersistentName)returns history for Building Block

Building Block Type history

The object that represents the Building Block Type history has the following properties:

FunctionDescription
getAuthor()returns name of change's author
getTimestamp()returns timestamp of changes
getAttributeChanges()returns array of attribute changes. Structure of array items is the same as for BuildingBlockChange (see below)
getInsertedBBs()returns array of objects that represent insererted Building Blocks
getDeletedBBs()returns array of objects that represent deleted Building Blocks
getUpdatedBBs()returns array of objects that represent updated Building Blocks

The object that represents data for inserted, deleted and updated Building Blocks has the following properties:

FunctionDescription
getBuildingBlockIdentityString()returns identify string for Building Block
getBuildingBlockID()return ID for Building Block

Building Block history

The object that represents the history for a Building Block has the following properties:

FunctionDescription
getAuthor()returns name of the author who performed the change
getTimestamp()returns timestamp of changes
getChangeType()returns type of change
getAttributeChanges()returns array objects that represents changes for attributes. Structure of array items is the same as for BuildingBlockChange (see below)
getBuildingBlockChanges()returns array objects that represent changes for Building Blocks
getAssociationChanges()returns array objects that represent changes for associations

The object that represents attribute changes for a Building Block has the following properties:

FunctionDescription
getFeaturePersistentName()returns persistent name of Building Block
isMultipleValue()returns true if the Building Block has multiple value
getFeatureType()returns type of feature
getAdded()returns array of added objects
getRemoved()returns array of removed objects

The object representing data for association changes has the following properties:

FunctionDescription
getRelationName()returns persistent name of the relation
getRelatedElementName()returns related element name
getChangeType()returns type of change
getFeaturePersistentName()returns persistent name of Building Block
getAdded()returns array of added objects
getRemoved()returns array of removed objects
isMultipleValue()returns if Building Block has multiple value

Reaction Event

Reaction events only occur in subscription scripts. A reaction event is an array containing all changes for a certain Building Block Type.

Array<ModelChange> reactionEvent;


The changes are described by the id of the Building Block, the type of the change (“UPDATE, “INSERT” or “DELETE”) and an array with all the changes:

ModelChange
int id;
String changeType;
Array <BuildingBlockChange> buildingBlockChanges;


These changes consist of the persistent name of the property, a removed-value an added-value.

BuildingBlockChange
String persistentName;
Object removed;

Object added;

"removed" and "added" can have values depending of the kind of feature the BuildingBlockChange represents:

  • Change for a single assignment attribute: The removed/added attribute value, or null
  • Change for a multi assignment attribute: Array of the removed/added attribute values
  • Change for a single assignment relation: The ID of the removed/added Building Block, or null
  • Change for a multi assignment relation: Array of the IDs of the removed/added Building Blocks

Example

The assigned Business Units of a Business Domain "Management" change from "Executive Board" (ID: 10) and "Human Resource Management" (ID: 11) to "Executive Board" (ID: 10) and "R&D Management" (ID: 21). The according BuildingBlockChange will then look as follows:

{
	persistentName: "businessUnits",
	removed: [11],
	added: [21]
}


To access the complete values as they are after the change, the datamodel referenced in the api object can be used. Search for the changed Business Domain with the ID from the ModelChange object. Then query the currently assigned Business Units:

var businessDomain = api.datamodel.findByTypeAndId("BusinessDomain", bbChangeObject.id);
var assignedBusinessUnits = businessDomain.getRelatedObjects("businessUnits");

Date

To create dates that can be used as attribute values or within date intervals the function api.createDate() has to be used. Directly creating dates in the script via "new Date()" does not work. The arguments for this functions can be:

  • a number containing the milliseconds value of the time
  • a string representing the date in a format that is supported by the new Date function, e.g. 'October 3, 2018 17:34:00' or '2018-10-03T17:34:00'
  • all of the following numbers in the following order: year, monthindex, day, hour, minutes, seconds, milliseconds. Caution: monthindex starts with 0 for January.



  • No labels