An Industrial IOT Platform

OPScript - Parameters

Parameters Overview

Overview

Open-Plant  allows users to save/store certain values as 'Parameters'. Parameters are 'memory synced variables' i.e. the parameters are stored in server memory with any changes synced back to Database once every second. This memory sync design makes accessing and writing Parameters fast making parameters perfect for OPScript calculation variables. Example of use are as such:
- The parameters can be used as an input to another analysis.
- The parameters can be used in the same analysis for consecutive runs.
- A parameter's current value can be seen in realtime in the Parameters tab in the Open-Plant Client Analytics console. This can be used to monitor the state of an executing script. 

NOTE: Parameters are bound to an Open-Plant Server. If there are multiple Open-Plant servers (e.g. for redundancy) sharing a single database, each server will store it's own Parameters (Parameter are not shared between servers).

The screenshot below shows the Parameters Tab in the Open-Plant Analtics Console. Clicking the Get or Set buttons next to the parameter will add the parameter into the script being edited.

Parameter Data Types

Open-Plant Parameters can store any data type, even structured objects. Data storage is done via the 'OP.SetParameter' function. If a simple data type is stored, the value will be first converted into the following data types:
- All real values (such as double, single, decimal) will be converted into a double
- All integer values (such as Int, In32, UInt, UInt64, long, etc) will be converted into an int type

If a structured object is stored in a Parameter, the object will first be converted into a JSON string. Retrieving the object requires one to specify an object definition.

Parameter Security Access Levels

Each parameter will have two associated minimum access levels (See user access control): 
- MinimumReadAccessLevel is for reading the underlying parameter. The default value is Access Level 1(L1 User).
- MinimumEditAccessLevel is for updating/deleting the underlying parameter. The default value is Access Level 6 (L1Engineer). 

Parameter Groups

Optionally, a parameter can be made to belong to a particular Parameter Group. This grouping is only for organizing and does not effect the function or accessibility of a Parameter. If a Parameter does not belong to a group, it will be placed the default group (Group name = null).

OPScript Functions

OPScript

OP.SetParameter

This OPScript function sets a Parameter (based on specified Group Name and Parameter Name) to a specific value. Any data type can be stored, even structured objects. However, the data will converted and stored as the following:
- All real values (such as double, single, decimal) will be converted to a double
- All integer values (such as Int, In32, UInt, UInt64, long, etc) will be converted to an int type
- All complex/structured objects are converted into a string type. These objects are stored as a JSON string.

If the parameter doesn't exist, it will create the parameter (and add the parameter to the Parameter List accessible from the console). 

If the parameter exists, it will update the value. The script however must be running with access level higher or equal to the parameter's MinimumEditAccessLevel.  If this requirement is not met the Script will fail and stop executing (unless the execution is caught with a try-catch block).

The function accepts the following input:

- GroupName [Optional]: The group to which the parameter belongs to. If the Group does not exist, it will create the group. The name can be of a any name with space characters allowed. Names are not case sensitive. If not specified, it will set this input to the default group.

- ParameterName: The name of the parameter. It can be a any name with space characters allowed. Parameter names are not case sensitive.

- ParameterValue: The value of the parameter to be set. The value can only be of simple DataTypes (and not complex objects) e.g. int, double, string, DateTime, TimeSpan, etc.

- MinimumReadAccessLevel [Optional]: This is the minimum access level that would allow a user to read the parameter value. If not specified, the default value is 1 (L1Users).

- MinimumEditAccessLevel [Optional]: This is the minimum access level that would allow a user to edit or delete the parameter. If not specified, the default value is 6 (L1Engneer).

Examples:
//This Parameter is saved as an Integer
OP.SetParameter("My Age", 39); 

//This Parameter is saved as a double and belong to group 'Price Group'
OP.SetParameter("Price Group","Current Oil Price", 40.0);

//This Parameter is saved as a string
OP.SetParameter("My Email", "info@Open-Plant.com");

//This Parameter is assigned based on FIC101.Value
OP.SetParameter("Last Known Value", OP.Tag("FIC101.Value").Sample.Value);

//These parameters are saved as a DateTime Object
OP.SetParameter("Last Processed Time", OP.Tag("FIC101.Value").Sample.TSUTC);
OP.SetParameter("Cut Off Date", "2020-11-27 00:00:00".ToDateTime());

The script's RunAsAccessLevel must be equal or higher than the existing Parameter's MinimumEditAccessLevel. If this is violated, the script will err and stop executing (unless caught by a try-catch block).

Example of a Try Catch Block (The following script will not err):
try
{
	OP.SetParameter("MyGroup","MyParam",DateTime.Now);
}
catch (UnauthorizedAccessException)
{
	OP.Log("You are unauthorized to edit this parameter!");
}
OPScript

OP.GetParameter

This OPScript function gets the value of a Parameter based on specified Group Name and Parameter Name. Depending on what is being fetched, this function will return either an int, double, string, DateTime or an object. 

The function accepts the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will set this input to the default group.

- ParameterName: The name of the parameter. Parameter names are not case sensitive.

- ObjectDefinition [Optional]: If the Parameter to be retrieved is an object, an object definition must be specified. Click here to learn more on how to specify an object definition.

Examples:
int MyAge = OP.GetParameter("My Age"); 

double OilPrice = OP.GetParameter("Live Prices","Current Oil Price");

string MyEmail = OP.GetParameter("Email Group","My Email");

var LastKnownValue = OP.GetParameter("Last Known Value");

DateTime LastProcessedTime = OP.GetParameter("Last Processed Time");

DateTime CutOffDate = OP.GetParameter("Cut Off Date");


/* The following JSON Object has definition:
{
  "employees":[
      {"firstName":"John", "lastName":"Doe"},
      {"firstName":"Anna", "lastName":"Smith"},
      {"firstName":"Peter", "lastName":"Jones"}
  ]
}
*/
var definition = new { employees = new[] { new { firstName = "", lastName = "" } }}
var JsonObj = OP.GetParameter("Employees", definition);
string Employee1_FirstName = JsonObj.employees[0].firstName;
string Employee2_LastName = JsonObj.employees[1].lastName;

The script's RunAsAccessLevel must be equal or higher than the existing Parameter's MinimumReadAccessLevel. If this is violated, the script will err and stop executing (unless caught by a try-catch block).

Example of a Try Catch Block (The following script will not err):
try
{
	OP.SetParameter("MyGroup","MyParam",DateTime.Now);
}
catch (UnauthorizedAccessException)
{
	OP.Log("You are unauthorized to edit this parameter!");
}
OPScript

OP.SetParameterItem

This function allows one to set a Parameter's Group, MinimumReadAccessLevel or MinimumEditAccessLevel based on specified Group Name and Parameter Name. The function is called as 'SetParameterGroup', 'SetParameterMinimumEdit' and 'SetParameterMinimumRead' accordingly. 

When setting a new parameter group, if the new group already has a Parameter with the same name, this function will attempt to overwrite the existing Parameter. 

The function accepts the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will check  the default group.

- ParameterName: The name of the parameter. Parameter names are not case sensitive.

- NewItemValueToChange: This can be an integer value between 1 to 10 for when calling 'SetParameterMinimumRead' and 'SetParameterMinimumEdit' or the new Group Name when calling 'SetParameterGroup'

Examples:
//This sets a Parameter from group "My Old Group" to "My New Group"
OP.SetParameterGroup("My Old Group","MyParameter","My New Group");

//This sets a Parameter from the default group to a New Group
OP.SetParameterGroup("MyParameter","My New Group");

//This sets a Parameter's group to the default group
OP.SetParameterGroup("My Old Group",null);


//This sets a Parameter's Minimum Read to 8
OP.SetParameterMinimumRead("MyParam",8);
OP.SetParameterMinimumRead("MyGroup","MyParam",8);


//This sets a Parameter's Minimum Edit to 8
OP.SetParameterMinimumEdit("MyParam",8);
OP.SetParameterMinimumEdit("MyGroup","MyParam",8);

The script's RunAsAccessLevel must be equal or higher than the existing Parameter's MinimumEditAccessLevel. If this is violated, the script will err and stop executing (unless caught by a try-catch block).

Example of a Try Catch Block (The following script will not err):
try
{
	OP.SetParameter("MyGroup","MyParam",DateTime.Now);
}
catch (UnauthorizedAccessException)
{
	OP.Log("You are unauthorized to edit this parameter!");
}
OPScript

OP.ParameterExists

This function returns true if a parameter exists and false otherwise. There are no access control restrictions, any Access Level can run this function. 

The function accepts the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will check  the default group.

- ParameterName: The name of the parameter. Parameter names are not case sensitive.

Examples:
if (OP.ParameterExists("Cut Off Date")) 
	OP.Log("Cut off Date = " + OP.GetParameter("Cut Off Date"));
else
	OP.Log("Parameter does not exist!");
    
    
if (OP.ParameterExists("MyGroup","MyItem")) 
	OP.Log("Cut off Date = " + OP.GetParameter("MyGroup","MyItem"));
else
	OP.Log("Parameter does not exist!");
OPScript

OP.DeleteParameter

This function deletes a parameter based on specified Group Name and Parameter Name. 

To call this function the script's RunAsAccessLevel must be larger or equal to the the Parameter's MinimumEditAccessLevel. If this is violated, the script will err and terminated (unless caught by a try-catch block).

If the Parameter to be deleted does not exist, the function will simply proceed (i.e. it will not terminate the running script).

The function accepts the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will check the default group.

- ParameterName: The name of the parameter. Parameter names are not case sensitive.

Examples:
OP.DeleteParameter("MyGroup","Cut Off Date");

OP.DeleteParameter("Cut Off Date");
OPScript

OP.ParameterNames

This function returns a list Parameter Names in a List<String> object. There are no access control restrictions. Any user can query the list of parameter names.

The function has the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will query the default group.

- SearchWildCard: Searches for Parameter Names that matches the wildcard. Use "*" to return all Parameter Names.

Examples:
//This logs all the Parameter name and values to the console
List ParameterNames = OP.ParameterNames("*");
foreach (string ParameterName in ParameterNames)
{
	OP.Log(ParameterName + " = " + OP.GetParameter(ParameterName));
}

//This logs all the Parameter name that ends with ".Value" in "My Group"
List ParameterNames = OP.ParameterNames("My Group","*.Value");
foreach (string ParameterName in ParameterNames)
{
	OP.Log(ParameterName + " = " + OP.GetParameter(ParameterName));
}
OPScript

OP.LogParameters

This function logs both Parameter Names and Values to the console. It will only log Parameters which has the running script's access level  equal or higher than the Parameter's MinimumReadAccessLevel.

The function has the following input:

- GroupName [Optional]: The group to which the parameter belongs to. Group names are not case sensitive. If not specified, it will query the default group.

- SearchWildCard: Searches for Parameter Names that matches the wildcard. Use "*" to return all Parameter Names.

- NumberOfParametersLimit: The number of Parameter to return limit. If not specified, it will return all Parameters.

Examples:
//This logs all parameter names
OP.LogParameters("*");

//This logs the first 100 parameter names
OP.LogParameters("*",100);

//This logs all parameter names from "MyGroup" which ends with ".Val"
OP.LogParameters("MyGroup","*.Val");

//This logs the first 90 parameter names from "MyGroup" which ends with ".Val"
OP.LogParameters("MyGroup","*.Val",90);

What's Next?

Open-Plant is a revolutionary Industrial IOT Platform software, used to create and deploy Industrial IT apps/solutions. It is an all-encompassing solution offering both back-end and front-end components i.e. the full stack. From our user's experience, creating and deploying Industrial IT apps became 10x faster and 10x less cost. We serve the mining, energy, oil & gas, construction and manufacturing industry. 

OPEN-PLANT PTY LTD

We are based in 
Perth, Australia

EMAIL

Sales / General Enquiry:

info@open-plant.com