Transactional Methods

Transactional methods are methods that when executed, will cause some form of change in the system. They can be executed from the Extended Interface, Extended Action, and Extended Target.

Methods

add

The add() method adds an object to another object.

The object to be added will be a generic, out-of-the-box version of the object type specified. It cannot make use of any templates in TemplateCategory or Defaults.
Optionally, values can be assigned to object properties when adding.

Syntax	Result
`<existingObject>.add(<objectType>)`	Adds object of `objectType` to `existingObject`
`<existingObject>.add(<objectType>, <property> := <value1>, ...)`	Adds object of `objectType` to `existingObject` and fills out properties

objectType: The class name of the object to be added (Scorecard, Kpi, FunctionStatus, etc,)
property, value: [Optional] The id of a property and the value to be assigned to it. It is possible to assign values to more than 1 property by separating the property-value pairs with commas

Examples

o.137.add(Scorecard)                // Adds a Scorecard to the Organization with id 137
t.6938.add(Kpi)                     // Adds a KPI to the Strategic Objective with id 6938
myObject.add(FunctionStatus)        // Adds a FunctionStatus to the object referenced by the myObject variable

// Adds a Scorecard to Organization 137 and sets it name to Finance Scorecard
t.137.add(Scorecard, name := "Finance Scorecard")

// Adds a KPI to Strategic Objective 6938 and sets its name to Revenue and its responsible to the user with id ahernandez
t.6938.add(Kpi, name := "Revenue", responsible := u.ahernandez)

affixLink

The affixLink() method links an unlinked model object to an object in the template. The objects must be the same type.

Syntax	Result
`<modelObject>.affixLink(<templateObject>)`	Links `modelObject` to `templateObject`

templateObject: The object in the template that the model object should be linked to

Examples

t.8345.affixLink(t.432)         // Links the model object with id 8345 to the template object with id 432
myObject.affixLink(t.KP001)     // Links the model object referenced by myObject to the template object with id KP001

change

The change() method changes the properties of an object or list of objects.

Syntax	Result
`<object>.change(<property1> := <value1>)`	Changes property1 to the specified value
`<object>.change(<property1> := <value1>, <property2> := <value2>, ...)`	Changes the properties of `object` to the specified values
`<objectList>.change(<property1> := <value1>)`	Changes property1 of the list objects to the specified value
`<objectList>.change(<property1> := <value1>, <property2> := <value2>,...)`	Changes the properties of the list objects to the specified values

property, value: The id of a property and the value to be assigned to it. It is possible to assign values to more than one property by separating the property-value pairs with commas

Examples

// Changes the name of the object to Revenue
t.KP001.change(name := "Revenue")

// Changes the name of the object to Revenue, the description to BLAHBLAH, and the responsible to the admin user
t.KP001.change(name := "Revenue", description := "BLAHBLAH", responsible := u.admin)

/*
* Creates a list of KPIs
* Sets the KPI Type property to Finance and the weight property to 15 for each KPI in the list
*/
myList := LIST(t.KP001, t.KP002, t.KP003)
myList.change(kpiType := "Finance", weight := 15)

clear

The clear() method can be used to clear the values (reset to default) from Object properties, as well as to clear the session and Object variables from InputViews.

InputView Syntax

When chained to an InputView, if the Persistence property of the InputView is set to Session then clear() will clear its session variables. If the Persistence property of the InputView is set to Object then clear() will clear its Object variables. When used un-chained, clear() will clear session variables.

Syntax	Result
`clear()`	Clears all session variables
`clear([<myVar>])`	Clears the `myVar` session variable
`clear([<myVar1>], [<myVar2>], [<myVar3>], ...)`	Clears the specified sessions variables
`<myObject>.inputView.clear()`	Clears all the session/Object variables of the first InputView found on `myObject`
`<myObject>.inputViews.clear()`	Clears all the session/Object variables of all the InputViews found on `myObject`
`<myObject>.inputView.clear([<myVar1>])`	Clears the `myVar1` variable of the first InputView found on `myObject`
`<myObject>.inputViews.clear([<myVar1>], [<myVar2>], ...)`	Clears the specified variables of all the InputViews found on `myObject`

myVar: The name(s) of the variable(s) to be cleared

Examples

clear()                                             // Clears all session variables
clear(memoText)                                     // Clears the memoText session variable

myInputView := t.IP1
myInputView.clear()                                 // Clears all the variables of myInputView

myRisk := t.123456
myRisk.inputView.clear()                            // Clears all the variables of the first InputView found under myRisk
myRisk.inputViews.clear()                           // Clears all the variables of all InputViews found under myRisk

myKpi := t.789
myKpi.inputView.clear(message)                      // Clears the message variable of the first InputView found under myKpi

Object Property Syntax

When used to clear Object properties, including Historical Properties, clear() will reset them to their System default. For most properties, this means they will be empty after clearing. Certain System properties, such as name will be reset to a default value. For example, clearing the name of a Scorecard named “Global Scorecard ABC” would reset the name to “Scorecard”.

Syntax	Result
`<myObject>.clear(<property>)`	Clears the `property1` property of `myObject`
`<myObject>.clear(<property1>, [<property2>], ...)`	Clears all the specified properties of `myObject`

property: The id of the property, or properties, to be cleared

Examples

myKpi := t.789
myKpi.clear(description)                            // Clears the description property of myKpi

myRisk := t.123456
myRisk.clear(historicalOwner)                       // Clears the historicalOwner property (historical property) of myRisk

copy

The copy() method copies an existing object to another object or to a list of objects. The destination object must be an acceptable parent for the object being copied. Optionally, values can be assigned to object properties when copying.

Syntax	Result
`<existingObject>.copy(<object>)`	Copies `object` to `existingObject`
`<existingObject>.copy(<object>, <property> := <value1>, ...)`	Copies `object` to `existingObject` and fills out properties
`<objectList>.copy(<object>)`	Copies `object` to the objects in `objectList`
`<objectList>.copy(<object>, <property> := <value1>, ...)`	Copies `object` to the objects in `objectList` and fills out properties

object: The object to be copied.
property, value: [Optional] The id of a property and the value to be assigned to it. It is possible to assign values to more than 1 property by separating the property-value pairs with commas

Examples

t.870.copy(t.499)                           // Copies the object with id 499 to the object with id 870
t.870.copy(t.499, id := "MYNEWID")          // Copies the object with id 499 to the object with id 870
                                            // and assigns the ID of the new object a value of MYNEWID

myScorecards := SELECT Scorecard            // Creates a list of Scorecards
myScorecards.copy(t.PERS_FIN)               // Copies the object with id PERS_FIN to all the objects in the list

delete

The delete method deletes an object, or a list of objects.

Syntax	Result
`<object>.delete()`	Deletes the object `object`
`<objectList>.delete()`	Deletes the objects in the list `objectList`

Examples

t.9683.delete()                                     // Deletes the object with id 9683

myKpis := SELECT Kpi FROM t.EXPIRED_KPIS_FOLDER     // Creates a list of Kpis
myKpis.delete()                                     // Deletes the objects in the list

error

The error() method can be used to trigger an error and print a message regarding the error. Errors triggered by the error() method will abort the Transactional script, and no changes will be applied.

Syntax	Result
`error(<string>)`	Causes an error and prints the string

string: A message to be printed if an error is triggered.

Examples

/*
* The script below would loop through all the Model Kpis and append " 2022" to their name.
* However, if a KPI with the name "Revenue" is found, an error will be triggered.
* The error will cause the script to be aborted and no changes will be done.
*/

myKpis := SELECT Kpi

myKpis.forEach(kp:
    IF kp.name = "Revenue" THEN
        error("Revenue Kpi was found")
    ENDIF

    kp.change(name := kp.name + " 2022")
)

generate

The generate() method is chained onto an object, or list of objects, and outputs the Transactional code needed to replicate the object(s). This code includes any descendant objects of the primary object(s).

By default, generate() will not output the code to replicate the ID of the object(s). However, if given an optional true argument, the id property will be included.

Syntax	Result
`<object>.generate()`	The code to create `object` and any descendant objects
`<object>.generate([true])`	The code to create `object` and any descendant objects, including their IDs.
`<objectList>.generate()`	The code to create the objects in `objectList` and any descendants
`<objectList>.generate([true])`	The code to create the objects in `objectList` and any descendants, including their IDs.

true: [Optional] Boolean true value. When true, generated script will include the ID property.

Examples

t.123.generate()                                // Code to create object with ID 123 and any descendants of it
t.123.generate(true)                            // Same as above, but will also include the IDs of the objects (id := '123', ...)

myKpis := SELECT Kpi FROM t.KPI_LIBRARY
myKpis.generate()                               // Code to create all the KPIs in the list, as well as any descendants of it

link

The link() method copies a template object to a model object, or to a list of model objects. The link() method preserves the link to the template object.

Syntax	Result
`<modelObject>.link(<templateObject>)`	Copies a linked `templateObject` to `modelObject`
`<modelObjectList>.link(<templateObject>)`	Copies a linked `templateObject` to the objects in `modelObjectList`

templateObject: The object from the Template Category to be copied

Examples

t.2389.link(t.500)                      // Creates a linked copy of template object with id 500 under the model object with id 2389

myScorecards := SELECT Scorecard
myScorecards.link(t.PERS_FIN)           // Creates a linked copy of the template object with id PERS_FIN under the objects myScorecards list

move

The move() method moves an object, or list of objects, to a new parent object. The method works similarly to a cut + paste with a few caveats:

The destination object must be a valid parent for the object(s) being moved.
It is not possible to move between models

Syntax	Result
`<object>.move(<destinationObject>)`	Moves `object` to `destinationObject`
`<objectList>.move(<destinationObject>)`	Moves the objects in `objectList` to `destinationObject`

destinationObject: The parent object that the object(s) should be moved to

Examples

t.KP001.move(t.KPI_FOLDER)                      // Moves the object with ID KP001 to the parent object with ID KPI_FOLDER

oldKpis := SELECT Kpi WHERE end < BOP           // Selects all KPIs with a lifetime end before the beginning of the current period
oldKpis.move(t.EXPIRED_KPI_FOLDER)              // Moves the KPIs in oldKpis to the parent object with ID EXPIRED_KPI_FOLDER

moveAfter

The moveAfter() method moves an object, or list of objects, after another object. The destination object must be a valid sibling for the object(s) being moved.

Syntax	Result
`<object>.moveAfter(<destinationObject>)`	Moves `object` after `destinationObject`
`<objectList>.moveAfter(<destinationObject>)`	Moves the objects in `objectList` after `destinationObject`

destinationObject: The object that the object(s) will be moved after

Examples

t.KP004.moveAfter(t.KP003)                      // Moves object with ID KP004 after the object with ID KP003

myKpis := LIST(t.KP005, t.KP004, t.KP003)
myKpis.moveAfter(t.KP002)                       // Moves all the objects in the list after the object with ID KP002

moveBefore

The moveBefore() method moves an object, or list of objects, before another object. The destination object must be a valid sibling for the object(s) being moved.

Syntax	Result
`<object>.moveBefore(<destinationObject>)`	Moves `object` before `destinationObject`
`<objectList>.moveBefore(<destinationObject>)`	Moves the objects in `objectList` before `destinationObject`

destinationObject: The object that the object(s) will be moved before

Examples

t.KP003.moveBefore(t.KP004)                      // Moves object with ID KP003 before the object with ID KP004

myKpis := LIST(t.KP003, t.KP004, t.KP005)
myKpis.moveAfter(t.KP006)                       // Moves all the objects in the list before the object with ID KP006

notify

The notify() method sends a notification to the notification system. The notification includes a subject (required), message body, message type, and recipients. If no recipients are specified as arguments, the notification is addressed to the System Administrator user.

Syntax	Result
`notify(<subject>)`	Notification to System Administrator User with subject `subject`
`notify(<subject>, [<body>], [<type>], [<recipients>)]`	Notification to `recipients` with subject `subject`, message `body` and message type `type`

subject: String to be used as subject line for the notification
body: [Optional] String to be used as the message body for the notification
type: [Optional] String to be used as the message type for the notification
recipients: [Optional] A User, Group, list of Users/Groups, or any combination of the previous that will be the recipients of the notification

Examples

notify("My Subject")                                            // Sends notifcation to System Administrator User with subject line "My Subject"


/*
* Sends a notification to User with id "testalot", with subject line "Red KPIs", message body "Your Kpi: 107 Revenue is red!",
* and message type "KPI Update"
*/

notify("Red KPIs", "Your Kpi: " + this.object + " is red!", "KPI Update", u.testalot)


/*
* Sends a notificatiion to all the Users in the group with id "PPM" and User with id "abourdain", with subject line "Project Approval",
* message body "PROJ1000 Optimize Synergies has been approved!", and message type "Projects"
*/

myProject := t.PROJ100
notify("Project Approval", myProject + " has been approved!", "Projects", g.PPM, u.abourdain)

reset

The reset() method resets the overriden properties of a linked object back to their template values. By default it resets all the overriden properties, but it can also reset only the properties provided as arguments to it.

Syntax	Result
`<object>.reset()`	Resets all the overriden properties of the object
`<object>.reset(<property1>)`	Resets the property with id `property1` of the object
`<object>.reset(<property1>, <property2>, ...)`	Resets the properties with id `property1`, `property2`
`<objectList>.reset()`	Resets all the overriden properties of the objects in the list
`<objectList>.reset(<property1>)`	Resets the property with id `property1` of the objects in the list
`<objectList>.reset(<property1>, <property2>, ...)`	Resets the properties with id `property1`, `property2` of the objects in the list

property1, property2: [Optional] The ID of specific properties that should be reset. It is possible to specify multiple properties by separating them with a commma.

Examples

t.67203.reset()                         // Resets all the properties of the object with ID 67203
t.67203.reset(name)                     // Resets only the name property of the object with ID 67203

myObjects := SELECT Scorecard
myObjects.reset()                       // Resets all the properties of the objects in the list
myObjects.reset(description)            // Resets the description property of the objects in the list

sendmail

The sendmail method can be used to send an email to a recipient, or list of recipients. A recipient can be a hardcoded email address, or a User. A list of recipients can be a list of hardcoded email addresses, a list of Users, or a Group (list of Users). The method accepts arguments for subject, body, and recipients.

Syntax	Result
`sendmail(<subject>, <body>, <recipients>)`	Sends an email with `subject` and `body` to `recipients`

subject: The subject line of the email
body: The message body of the email
recipients: The recipients of the email

Examples

// Sends an email to a hardcoded email address
sendmail("KPI Update", "Please enter your monthly comments for your KPI", "bruce@wayneenterprises.com")

// Sends an email to a list of hardcoded email addresses
sendmail("KPI Update", "Please enter your monthly comments for your KPI", list("bruce@wayneenterprises.com", "alfred@wayneenterprises.com"))

// Sends an email to the Users in the Responsible property of the current object (a Risk)
sendmail("Risk Warning", "Your Risk has entered red territory this month, please add mitigations!", this.object.responsible)

// Sends an email to the measureOwner (custom property) for each KPI with a Red status for the selected context month
redKpis := SELECT Kpi WHERE statusClassfication = RED

redKpis.forEach(redKpi:
    sendemail("Red KPI Notice", "Your KPI is Red", redKpi.measureOwner)
)

// Sends an email to all the Users in a Group
sendemail("Data entry is read", "Data entry is ready for your department's metrics", g.financeDept)

start

The start() method can be used to execute runnable objects, such as Event Rules, Transformer Jobs and Transformer Groups. It can start both individual objects, as well as lists of objects.

Syntax	Result
`<runnableObject>.start()`	Starts `runnableObject`
`<runnableObjectList>.start()`	Starts all the objects in `runnableObjectList`

Examples

t.81037.start()                                                     // Starts the object with id 81037

dailyJobs := SELECT FlowProject WHERE name = "*Daily Load*"
dailyJobs.start()                                                   // Starts all the Transformer Jobs in the dailyJobs list

unlink [ 5.1.10.0 +]

The unlink() method removes the link from a linked object and converts it to a model object.

Syntax	Result
`<object>.unlink()`	Removes the link from `object`
`<objectList>.unlink()`	Removes the link from all the objects in `objectList`

Examples

t.5492.unlink()                                     // Unlinks the object with ID 5492

myKpis := SELECT Kpi WHERE linkedTo.id = "KP001"
myKpis.unlink()                                     // Unlinks all the Kpis in the list myKpis

this.objects.descendants.unlink()                   // Unlinks all the descendant objects of the context object