Scripts

Using Java Classes

Furthermore, external classes through Java may be imported, using importClass and importPackage where necessary, for example:

When these are defined, their Java methods may be accessed. For example:

may be used in your script with the above segment imported.

Using Third Party Java Libraries

This is similar to importing Bright Software helper classes and Java classes, using importClass or importPackage statements. Make sure the full package and class path is included in the statement.

Native Data Types

Values are generally able to be passed using corresponding JavaScript native objects as is. The exception to this is with Integers, as JavaScript uses doubles by default, and binary data, which is not supported. Refer to the table below for more detail.

Depending on the type, the fields of records must specify an int value of the type to be read, as JavaScript does not support type definitions. These are also listed in the table below, and will be explained further in the Fields section below.

Fields

Fields hold values of data, and other values used for database functionality and synchronisation. On the server, they must map to fields in tables if mapping is set to default, or to the mapping that is specified in the BrightServer project.

Fields are defined using a vector of FieldInfo in scripts, and are applied on RecordSet construction, or via the setFieldInfo() method.

• Table Name - result set's name must match the table the records are mapped to.

• Column - name mapped, string

• Type - specifies how the Field should be read to BrightServer. The codes for these types, and the constant values that may be used are as follows.

• Int Value	Constant
  0	FieldInfo.UNKNOWN
  1	FieldInfo.STRING
  2	FieldInfo.BOOLEAN
  3	FieldInfo.INTEGER
  4	FieldInfo.DOUBLE
  5	FieldInfo.DATETIME
  6	FieldInfo.BASE64BINARY

  
  Note, the type of the field must correspond to the value place in it. Depending on the type, using values as is may cause errors. For more information, see the above section - Values.

• Primary Key - boolean value stating whether the passed value is a primary key or not.

• Length - necessary for strings. 0 otherwise.

• Allow Nulls - boolean value stating whether NULL can exist as the value for the field.

Records

Record – a vector of fields which can also be referenced to see if the values need creating/modifying or deleting in the database. This is done via the method getStatus().

When a record is to be deleted, please note that only the primary key values will be passed to the script.

RecordSets

A RecordSet is a vector of records, passed to write and expected to be returned by the Read() method for use in Bright Applications. It's is how table data is passed to and from the script data source, and is thus analogous to the concepts of Tables in BrightBuilder and BrightServer.

Thus when synchronising RecordSets, they pass the string name of the table to synchronise to, as defined by the server's mapping. This is achieved by setting the name on creation with new RecordSet(<name>).

A vector of records also acts as the input parameter for Write(), and has the variable name 'data'. These record sets may be iterated through, using the RecordSet.size() and RecordSet.get() methods. Refer to Scripts > Implementing Scripts > Sync Writer for more detail.

Payloads

Payload - Data used for online and read queries. This is passed to the script query in a form defined by the Bright Software Application. The format is usually a string, but can be of any type set by the application. For more information, refer to the Sync Reader and Online Query sections below.

ResultRPC

RPC calls may return complex data values. It may not return just a single data value. To simplify returning data from script queries, ResultRPC objects are used.

ResultRPC object represents a RPC result. A RPC call may return a number of output parameter values, or a recordset, or both depending upon the requirements for the RPC query sent from the remote field device. This object is simply a container object for holding the returned values. It allows setting the returned output parameter name and value pairs. It also allows returning a RecordSet object for returning records in the RPC result object. A ResultRPC object also holds a query result integer value. An error code can be returned by setting the result code as well.

Parameters

Parameters are passed to scripted Remote Procedure Calls (also known as stored procedures) via two variables:

• paramNames - Vector of strings holding the names of parameters passed for a remote procedure call.

• paramValues - Vector of Objects, types equal to those passed by the Bright Software Application

Below is a diagram to show how data is mapped from query panel to script.

Sync Reader

The goal of the sync reader is to take a defined payload, process it, and then return a set of results via the read method. This read method will be called numerous times, thus producing a number of record sets, which are then processed by BrightServer's synchronisation engine to ensure that records are read efficiently. The reading will occur until an empty RecordSet is retrieved from the read() operation.

This transaction must be defined in a BrightForms application via a Server to Client sync rule on a script query. For more information on this process, please refer to BrightBuilder > Sync Rules and BrightBuilder > Queries > Scripted Queries.

Below is a diagram how the sync reader is utilised, both between server and script (represented by grey arrows) and the order of method calls (purple arrows).

In order to implement a sync reader script, the following methods must be implemented:

• openReader() takes in a payload – i.e. the query sent to the script to process, and a limit. The limit value is typically unused. The query may be in any form the user specifies in the application and, it is up to this function to read or parse it in order for the read() method to return the desired result set.
• 

  function openReader(query, limit)

  {

  in = new BufferedReader(new FileReader("filename"));

  mark1 = query.charAt(0); // get 1st char

  mark2 = query.charAt(1); // get 2nd char

  }

  The function may also be used to open/retain any resources needed by the reader.

• read() commands return a specific record set based on the query given with openReader(). It may be called numerous times, with BrightServer amalgamating the results when sending them to the device. Record.add() and RecordSet.addRecord() are thus typically used to populate the returned set of records.

• function read()

  {

  rs = new RecordSet("TABLE4");

  // operations to populate the result set ...

  while ((str = in.readLine()) != null)

  {

  strs = str.split(mark1,2);

  strs2;

  if (strs.size() < 2)

  strs2 = strs[1].split(mark2,2);

   

  // create record

  record = new Record();

  record.add(strs[0]);

  record.add(strs2.size() < 2 ? "" : strs[1]);

  record.add(strs2.size() < 2 ? "" : strs[2]);

  rs.addRecord(record);

  }

  return rs ;

  }

• dataConsumed() signals to the reader that data from the read() command has been successfully retrieved.

• closeReader() closes the reader, used to close or release any resources used at the opening stage.

• function closeReader()

  {

  // ...

  in.close();

  }

Sync Writer

Like the sync reader, the sync writer uses BrightServer's synchronisation engine to process records being sent to the script. While the reader deals with server to client transactions, the sync writer's methods are called for client to server ones.

The sync writer's goal is to write data, maintaining its integrity, given a set of records. As such, commit and rollback methods must also be provided to support this process of ensuring data is not compromised.

Whether or not a writer is to commit or rollback is dependant upon the isInTransaction() method, which returns a boolean value given the state of the writer. Using this value, the server will determine if it is to commit or roll back. If not in transaction, the server assume the data is automatically committed (i.e. the writer is in the auto-commit mode).

Below is a diagram how this process takes place, both between server and script (represented by grey arrows) and the flow of method calls (purple arrows).

In order to implement a sync writer script, the following methods must be implemented:

• openWriter()/closeWriter() used to open/close the reader, and any resources that may be needed for its operations.

• openWriter()

  {

  out = new BufferedWriter(new FileWriter("filename", true));

  // ...

  }

  closeWriter()

  {

  // ...

  out.close();

  }

• beginTransaction() is used to set up any write operations that may take place. It marks the beginning of a transaction.

• write() is used writing created, modified or deleted data based on records sent to the method. Recordsets are sent via a vector called "data", i.e. the set of tables. Thus, this data type needs to be parsed correctly in order for values to be accessed. If a data for multiple tables are sent from client (i.e. a sync rule using a multi table query to send multiple tables records, for example, order headers and order items in a sync rule), then the data input parameter will be a vector of recordsets. For a single table write this data vector will contain just a single recordset containing the records from the table in question.
  
  A template for this is provided in the writing template, using get() methods, and for loops to access a particular record set, a particular record.

• write(data)

  {

  for (i = 0; i < data.size(); i++)

  {

  rs = data.get(i) ;

  for (j = 0; j < rs.size(); j++)

  {

  record = rs.get(j) ;

  // Consume ...

  //...

  }

  }

  }

  With this record ( rs.get(j) ), field values may be processed individually.

  // Consume ...

  if ( record.getStatus() == 1)

  {

  v.add( record.get(0) );

  v.add( record.get(1) + "/" + record.get(2) );

  v.add( "\n" );

  } else if ( ...

  The state of data, ie, whether to modify, create or delete can be retrieved by the getStatus() method. It will return an int value depending on the record’s state. For more information on the status of records, please refer to the Records section in the previous section.

• commit() is called by the transaction manager to make the write commands’ changes permanent. It also marks the end of a transaction, and this should be reflected in the code.

• write(data)

  {

  for (i = 0; i < v.size; i++)

  {

  out.write(v.get(i) + ",");

  if (v.get(i) == "\n")

  out.newLine();

  }

  }

• rollback() is called by the transaction manager to revert any write changes that took place and restore the state to what it was after BeginTransaction() was called.

• rollback()

  {

  v = new Vector();

  }

• isInTransaction() is called by the transaction manager to query whether write operations are in progress.

• isInTransaction()

  {

  return (v.size() > 0);

  }

Script Job

A Script Job is a type of script that will run its set of operations repeated over a set period, defined by the server. This period is defined either by a set interval or via a Cron expression, and when elapsed, will call the run() function defined in the script. This run function may encompass any range of procedures or call a range of methods, and does not have a return type. Once performed, the server will call the function again once the particular interval has elapsed.

Job scripts is an excellent mechanism to implement various housekeeping jobs, distributing the data collected from field to multiple destinations, generating emails, creating reports, exporting data in specific formats for instance in XML or HTML formats at the scheduled intervals.

 

A script may be defined as a Script Job by its properties, accessed with by the context menu (shown below) or the properties panel.

Once in the properties pane or dialog, perform the following steps:

• Set 'Execute On Schedule' as true. The icon should change in the projects panel under the Script node as shown.

•  

• Define how you want to the script to operate, via the 'Schedule Type' drop down menu. This will define whether the script's run() method will execute at a set interval in seconds or via Cron scheduling.

• 

• Input the schedule intervals (in seconds) or the Cron string. For more information on Cron scheduling, refer to Appendix > Cron Expressions.

• 

When deployed to a BrightServer instance, job scripts may be monitored, enabled and disabled via the server's Job Status node.

By default, scripts uploaded from BEP files will be added to the server in the 'enabled' state.

Furthermore, Job scripts may also be implemented on the server via defining them as 'User Scripts' and deployed via BrightServer runtime configuration. For more information, please refer to the Job Configuration chapter of this document.

Online Query

Similar to Read queries, online queries take in a payload with their execute() method and returns a set of values matching the types specified by the queries’ output field. The payload will be defined in the application, and the execute() method will be expected to interpret it, much like the read() method of the sync reader interface.

The difference between these two types of queries is that Online Queries bypass the synchronisation process in BrightServer, and thus is useful when data does not need to be saved to the local database at the client side.

Despite taking in the same payload variable, the two payloads could be of completely different formats in a read and online query.

RPC (Remote Procedure Calls)

Remote procedure calls, also referred as stored procedure queries, are handled by scripts by implementing executeRPC() methods. Inputs into this method are the name of the function to be executed, a vector of parameter names and a vector of parameter values, which are all set in the Queries panel of a Bright Software BSP Project. These parameters are indexed in order of definition in this project. Likewise, output should match the output fields specified in the query panel and be of the expected types.

Every executeRPC() method should return a ResultRPC object. This object represents a RPC query result. It is a data container and it holds output parameter names and values, a result code, and a RecordSet object for returning resultsets if needed. This mean a RPC call can return a set of out parameter values, or a RecordSet, or both depending on the requirements. The output parameters defined the query's "out" or "in/out" parameters are returned by the ResultRPC object using setOuputParameter method. Scripts can also return records in a RecordSet object by creating and setting a recordset object in the RPC result object. If the recordset of a ResultRPC is not set, then the query result will not return any records. See the reference manual for details on the executeRPC method and the ResultRPC object.

Transformation Scripts

Transformation scripts are used as intermediary points between device/server tables and data accessors or mappings. Using this script, data retrieved from a device may be modified, having complex operations occur for particular fields, or completely re-arranging the record itself. It is specified as an intermediate sync point in the Sync Panel as follows:

The transformation within the script is performed via a single transform() method, which takes in and returns a vector of Record Sets - 'data'. This output set is then used to write the record to the server.

An example, which multiplies the incoming data set's field by 1000 before sending it to its destination, is as follows:

The number of RecordSets in this vector is determined by the number of parent and child tables are included in the synchronisation transaction; if there are no child tables, only data.get(0) would need to be used to retrieve the record set, however, if there are parent/children tables and relationships in the sync, all tables will be contained in the data vector.

Transformations will also occur at the end of the transaction when after the final table is sent - which in parent/child scenarios, may differ depending which child records are sent to the server. As a result, the same transformation script must be connected to all client to server pathways in the entire set, and contain the transformation logic for each table in the transaction, even if the particular table itself does not need a transformation on its records.

For an example how to implement this, please refer to Transformation Examples > Multiple Table Transformations.

Script Types

Using a script's 'Type' property, scripts may be set to run on events which occur on BrightServer, such as the server starting up, shutting down, and during the user login/log off process. This property may be set in the script properties panel for any script in the BEP.

These scripts executing on server events require a run() function, with the exception of the Authentication type of script. Any script with a script type without the expected function defined will produce an error on the server upon execution. BrightServer will invoke these functions when the event occurs, set by the 'Type' field.

The types which scripts may be defined as are as follows:

Server Start : Runs immediately after the server has been started. This may be used to perform or prepare the server as it starts. The example below will display information in the log regarding last server start time:

Server Stopped : Runs when the server has been stopped. This may be used in cases to capture the server state, or send notifications the state, such as via the Email object. The following is an example capturing the time the user logs off and persisting it for future use:

User Login : Runs when a user successfully logs in to the system. This happens after an Authentication type script returns true, if it exists in a project. This type of script may be useful for preparing and performing specific procedures by the server after login. The following script displays how to retrieve the user who currently logged in.

User Logout : Runs when a user logs out of the system. This may be used for clearing a server state after the user logs out.

Authentication : Runs when a user attempts to log in to the system via BrightForms or BrightWeb. Unlike other scripts specified to run on server events, the Authentication script uses an authenticate() function with username and password parameters. These parameters passed by BrightServer may be processed by the script, which will return a boolean return value - true if the user login is to continue, and false to invalidate the login attempt.

Due to its nature, only a single authentication script may exist in a project. If there are more than one script in the system marked as Authentication script, BrightServer will execute only the first one found, ignore the other authentication scripts defined in the system.

The following demonstrates how the username and password are passed to the authenticate() method.

Web Services

BrightServer has the ability to process Web Service calls, with the Web Services script type.

These requests are directed to the URL: /brightserver/ws?<name of script>.

Upon receiving the request, the script will process the message via its handle() function. This function will also construct the response message to send back to the server as its return value.

SOAP requests and responses are deserialised internally via the WebMessage object. This enables developers to analyse and construct SOAP communications, while not needing any specific parsing. The methods to analyse and construct these WebMessage objects are as follows:

• request.getMessageName() Returns the name of the WebMessage.

• request.getParam() Returns the value of the specified parameter of the WebMessage. Requires a parameter name.

• response.createMessage() Create a new message to send to the web service caller as a response. Message name is specified as an input.

• response.addParam() Used to add a new parameter to the response message, which serialised as a SOAP message when sent back to the caller. Takes in inputs for parameter name and the parameter value itself.

For more information, please refer to the BrightServer > Web Services chapter of this documentation.

Blobs

The blob object is provided to assist the handling of binary data, as JavaScript supports only native data types. Binary data is synchronised to and from BrightServer as byte arrays (byte[]). This binary data may be processed from the client via the Blob object when implementing scripts. The blob object's methods used to access this byte array, providing methods to access and store binary data. An example of blob use is as follows:

Furthermore, this data may be mapped to incorporate compression specified by a BrightXpress project. As such, in order to access these values to conventional BrightXpress project types, decompression must take place. Similarly, to store these values correctly, compression of blobs must be done.

Base64

If base64 operations are needed within a script, the Util.encodeBase64() and Util.decodeBase64() methods may be used. They can be used on strings to covert them into byte arrays, and vice versa. An example of this code is as follows:

Script Session

The script session object holds information about a script when instantiated, and also allows information to be outputted to the server’s log through a number of methods. It is primarily used to query system information, log data or output of the script, and handle exceptions. For more information, please refer to the sections below, and the Script Methods Reference Manual.