Shared Libraries

The Shared Libraries dialog imports pages, UDT Definitions, User Groups, Python Scripts, Reports, Converters and Color Library colors from another project, follows what was imported and updates it when the library changes.

Updated 13 min read
On this page (14 sections)
  1. Overview
  2. Prepare the Library Project
  3. Library Sources
  4. Add Items
  5. User Groups
  6. Python Scripts
  7. Reports
  8. Converters
  9. Color Library
  10. EnvisionSCADA Library
  11. Updates
  12. Followed Items in the Project
  13. Configuration API and MCP
  14. Import Page(s) from a File

A library is an ordinary ENVISION project that holds the pages, symbols, UDT Definitions, User Groups and Python Scripts that several projects have in common. The Shared Libraries dialog connects a project to one or more libraries, imports items from them and keeps track of what was imported.

An imported item is a normal item of the project. It is stored in the project, it runs without a connection to the library and it can be edited like any other item. The project remembers where the item came from, so the dialog can show when the library holds a newer version and replace the item on request.

Open the dialog in one of these ways:

  • In the page editor, click the Shared Libraries icon in the row of icons at the bottom of the left menu.
  • In the configuration menu, click Shared Libraries.
  • Click the purple pill with the Library Source name on a followed item.
The dialog is available to members of the Administrators user group. On a redundant pair, sources are saved and items are imported on the primary node.

Prepare the Library Project

In the library project, mark the pages, UDT Definitions, User Groups, Python Scripts, Reports and Converters that are made for use in other projects as Shared. A project that imports from the library is then offered the Shared items first.

ItemWhere to set Shared
Page or symbolOpen the page in the page editor, open the page settings and tick Shared. Save the page. On the Pages page, the Shared column sets the same mark.
UDT DefinitionOpen the UDT Definition in the Asset Manager or on the UDT Manager page and tick Shared. Save the definition.
User GroupOn the User Groups page, click Settings on the row of the group and switch on Shared under Shared Libraries. Click Save.
Python ScriptOn the Python Scripts page, click Settings on the row of the script and switch on Shared under Shared Libraries. Click Save.
ReportOn the Reports page, click Settings on the row of the report and switch on Shared under Shared Libraries. Click Save.
ConverterOn the Converters page, click Settings on the row of the converter and switch on Shared under Shared Libraries. Click Save.

The Administrators group is part of every project and is left out of the list. The Shared setting describes the library project only: an imported item arrives without it.

Library Sources

A Library Source is the saved connection to one library. Click New Source, fill in the fields and click Save. A project without sources opens the dialog directly on this form. Select a source in the list at the top of the dialog to work with it. Edit changes the selected source and Delete removes it.

The Source field selects where the library is read from:

SourceReads fromUse when
ENVISION SystemA running ENVISION system that holds the library project.The library runs on an engineering server that this system can reach.
Git RepositoryA Git repository that holds a project pushed from ENVISION with Git Version Control. The latest commit of the branch is read.The library is kept in Git, on an internal Git server or on a hosted service.
FileAn .envision file made with Export Project.The library is handed over as a file, for example to a site without a network connection to the library.

The fields depend on the source type:

SourceFieldDescriptionExample
AllNameThe name of the Library Source. It is shown in the source list and on the pills of followed items.Plant Library
ENVISION SystemAddressThe address of the other ENVISION system.https://eng-lib01
ENVISION SystemUsernameAn account of the Administrators group on the other system.LibraryReader
ENVISION SystemPasswordThe password of that account. It is stored in this project.
ENVISION SystemAllow untrusted certificateAccepts an HTTPS certificate of the other system that this server does not trust, for example a self-signed certificate.
Git RepositoryRepository URLThe HTTPS address of the repository.https://git.example.local/library.git
Git RepositoryBranchThe branch to read.main
Git RepositoryUsernameThe user name for a repository that requires a login.
Git RepositoryTokenThe access token or password for a repository that requires a login. Read access to the repository is sufficient. It is stored in this project.
FilePathThe path of the .envision file as the server sees it. The ENVISION service account reads the file, so a network share needs access for that account. A path that starts with {Program} is read from the program folder of this system, for example {Program}\Library\EnvisionLibrary.envision.\\server\share\Library.envision
A Git Repository source is cloned into the data folder of this system, apart from the Git working copy of the project itself. The clone is refreshed each time the source is opened.

Deleting a Library Source keeps the imported items in the project. They are no longer followed.

When the installation holds the library that ships with the product, a new project starts with the Library Source EnvisionSCADA Library. It reads the file {Program}\Library\EnvisionLibrary.envision, which each installation of a new version replaces. The source only links the library: items are added with Add Items. Delete the source when the project does not use it.

Add Items

The Add Items tab lists what the selected source holds, grouped as Pages, UDT Definitions, User Groups, Python Scripts, Reports, Converters and Color Library. Pages are grouped by their Library Path. Tick the items to import, or tick a group or folder heading to tick everything under it, and click Import. The button shows the number of ticked items.

ControlDescription
SearchFilters the list on name, Library Path and description.
Shared onlyLimits the list to the items that are marked Shared in the library. Untick it to list every item of the library. The option is shown when the library has at least one Shared item. Color Library colors are always listed.

Each item carries one or two chips:

ChipMeaning
NewThe project has no item with this name.
ExistsThe project already has an item with this name, whatever its origin.
FollowedThe item was imported from the selected source and is followed from it.
Followed: source nameThe item is followed from another Library Source. Importing it from the selected source moves it to this source.

Replace existing decides what happens to an item whose name already exists in the project:

ItemReplace existing offReplace existing on
Page or symbolImported beside the existing page, with a timestamp in its name.Replaced. The page keeps its User Groups and Library Path, and its previous version stays in Page History.
UDT DefinitionSkipped.Replaced.
Python ScriptSkipped.Updated, see Python Scripts below.
User GroupUpdated.Updated.

After the import the dialog lists the result per item: Imported, Replaced, Imported beside the existing page, Skipped, Failed and Notes. Symbols and UDT Definitions that an imported page or UDT Definition depends on are imported with it. The imported items are followed from then on.

When a page was imported, the open page is saved before the import and the editor reloads when the dialog closes. After a symbol was replaced, use Push to Instances to bring its instances up to date. After a UDT Definition was replaced, push the assets in the Asset Manager.

User Groups

A User Group from a library is handled like the Import button of the User Groups page: a group with a new name is added, and a group whose name exists is updated with all settings of the library group. The users of the project keep their membership.

The Administrators group is part of every project. It is left out of the list and stays as it is.

Python Scripts

The library owns the code of a Python Script. The settings that decide whether and how the script runs on a system stay with that system:

SettingNew scriptExisting script
Script, Description, ModuleFrom the library.Replaced by the library version.
EnableFrom the library.Kept.
Network & File AccessOff.Kept.
User Groups, AssetFrom the library.Kept.
EndPointFrom the library when it is free in the project.Kept.

A new script arrives with the Enable setting it has in the library and with Network & File Access off. Review the script and tick Network & File Access on the Python Scripts page when the script needs it. When the EndPoint of a new script is already in use in the project, the script is imported with an empty EndPoint and the result lists a note.

Reports

The library owns the layout of a report. The settings that decide who runs the report on a system and where its files are written stay with that system:

SettingNew reportExisting report
Layout, DescriptionFrom the library.Replaced by the library version.
EnableFrom the library.Kept.
User GroupsEmpty.Kept.
Output PathEmpty. The files are written to the Reports folder of the project.Kept.
File NameFrom the library.Kept.

A new report arrives with the Enable setting it has in the library and without User Groups, so only Administrators can run it. Set its User Groups and Output Path on the Reports page. An existing report is replaced only when Replace existing is ticked.

Converters

A Converter from a library arrives with its Read and Write expressions and its Description. A converter with a new name is added. A converter whose name exists is replaced only when Replace existing is ticked.

Color Library

Each color of the Color Library is one item, identified by its name, and carries its value in every theme. The list shows the value of the default theme of the library. All colors of the library are listed; a color has no Shared setting.

SituationResult
New colorAdded to every theme of the project. A theme with the same name as a library theme takes the value of that theme. Every other theme starts with the value of the default theme of the library.
Existing colorReplaced only when Replace existing is ticked. Themes with the same name take the library value; the other themes keep their value.
Library theme that the project does not haveLeft out, and listed in the result. Add a theme with the same name in the Color Library and update the colors to take its values.

A theme of the library and a theme of the project are the same theme when they have the same name. Themes are left as they are: an import adds or changes colors only. Reload an open page to draw it with the imported colors.

EnvisionSCADA Library

The Library Source EnvisionSCADA Library offers one page per symbol group, listed under the folder OpenBridge, and the Color Library colors whose names start with OB_. The pages hold group symbol masters for automation diagrams, based on the automation components of the OpenBridge Design System version 1.0.0, each with its name below it. Import the pages of the groups the project uses to make their symbols available in the Symbols tab, under the folder OpenBridge/Automation. Import the colors as well: the symbols use them for every color. Draw pipes and lines between the symbols with Polyline objects.

PageSymbolsReplacers
OB_MotorsOB_Pump, OB_PumpVertical, OB_Fan, OB_Motor, OB_MotorVerticalRunning, Speed %, Alarm
OB_ValvesOB_DigitalValve, OB_DigitalValveVert, OB_AnalogValve, OB_AnalogValveVertOpen, Opening % (analog valves), Alarm
OB_EquipmentOB_Damper, OB_Router, OB_Router2On, Alarm
OB_Electrical57 electrical symbols, one row per component: bipolar transistors, capacitors, converters, diodes, filters, grounds, logic gates, MOSFETs, resistors, sources, switches and transformers, for example OB_Resistor1 to OB_Resistor5On, Alarm
OB_ReadoutsOB_ReadoutRight, OB_ReadoutLeft, OB_ReadoutTop, OB_ReadoutBottomValue, Unit
OB_TanksOB_Tank, OB_TankCompactValue, Max, Trend (-2 to 2), Unit, Tag
OB_BadgesOB_Badge<Type><Mode> for the types Auto, CommandLocked, Duty and AlertOff and the modes Flat, Regular and EnhancedVisible

Each symbol shows the states of the original component through its replacers. A replacer for a value that changes, such as Running, On, Open, Alarm, Speed %, Opening %, Value, Max or Trend, accepts a fixed value or a variable name. A true/false replacer accepts true, false, 1, 0 or a variable. The replacers Tag and Unit take fixed text.

Example: an instance of OB_Pump with Running set to Pump1_Running and Speed % set to Pump1_Speed follows both variables. The same instance with Running set to true and Speed % set to 75 shows a fixed state.

The colors carry the values of the four OpenBridge palettes in the themes Default (day), Dusk, Night and Bright. To use the Dusk, Night and Bright palettes, add themes with these names in the Color Library before the colors are imported. The license text of the OpenBridge components is included in the library file.

Each page starts with the symbol ES_LibraryHeader: a reminder that Ctrl+I shows invisible objects in the editor, and the buttons Day, Dusk, Night and Bright, which select the theme of the same name (Day selects the theme Default). Delete the header from an imported page when the project does not need it.

Updates

The Updates tab lists the items that are followed from the selected source and compares each one with the library as it is now. The number on the tab is the number of followed items.

StatusMeaning
Up to dateThe item equals the library version that was imported.
Update availableThe library version changed since the import.
Edited hereThe item was changed in this project since the import.
Changed in bothThe library version changed and the item was also changed in this project.
Not in the libraryThe source no longer holds an item with this name.
Not in this projectThe item was deleted or renamed in this project.

Items with Update available are ticked. Click Update to replace the ticked items with the library version. An item that was edited in the project is left unticked, because an update overwrites the edit. Tick it to take the library version anyway. For a page, the edited version stays in Page History.

Editing a setting that stays with the project, for example Enable on a Python Script, leaves the status at Up to date.

Stop Following ends the tracking of the ticked items. The items stay in the project unchanged, their pill disappears and they leave the Updates tab. Import an item again from the source to follow it again.

An item is followed by its name and from one Library Source at a time. After a followed item is renamed in the project, it shows as Not in this project. Tick it and click Stop Following to remove the entry.

Followed Items in the Project

A followed item carries a purple pill with the name of its Library Source. The pill is shown in the Pages and Symbols panels of the page editor, on the UDT Definitions in the Asset Manager, and in the name column of the User Groups, Python Scripts, Reports and Converters pages. Click a pill to open the Shared Libraries dialog.

Configuration API and MCP

The followed items and an import are available through the Configuration API and, mirrored one to one, through the MCP tool ManageSharedLibraries. Both are restricted to Administrators, and an import to the primary node. Library Sources are created and edited in the Shared Libraries dialog only, and no answer contains a user name, password or token.

EndpointMCP toolDescription
GET API/Config/SharedLibrariesManageSharedLibraries, action 'status'Lists the Library Sources and the items followed from each, with their status. The optional sourceId limits the answer to one source.
GET API/Config/SharedLibraries/ItemsManageSharedLibraries, action 'list'Lists what one source offers per kind. Each item states whether it is Shared, whether the name exists in the project and whether it is followed.
POST API/Config/SharedLibraries/ImportManageSharedLibraries, action 'import'Imports the named items from one source and follows them. The answer lists the imported, replaced, skipped and failed items and the notes.

An import request names the items per kind: pages, udtDefinitions, userGroups, pythonScripts, reports, converters and colors, each an array of names. replaceExisting has the meaning of Replace existing in the dialog. A followed item with the status Edited here is replaced only when replaceEdited is set as well.

The MCP tool is described to an AI client as a tool to use only when the user asks for an import or an update from a library.

Import Page(s) from a File

A page export file is imported with the Import button on the Pages tab of the left menu. The Import Page(s) dialog opens: click Choose File, select a page export file (.json) made with Export, tick the pages and click Import. Replace existing works as described under Add Items. Pages imported from a file are not followed.

Something missing or wrong in this article? Contact us