Scripting Functions are used when developing processes or application server-side pages. Functions listed here are additional to the standard library of functions supported within the JavaScript language. These functions are used to automate the development and data feeds across all components of a model, within model applications they are used to deliver custom user interfaces and notifications.

These functions are used to manipulate dimension alias.

• alias.create(String dimensionName, String aliasName)
• alias.delete(String dimensionName, String aliasName)
• alias.exists(String dimensionName, String aliasName)
• alias.get(String dimensionName, String aliasName, String element)
• alias.set(String dimensionName, String aliasName, String element, String value)
• alias.wipe(String dimensionName, String aliasName)

Creates an alias within a dimension

alias.create(dimension, aliasName); 

Parameters

• Dimension - The dimension in which to create an alias
• aliasName - The identifier of the alias created

Example

alias.create("Account","No - Name");

Deletes an alias from within a dimension permanently

Deletes an alias from within a dimension. Please note that this function is permanent.

alias.delete(dimension, aliasName)

Parameters

• Dimension - The dimension in which to delete an alias
• aliasName - The identifier of the alias to be delete

Example

alias.delete("Account","No - Name");

Checks whether an alias exists within a dimension

Returns a boolean value.

alias.exists(dimension, aliasName)

Parameters

• Dimension - The dimension within which to check if alias exists
• aliasName - The identifier of the alias to be checked

Example

if( dimension.alias.exists("Account", "No - Name")) {
    //do something
}

Returns the alias of a given element from within the dimension

alias.get(dimension, aliasName, element) 

Parameters

• Dimension - The dimension within which to return the specified alias
• aliasName - The identifier of the alias to be returned
• Element - The element for which the alias will be returned

Example

var noName = alias.get("Account","No - Name", "600000");

Updates the alias of a given element within the dimension

alias.set(dimension, aliasName, element, value) 

Parameters

• Dimension - The dimension within which to update the specified alias
• aliasName - The identifier of the alias to be updated
• Element - The element to which the alias will be set
• Value - The alternate name to be saved as the elements alias

Example

alias.set("Account","No - Name","600000","600000 - Revenue");

Removes all given alias names from the element within the dimension

alias.wipe(dimension, aliasName) 

Parameters

• Dimension - The dimension within which to wipe alias names from
• aliasName - The identifier of the alias to be wiped

Example

alias.wipe("Account","No - Name");

These functions are used mostly for debugging purposes.

• console.log(String outputText)

Write a line of text to the logs.

This function is commonly used to debug or output status updates from scripts into console.

console.log(outputText); 

Parameters

• outputText - the line of text to output.

Example

console.log('The processes has commenced');

These functions are used to manipulate cubes.

• cube.create(String cubeName, String dimension1 ... to dimensionN)
• cube.delete(String cubeName)
• cube.exists(String cubeName)
• cube.get(String cubeName, String element1 ... to elementN)
• cube.wipe(String cubeName, String element1 ... to elementN)
• cube.set([String or Float] Value, String cubeName, String element1 ... to elementN)
• cube.increment([String or Float] Value, String cubeName, String element1 ... to elementN)
• cube.dimensions(String cubeName)
• cube.dimensionCount(String cubeName)
• cube.getId(String name)
• cube.getName(String id)

Creates a cube within a model

cube.create(name, d1 - dN)

Parameters

• Name - The identifier of the cube to create
• d1 - dN - The names of the dimensions from which the Cube intersections will be defined.

Example

cube.create("General Ledger", "Scenario", "Time", "Department","Account","Project","Measures General Ledger");

Returns the number of dimensions present in a cube within the specified model

This function returns an integer value.

cube.dimensionCount(cube_name)

Parameters

• cube_name - Name of a cube.

Example

var count = cube.dimensionCount("General Ledger");

Returns the dimensions present in a cube within the specified model

This function returns a JSON string.

cube.dimensions(cube_name)

Parameters

• cube_name - Name of a cube.

Example

var dimensions = cube.dimensions("General Ledger");

Checks that a cube exists

This function returns a boolean.

cube.exists(name)

Parameters

• Name - The identifier of the cube

Example

var itExists = cube.exists("General Ledger");

Either changes whether the cube outputs a change log. Or returns whether the cube presently is logging changes. 

cube.log(name, bShouldLog);

or

var isLogging = cube.log(name);

Parameters

• Name - The identifier of the cube
• bShouldLog - (Optional) true or false. If this argument is omited the function will return the cubes current logging flag.

Example

var value = cube.log("General Ledger",false);
if (value) {
    console.log("Cube loggig has been turned off for the General Ledger.");
}

Retrieves data from an intersection of elements from their respective dimensions within the cube

cube.get(name, e1 - eN)

Parameters

• Name - The identifier of the cube
• e1 - eN - An element for each dimension within the cube which when used, finds a specific intersection

Example

var value = cube.get("General Ledger", "Actual","2014","Total Revenue","All Departments","All Projects","Amount");

Returns the Id of a cube within the specified model

This function is used to retrieve the Id of a cube.

cube.getId(cube_name)

Parameters

• cube_name - The name of a cube.

Example

var cube_id = cube.getId("CubeA");

Returns the name of a cube within the specified model

This function is used to retrieve the name of a cube.

cube.getName(cube_id)

Parameters

• cube_id - Id of a cube.

Example

var cube_name = cube.getName("123");

Increments the value at an intersection of elements from their respective dimensions within the target cube

cube.increment(objectData, name, e1 - eN)

Parameters

• objectData - The value to send into the cube to update.
• Name - The identifier of the cube
• e1 - eN - An element for each dimension within the cube which when used, finds a specific intersection

Example

cube.increment(100,"General Ledger", "Actual","2014","600010","100 - Finance","No Project","Amount")

Removes a cube within a model permanently

When removing a cube within a model please note that this action is irreversible

cube.remove(name)

Parameters

• Name - The identifier of the cube to delete

Example

cube.remove("General Ledger");

Sets the value at an intersection of elements from their respective dimensions within the target cube

cube.set(objectData, name, e1 - eN)

Parameters

• objectData - The value to send into the cube.
• Name - The identifier of the cube
• e1 - eN - An element for each dimension within the cube which when used, finds a specific intersection

Example

cube.set(100,"General Ledger", "Actual","2014","600010","100 - Finance","No Project","Amount");

Slices data from an intersection of elements from their respective dimensions within the cube

cube.slice(name, e1 - eN)

Parameters

• Name - The identifier of the cube
• e1 - eN - An element for each dimension within the cube which when used, finds a specific intersection

Methods

• EOF - Returns a boolean value which indicates if the last row has been read.
• Next - Returns the next available row.

Example

// Cube Name - Sales.  
// Dimensions: year, month, scenario, department, product, measures
var slice = cube.slice("Sales","2017,2018","","Actual","","","Units sold"); 
while( !slice.EOF() ) {
  var elms = slice.Next();
}

// The following rows will be stored in the variable elms for every iteration, until it reaches the last record.
// ["2017","Jan","Actual","Store 01","Product A","Units Sold",19200]
// ["2017","Feb","Actual","Store 01","Product A","Units Sold",374]
// ... //
["2018","Dec","Actual","Store 10","Product Z","Units Sold",152]

Note:

• Each argument for the dimensions can have a single value or multiple values (separated by comma)
• An argument which is empty will include all elements within the particular dimension depending on the intersection of cells

Wipes the data from a selection of intersections within a target cube

Where no members from a dimension are specified the wipe will apply to all members from that Dimension. All dimension elements should be listed as arguments including where no selection is made.

cube.wipe(name, e1, e2, e3, eN)

Parameters

• Name - An identifier used to name the dimension to be wiped.
• e1 - eN - The areas from the cube to wipe. Providing a blank string applys the wipe to all members from that Dimension.

Example

cube.wipe("General Ledger","Budget","","","","","Amount");

This example wipes all Budget data from the cube.

These functions are used to manipulate databases using SQL.

• datasource.select(String datasourceName, String sql)
• datasource.select(String datasourceName, String sql, String[] parameters)
• datasource.update(String datasourceName, String sql)
• datasource.update(String datasourceName, String sql, String[] parameters)
• datasource.insert(String datasourceName, String sql, String[] parameters)

Executes SQL against a datasource

This function is used to execute a SQL statement against a registered JDBC datasource.

datasource.insert(datastoreName,sql)

Parameters

• datastoreName - The name of a registered datasource.
• sql - INSERT SQL statement.
• [arguments] (Optional) - Parameterized Values

Example

var latest_generated_id = datasource.insert(
    "Internal Datastore",
    "INSERT INTO department_codes (department_id,department_name) VALUES ('001','Head Office');"
);

Parameterized Query

var latest_generated_id = datasource.insert(
    "Internal Datastore",
    "INSERT INTO department_codes (department_id,department_name) VALUES (?, ?);", 
    ['001', 'Head Office']
);

Executes a SQL Select Statement against a datasource

This function is used to execute a SQL Select statement against a registered JDBC datasource and returns the results as a JSON String.

datasource.select(datastoreName,sql)

Parameters

• datastoreName - The name of a registered datasource.
• sql - Either a INSERT, UPDATE or DELETE SQL Function.
• [bExtended] - An optional argument which when provided as true adds the query metadata (data types and specifications of the returned fields).

Example

var dataset = datasource.select(
    "Internal Datastore",
    "SELECT department_id, department_name FROM department_codes ORDER BY department_name ASC;"
);
var rows = JSON.parse(dataset);

for(var i=0;i < rows.length; i++) {
    var row = rows[i];     
    var department_id = row['department_id'];     
    var department_name = row['department_name'];
}

Parameterized Query

var dataset = datasource.select(
    "Internal Datastore",
    "SELECT department_id, department_name FROM department_codes WHERE department_code = ? ORDER BY department_name ASC;",
    [department_code]
);

Executes SQL against a datasource

This function is used to execute a SQL statement against a registered JDBC datasource.

datasource.update(datastoreName,sql);

Parameters

• datastoreName - The name of a registered datasource.
• sql - Either a INSERT, UPDATE or DELETE SQL Function.
• [arguments] (Optional) - Parameterized Values

Example

var success = datasource.update(
    "Internal Datastore",
    "INSERT INTO department_codes (department_id,department_name) VALUES ('001','Head Office');"
);

Parameterized Query

Example

var success = datasource.update(
    "Internal Datastore",
    "INSERT INTO department_codes (department_id,department_name) VALUES (?, ?);", 
    ['001', 'Head Office']
);

The function will return a boolean true or false depending on if the statement executed without issue.

These functions are used to manipulate dimensions.

• dimension.create(String dimensionName, String type)
• dimension.delete(String dimensionName)
• dimension.exists(String dimensionName)
• dimension.wipe(String dimensionName)
• dimension.elements(String dimensionName,int offset, int count)
• dimension.elementCount(String dimensionName)
• dimension.aliases(String dimensionName)
• dimension.hierarchies(String dimensionName)
• dimension.getId(String name)
• dimension.getName(String id)
• dimension.item(String name, int index)
• dimension.size(String name)

Returns the aliases in a dimension within the specified model

This function is used to retrieve the aliases in a dimension, returns a JSON string object

dimension.aliases(dimension_name)

Parameters

• dimension_name - Name of a dimension.

Example

var aliases = dimension.aliases("time");

Creates a dimension

Creates a dimension within the specified model of the given type

dimension.create(name, type);

Parameters

• Name - An identifier used to name the dimension.
• Type - One of the valid dimension types

Example

dimension.create("Account","standard");

Valid Dimension Types

• Standard
• Measure
• Time
• Scenario
• Geography

Deletes a dimension

Deletes a dimension within the specified model

dimension.delete(name)

Parameters

• Name - The identifier of the dimension to delete.

Example

dimension.delete("Account");

Returns the number of elements in a dimension within the specified model

This function is used to retrieve the number of elements in a dimension, returns an integer. Returns -1 in case of invalid dimension name.

dimension.elementCount(dimension_name)

Parameters

• dimension_name - Name of a dimension.

Example

var elementCount = dimension.elementCount("time");

Returns the elements in a dimension within the specified model

This function is used to retrieve the elements in a dimension, returns a JSON string object

dimension.elements(dimension_name, offset, count)

Parameters

• dimension_name - Name of a dimension.
• offset - Number of elements to exclude.
• count - Number of elements to retrieve after the offset.

Example

var elements = dimension.elements("time", 1, 5);

Checks whether a dimension exists

Returns a boolean value.

dimension.exists(name)

Parameters

• Name - The name which identifies the dimension.

Example

if( dimension.exists("Account")) {
    //do something
}

Returns the Id of a dimension within the specified model

This function is used to retrieve the Id of a dimension.

dimension.getId(dimension_name)

Parameters

• dimension_name - The name of a dimension.

Example

var dimension_id = dimension.getId("time");

Returns the name of a dimension within the specified model

This function is used to retrieve the name of a dimension.

dimension.getName(dimension_id)

Parameters

• dimension_id - Id of a dimension.

Example

var dimension_name = dimension.getName("123");

Returns the hierarchies in a dimension within the specified model

This function is used to retrieve the hierarchies in a dimension, returns a JSON string object

dimension.hierarchies(dimension_name)

Parameters

• dimension_name - Name of a dimension.

Example

var hierarchies = dimension.hierarchies("time");

Returns the name of an element in a dimension within the specified model at specified index

This function is used to retrieve the name of an element in a dimension at specified index, returns a String

dimension.item(dimension_name, index)

Parameters

• dimension_name - Name of a dimension.
• index - Position of an element

Example

var element_name = dimension.item("time", 1);

Returns the size of a dimension within the specified model

This function is used to retrieve the size of a dimension, returns an integer. Returns 0 in case of invalid dimension name.

dimension.size(dimension_name)

Parameters

• dimension_name - Name of a dimension.

Example

var dimension_size = dimension.size("time");

Wipes the contents of a dimension

Removes all elements from the dimension and subsequent hierarachy elements.

dimension.wipe(name)

Parameters

• Name - An identifier used to name the dimension to be wiped.

Example

dimension.wipe("Account");

These functions are used to manipulate dimension elements.

• element.create(String dimensionName, String elementName, String type)
• element.exists(String dimensionName, String elementName)
• element.delete(String dimensionName, String elementName)
• element.principal(String dimensionName, String elementAlias)

Creates an element within a dimension

element.create(dimension, name, type)

Parameters

• Dimension - The dimension in which to create an element
• Name - The identifier of the element created
• Type - Either N or S, depending on the data type held against it. However S is only ever used in measures dimensions.

Example

element.create("Account","600010", "N");

Deletes an element within a dimension

element.delete(dimension, name)

Parameters

• Dimension - The dimension in which to delete an element
• Name - The identifier/name of the element

Example

element.delete("Account","600010");

Checks whether an element exists within a dimension

Returns a boolean value.

element.exists(dimension, name)

Parameters

• Dimension - The dimension within which to check an element exists
• Name - The identifier of the element

Example

if( element.exists("Account", "600010") ) {  
    //do something
}

Returns the name of an element from the alias.

element.principal(dimension, alias)

Parameters

• Dimension - The dimension in which to identify the element
• Alias - The alias of the element to identify

Example

element.principal("Account","Net Profit");

These functions are used to manipulate dimension hierarchies where its not possible to discern the depth of the dimension from the datasource.

• blueprint.create(String blueprintIdentifier)
• blueprint.add(String blueprintIdentifier, String elementName)
• blueprint.addChild(String blueprintIdentifier, String parentName, String childName)
• blueprint.publish(String dimensionName, String hierarchyName, String blueprint)

Adds a member to the blueprint.

Creates a blueprint for a hierarchy which can then be applied to any dimension.

blueprint.add(name, elementName) 

Parameters

• Name - An identifier used as the blueprint name.
• elementName - An identifier used as an element under said blueprint.

Example

blueprint.add("Default");

Adds a member as a child of another member.

blueprint.addChild(name, parentName, childName)

Parameters

• name- An identifier used when referencing the created blueprint.
• parentName - An identifier used when referencing the parent of the created blueprint.
• childName - An identifier used when referencing the child created blueprint.

Example

blueprint.addChild("Default");

Creates a blueprint.

Creates a temporary blueprint object which can be used to update a dimension hierarchy. This is useful when the depth of a hierarchy is not easily predictable. When published the blueprint will add elements to both the hierarchy and its underlying dimension as required.

hierarchy.blueprint.create(blueprintIdentifier)

Parameters

• blueprintIdentifier - An identifier used when later referencing the created blueprint.

Example

hierarchy.blueprint.create("Default");

Apply a blueprint to a hierarchy.

Applies a blueprint to a hierarchy, creating members in a dimension as well as a hierarchy where required.

blueprint.publish(dimensionName, hierarchy, blueprint)

Parameters

• dimensionName - An identifier used as the dimension name in which to add the hierarchy to.
• Hierarchy - The identifier of the hiearachy to overwrite.
• Blueprint - The identifier of the blueprint published.

Example

blueprint.publish("Default");

These functions are used to manipulate dimension hierarchies.

• hierarchy.create(String dimensionName, String hierarchyName)
• hierarchy.delete(String dimensionName, String hierarchyName)
• hierarchy.exists(String dimensionName, String hierarchyName)
• hierarchy.group(String dimensionName, String hierarchyName,String parent,String child)
• hierarchy.hasMember(String dimensionName, String hierarchyName, String element)
• hierarchy.hasRootMember(String dimensionName, String hierarchyName, String element)
• hierarchy.rootElements(String hierarchyName, int limit)
• hierarchy.rootMember(String dimensionName, String hierarchyName)
• hierarchy.structure(String dimensionName, String hierarchyName,String parent,String child)
• hierarchy.wipe(String dimensionName, String hierarchyName)
• hierarchy.childCount(String dimensionName, String hierarchyName, String element)
• hierarchy.childByIndex(String dimensionName, String hierarchyName, String element, String index)
• hierarchy.parentCount(String dimensionName, String hierarchyName, String element)
• hierarchy.parentByIndex(String dimensionName, String hierarchyName, String element, String index)
• hierarchy.offset(String dimension, String hierarchy, String element, int shift)

Returns the name of a child element of a parent element in a hierarchy.

hierarchy.childByIndex(dimension, hierarchy, element, index)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to search
• Element - The identifier of the parent element
• Index - A Zero-based index of the child to return. (Zero is the first child)< /p>

Example

var child = hierarchy.childByIndex("Account","Management Profit and Loss","EBIT",0);

The "child" variable will be the name of the first child of the element "EBIT" in the Management Profit and Loss Hierarchy.

Returns the number of children of a parent element in a hierarchy.

hierarchy.childCount(dimension, hierarchy, element)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to search
• Element - The identifier of the parent element

Example

var childrenCount = hierarchy.childCount("Account","Management Profit and Loss","EBIT");

Creates a hierarchy within a dimension

hierarchy.create(dimension, hierarchy)

Parameters

• Dimension - The dimension in which to create a hierarchy
• Hierarchy - The identifier of the hierarchy created

Example

hierarchy.create("Account","Profit and Loss");

Deletes a hierarchy within a dimension

hierarchy.delete(dimension, hierarchy)

Parameters

• Dimension - The dimension in which to delete a hierarchy
• Hierarchy - The identifier of the hierarchy to be deleted

Example

hierarchy.delete("Account","Profit and Loss");

Returns a boolean.

hierarchy.elementHasAncestor(dimensionName, hierarchyName, elementName, ancestorName)

Parameters

• dimensionName - The dimension.
• hierarchyName - Name of Hierarchy
• elementName - Child element to be tested
• ancestorName - The ancestor element name (note. you can prefex with the hierarchy).

Example

var value = hierarchy.elementHasAncestor("Time","Default (Calendar)","August","2015");

Checks whether a hierarchy exists

Returns a boolean value.

hierarchy.exists(dimension, name)

Parameters

• Dimension - The dimension within which to check a hierarchy exists
• Name - The identifier of the hierarchy

Example

if( hierarchy.exists("Account", "Profit and Loss")) {
    //do something
}

Adds a dimension member as a child of a hierarchy member. Note this function is used when linking a hierarchy member as a parent of a dimension member.

hierarchy.group(dimension, hierarchy, parent, child)

Parameters

• Dimension - The dimension in which to create a relationship
• Hierarchy - The identifier of the hierarchy in which to create a relationship
• Parent - The identifier of a member which may/maynot exist
• Child - The identifier of a member which may/may not exist

Example

hierarchy.group("Account","Profit and Loss", "Total Revenue", "600010");

Checks whether a member exists within a hierarchy

Returns a boolean value.

hierarchy.hasMember(dimension, hierarchy, name)

Parameters

• Dimension - The dimension in which the hierarchy exists
• Hierarchy - The hierarchy in which to check for a member
• Name - The identifier of the member

Example

if (hierarchy.hasMember("Account", "Profit and Loss", "Operating Expenditure")) {
    //do something
}

Checks if a hierarchy has a specific element as its root member

Returns a boolean value.

hierarchy.hasRootMember(dimension, hierarchy, name)

Parameters

• Dimension - The dimension in which the hierarchy exists in which to check for a root member
• Hierarchy - The hierarchy in which to check for a root member
• Name - The identifier of the root member

Example

if( hierarchy.hasRootMember("Account", "Profit and Loss", "EBITDA") ) {  
    //do something  
}

Returns an element from a hierarchy based on the offset

This function returns an element from hierarchy based on the offset provided. Please note that this function always returns a string value.

hierarchy.offset(dimension, hierarchy, element, shift)

Parameters

• Dimension - The dimension in which to create a relationship
• Hierarchy - The identifier of the hierarchy in which to create a relationship
• Element - The identifier of an element which may/maynot exist
• Shift - The offset value

Example

var element = hierarchy.offset("Account","Profit and Loss", "EBITDA", 2);

Returns the name of a parent element in a hierarchy.

hierarchy.parentByIndex(dimension, hierarchy, element, index)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to search
• Element - The identifier of the parent element
• Index - A Zero-based index of the parent to return. (Zero is the first parent)

Example

var child = hierarchy.parentByIndex("Account","Management Profit and Loss","EBIT",0);

The "parent" variable will be the name of the first parent of the element "EBIT" in the Management Profit and Loss Hierarchy.

Returns the number of parent elements in a hierarchy.

hierarchy.parentCount(dimension, hierarchy, element)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to search
• Element - The identifier of the parent element

Example

var count = hierarchy.childCount("Account","Management Profit and Loss","EBIT");

Returns the position of an element in the hierarchy.

hierarchy.position(dimension, hierarchy, element)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to search
• Element - The identifier of the element to get the position of

Example

var position = hierarchy.position("Account","Management Profit and Loss","EBIT");

Returns all the root elements for a hierarchy in a dimension

Returns a JSON string.

hierarchy.rootElements(dimension, hierarchy)

Parameters

• Dimension - The dimension in which the hierarchy exists in which to check for a root elements
• Hierarchy - The hierarchy in which root members need to be listed

Example

var members = JSON.parse(hierarchy.rootElements("Account", "Profit and Loss"));

Adds a hierarchy member as a child of another hierarchy member

Adds a hierarchy member as a child of another hierarchy member. Note this function is used when linking two hierarchy members which are both parents of their respective children.

hierarchy.structure(dimension, hierarchy, parent, child)

Parameters

• Dimension - The dimension in which to create a relationship
• Hierarchy - The identifier of the hierarchy in which to create a relationship
• Parent - The identifier of a member which may/maynot exist
• Child - The identifier of a member which may/may not exist

Example

hierarchy.structure("Account","Profit and Loss", "EBITDA", "Total Revenue");

Removes the structure from a hierarchy from a specified element down through all its descendants. 

hierarchy.unqind(dimension, hierarchy, parent)

Parameters

• Dimension - The dimension in which to create a relationship
• Hierarchy - The identifier of the hierarchy in which to create a relationship
• Parent - The identifier of a member to unwind from

Example

hierarchy.unwind("Account","Profit and Loss", "EBITDA");

This function will remove all structure under EBITDA within the Profit and Loss hierarchy of the Account dimension.

Wipes the elements of a hierarchy

hierarchy.wipe(dimension, hierarchy)

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy to be wiped

Example

hierarchy.wipe("Account", "Default");

These functions are used to post and pull data from external websites.

• http.document(String url, String method, String postData)
• http.download(String url, String method, String postData, String saveAsFilename)
• http.raw(String url, String method, String postData)
• http.headersAdd(String key, String value)
• http.headersClear()

Performs a HTTP Request

This function downloads a webpage and returns a document object model using the jsoup library. For more information on how to traverse a document visit http://jsoup.org/.

http.document(url, method, postData)

Parameters

• url - the URL of the resource to download.
• method - the method of the request (GET or POST).
• postData - the post data to send to the server.

Example

var doc = http.document("www.google.com","GET","");

Performs a HTTP Request

This function downloads a resource and stores it ias the provided file name in the MODLR Filesystem. This can be accessed via processes using the MODLR Filesystem or through the MODLR FTP Server.

http.download(url, method, postData, saveAsFilename)

Parameters

• url - the URL of the resource to download.
• method - the method of the request (GET or POST).
• postData - the post data to send to the server.
• saveAsFilename - the name and subfolder to store this file as.

Example

var success = http.download("https://go.modlr.co/images/logo.png","GET","","logo.png");

Adds an item to the header for the next HTTP Request

This function adds an item to the header for the next HTTP Request

http.headersAdd(key, value)

Parameters

• key - the header key
• value - the header value

Example

http.headersAdd("Token", "1");

Wipes the current HTTP Request headers

This function clears the headers set in the HTTP request.

http.headersClear();

Performs a HTTP Request

This function downloads a resource and stores it into a String.

http.raw(url, method, postData)

Parameters

• url - the URL of the resource to download.
• method - the method of the request (GET or POST).
• postData - the post data to send to the server.

Example

var html = http.raw("www.google.com","GET","");

These functions are used to notify collaborators via Processes or Custom Pages.

• notification.sms(int userId, String content)
• notification.email(Stirng to, String from, String subject, String html)

Sends an email

This function can be used to send a notification through email. Returns an integer.

notification.email(to, from, subject, html)

Parameters

• to - Recipient of the email.
• from - Sender of the email.
• subject - Subject of the email.
• html - Content of the email.

Example

notification.email("support@modlr.co", "admin@modlr.co", "Hello", "Hello Support");

Sends a SMS

This function can be used to send a notification through SMS. Returns an integer.

notification.sms(userId, content)

Parameters

• userId - Unique Identifier of an user
• content - Content of the SMS

Please note that the recipient must have a phone number for this to be delivered. Users can update phone numbers from Manage Account page

Example

notification.sms(1, "Hello. This is a test SMS");

These functions are used to manipulate a model mapping.

• mapping.create(String mappingName, String[] leftDimensions, String[] rightDimensions)
• mapping.delete(String mappingName)
• mapping.exists(String mappingName)
• mapping.wipe(String mappingName)
• mapping.findUsingLeft(String mappingName, String[] leftKeys)
• mapping.findUsingRight(String mappingName, String[] rightKeys)
• mapping.rowAdd(String mappingName, String[] leftKeys, String[] rightKeys)
• mapping.rowUpdate(String mappingName, int rowId, String[] leftKeys, String[] rightKeys)
• mapping.rowDelete(String mappingName, int rowId)

Creates a mapping table with the given name. 

Note: Mappings are bidirectional, meaning when used in a cube formula it is possible to map from left-to-right and right-to-left.

mapping.create(mappingName,leftDimensions, rightDimensions);

Parameters

• mappingName - An identifier used to find the target mapping.
• leftDimensions - An Array of strings which are the dimension names to include in the left side of the mapping.
• rightDimensions - An Array of strings which are the dimension names to include in the right side of the mapping.

Example

var res = mapping.create("Time to Year and Month",["Time"],["Year","Month"]);

"Time to Year and Month". If the mapping already exists or a dimension does not exist the function will return false.

Deletes a mapping with the given name.

mapping.delete(mappingName);

Parameters

• mappingName - An identifier used to find the target mapping.

Example

var res = mapping.delete("Time to Year and Month");

If a mapping exists with this name the mapping will be deleted and the res variable will be set to true.

Returns true or false if the mapping exists or does not.

mapping.exists(mappingName);

Parameters

• mappingName - An identifier used to find the target mapping.

Example

if(mapping.exists("Time to Year and Month")) {
    //it exists
}

If a mapping exists with this name the code inside the if statement will run, otherwise it will be skipped.

Adds a row within a mapping table. If the unique combination of keys for one side of the mapping conflict with another row, the other row is removed from the mapping table. This ensures that there is always a 1:1 mapping between keys on each side of the mapping.

mapping.rowAdd(mappingName, leftKeys, rightKeys);

Parameters

• mappingName - An identifier used to find the target mapping.

• leftKeys - An Array of strings representing elements from each of the mapping dimensions on the left side of the mapping table in order.

• rightKeys - An Array of strings representing elements from each of the mapping dimensions on the right side of the mapping table in order.

Example

mapping.rowAdd("Time to Year and Month", ["FY2017 - Jul"], ["2017","Jul"]);

This adds a new mapping between the Time dimension and the Year and Month dimensions allowing the mapping to be used in a cube formula linking two cubes with different dimensionality.

All elements specified on each side of the mapping need to be currently existing elements in the mapping dimensions.

Deletes a row within a mapping table.

mapping.rowDelete(mappingName, rowId);

Parameters

• mappingName - An identifier used to find the target mapping.
• rowId - An identifier for the target row.

Example

mapping.rowDelete("Time to Year and Month", 1);

This removes the row with an identifier of 1 from the mapping table "Time to Year and Month".

Updates a row within a mapping table. If the unique combination of keys for one side of the mapping conflict with another row, the other row is removed from the mapping table. This ensures that there is always a 1:1 mapping between keys on each side of the mapping.

mapping.rowUpdate(mappingName, rowId, leftKeys, rightKeys);

Parameters

• mappingName - An identifier used to find the target mapping.
• rowId - An identifier for the target row.
• leftKeys - An Array of strings representing elements from each of the mapping dimensions on the left side of the mapping table in order.
• rightKeys - An Array of strings representing elements from each of the mapping dimensions on the right side of the mapping table in order.

Example

mapping.rowUpdate("Time to Year and Month", 1, ["FY2017 - Jul"], ["2017","Jul"]);

All elements specified on each side of the mapping need to be currently existing elements in the mapping dimensions.

Returns the definition for a row of the mapping table as a String of JSON Data.

mapping.findUsingLeft(mappingName, leftKeys);

Parameters

• mappingName - An identifier used to find the target mapping.
• rightKeys - An Array of strings representing elements from each of the mapping dimensions on the right side of the mapping table in order.

Example

var row = JSON.parse(mapping.findUsingLeft("Time to Year and Month", ["FY2017 - Jul"]));
console.log(row);

This returns a row mapping (if it exists) with the left keys being equal to the "FY2017 - Jul" element form the Time dimension . The resulting output could appear as follows:
{"id":1,"left":["FY2017 - Jul"],"right":["2017","Jul"]}

Returns the definition for a row of the mapping table as a String of JSON Data.

mapping.findUsingRight(mappingName, rightKeys);

Parameters

• mappingName - An identifier used to find the target mapping.
• rightKeys - An Array of strings representing elements from each of the mapping dimensions on the right side of the mapping table in order.

Example

var row = JSON.parse(mapping.findUsingRight("Time to Year and Month", ["2017","Jul"]));
console.log(row);

This returns a row mapping (if it exists) with the right keys being equal to the "2017" element form the Year dimension and "Jul" element from the Month dimension. The resulting output could appear as follows:
{"id":1,"left":["FY2017 - Jul"],"right":["2017","Jul"]}

Wipes all rows from a Mapping within a Model. This function also resets the identifier numbering in the mapping.

mapping.wipe(mappingName);

Parameters

• mappingName - An identifier used to find the target mapping.

Example

mapping.wipe("Mapping Name");

These functions are used to manipulate text and commentary.

• script.abort(String reasonString)
• script.escape(String inputStr)
• script.getQuery()
• script.library(String pathToJSFile)
• script.log(String message)
• script.md5(String stringToEncode)
• script.modelName()
• script.modelId()
• script.processName()
• script.processId()
• script.prompt(String messageToUser,String variableName,String defaultValue)
• script.qrcode(String input, int sizeInPixels)
• script.save()
• script.setQuery(String sql)
• script.variableSet(String key, String value)
• script.variableDelete(String key)
• script.processUpdateQuery(String sql)
• script.variableGet(String key)
• script.execute(String processName, String prompt_name_1, String prompt_value_1, String prompt_name_N, String prompt_value_N)
• script.getUserId()
• script.getUserName()
• script.getUserEmail()
• script.getAccessTag(String email)
• script.getTaggedUsers(String tag)
• script.save()

Stops a running process and reports the specified reason in the message log.

This function is used cancel the execution of a process when an handled error has occurred.

script.abort(reasonText) 

Parameters

• reasonText - the line of text to output which explains why the process is aborting.

Example

script.abort('Something was not as expected.');

Sanitizes the provided string.

This function is commonly used to sanitize input from users which is then going to form part of a SQL query.

script.escape(inputStr)

Parameters

• inputStr - the string which needs to be escaped/sanitized.

Example

var valueForSQL = script.escape("It's usually not ok to have a single quote in a SQL statement.");

the result in valueForSQL will be "It\'s usually not ok to have a single quote in a SQL statement." which will no longer break a SQL statement.

Executes another process

This function is used to run another process. Prompt values can be passed to the sub process.

script.execute(processName, prompt_name_1, prompt_value_1, prompt_name_N, prompt_value_N)

Parameters

• processName - the name of the process to run.
• prompt_name_1 - the first prompt which the sub process requires.
• prompt_value_1 - the first prompt's value which the sub process requires.

Example

var success = script.execute("Dimension - Department - Add","deptName","Finance");

the result in success will be either true or false depending on if the sub process aborted or not.

Returns the access tags of the specified user.

script.getAccessTags(user_email)

Parameters

• user_email - Email Address.

Example

var access = script.getAccessTags(user_email);

Returns the query which is sourcing data

This function is commonly used to retrieve the SQL used in the datasource.

script.getQuery()

Parameters

None

Example

var query = script.getQuery();

Returns the users under specified tag.

script.getTaggedUsers(tag)

Parameters

• tag - Name of the tag.

Example

var users = script.getTaggedUsers(tag);

Returns the email address of the calling user.

script.getUserEmail(userId)

Parameters

• userId - Optional. If specified, it retrieves the email of that user.

Example

var user_email = script.getUserEmail();

Returns the identifier of the calling user.

script.getUserId()

Parameters

None.

Example

var userId = script.getUserId();

Returns the username of the calling user.

script.getUserName(userId)

Parameters

• userId - Optional. If specified, it retrieves the username of that user..

Example

var userName = script.getUserName();

Load a custom javascript library

This function is used to import another javascript file which has been uploaded to the server via FTP. This provides all the library functions and variables from within the chosen library to the processes available functions and variables.

script.library(pathToJSFile)

Parameters

• pathToJSFile - The relative path from the MODLR FTP Root Directory.

Example

script.library('dimension-functions.js');

This will open the file called "dimension-functions.js" found in the root directory of the MODLR ftp server.

Write a line of text to the log file.

This function is commonly used to debug or output status updates from scripts in processes.

script.log(outputText)

Parameters

• outputText - the line of text to output.

Example

script.log('The processes has commenced')

Creates a MD5 Hash

This function is commonly used to store passwords in databases without them being readable or recoverable.

script.md5(inputStr)

Parameters

• inputStr - the string which needs to be hashed.

Example

var hash = script.md5("PasswordString");

Returns the identifier of the model.

Returns the identifier of the model within which this process exists.

script.modelId()

Parameters

None.

Example

var modelId = script.modelId();

Returns the name of the model.

Returns the name of the model within which this process exists.

script.modelName()

Parameters

None.

Example

var modelName = script.modelName();

Returns the identifier of the process which is executing.

script.processId();

Parameters

None.

Example

var processId = script.processId();

Returns the name of the process which is executing.

script.processName()

Parameters

None.

Example

var processName = script.processName();

Update the query which is sourcing data

This function is commonly used to update the SQL provided to the datasource based on user input from a prompt.

script.processUpdateQuery(sqlQuery)

Parameters

• sqlQuery - a string value which is the updated sql.

Example

var sqlQuery = "SELECT * FROM products";
script.processUpdateQuery(sqlQuery);

Prompts the user for input.

When used in the pre() function, upon execution of the process this function will raise a question to the user executing the process.

script.prompt(messageToUser,variableName,defaultValue)

Parameters

• messageToUser - the name of the request to the user (who is executing the process).
• variableName - the variable within which to store the users response.
• defaultValue - the default value to prepopulate the prompt with.

Example

script.prompt("Current Month","current_month","2014 - Jan");

Creates a QR Code image from a data string.

This function is used to create a QR Code in Portable Network Graphics (PNG) format. This function returns the image in Base64 data encoded string.

script.qrcode(inputStr)

Parameters

• inputStr - the data string to be encoded.
• size - an integer being the width and height of the resulting image.

Example

var base64Image = script.qrcode("Data to encode", 300);

the result in base64Image will be the raw base 64 encoded image.

Performs a server save

script.save()

Parameters

None

Deletes a Model Variable permanently

Deletes a variable in the Model. Note this function is permanent.

script.variableDelete(key)

Parameters

• key - The identifier of the variable to be deleted.

Example

script.variableDelete("Current Month");

Returns the value of a Model Variable

script.variableGet(key)

Parameters

• key - An identifier for the variable.

Example

var value = script.variableGet("Current Month");

Sets or creates a variable in the Model.

script.variableSet(key,value)

Parameters

• key - An identifier for the variable.
• value - The value to set the variable to.

Example

script.variableSet("Current Month","2014 - Jan");

• Account User Management
  • security.users()
  • security.createUser(String name, String email, String mobile)
  • security.resetUserPassword(int userId)
  • security.removeUser(int userId)
  • security.currentUserEmail()
  • security.currentUserName()
  • security.currentUserId()
  • security.getUserEmail(int userId)
  • security.getUserName(int userId)
  • security.getUserId(String email)
• Application User Management
  • security.applicationUsers(String applicationId)
  • security.applicationAddUser(String applicationId , int userId,String activity, String tags)
  • security.applicationRemoveUser(String applicationId , int userId)
  • security.applicationWipeUsers(String applicationId)
• Application Tag Management
  • security.applicationTags(String applicationId)
  • security.applicationTaggedUsers(String applicationId, String tagIdOrName)
  • security.applicationRemoveAllTags(String applicationId)
  • security.applicationRemoveTag(String applicationId, String tagIdOrName)
  • security.applicationAddTag(String applicationId, String tagName, String dimensionId,String hierarchyId, boolean All)
  • security.applicationWipeTagElementSecurity(String applicationId, String tagIdOrName)
  • security.applicationAddTagElementSecurity(String applicationId, String tagIdOrName, String hierarchy, String element, String access)
• Application User Tag Management
  • security.applicationUserTags(String applicationId, int userId)
  • security.applicationUserRemoveAllTags(String applicationId, int userId)
  • security.applicationUserRemoveTag(String applicationId, int userId, String tagIdOrName)
  • security.applicationUserAddTag(String applicationId, int userId, String tagIdOrName)
  • security.applicationUserSetTags(String applicationId, int userId, String tagIdsOrNamesPipeDel)

Adds a tag to an application. Returns a boolean value depending on the outcome.

security.applicationAddTag(applicationId, tag, hierarchyId, AllElements)

Parameters

• applicationId - Identifier of the activity
• tag - Tag name
• hierarchyId - Identifier of the hierarchy
• AllElements - If it should be added for all elements in the hierarchy

Example

var arr = security.applicationAddTag("MyActivityId", "Admin", "HierarchyId", false);

Add element security for a tag in an application. Returns a boolean value depending on the outcome.

var boolean = security.applicationAddTagElementSecurity(applicationId, tag, element, access);

Parameters

• applicationId - Identifier of the activity
• tag - Tag name or Identifier
• element - Name of the element
• access - Name of the access

Adds a user to an application.

security.applicationAddUser(applicationId, userId, tags)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• tags - Tags that should be set

Example

var arr = security.applicationAddUser("MyActivityId", 1, "Admin");

Removes all tags in an application. Returns a boolean value depending on the outcome.

security.applicationRemoveAllTags(applicationId)

Parameters

• applicationId - Identifier of the activity

Example

var arr = security.applicationRemoveAllTags("MyActivityId");

Removes a tag from an application.

security.applicationRemoveTag(applicationId, tag)

Parameters

• applicationId - Identifier of the activity
• tag - Tag name or Identifier

Example

var arr = security.applicationRemoveTag("MyActivityId", "Admin");

Adds a user to an application.

security.applicationRemoveUser(applicationId, userId, activity)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• activity - Optional

Example

var arr = security.applicationRemoveUser("MyActivityId", 1, "Admin");

Checks whether a tag exists on an application. Returns a boolean value.

security.applicationTagExists(applicationId, tag)

Parameters

• applicationId - Identifier of the activity
• tag - Tag to be checked in the activity

Example

var boolean = security.applicationTagExists("MyActivityId", "Tag");

Returns the list of users with a particular tag in an application

security.applicationTaggedUsers(applicationId, tag)

Parameters

• applicationId - Identifier of the activity
• tag - Tag name or identifier to be checked in the activity

Example

var arr = security.applicationTaggedUsers("MyActivityId", "Tag");

Returns the tags on an application.

security.applicationTags(applicationId)

Parameters

• applicationId - Identifier of the activity

Example

var arr = security.applicationTags("MyActivityId");

Add a tag to an user in an application. Returns a boolean value depending on the outcome.

security.applicationUserAddTag(applicationId, userId, tag)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• tag - Tag name or identifier

Example

var boolean = security.applicationUserAddTag("MyActivityId", 1, "Admin");

Removes all tags for an user in an application. Returns a boolean value depending on the outcome.

security.applicationUserRemoveAllTags(applicationId, userId)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)

Example

var bool = security.applicationUserRemoveAllTags("MyActivityId", 1);

Removes a tag for an user in an application. Returns a boolean value depending on the outcome.

security.applicationUserRemoveTag(applicationId, userId, tag)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• tag - Tag name or identifier

Example

var boolean = security.applicationUserRemoveTag("MyActivityId", 1, "Admin");

Returns the users on an application.

security.applicationUsers(applicationId)

Parameters

• applicationId - Identifier of the activity

Example

var arr = security.applicationUsers("MyActivityId");

Sets tag (removes existing tags and adds this) to an user in an application. Returns a boolean value depending on the outcome.

security.applicationUserSetTags(applicationId, userId, tag)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• tag - Tag names or identifiers

Example

 var boolean = security.applicationUserSetTags("MyActivityId", 1, "Admin");

Returns the list of tags for a particular user in an application. Returns a JSON string.

security.applicationUserTags(applicationId, userId)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)

Example

var arr = security.applicationUserTags("MyActivityId", 1);

Removes element security for a tag from an application. Returns a boolean value depending on the outcome.

security.applicationWipeTagElementSecurity(applicationId, tag)

Parameters

• applicationId - Identifier of the activity
• tag - Tag name or Identifier

Example

var arr = security.applicationWipeTagElementSecurity("MyActivityId", "Admin");

Wipes all users in an application

security.applicationWipeUsers(applicationId)

Parameters

• applicationId - Identifier of the activity

Example

var arr = security.applicationRemoveUser("MyActivityId");

Creates an user

security.createUser(name,email,mobile)

Parameters

• name - Name of the user
• email - Email address of the user
• mobile - Mobile number of the user

Example

var user = security.createUser("admin", "admin@modlr.co", "0123 456 789");

Retrieves the email of the current user

var user_email = security.currentUserEmail();

Parameters

None

Retrieves the Id of the current user

var userid = security.currentUserId();

Parameters

None

Retrieves the username of the current user

var username = security.currentUserName();

Parameters

None

Removes an user from the specified model

security.removeUser(userId)

Parameters

• userId - Unique Identifier of an user

Example

security.removeUser("123");

Returns the users on an account as a JSON array.

var arrString = security.users();

Parameters

none

Example

var arr = JSON.parse(security.users());

This example sets arr to an array of user data.

These functions are used for managing templates.

• templates.apply(String template)
• templates.context(data object)
• templates.registerHelpers(String fileLibrary)

Applies a template 

templates.apply(template)

Parameters

None

Example

templates.apply("template");

Populates the template variables (inside handlebars {{}}) with data.

templates.context(data)

Parameters

• data - an object containing template variables to use in a template

Example

<script runat="server"> 
    var data = { name: 'world' }; 
    template.context(data); 
</script> 

<div>
    <h1>Hello, {{name}}!</h1>
</div>

Registers a handlebar helper

templates.registerHelpers(fileLibrary)

Parameters

• fileLibrary - Name of the library file that should be registered

Example

templates.registerHelpers("file.extension");

These functions are used to manipulate Microsoft Excel Workbooks. This set of functions use the XSSFWorkbook class object. Please refer to the documentation for this class for its properties and methods.

• workbook.create()
• workbook.open(String filename)
• workbook.convertToBase64(Workbook wb)
• workbook.convertFromBase64(String base64)
• workbook.workbookFromQuery(String datasourceName, String sql)
• workbook.getColumnName(int columnNumber)

Returns a workbook that has been decoded from Base64

Example

var wb = workbook.convertFromBase64(base64str);

Parameters

• base64str - Base64 data

Returns Base64 encoded data from a workbook.

Example

var wb = workbook.convertToBase64(workbook_obj);

Parameters

• workbook_obj - Workbook object that should be encoded

Returns a new Workbook Object.

Returns a new Workbook XSSFWorkbook Object using the POI library. For a full reference please visit the library webside here: XSSFWorkbook.

Example

var wb = workbook.create();

Parameters

None.

Returns the name of a column based on the column number

Example

var column_name = workbook.getColumnName(columnNumber);

Parameters

• columnNumber - Position/Index of the column on a workbook

Opens a Excel Workbook which is in the Server FTP Folder.

Example

var wb = workbook.open(filename);

Parameters

• filename - Name of the file that is to be opened

Returns a workbook from a JDBC SQL query.

Example

var wb = workbook.workbookFromQuery(datasource, query, prompts);

Parameters

• datasource - Name of the JDBC datasource
• query - SQL query
• prompts (optional) - Parameterized values

These functions are used to interact with Workviews.

• workview.cache(String workview)
• workview.execute(String workview, Object titleDimensions,Object titleElements)
• workview.visualize(String workview, Object titleDimensions,Object titleElements)

Caches a workview within the specified model

Example

var wv = workview.cache(workview);

Parameters

• workview - Name or Identifier of the Workview

Executes a Workview

This function executes a Workview and returns a JSON object.

Example

var wv = workview.execute(workview, titleDimensions, titleElements);

Parameters

• workview - Name or Identifier of the Workview
• titleDimensions - Dimensions
• titleElements - Elements

This function returns the visualization of the Workview.

Example

var wv = workview.visualize(workview, titleDimensions, titleElements);

Parameters

• workview - Name or Identifier of the Workview
• titleDimensions - Dimensions
• titleElements - Elements