Built-in Methods and Libraries

ServerMain Class Methods

This section has information on some methods accessible by the ServerMain Class pre-built in any new project and how to use them in your projects. This section covers the following ServerMain class methods:

• OnActivate

• OnDeactivate

• GetInitialDataSetParameters

These methods can be adapted to fit various application requirements and ensure smooth transitions between different project states or dynamic configurations. To utilize methods from the ServerMain Class, follow these steps:

1. Navigate to Scripts → Classes → ServerMain.

2. Within the ServerMain class, you can create methods to execute code during the server processes.

3. To implement these methods, go to Scripts → CodeEditor.

4. In the CodeEditor, write the necessary code for the methods you've created in the ServerMain Class.

For instance, you can utilize ServerMain Class methods to reestablish communications after any project or server state change. This applies to scenarios like starting the project or switching between active and standby states in a two-project redundancy setup.

OnActivate

The OnActivate method is invoked when a project transitions from an inactive to an active state, such as during initial startup or when a standby project becomes active in a redundancy scenario. 

public void OnActivate(){
     //Write your code here 
}

This method executes the instructions within its code block whenever the project or server changes from inactive to active.

OnDeactivate

The OnDeactivate method is invoked when a project transitions from an active to an inactive state, either when it is stopped or during a redundancy scenario. 

public void OnDeactivate(){
     //Write your code here 
}

Upon each change from active to inactive, this method executes the instructions specified within its code block.

GetInitialDataSetParameters

The GetInitialDataSetParameters method retrieves initial parameters for a DataSet, which is useful for configuring dynamic data sources with diverse initial settings. This method is called for every dataset configured in Datasets→DBs, enabling customization of each field (columns) within the Datasets→DBs, such as reading from an XML file. If the method returns "true", the configuration in the Manager is replaced with the new values obtained from the output arguments.

public bool GetInitialDataSetParameters(string datasetName, out string provider, out string database, out string connectionString, out string logonName, out string logonPassword, out string serverIP)
{
       //Write your code here
  return true;
}

Remote Assets and Tags Methods

The Remote Tags API allows the application to consume directly Assets and Tags defined in remote system such as OSIsoft PI System or OSIsoft PI AF (Asset Framework).

You can use that functionality in two ways:

1. The Drawing Tool object "Remote Assets" will display automatically the remote asset tree, and the configuration on DEVICES, as describe below, is executed. 

2. There are methods on the Script which allows the dynamic binding to consume the remote data model.

In order to use the Remote Tag API, you need to make sure some requirements are met.

Feature Requirements

Project Settings

To enable the RemoteAssets and RemoteTags features in your Project, you must be configured for the Enterprise Family. To do so, go to Info → Settings, and select the correct family.

Otherwise, you may see an error message on your TraceWindow Logs, as shown in the image.

Device Configuration

In the Devices → Channels tab, create a new Channel for the desired communication protocol. Configure the ProtocolOptions field with the necessary information if the driver requires it.

In the Devices → Nodes tab, create a node, assign it to our newly created channel, and fill in the Station parameters as required by the driver.

There is no need to create communication Points when using the Remote Tags and Assets feature.

Server Startup Task

On Scripts → Tasks, select the default ServerStartup task, and go to its Code Editor environment. Add the following call method:

The following code block defines a function that sets up the device node for RemoteTags and RemoteAssets services. It should only be invoked during the ServerStartup task and expects two parameters: the device node name for RemoteTags and the device node name for RemoteAssets.

@Server.SetRemoteDeviceNode(string deviceNodeNameTags, string deviceNodeNameAssets)

string nodeRemoteTags =  @Device.Node.<NodeForRemoteTags>.GetName();
string nodeRemoteAssets = @Device.Node.<NodeForRemoteAssets>.GetName();
@Server.SetRemoteDeviceNode(nodeRemoteTags, nodeRemoteAssets);

This call method will enable some predefined methods available for Remote Tags and Assets in the chosen Node. These methods are described in the next sections.

RegisterElementToTag

This runtime method allows you to map a whole remote asset to a tag. In order to do this, you need to create a Template with the same structure of your asset.

This means that you will have a Template that contains the same elements your Asset does.

The RegisterElementToTag registers an element name to a tag within the RemoteAssets service. The function accepts three parameters: assetName (the element name in the remote device), tagName (the tag name in your project), and an optional readOnly flag that indicates if the asset is read-only. The function returns a boolean flag indicating success (true) or failure (false). The function is called using the following method's syntax:

@Client.RegisterElementToTag(assetName, tagName);

string assetName = "User\Motor";
string tagName = @Tag.Motor.GetName();
@Client.RegisterElementToTag(assetName, tagName);

In the example, assetName is assigned the value "User\Motor", and tagName is assigned the value from @Tag.Motor.GetName(). Then, both are passed as parameters when the RegisterElementToTag method is called.

@Client.RegisterElementToTagAsync(assetName, tagName).

When executing this method, you should see messages in the TraceWindow Logs stating that the Remote Asset was registered to a Parent Tag and its Template elements have their values updated.

RegisterRemoteTag

This method allows you to map a specific remote tag to a Project Tag.

The RegisterRemoteTag registers a remote tag within the RemoteTags service.

The function accepts four parameters: remoteTagName (the tag name in the remote device), tagName (the tag name in your project), an optional readOnly flag that indicates if the asset is read-only, and an optional onlyValueProperty flag that indicates whether only the value property is used, ignoring Min, Max, EngUnits, and Description properties.

The function returns a boolean flag indicating success (true) or failure (false).

The method is called using the following syntax:

@Client.RegisterRemoteTag(remoteTagName, tagName). 

string remoteTagName = "User\Historian-MyTag";
string tagName = @Tag.DoubleTag.GetName();
@Client.RegisterRemoteTag(remoteTagName, tagName);

In the example, remoteTagName is assigned the value "User\Historian-MyTag", and tagName is assigned the value from @Tag.DoubleTag.GetName().

@Client.RegisterRemoteTagAsync(remoteTagName, tagName)

When executing this method, you should see messages in the TraceWindow Logs stating that the remoteTagName was registered and its value was updated.

RefreshRemoteTags

The RefreshRemoteTags performs a new reading on the registered elements within the RemoteTags service. The purpose of this function is to refresh the tag data configured in the service, and it does not require any parameters. The method's syntax is:

@Client.RefreshRemoteTags();

UnregisterRemoteTag

The UnregisterRemoteTag removes remote tags from the registered list within the RemoteTags service. The method's syntax is:

@Client.UnregisterRemoteTag(remoteTagName);

string  remoteTagName  =  "User\Historian-MyTag";
string tagName = @Tag.DoubleTag.GetName();
@Client.UnregisterRemoteTag(remoteTagName);

In the example, remoteTagName is assigned the value "User\Historian-MyTag", and tagName is assigned the value from @Tag.DoubleTag.GetName().

@Client.UnregisterRemoteTagAsync(remoteTagName, tagName);

UnregisterElementToTag

The UnregisterElementToTag removes assets from the registered list within the RemoteAssets service. It requires one parameter: assetName, which is the asset name in the remote device. The function returns an integer with the value 0 if the operation is successful. The method's syntax is:

@Client.RegisterElementToTag(string assetName);

In the the following example, assetName is assigned the value "User\Motor", and the function is called using @Client.UnregisterElementToTag(assetName).

string assetName = "User\Motor";
@Client.UnregisterElementToTag(assetName);

@Client.UnregisterElementToTagAsync(assetName);

UnregisterAllAssets

The UnregisterAllAssets removes all remote assets from the registered list. The method's syntax is:

@Client.UnregisterAllAssets();

UnregisterAllRemoteTags

The UnregisterAllRemoteTags removes all remote tags from the registered list. The method's syntax is:

@Client.UnregisterAllRemoteTags();

In this section...