The Cross Reference tool allows project-wide searching and replacing of variables and texts. Open it with CTRL+F while the Envision editor is active. The tool is available to members of the Administrators user group.
Searching
Enter a search term and select Search. The search is case-insensitive and runs across the whole project. Each match is listed with its Type, Location, and Context so you can see exactly where the term occurs before you change anything. The search covers the following project content:
- Devices of every protocol, including the name, template, and description fields
- Variables of every protocol, including the name, description, recipe, Kafka, sample group, and converter fields
- Page content, covering the settings of the graphic objects on every page
- Alarms and events, including asset, condition, message, and action fields, and the Suppress When expression of an alarm
- Converters, including the read and write conversions
- Python scripts, including the script content
- Schedules, including the actions
- The global script parameter
- UDT definitions, including parameter, variable, alarm, and event members, the Suppress When and Parent Alarms of an alarm member, and the device a variable member materializes on
- UDT instances, covering the parameter values that are filled in per instance
- Report Designer reports, covering the period variables, the KPI tile bindings, the chart series, the historian table variables, the computed columns, and the summary aggregates of the report template
Replacing
Enter a replace term, select the matches you want to change, and select Replace. Every occurrence of the search term in the selected fields is replaced and the affected devices and services are reloaded so the change takes effect immediately.
Each replacement is validated with the same rules as the configuration pages before it is written. A replacement that fails validation is listed with the reason and the original value is kept:
- A variable name must stay globally unique across all protocols, must stay out of the reserved SYSTEM and client namespaces, and must follow the variable naming rules
- A device name must stay unique across all device types
- Names of converters, Python scripts, and schedules must stay unique
- Alarm and event conditions must stay unique
- Field content must keep matching the format of the field, for example numeric fields must remain numeric
When the selected matches include the page that is open in the editor, the editor saves that page first, including unsaved changes, runs the replace and then reloads the page, so the page shows the replaced values. The Cross Reference dialog opens again with the result and the remaining matches. After the reload the page is in runtime; press CTRL+E to return to Edit Mode.
The editor works on its own copy of the open page, and a save stores that complete copy, so a copy from before the replace still holds the previous values. Until the page is reloaded, saving that copy shows the message This page was changed by Cross Reference. Reload the page before saving it. and the page keeps the replaced values.
A replace inside a UDT definition member updates the definition itself. The definition version is restamped, so its instances show as Outdated in the Asset Manager until you push the definition. A replace in a UDT instance parameter value is staged the same way and is delivered by the next push.
On a row that is materialized by a UDT instance, the fields the definition owns are protected; edit them through the UDT Manager or detach the instance first. Fields that the definition does not own, and fields that have been released on the row, stay editable here.
An element of a variable array is edited through its parent variable, which is the first element of the array. Replacing on the parent applies the change to the whole array: the elements are renamed, re-addressed, and given the same field content in the same action. The name of an array parent must keep its index, for example Temps[0], so a replacement that removes it is refused.
Renaming a variable or a device
A name is stored as text by everything that uses it. A variable name appears in the settings of graphic objects, alarm and event conditions and messages, Suppress When expressions, Python scripts, schedules, converter expressions, report templates, and UDT definition members. Renaming the variable changes its own row only, so those references keep the previous name and stop working. The condition no longer evaluates, the graphic object shows the name as static text, and the report field stays empty.
The same applies to the other names an engineer changes. A Python script is named by Execute Script actions on schedules, alarms, events, and page objects, by RunScript in other scripts, and by the hook script of a report. A Module script and a Database Connection are also named by History Sources: that link follows the rename in the same save and is not listed in the dialog. A converter is named by the Converter setting of every variable that converts through it. A page is named by navigation actions and by the home page of a user or an Active Directory group. A report is named by Execute Report actions, by RunReport in scripts, and by a Document Viewer.
A user group is named by the User Groups setting of variables, pages, Python scripts, reports, and UDT variable members, and by the group membership of each user. A user group rename is searched in those settings only, because a group name is an ordinary word and is not a reference when it appears in a description or an alarm message. Matching there is per entry of the User Groups list, so renaming Operators leaves Operators2 unchanged. Rows that a UDT instance materializes take their User Groups from the definition member, so the member is updated and the next push applies it to the rows.
Graphic objects are the one addition to that list. An object that decides its own visibility or enable state with an expression such as SYSTEM.UserGroups.includes('Operators') holds the group name in that expression, and the object grants or withholds access on the result. Those expressions are listed as references when the group is renamed. The group name is only treated as a reference where it appears between quotes on a line that reads SYSTEM.UserGroups, so a label or a message that contains the same word is left alone.
When you rename any of them on a configuration page and save, a dialog reports how many places in the project still use the previous name, lists them with their Type, Location, and Context, and offers three choices:
- Update all rewrites the selected references to the new name, which is every reference in the list unless you clear one
- Review opens the Cross Reference tool with the previous name in Search and the new name in Replace, and the references already listed, so you can choose them one by one
- Keep as is leaves the references unchanged, which is what you want when the rename was made so the existing references point at another variable
Every place in the list has a check box and is selected when the dialog opens. Clear the check box of a place to leave it on the previous name. This matters because a name is also written in text that is not a reference: the same name can appear in an alarm message, in the label of a graphic object, or in a comment in a Python script, and those places are listed together with the bindings. The previous name is highlighted in the Context column so you can see where it sits in the value, and the search box above the list filters the list on Type, Location, and Context. The check box in the header of the list selects and clears the places the search currently shows, so you can search for a part of the project and clear it in one action. Selecting and clearing does not depend on the search: filtering the list only changes what is displayed.
The button reads Update all while every place is selected and changes to Update selected with the number of places when it is not. When the update is done, the message reports how many references were updated, how many failed, and how many were left unchanged. The audit trail records the same three numbers, so a partial update is visible as a decision afterwards.
The same dialog appears when you rename a device. A variable name may contain the {Device} replacer, which resolves to the name of the device the variable belongs to, so renaming the device changes the name of every one of those variables at once. Variables with a fixed name keep their name when the device is renamed and are not affected.
A UDT instance names its target device as the value of a parameter of type Device, and that value is listed as a reference as well. Update all rewrites it and marks the instance as having pending changes; push the instance afterwards to apply the new device name to the rows it materializes. Keep as is leaves the parameter on the previous device name, which is what you want when the instance is meant to stay with a different device.
Matching is on the complete name, so renaming Flow1 does not change Flow10 or MyFlow1Total. When the variable is the first element of an array, the elements are renamed with it and their references are included.
Samples that the historian has already recorded keep the previous name. A trend or a historian report on the variable shows history from the moment of the rename onwards. Records in the audit trail and the alarm and event history keep the name that was in use when they were written.
Rows that a UDT instance materializes are not written directly. Their definition member is updated instead, and the next push of the instance applies it to the rows.
A push can rename variables as well, when a variable member of the definition was renamed or when a replacer in its name resolves to another value. The push preview lists those renames, and after the push the Asset Manager and the UDT Manager offer to update the references through the same dialog, for the whole set of renames at once. Review is not offered there because a push renames several variables in one operation.