Substitute characters in object names

PI Connector for UFL includes a function that allows for the substitution of characters that are not supported in PI Point names, PI AF Element names, PI AF Element attribute names, Event Frames, and Event Frame attribute names. While the best practice is to avoid using "illegal" characters (including * ' ? ; { } [ ] | \ ` ") as part of object names, it is sometimes difficult to guarantee that the data source will not produce such characters. If this is your case, use the following procedure to replace the default substitution of the unsupported characters the connector implements with new characters that you define.

1. Stop the connector and the connector service.

2. Navigate to: %PIHOME64%\Connectors\UFL\Configuration and open the ConnectorGlobal.config.json file.

3. Add Key-Value pairs to SubstitutionCharactersListsection. For example: {"Key":"|","Value":""} or {"Key":"?","Value":"-"}

   • A character can be replaced with nothing, "".

   • If more than one character is in the key, you will get an error. If more than one character is in the value, only the first character will be taken.

   • Backslash (\) and double-quotes (") must be prefixed with the backslash escape character.

     The modified global configuration file should look like the following example:

     {
     "connectorglobal": {
     "ConfigObject": {
     "OutputPath":
     "C:\\ProgramData\\OSIsoft\\PI Connectors\\UFL.ConnectorHost\\Output",
     "PurgeTime": 1,
     "RestBasicAuthentication": 1,
     "ActiveRestVerifyCertificates": false,
     "SubstitutionCharactersList": [
     {
     "Key": "\"",
     "Value": ""
     },
     {
     "Key": "\\",
     "Value": "/"
     },
     {
     "Key": "?",
     "Value": "-"
     }
     ]
     }
     }
     }
     

4. Start the PI Connector for UFL service.

Object names with substituted characters will be created once values are received.

Note: Using the substitute function creates a new object name. It does not rename the object that has already been created. For instance, if you attempt to rename a PI point using this feature, a second point will be created leaving the so-far-collected events in the original point.