Client Script Library Reference

Web HMI provides some useful client script utilities for developers who wish to have more control over application behavior. The following objects and functions are available to use:

Authentication

OAS.authenticate(string, string [, auth_callback])
Pass in a username and password to perform a server authentication call. Once complete, all tag data requested from the server will occur within that user’s context and bound to that user’s permissions. If the user does not have access to a given tag, no value will be returned. The authentication is performed asynchronously, and will take effect when either the call completes successfully or fails. Upon completion or failure, the OAS.token value will be updated. Upon failure, the OAS.token will be set to “AUTH FAILURE” when there is a communications issue, but will be set to a GUID token for all other results. Note: the user identity and permissions are managed within the Open Automation Software Server:

OAS.authenticate("someuser", "somepassword");

You can also include an optional authentication callback as the final parameter in the authenticate call. This function will execute when the authentication is completed on the server, and will pass in either the new authentication token or an error string starting with “ERROR:”.

function auth_callback(result){
  if(result.indexOf("ERROR:")>=0) {
    // auth failed
  } else {
    // result is the new auth token
  }
}
OAS.authenticate("someuser", "somepassword", auth_callback);

OAS.logout()
If you choose to disconnect from the server, you can call OAS.logout() and the current authentication token will be nullified, and server polling will cease immediately. Calling OAS.authenticate will also issue a logout before re-authenticating, so if you choose to use a different credential, it is unnecessary to call logout and then authenticate again.

Tag Syntax

Once authenticated, you are now able to read and write Tag properties. When referencing Tags in any call, you it is assumed that you are accessing them on the OAS server referenced in the OAS_config section’s serverURL field. However, you can also access remote Tags on any OAS server networked with the target server. Read more about the proper syntax for accessing Tags and Tag Variables. Also, only tags added to the watch_tags list or referenced in any oas-tag markup attribute can be accessed with the get_value function.

Reading Tag Values

OAS.get_value(string)
Pass in a tag as a string to get the current value for that tag:

var pump = OAS.get_value("Pump.Value");

Writing Tag Values

OAS.set_value(string, string)
Pass in a tag as a string, and a new value and that value will be set on the server:

OAS.set_value("Pump.Value", false);

Reading Tag Quality

OAS.get_quality(string)
Pass in a tag as a string and a boolean(true/false) will be returned indicating Tag quality:

var pump_q = OAS.get_quality("Pump.Value");

Toggle Polling

OAS.toggle_refresh(bool)
Temporarily disable or re-enable server polling for new tag values. If no parameters are passed in, polling will toggle, turning off when currently active, or back on when suspended. To explicitly start or stop polling, pass in a boolean true or false, respectively:

OAS.toggle_refresh();   //toggle
OAS.toggle_refresh(false);  //disable
OAS.toggle_refresh(true);   //enable

Initialize Script Engine

OAS.init()
Reinitialize the client script engine and begin polling. Use this function if there is ever a need to dynamically update any configuration settings, for example if you ever choose to programmatically point to a different serverURL, add tags to the watch_tags array, or add elements to the screen to be parsed and managed by Web HMI behaviors:

OPC_config.watch_tags.push("NewTag.Value");
OAS.init();

Client Object Structure

The client script library caches tag data in an object structure that can always be inspected in your custom code. This is particularly useful for debugging data being sent by the server, and for determining Tag data quality in your own script. You can access this object store at any time:

var tags = OAS.tags;

Below is the general structure of the tags object. Each tag is a node in the object containing a props structure that tracks every OAS Tag property being monitored. For example, if you are tracking Pump.Value, there will be a Value property in the props object. If you are tracking both the Value and the Description of each tag, you will find one object for each.

{
  TagName: {
    name: "TagName",
    props: {
      PropName: {
        data_type: "int|float|string",
        quality: true|false|null,
        name: "PropName",
        val: "Property Value"
      },
      ...
    }
  },
  ...
}

For example, using this prototype you would check the data quality of the Pump.Value using the following code:

var pq = OAS.tags["Pump"].props["Value"].quality;

Knowledge Base