Tips and Tricks for using Substitution Parameters

Blog Post created by dasmith on Nov 10, 2017

I’ve seen some confusion around how best to use Substitution Parameters, particularly when generating Tag Names in your templates. These can be incredibly useful when generating your AF structure, as once you get the syntax down you should be able to automatically generate tag names based on your site’s tag naming convention and rapidly build up hierarchies that automatically fill with your real time data! Even if your site doesn’t have a standard naming convention, substitution parameters can still be useful! This PI Square post has some great recommendations on how to best handle PI Point attributes in these situations!


One great resource I’ve found is this Asset Framework Tips and Tricks post, which has a very comprehensive document describing Substitution Parameters with some great examples! The online documentation is also very thorough, though it can be pretty confusing as well, as there are a lot of similar symbols that are used. These are the two main ways you can use substitution parameters when generating tag names:


Name substitutions – enclosing the location of an object in percent signs (%) will replace the string with the name of the corresponding object. You can use this to reference both Elements and Attributes. For example, %Element% will be replaced with the name of the current element, and %Attribute% will be replaced with the name of the current attribute. You can also use these to pull names from elements up the hierarchy. For example, %..\Element% will return the name of the current element’s parent element.


Value substitutions – when using the @ symbol with an existing attribute’s name, the value of that attribute will be substituted. For example, if you had an attribute called ‘Unit Number’ that you wanted to use in a tag name, using %@Unit Number% would be replaced with the value of the ‘Unit Number’ attribute.


While the substitution parameters video does a good job of explaining the different ways to use substitution parameters for building tag names, I find the best way to get these substitution parameters to do what you want is by trial and error. One thing you can do when testing is to use an example instance to check syntax. You can do this in the template page under the Preview section when clicking Settings on a PI Point attribute:



Here you can specify an existing element that uses the template and it will preview what the Tag Name and values would look like, so you can play around with the Substitution Parameters until you get the desired results!


You can also use the arrow next to the Tag Name field to browse through some of the available Substitution Parameters in case you forget what’s available, like so:




Another incredibly useful tool for building tag names is the String Builder data reference. String Builder can be used to parse strings to help you build parts of your tag name. The great thing is that String Builder supports standard substitution parameter syntax as well! For example, if you had a ‘Line 01’ element, but your tag naming convention only used the number itself to designate which line the tag belongs to, you could use the String Builder to pull just the last two characters from the element’s name, like so:




There are many available functions to use in string builder, and just like with Substitution Parameters and building Tag Names, the String Builder video is a great resource to start with, but trial and error is definitely the way to go. Just like when configuring Tag Names, you can get suggestions for all the available String Builder functions by clicking Settings on a string builder attribute:




From here you will be able to build your string the way you want it! Unfortunately, you can’t specify an example instance to preview your string, so if you are using Substitution Parameters with string builder, they won’t show up substituted in the Value box, and you will have to check your element itself to verify it substituted correctly.



I also wanted to address a couple common mistakes I’ve seen:




The first is that when creating PI Point attributes in a template, the default suggested tag name is often used: %Element%.%Attribute%.%ID%


This is especially common when you are building a sample element first then converting it to a template, as during the conversion a dialog box will pop up asking how you want to specify the tag names for your PI Point attributes and if you don’t specify this manually, it will just use the default. The problem with this is that once you create a new element from the template, instead of finding the correct tags corresponding to that template, it will not be able to find a tag with that particular name, and you would have to manually replace each tag name in the element after it’s created, which would be particularly undesirable for large hierarchies with lots of PI Points. It also makes editing and expanding templates a huge hassle, as the changes won’t get propagated to existing elements.




Another default setting that isn’t really recommended is the %Server% Substitution Parameter when specifying the PI Point’s source Data Archive. Since this will be substituted with the name of the default PI Server for your local machine, it can cause trouble if different users try to look at the hierarchy, especially if your site has multiple PI Servers, since different users can have different PI Servers setup as their default.


Instead, it’s better to create a separate “PI Servers” element with static attributes containing the different PI Server names, then use substitution parameters to reference the correct PI Server. This way, even if end users have different default PI Servers, they will always be directed to the intended source.



I hope this post helps some, building templates that best make use of substitution parameters can be a pretty big task but once you get it all set up the benefits are endless! And if you get stuck at all, always feel free to post your questions on PI Square!!!