Renaming Tags

With the Historian SDK,  tag owners, such as Historian SDK applications,can rename existing tags on the fly without stopping the Historian server or using a separate utility. This mechanism also allows for continued data storage while the tag names are being changed.

Tag renaming occurs on the Historian server and may take some time. To avoid blocking the caller, the RenameTags method requests the server to start the renaming operation and immediately returns. The caller must periodically check a HistorianTagRenameStatus object until it is no longer pending, and then check its ErrorOccurred property. If it is false, then the tag renaming operation succeeded. If it is not false, check the status object’s Error property to see the reason for the failure.

The RenameTags method performs some basic validation of the provided array of new and old tag names. If it detected anything wrong with it, it will return an error immediately and will not even try to start the rename operation.

The RenameTags method renames tags only if they exist. That means that you can safely perform the same tag rename operation again. If some tags have been renamed already, then the old names do not exist anymore, and the repeated rename request will succeed.

These are the requirements for the tag name array validated on the client side:

• It can be empty, but then RenameTags will immediately succeed without contacting the server.

• All old and new tag names should be unique, no repetitions or circular renaming allowed. The uniqueness check is performed in accordance with the historian server case sensitivity setting. If the historian server is unavailable, the operation will immediately fail.
• The tag names should comply with the tag naming rules for allowed characters and maximum name length.
• The tag name array size should not exceed 1,000. If you need to rename more tags, then do it in several consecutive RenameTags calls. If you have a large number of tags in your Historian server, renaming 1,000 tags may take several minutes due to multiple dependent tables to be updated in the Runtime database. In that case, it is recommended to pass smaller tag name arrays in each RenameTags call.

Example

Tuple<string, string>[] tags =
{
   Tuple.Create("TagName1", "NewTagName1"),
   Tuple.Create("TagName2", "NewTagName2"),
   Tuple.Create("TagName3", "NewTagName3")
};
HistorianAccessError error;
HistorianTagRenameStatus tagRenameStatus = new HistorianTagRenameStatus();
if (!historian.RenameTags(tags, ref tagRenameStatus, out error))
{
    Console.WriteLine("Failed to rename tags: {0}", error.ErrorDescription);
}
else
{
    while (tagRenameStatus.Pending)
    {
        Console.WriteLine("Tag rename status is pending");
        Thread.Sleep(1000);
        historian.GetTagRenameStatus(ref tagRenameStatus);
    }
    if (tagRenameStatus.ErrorOccurred)
        Console.WriteLine("Tag rename error: {0}", tagRenameStatus.Error.ErrorDescription);
    else
        Console.WriteLine("Success!");
}

After HCAL validates the tag name array, it contacts the Historian server which should be up, but can be either in the Stopped or Running state. The server may perform some extra validation and then update the metadata of those tags in all Historian server subsystems. Because the data storage is performed based on TagIds, not tag names, the data could be continuously stored during this operation. HCAL continues polling the Historian server in background about the status of the operation and as soon as it is completed, it changes the pending status of the corresponding HistorianTagRenameStatus object.

If the connection to the Historian server is lost, the server continues to work on the rename job. After the connection is restored, the HCAL internally will try to find the rename job on the server and continue polling its status. It is recommended to have the store/forward folder configured for the HistorianAccess object so that the HCAL can persist the information about the pending tag rename operations in case of the SDK application restart.

Current Limitations

• Tag renaming is supported only through the connection currently owning the tag. For example, if one SDK application is currently sending data for a tag, another SDK application should not try to rename it at the same time.
• The new tag name cannot be an already existing, active tag. If such renaming is needed, then the user should stop sending data to that tag and delete it using the DeleteTags method. Then he or she can use that name as the new name. After the rename operation is completed, the data previously collected for the deleted tag becomes retrievable again.
• Tier-2 tags do not get renamed when the user renames their source Tier-1 tags, but their metadata gets updated to show the new source tag name.