Predefined objects

This section describes the predefined objects used in the Scripting Language. The predefined objects are highlighted in the editor as default JavaScript reserved words.

Accessing the current record's property values

In order to access record data, use the 'record' object. The current record is converted to a script bean object and assigned to the 'record' object. The conversion does as follows:

• A normal field is converted to a property having the same name of 'record'.

• A multiple value field is converted to an array then assigned to a property having the same name of the 'record'.

• Groups convert to another script bean and are then assigned to a property having the same name as the 'record'.

• For a foreign key field, the system looks for the reference record first. If the reference record exists, it will be converted to another script bean before being assigned to the property of the 'record'.

For example, with the given structure of the 'Strategies' table, the script bean of one record on this table is presented as follow:

The following example shows how to access different record properties in the 'Strategies' table.

The Scripting Language supports "navigation" through foreign keys. As shown in the following image, the 'Strategies' table's script bean presents all foreign keys as objects instead of strings. These objects contain all associated records and not just the associated records' primary keys.

The following example shows how to access 'article.libelleCourt' object's data.

In order to access to a record attribute whose name contains a dot such as 'loc.code' field in 'Article' table, you must use the format record.["loc.code"]. The following example shows how to access 'loc.code' field's data.

Even though the foreign key is presented as an object, you only need to assign another associated primary key value to change its association. So, when you 'get' the foreign key value the script returns an object containing all of the associated records. When you 'set' the foreign key value, the parameter is only the primary key of the associated record.

Updating the current record

The script bean is just a copy of the record. Modifications made in the script bean do not have any affect on the corresponding record until you call the 'save()'method. However, this only works in certain contexts. For example, only an 'Automated rule', or a 'Table set rule' can modify data. Additionally, permissions may prevent a rule from executing. If you are using a different type rule, the 'save()' method returns 'false' and no modifications are committed.

Additionally, you can disable triggers by calling the 'save(isActivated)' method with a 'true' or 'false' parameter. These enable and disable the trigger, respectively. If you call this method without a parameter, triggers default to enabled.

Deleting the current record

You can call the 'del()' method to delete a record. However, just as with the process of updating a record, you can only modify data in certain contexts. You must have sufficient permission and the rule type should be either an 'Automated rule' or a 'Table set rule'. If the correct conditions are not met, the method returns 'false'.

The following example shows how to delete the current employee record:

The 'del()'method returns 'true' if it deletes corresponding record successfully, otherwise it returns 'false'.

Querying data in the current table

The Scripting Language uses the 'query' object to query data in the current table. It also supports the 'records(XPathPredicate)' function to get a list of records - which, are converted to object beans - in the current table based on the specified predicate. To get all records in the current table, set the predicate to 'null' (query.records(null)). If you want to set conditions replace 'null' with an XPath predicate. To get the number of rules use JavaScript's 'length' property.

The following example checks the number of records in the current table. If the number of records is smaller than 5, it returns 'true'. Otherwise, it returns 'false'.

Querying data in the current data set

When defining a rule that involves querying data in a different table from the same data set you most likely "navigate" through the foreign keys. To accommodate this process, the Scripting Language contains the 'getQuery(tablePath)' method.

The script in the following example states, "One article cannot be the substitute article for more than 10 articles."

The following bullet points breakdown the content of the above script:

• The 'pk' variable returns the current record's primary key.

• The 'articleQuery' variable uses the 'getQuerry()' method to query the 'Article' table. Notice that input parameter uses the table's path.

• The 'articles' variable is a query object that queries the 'Article' table records and uses the 'records(XPathPredicate)' function to return all articles that use the current article as the substitute article.

• The final statement counts the number of object beans contained by the 'articles' object. If the number is larger than 10, the rule returns 'true', otherwise it returns 'false'.

Querying data from a data set in the current data space

The 'query' object allows you to query data in a table from a specific data set in the current data space. To accomplish this, the Scripting Language contains the 'getQuery(String datasetName, String tablePath)' method. The query object returned from this method allows you to modify data on a given data set in the current data space.

The following shows an example query:

The following bullet points breakdown the content of the above script:

• The 'otherDatasetQuery' variable uses the 'getQuerry(String datasetName, String tablePath)' method to query the 'DataType' table from the 'Chart-API' data set in the current data space. Notice that input parameter uses the data set's unique name and the table's full path.

• The 'dataType' variable is a query object that queries the 'DataType' table records and uses the 'records(XPathPredicate)' function to return all data types that have the 'DateTime' label.

• If the 'dataType' object is not null and contains one or more objects, the rule returns true. Otherwise, the 'newRecord()' method creates the 'newDataType' variable. After setting the value for each of the 'newDataType' variable's fields, the 'save()' method commits the new record to the 'DataType' table.

Querying data from a specified data set and data space

You can use the 'query' object to query data in a table from a specific data set and data space. To support this functionality, the Scripting Language contains the 'getQuery(String homeKey, boolean isBranch, String datasetName, String tablePath)' method. However, the query object returned by this method does not allow you to modify data.

The following examples will help you to understand this feature more deeply:

The following bullet points breakdown the content of the above script:

• The 'otherDatasetQuery' variable uses the 'getQuerry(String homeKey, boolean isBranch, String datasetName, String tablePath)' method to query the 'DataType' table from the 'Chart-API' data set in the 'TestDataspace' data space. Notice that input parameter uses the data space's identifier, the data set's unique name and the table's full path.

• The 'dataType' variable is a query object that queries the 'DataType' table records and uses the 'records(XPathPredicate)' function to return all data types that have the 'DateTime' label.

• If the 'dataType' object is not null and contains one or more objects, the rule returns true. Otherwise, it returns false.

Creating new records in the current table

The 'newRecord()' method returns the object bean for a new record on the current table. You can then assign values to each of the record's fields. As shown below, you must use the 'save()' method to commit the new record to the current table.

Writing to the log file

As the complexity of your code increases, keeping track of each line becomes more and more important. To assist you in this endeavor the Scripting Language provides the 'log' object to write information to the log file.

The following example shows how to check the current record's name. If the name is not 'null', this returns 'true'. However, anything that returns a value of 'false' gets added to the log file. Four methods - 'error(message)', 'info(message)', 'debug(message)' and 'warn(message)' - write messages to the 'ebx-addon-common.log' file with respective severity levels of 'ERROR', 'INFO', 'DEBUG' and 'WARNING'. You can find that log file in configured logs folder. See section 'Configuring the EBX® logs' in EBX® document for more detail.

Setting a validation message

You can use the 'validation' object to change add-on error messages. This object contains one message that corresponds to the respective severity level.

The following example shows how to check the current record's name. If this returns a value of 'false', an error message displays. In this case, 'The name is null'.

The following image shows this error message. The 'validation' object supports other methods, see the appendix for more information.

Getting data set information

You can retrieve information about the current data set using the 'dataset' object. This object specifically applies to permission rules. The following table shows the relationship between the type of information and its related method:

The following example shows how to set permissions by checking the owner. If the owner is 'Beveryone' (B is a specific prefix), permission becomes read-only. Otherwise, it becomes read-write.

Getting node information

Like 'dataset', the 'node' object only applies to permission rules. This object retrieves information about the current node and is very useful because nodes are frequently used when creating permission rules. Information retrieved can be a path in the schema, category and data type using the 'getPath()', 'getCategory()', 'getDataType()' pre-defined methods. Other methods tied to the 'node' object check whether the current node is a terminal node and whether history is disabled on the current node. These are 'isTerminalValue()' and 'isHistoryDisabled()', respectively. See the appendix for more information.

Example 1: In this example, the permission rule returns the read-only or read-write access permission depending on whether the current node is auto-incremented.

Example 2: In this example, a line of code is added to show the node's path in the schema to the log file.

The image below shows the result.

Getting session information

When you create a permission rule, a tool to retrieve current session information is extremely useful. The Scripting Language provides the 'session' object. By using the supported methods, this object can get the current user id, attribute values by name and check whether the current user is in a specific role.

For example, the following piece of scripting code expresses a permission rule. This permission rule controls access permission based on the specific role of the current user. If the role is 'developer', the access permission will be read-only. Otherwise, the access permission will be read-write.

Predefined permission

The add-on provides some predefined keywords that represent access and action permissions. These keywords are used in the permission rule to return the permission as the result of the permission rules.

These keywords are listed in the following table:

The following example shows how a permission rule sets read-only permission for the article record if the internal code is > 1000: