New Functions

The following is a list of functions added in the July 2021 update.

• datasource.csv(String fileName)
• datasource.csvRead(String fileName, int skipLines)
• http.base64(String url, String method, String post)
• script.getRecordsProcessed()
• script.shell(String command)
• workview.definitionGet(String workviewName)

Supported from engine version 2.5.466

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");

Creates an alias within a dimension if it doesn't exist, or wipes the data on the alias if it already exists.

alias.createOrWipe(dimension, aliasName); 

Parameters

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

Example

alias.createOrWipe("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, [returnPrincipalIfMissing]) 

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
• returnPrincipalIfMissing - Optional, Boolean, if the alias is not set should the function return the principal name.

The returnPrincipalIfMissing argument is supported from version 2.4.891 onwards.

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');

Following are the functions for the CSVReader object returned from the datasource.csvRead function. These functions are used to read data from the csv file specified in the datasource.csvRead function.

• close()
• getDelimeter()
• getLineBreak()
• getQuoteString()
• isEOF()
• read()
• setDelimeter(String delim)
• setLineBreak(String lb)
• setQuoteCharacter(String quote)

Closes the stream to the CSV file. The object the function is called with will no longer be useable. 

Parameters

No parameters

Example

var csv = datasource.csvRead("example_file.csv", 0);
csv.close(); 

Returns the character the csv reader object is using to split data into cells in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csvRead("example_file.csv", 0);
​var delim = csv.getDelimeter();​​​​​​
console.log(delim);

Output: ,

Returns the character the csv reader object is using to signify a line break in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csvRead("example_file.csv", 0);
​var lb = csv.getLineBreak();​​​​​​
console.log(lb);

Output: \r\n

Returns the character the csv reader object is using to signify quotes in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csvRead("example_file.csv", 0);
​var qc = csv.getQuoteCharacter();​​​​​​
console.log(qc);

Output: "

Returns a boolean. Returns true if there is no more lines of the csv file to be read. Returns false if there are more lines to read. 

Parameters

No parameters

Example

let csv = datasource.csvRead("example_file.csv);
while(!csv.EOF()) {
    let line = csv.read();
    console.log(line);
}

This will log all lines of the csv file into the console in a JSON format.

Returns the next line from the csv file in a JSON format. 

Parameters

No parameters

Example

let csv = datasource.csvRead("example_file.csv", 0);
while(!csv.EOF()) {
    let line = csv.read();
    let values = JSON.parse(line);
    console.log(values);
}

This will log all lines of the csv file into the console.

Set the delimeter character that the CSV Reader object uses to read the connected csv file.

csv.setLineBreak(delim);

Parameters

• delim - String of the character to be used delimeting the csv file

Example 

var csv = datasource.csvRead("example_file.csv", 0);
csv.setDelimeter(",");

This will set the delimeter character to a , (comma).

Set the quote character that the CSV Reader object uses to read the connected csv file.

csv.setLineBreak(lineBreak);

Parameters

• lineBreak - String of the character to be used for a line breaks

Example 

var csv = datasource.csvRead("example_file.csv", 0);
csv.setLineBreak("\n");

This will set the line break character to a \n (new line character).

Set the quote character that the CSV Reader object uses to read the connected csv file.

csv.setQuoteCharacter(quoteCharacter);

Parameters

• quoteCharacter - String of the character to be used for a quote character

Example 

var csv = datasource.csvRead("example_file.csv", 0);
csv.setQuoteCharacter("\"");
//alternatively
csv.setQuoteCharacter('"');

This will set the quote character to a " (quotation mark).

Following are the functions for the CSVWriter object returned from the datasource.csv function. These functions are used to write to the csv file specified in the datasource.csv function.

• close()
• getDelimeter()
• getLineBreak()
• getQuoteCharacter()
• setDelimeter(String delim)
• setLineBreak(String lb)
• setQuoteCharacter(String quote)
• write(Object data)

Closes the stream to the CSV file. The object the function is called with will no longer be useable. 

Parameters

No parameters

Example

var csv = datasource.csv("example_file.csv");
csv.close(); 

Returns the character the csv writer object is using to split data into cells in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csv("example_file.csv");
​var delim = csv.getDelimeter();​​​​​​
console.log(delim);

Output: ,

Returns the character the csv writer object is using to signify line breaks in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csv("example_file.csv");
​var lb = csv.getLineBreak();​​​​​​
console.log(lb);

Output: \r\n

Returns the character the csv writer object is using to signify quotes in the connected csv file.

Parameters

No parameters

Example

var csv = datasource.csv("example_file.csv");
​var qc = csv.getQuoteCharacter();​​​​​​
console.log(qc);

Output: "

Set the delimeter character that the CSV Writer object uses to write to the connected csv file.

csv.setLineBreak(delim);

Parameters

• delim - String of the character to be used delimeting the csv file

Example 

var csv = datasource.csv("example_file.csv");
csv.setDelimeter(",");

This will set the delimeter character to a , (comma).

Set the quote character that the CSV Reader object uses to write to the connected csv file.

csv.setLineBreak(lineBreak);

Parameters

• lineBreak - String of the character to be used for a line breaks

Example 

var csv = datasource.csv("example_file.csv");
csv.setLineBreak("\n");

This will set the line break character to a \n (new line character).

Set the quote character that the CSV Writer object uses to write to the connected csv file.

csv.setQuoteCharacter(quoteCharacter);

Parameters

• quoteCharacter - String of the character to be used for a quote character

Example 

var csv = datasource.csv("example_file.csv");
csv.setQuoteCharacter("\"");
//alternatively
csv.setQuoteCharacter('"');

This will set the quote character to a " (quotation mark).

Inserts an array into the connected csv file as a new line. 

csv.write(array);

Parameters

• array - An array of Strings, each element being a new colunm to be inserted in the row of the csv file.

Example

let csv = datasource.csv("example_file.csv);
let array = ["This", "is", "a", "new", "row", "of", "values", "in", "the", "csv", "file"];
csv.write(array);

This will insert a row with 11 separate values.

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");

Enable or disable cube formula evaluation. 

This is useful when adding lots of data to the cube in a short amount of time and formula evaluation might slow the process. Remember to re-enable it after.

cube.formulaEvaluation(cubeName, bShouldEvaluate);

Parameters

• cubeName - name of a cube.
• bShouldEvaluate - Boolean (true or false). Whether to run formula evaluation

Example

cube.formulaEvaluation("Profit and Loss", false); // Disable formula evalutions
// Do some heavy data input...
cube.formulaEvaluation("Profit and Loss", true); // Enable it

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")

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.");
}

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

Supported from version 2.4.910

Enable or disable cube wipe batching.

If the cube.wipe function is to be called multiple times, enabling the wipe batch will prevent unneccessary formula invalidations from occuring until the end of the batch.

Remember to turn batching off again once you have completed the cube,wipe calls, especially prior to running any cube.get calls.

cube.wipeBatchActive(cubeName, bSetBatchActive);

Parameters

• cubeName - name of a cube.
• bSetBatchActive - Boolean (true or false). Whether the batch is active.

Example

cube.wipeBatchActive("Profit and Loss", true); // Enable Batch Wipes
// Do some frequent cube.wipe calls ...

cube.wipeBatchActive("Profit and Loss", false); // Disable Batch Wipes

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 read or modify csv file, or to manipulate databases using SQL.

• datasource.csv(fileName)
• datasource.csvRead(fileName, int skipLines)
• 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)

Returns the specified csv file as an object. The returned object has multiple functions that are documented in CSV Writer.

datasource.csv(fileName)

Parameters

• fileName - The name and file path of the csv file in MODLR file system to be read. File path can be found in the filesystem page.

Example

var csv = datasource.csv("budget_review_2020.csv");

Returns the specified csv file as an object. The returned object has multiple functions that are documented in CSV Reader.

datasource.csvRead(fileName, skipLines)

Parameters

• fileName - The name and file path of the csv file in MODLR file system to be read. File path can be found in the filesystem page.
• skipLines - The number of lines to be skipped in the csv file.

Example

var csv = datasource.csvRead("budget_review_2020.csv", 0);

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] - Parameterized Values

Example

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] - Parameterized Values

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 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

Creates a dimension, if it doesn't exist, within the specified model of the given type. If it already exists, it wipes the data on the dimension.

dimension.createOrWipe(name, type);

Parameters

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

Example

dimension.createOrWipe("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 connect ftp to an FTP Server.

• ftp.Connect(String protocol, String host, int port, String username, String password)
• ftp.ConnectWithKey(String protocol, String host, int port, String username, String keyFile)
• FTPClient#IsConnected()
• FTPClient#Directory(String remoteDirectory)
• FTPClient#Upload(String localPath, String remotePath)
• FTPClient#Download(String remotePath, String localPath)
• FTPClient#Rename(String oldPath, String newPath)
• FTPClient#Delete(String remotePath)
• FTPClient#Disconnect()

Creates an FTPClient instance that can be used to interact with an ftp server.

var client = ftp.Connect(protocol, host, port, username, password);

Parameters

• protocol - The ftp protocol for this connecton. At the moment, only "sftp" is supported.
• host - The ftp host like a domain name or an ip address
• port - The port to use on the ftp connection
• username - The username to use
• password - The password for the user

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");

Creates an FTPClient instance that can be used to interact with an ftp server but using a key file to connect.

var client = ftp.ConnectWithKeyFile(protocol, host, port, username, keyFile);

Parameters

• protocol - The ftp protocol for this connecton. At the moment, only "sftp" is supported.
• host - The ftp host like a domain name or an ip address
• port - The port to use on the ftp connection
• username - The username to use
• keyFile - A key file

Example

var client = ftp.ConnectWithKeyFile("sftp", "example.domain.com", 22, "abby", "/path/to/key_file");

You can then interact with the ftp server using the FTPClient instance's methods.

Returns true if the client has successfully connected or false otherwise.

client.IsConnected();

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
var success = client.IsConnected();
if (success) {
    script.log('Connection successful');
}

Lists the files and folders under a directory. Returns a JSON array of directory items.

client.Directory(remoteDirectory);

Parameters

• remoteDirectory - The directory to list items of

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var list = JSON.parse(client.Directory('/remote/path'));
    console.log(list);
}

It should return a JSON array with a structure like the following:

[
    {
        "name": "a_folder",
        "isDirectory": true
    },
    {
        "name": "pub",
        "isDirectory": true
    },
    {
        "name": "readme.txt",
        "isDirectory": false
    }
]

Upload a local file to the a location in the remote ftp server. Returns true if the upload was successful or false otherwise.

client.Upload(localPath, remotePath);

Parameters

• localPath - The file to upload
• remotePath - The remote path where the file will be uploaded

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var result = client.Upload('MyFile.txt', '/remote/path');
    console.log("Uploading file result: " + result);
}

Download a remote file from the ftp server. Returns true if the download was successful or false otherwise.

client.Download(remotePath, localPath);

Parameters

• remotePath - The remote path to download
• localPath - The local path where the downloaded file will be

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var result = client.Download('/remote/path/README.md', '/local/README.md');
    console.log("Downloading file result: " + result);
}

Creates a directory on the ftp server. Returns true if the directory was created or false otherwise.

client.MakeDirectory(remoteDirectory);

Parameters

• remoteDirectory - The remote directory to create

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var result = client.MakeDirectory('/remote/path/docs');
    console.log("Make directory result: " + result);
}

Renames a remote file on the ftp server. Returns true if renaming was successful or false otherwise.

client.Rename(oldPath, newPath);

Parameters

• oldPath - The remote path to rename
• newPath - The new remote path

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var result = client.Rename('/remote/path/README.md', '/remote/path/README2.md');
    console.log("Renaming file result: " + result);
}

Delete a remote file in the ftp server. Returns true if it was successful or false otherwise.

client.Delete(remotePath);

Parameters

• remotePath - The remote path to delete

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
if (client.IsConnected()) {
    var result = client.Delete('/remote/path/README2.md');
    console.log("Deleting file result: " + result);
}

Disconnects the FTPClient.

client.Disconnect();

Example

var client = ftp.Connect("sftp", "example.domain.com", 22, "abby", "*******");
var success = client.IsConnected();
if (success) {
    // Do some ftp work...
    client.Disconnect();
}

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");

Creates a hierarchy within a dimension if it doesn't exist or wipes the data on the hierarchy if it exists.

hierarchy.createOrWipe(dimension, hierarchy)

Parameters

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

Example

hierarchy.createOrWipe("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, sign)

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
• Sign - (Optional) Determines whether the child's values will be added or subtracted from the parents values. Accepts -1 or 1 as integers.

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");

Removes a child element from a parent.

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

Parameters

• Dimension - The dimension in which the selected hierarchy exists
• Hierarchy - The identifier of the hierarchy
• Parent - The identifier of the direct parent of the child element
• Child - The identifier of the child element

Example

hierarchy.removeChild("Account", "Profit and Loss", "Revenue", "Other Sales");

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, sign)

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
• Sign - (Optional) Determines whether the child's values will be added or subtracted from the parents values. Accepts -1 or 1 as integers.

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.unwind(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.base64(String url, String method, String post)
• 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 converting binary data into base64 String. 

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

http.base64(url, method, post)

Parameters

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

Example

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

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: One to one mappings are bidirectional, meaning when used in a cube formula it is possible to map from left-to-right and right-to-left. One to many mappings will only work in one direction when used in cube formula.

mapping.create(mappingName, leftDimensions, rightDimensions, leftMany, rightMany);

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.
• leftMany - (Optional) A true or false which determines whether the elements in the left dimensions may map to many right elements.
• rightMany - (Optional) A true or false which determines whether the elements in the right dimensions may map to many left elements.

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.

var res = mapping.create("Date to Month",["Date"],["Month"],false,true);

"Date to 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.getRecordsProcessed()
• 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.shell(String command)
• 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 number of records a process has processed so far.

script.getRecordsProcessed()

Parameters

None

Example

var count = script.getRecordsProcessed();

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

Allows the user to execute a shell script which has been preconfigured on the MODLR instance (via the instance config file) this can only be arranged via the support process.

script.shell(command)

Parameters

• command - Name of shell command to be executed.

Example

script.shell("example_command_name");

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.createUser(String name, String email, String mobile)
  • security.currentUserEmail()
  • security.currentUserName()
  • security.currentUserId()
  • security.getUserEmail(int userId)
  • security.getUserName(int userId)
  • security.getUserId(String email)
  • security.removeUser(int userId)
  • security.resetUserPassword(int userId)
  • security.users()
• Application User Management
  • security.applicationAddUser(String applicationId , int userId,String activity, String tags)
  • security.applicationUsers(String applicationId)
  • security.applicationUserElements(String applicationId, int userId, String dimensionName, String hierarchyName)
  • security.applicationUserElementAccess(String applicationId, int userId, String dimensionName, String elementName)
  • security.applicationRemoveUser(String applicationId , int userId)
  • security.applicationWipeUsers(String applicationId)
• Application Tag Management
  • security.applicationAddTag(String applicationId, String tagName, String dimensionId,String hierarchyId, boolean All)
  • security.applicationAddTagElementSecurity(String applicationId, String tagIdOrName, String hierarchy, String element, String access)
  • security.applicationRemoveAllTags(String applicationId)
  • security.applicationRemoveTag(String applicationId, String tagIdOrName)
  • security.applicationTagExists(String applicationId, String tag)
  • security.applicationTaggedElements(String applicationId, String tag, boolean nLevel)
  • security.applicationTaggedUsers(String applicationId, String tagIdOrName)
  • security.applicationTags(String applicationId)
  • security.applicationWipeTagElementSecurity(String applicationId, String tagIdOrName)
• Application User Tag Management
  • security.applicationUserAddTag(String applicationId, int userId, String tagIdOrName)
  • security.applicationUserRemoveAllTags(String applicationId, int userId)
  • security.applicationUserRemoveTag(String applicationId, int userId, String tagIdOrName)
  • security.applicationUserSetTags(String applicationId, int userId, String tagIdsOrNamesPipeDel)
  • security.applicationUserTags(String applicationId, int userId)
• Utilities
  • security.md5(String str)
  • security.sha1(String str)
  • security.sha1hmac(String key, String str)
  • security.sha256(String str)
  • security.sha256hmac(String key, String str)

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

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

Parameters

• applicationId - Identifier of the activity
• tag - Tag name
• dimensionName - Name of the dimension
• 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 (Comma delimited string)

Example

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

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 elements available to a tag in an application

security.applicationTaggedElements(applicationId, tag, nLevel)

Parameters

• applicationId - Identifier of the application
• tag - Tag name or identifier
• nLevel - Boolean. Wether to include parent levels (false) or just the elements (true)

Example

var arr = security.applicationTaggedUsers(appId, "employee", true);

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, tags)

Parameters

• applicationId - Identifier of the activity
• userId - Identifier of the user (Integer)
• tags - Tag names or identifiers (Comma delimited string)

Example

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

List all elements on a dimension visible to the user on a particular application. Returns a JSON array

var json = security.applicationUserElements(applicationId, userId, dimensionName, hierarchyName);

Parameters

• applicationId - Identifier for the application
• userId - Identifier for the User
• dimensionName - Name of the dimension
• hierarchyName - Name of the hierarchy on the dimension

Example

const appId = "someAppId";
const users = JSON.parse(security.applicationUsers(appId));
const userId = users[0].id;
const result = JSON.parse(security.applicationUserElements(appId, userId, "Account", "Default"));
console.log(result); // ["All Accounts", "Revenue", ...]

Get the access mode available to the user for a particular element in a dimension. Returns a string. Possible values are "R" for Read Access, "W" for Write Access, or "N" for no access.

var json = security.applicationUserElementAccess(applicationId, userId, dimensionName, elementName);

Parameters

• applicationId - Identifier for the application
• userId - Identifier for the User
• dimensionName - Name of the dimension
• elementName - Name of the element to get access information from

Example

const appId = "someAppId";
const userId = 123;
const access = security.applicationUserElements(appId , userId, "Account", "Revenue");
console.log(access); // "R"

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

Get the email address of a user from its userId (integer).

security.getUserEmail(userId)

Parameters

• userId - User ID

Example

var email = security.getUserEmail(1234); // "jande.doe@somewhere.com"

Get the userId (integer) of user with a known email address.

security.getUserId(email)

Parameters

• email - Email address of the user

Example

var userId = security.getUserId("jande.doe@somewhere.com"); // 1234

Get the user's name from their userId (integer).

security.getUserName(userId)

Parameters

• userId - User ID

Example

var userName = security.getUserName(1234); // "Jane Doe"

See script.md5.

Removes an user from the specified model

security.removeUser(userId)

Parameters

• userId - Unique Identifier of an user

Example

security.removeUser("123");

Send a Reset Password link to a user so they can reset their password. The link is sent through email. Returns true if the reset link has been sent. Note that the email might reach the user within a few minutes.

security.resetUserPassword(userId);

Parameters

• userId - The user's User ID

Example

var success = security.resetUserPassword(1234); // Returns true if successful

Generate a SHA1 hash from a string.

security.sha1(str);

Parameters

• str - The string to hash

Example

var hash = security.sha1("Hello"); // "f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0"

Generate a SHA1 HMAC hash.

security.sha1hmac(key, str);

Parameters

• key - A secret key (string)
• str - The string to hash

Example

var hash = security.sha1hmac("mySecret", "Hello"); // "YuM0lx19wbPh15dGIJ0q/9EG7RI="

Generate a SHA256 hash from a string.

security.sha256(str);

Parameters

• str - The string to hash

Example

var hash = security.sha256("Hello"); // "185f8db32271fe25f561a6fc938b2e264306ec304eda518007d1764826381969"

Generate a SHA256 HMAC hash.

security.sha256hmac(key, str);

Parameters

• key - A secret key (string)
• str - The string to hash

Example

var hash = security.sha256hmac("mySecret", "Hello"); // "wXJ+DzC4r15MVx/w0i0PXezGMBjy1uN2rBbcBNBuSCw="

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 

template.apply(template)

Parameters

None

Example

template.apply("template");

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

template.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

template.registerHelpers(fileLibrary)

Parameters

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

Example

template.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, [password]);

Parameters

• base64str - Base64 data
• password - Optional, The workbook password.

The password argument is supported from version 2.4.891 onwards.

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, [password]);

Parameters

• filename - Name of the file that is to be opened
• password - Optional, The workbook password.

The password argument is supported from version 2.4.891 onwards.

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.definitionGet(String workviewName)
• 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

This function returns the JSON representation of a Workview definition.

Example

var def = workview.definitionGet(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