Libraries
Say once what a value means: what it measures, its unit, the rules it must satisfy, its alarm and how often it arrives. Every topic given that meaning follows it.
- Where
- Explore › Libraries
- Holds
- Properties: value, unit, rules, alarm, sampling
- Validation
- Observe · Warn · Enforce, per branch of the tree
- Licence
- Semantic layer (Foundation, Enterprise)
New here? Start with the 10-minute tutorial: three pumps that report psi and bar end up on one kPa chart with one alarm for all of them.
A library is a versioned set of properties. A property says what a value is: a pump's discharge pressure in bar between 0 and 16, a tank's level in metres, a motor's running state. Topics are then given that meaning (Giving a topic a meaning), and every value they carry is checked, converted to the property's unit, alarmed on and charted the same way.
Libraries replaced the data schemas of earlier 3.0 builds. On upgrade from such a build, its schemas become libraries and their attributes become properties (each schema version a published library version, as schema versions could not change), with their constraints, alert limits and sampling carried over, and every schema binding becomes a meaning of the same topic (see Changes in 3.0). The 2.6 schema registry is not carried over. An old link to the Schemas page opens this page.
The semantic layer needs a licence that includes it: Foundation or Enterprise. Without it there are no meanings and no alarm limits, and the Libraries page says so and where a licence is applied (System Management → License).
The Libraries page
Open Explore › Libraries. The left panel lists libraries by namespace, newest version first; the Retired toggle shows retired versions too. The right panel shows the selected library, its versions and its properties.
The CNC library, a draft, with its properties. Each row shows the value, the unit, whether an alarm and sampling are set, and how many topics use it.
| Action | What it does |
|---|---|
| Import file | Imports a library file as a published version (Libraries as files). |
| Export file | Saves the selected version as a JSON Schema file (Libraries as files). |
| New library | Creates a draft library. Its namespace and version identify it and never change, for example urn:acme:pumps version 1.0.0. The maestro namespace is reserved for the built-in library. |
| New version | Creates a new draft in the same namespace, with the version number you choose, started as a copy of an earlier version or empty (Starting a new version). The versions before it stay as they are. |
| Rename | Changes the name and description people read, on a draft or a published version. A retired library's name is fixed. |
| Publish | Fixes the version's definitions for good (Publishing a version). |
| Retire | Retires a version no topic uses any more. It is kept, so anything that named it still resolves. |
A library is draft (properties can be added, renamed and retired, and a formula edited), published (its definitions fixed: a change to one is a new version) or retired.
A library is owned by the person who created it. One created by an agent or an API client, or by someone who left the workspace before it was recorded, has no person to own it: it is listed under Resources that need an owner as No human owner yet, for a workspace administrator to give it an owner (Ownership). The built-in library has no owner.
What meanings do for you
What meanings do for you, in the page header, opens a page of five outcomes, each with a button to the screen that does it: one alarm for all similar equipment, the same units everywhere, bad sensors caught, clean data downstream, and data found by what it is. Start from your data sits at the top. The same link is on the empty Libraries page, beside Start from your data's groups, and as Why? beside Give this topic a meaning on a topic page.
Five outcomes, each with the screen that does it. The tutorial link sits underneath.
Start from your data
A workspace that has not started yet opens its Libraries page on Start from your data: your plant as MaestroHub reads it, by area, line and machine. "Not started" means the workspace has no library of its own and no topic with a meaning (a proposed one counts); the built-in library alone does not count. Later, Start from your data stays in the page header. On the workspace Overview, the optional setup step Give your data meaning opens it too, until the workspace has its first topic with a meaning.
Every topic you can read that has sent values is read once: its name, the unit on record for it and its recent values, by the same rules as the suggestions. Nothing is changed. A large tree takes a few seconds and the page says how far it is ("Reading your signals: 3,200 of 10,000"); the result is kept until topics are added or removed, or a library or a meaning changes, and then read again.
Your plant, understood
The demo plant, read. Use this does not wait for the questions; the signals that report no unit wait for an answer.
- The headline says how many of your signals were recognised ("We recognised 45 of your 92 signals"), with a bar of three parts: recognised, waiting for your answer, and left as they are. A topic that sends several values is one signal. When some already had a name and a unit, a line says how many.
- A unit only one answer fits is not a question. A value that reports no unit is read in the only unit that is plausible for that kind of signal, and the card says why: "read as °C: as °F it would read -15 to -11 °C, colder than any plant room a machine part sits in". The rules read the signal's name and its machine's folder, and only rule out a reading no state of the signal explains: a bearing, a motor or an oil temperature is never below about -10 °C, even idle; a product temperature is a liquid's, never below -5 °C (a brine or a freezer gets no rule); a vibration above 45 mm/s would wreck the machine; a counter of hours counts hours; an energy meter measures at least 1 kW. A cold, idle pump at 7 to 10 °C could also be 45 to 50 °F, so it is asked.
- Questions, only when both answers are plausible. "Filling hall · Line 3 P301 and P302 send pressure as a bare number around 48. Which unit?". The likely unit is marked most likely, with what the values read as in it. A strip under the headline says how many signals wait, and the questions sit below the plant. Tap the unit you know, or press Use the most likely units for these N: it lists every signal with the unit it would get and why, and nothing is applied until you press Use these units.
- The plant. Each area and line is a section, each machine a card named from its folder (
f2reads F2,line-2reads Line 2), with its state when it sends one ("running") and its values live, converted to the unit they will read in. A value waiting for your answer shows "48 (unit?)" until you answer. A machine whose every signal was left alone has no card: its signals are in the folded list. A folder of more than 12 signals and no sub-folders is a list instead of cards. - Left as they are, folded: the signals no value fits, each kind with how many and up to three examples (values we could not read as anything we know, only 0 and 1, nothing sent yet). Records from your MES and maintenance systems (alarms, work orders, orders, stops) are folded on their own line: they are kept as they are.
Use this, pinned at the bottom, gives every recognised signal and every answered one its name and unit. It never waits for the questions: the signals that report no unit simply wait, and you can answer them later. Nothing is applied by itself: you press it. The bar says what will happen ("45 signals get one name and one unit now; 19 wait for your answer. You can undo this."). Every step is checked first, and if one would be refused, nothing is written and the bar names the signals and why. When a value will change for whoever reads it (a pump sending psi now read in kPa), one line above the button names the dashboards and pipelines that read it, and pressing Use this with that line on screen is the confirmation; when nothing converts, nothing is asked. If who reads them cannot be checked, Use this waits and says so.
- When you may not give names and units here, everything stays visible and the chips and Use this are disabled with who can ("Only a Data Admin, a Workspace Admin or the steward of a branch can..."). Someone who looks after one branch sees the rest greyed.
- If you may only propose, the button reads Propose this, and the signals are sent for approval.
- If a step fails half way (another change came in, or the trial limit was reached), the bar says how many got their name and unit and why the rest did not, with Undo and Try the rest.
- Review signal by signal opens every value one row at a time, grouped by what it measures (below).
You see only the topics you can read, and only meanings from the libraries you can read: someone who looks after line 2 sees line 2's topics.
What do you want to do now?
After Use this: Undo while you stay on the page, and three things each one step away.
After Use this, a banner says what was done, with Undo: it takes the names and units off those signals again, in one step, all or none; values recorded meanwhile keep the unit they were recorded in. Undo is there until you leave the page; after that, take a name off one signal from its topic's page. Then up to three outcomes, each shown only when it has something to show:
- Alarm when any of these vibrates too much (or runs too hot, or its pressure or level goes too high): a slider sets the line, each machine shows its value now and its peak, and the sentence under it says what the line would have raised over the span the history really covers ("At 7.5 mm/s, 2 pumps would have alarmed 5 times in the last 33 minutes"). Turn on for all sets it: on a property of your own library for every signal given it later too; on a built-in one for these signals, and a pump added later needs it turned on again.
- Line 2 and line 3 on one scale, when one value came in from two lines in two units. Open the chart shows them together.
- Catch stuck or silent sensors: which of these signals have gone quiet now. Stuck sensors come with the next update.
Or go to your signals leaves the page.
Machines that look alike
Now and then a machine card ends with a quiet line: "COMP-1 and COMP-2 look like COMP-3. COMP-3's pressure may be in psi. Use the same?" It means those machines send the same signals, read from their names, units and values, and one of them looks like it reports another unit, which Use this would not catch. It is a suggestion, not a fact: you check it, and nothing changes until you confirm. Machines that look alike with nothing to catch get no line: Use this already gives them their names.
Use the same? opens the machines it suggests:
- Each machine with a tick, all ticked to start. Untick any that is not really the same. A machine already named as something else cannot be ticked and says so: change it on its own topic's page.
- Why we think so, in plain sentences: "All 4 send flow, vibration, temperature, run hours and machine state.", "P-302 has no temperature.", "Named alike: P-101 to P-302."
- A unit question when one machine's values look like another unit: "P-302's discharge pressure looks like psi, the others bar. Which is it?" Tap the unit it sends.
- What readers will see, for example: one of their numbers as the server converts it ("Discharge pressure: 43.5 psi becomes 3 bar").
Use the same names for 3 machines gives the ticked machines their names and units in one step, checked first. It stays off, and says why, while nothing is ticked, a unit question is open or you may not give names here. The page stays where it is, with what was done and Undo; What can I do now? opens the next steps. Undo takes the names and units off those signals again in one step, all or none. If one of them was changed since, nothing is undone and the page names it.
What history keeps. Values recorded while the names were in place keep them: they stay stored in the property's unit. Values from before the names were given, and after an undo, are served as the device sent them.
Why only a suggestion. Which machines are the same kind cannot be read reliably from signals alone: on a plant it had never seen, the suggestions were right about 4 times in 5 and found only a small share of the machines that really are alike. So they are offered where they help and never decide for you. Use this at the bottom of the page does not depend on them.
Map one, find the rest
When you give one signal a name by hand (Giving a topic a meaning), the panel looks for the signals that share its name pattern and send the same kind of values, from your last reading: "4 more machines have a position that sends closed, open, moving: give them the same name?", with the machines named. Give all 4 the same name gives them the same name and unit in one change, checked first, with Undo. TT_201 mapped by hand offers TT_202 to TT_206. With no reading, or no signal like it, the panel offers its search for look-alikes instead.
Review signal by signal
Review signal by signal lists your values grouped by what they measure; Review opens one group's topics, one row each: what it sends, the unit it is read in, how that is known, and, when it converts, what it will read as.
The line's spindle speeds, all ready, and the pipeline that reads them.
- Rows sit under headings of the same shape (
line#/filler/P_#_PSI), each with Select all. Ticking across headings is fine: both filler lines apply together. - Ready rows are ticked. Untick anything that is not one.
- Held back rows are unticked and say why: the name and values fit two meanings, the evidence is weak, the values are only 0 and 1 (a state, not a pressure), or the topic has sent nothing yet. Tick one if you know better.
- When no unit is reported and the values fit more than one unit, you are asked. The question shows what the values read as in each unit and whether that is inside the property's plausible range, and marks one more likely when the other devices in the same folder report units of one system (psi and gal/min suggest °F). Pick one for all of them, or Different units per topic. Apply to all stays disabled, and says why, until every question is answered; Apply the N now gives the ready topics their meaning and leaves the rest for later.
- When you may not give meanings here, the apply button is disabled and says so, with what to ask for. When that cannot be checked at all, it says so with the server's reason; try again in a moment.
When you apply says how many topics, the meaning and the unit they will read in. For a built-in meaning such as Pressure you choose the meaning: Pressure itself, a meaning of your own made from it before (with how many topics have it and its alarm), or A meaning of their own…. A built-in Pressure group holds pumps, suctions, headers and boilers together, and one alarm must not reach all of them: tick the rows you mean, choose A meaning of their own…, check the proposed name (for example Pump discharge pressure) and the library it is saved in, and the ticked topics are given it. Later topics are offered that meaning, never given it for you. If you may not make one (only a Data Admin, a Workspace Admin or someone who may update a draft library can), the card says so and how to set limits on these topics only. When a value will change for anything that reads these topics (pipelines, dashboards, apps), they are named in one line above the button, and applying with that line on screen is the confirmation; when nothing converts, nothing is asked. Apply gives the ticked topics their meaning in one change, all or none, each topic with its own device unit. A group of more than 500 topics, or one whose topics carry the value in different fields, is applied in several steps, each checked before any is written, and the page shows how far it is. If you may only propose meanings here, the button reads Send N for approval. On a trial licence, a group that would pass the limit of topics with a meaning is refused whole, with how many places are left.
What you just got, and one alarm for all
After applying, the page shows the result and two of the topics that used to report different units, on one scale for the last hour (their older values are shown converted). When every topic reported the same unit, it shows one of them.
Every spindle reported rev/min already, so the chart shows one topic in its unit. When two topics reported different units, both are drawn on one scale. Next: one alarm for all 8, or the next group.
Add the alarm sets warning and high lines once for the group, and before you save shows what they would have raised over the last 24 hours, from the topics' history, judged exactly as live alarms are (with the delay you choose).
Before anything is saved: the warnings a line at 4,700 rev/min would have raised in the last day, on the topics that would have raised them. A topic far from the rest is named and left out.
- The preview reads the first 50 topics of the group and up to 2,000 values of each, and says so when there are more.
- Values a device sent before the meaning was set, in a unit that cannot be converted, are left out of the preview, and it says how many.
- A topic whose values sit far from the rest (a steam boiler among filler pumps) is named, with a link to give it its own limits, and left out of the alarm unless you tick it.
- On a property of your own library, a meaning of your own included, the alarm is the property's: these topics and every topic given it later. After saving, Change the alarm opens it again. A property of the built-in library cannot be changed, so the alarm is set on each topic of the group in one change; a topic given the meaning later needs it set again, or copy the property into your own library for an alarm that follows every topic.
The built-in library
Every workspace starts with one library already in it: MaestroHub Common (maestro:common, version 1.0.0), listed under Built in. It holds 33 everyday plant measurements, so a topic can be given a meaning on the first day, before anyone has written a library.
| Property | Measures | Reads in | Goes by (some of) |
|---|---|---|---|
| Temperature | temperature | °C | temp, tmp, pt100, rtd, TT, TIC |
| Pressure | pressure | kPa | press, pres, PT, PIC |
| Differential pressure | pressure | kPa | dp, delta_p, PDT |
| Volume flow | volume flow rate | m³/h | flow, flowrate, FT, FIC |
| Mass flow | mass flow rate | kg/h | mass_flow, steam_flow, FT |
| Volume counter | volume, counts up | m³ | totalizer, tot, gas_meter, FQ, FQI |
| Level | length | m | level, lvl, LT, LIC |
| Rotational speed | rotational frequency | rev/min | speed, rpm, spd, ST, SIC |
| Linear speed | linear velocity | m/s | line_speed, belt_speed |
| Active power | active power | kW | power, kw, pwr, JT |
| Energy counter | energy, counts up | kW·h | energy, kwh, consumption, JQ, JQI |
| Current | electric current | A | current, amps, IT, II |
| Voltage | voltage | V | voltage, volts, ET, EI |
| Frequency | frequency | Hz | frequency, freq, hz |
| Power factor | power factor | 1 | pf, cos_phi |
| Vibration velocity | velocity | mm/s | vibration, vib, vrms, VT |
| Relative humidity | relative humidity | %RH | humidity, rh, MT |
| Weight | mass | kg | weight, wt, load_cell, WT, WIT |
| Torque | torque | N·m | torque, trq |
| Density | density | kg/m³ | density, rho, DT |
| pH | acidity | pH | ph, AT, AIT |
| Conductivity | electric conductivity | µS/cm | conductivity, cond, ec, AT |
| Dissolved oxygen | mass concentration | mg/L | dissolved_oxygen, o2, AT |
| Turbidity | turbidity | NTU | turbidity, turb, ntu, AT |
| Gas concentration | mole fraction | ppm | co2, ppm, h2s, AT |
| Valve position | ratio | % | valve_position, position, opening, ZT, ZI |
| Output or setpoint (percent) | ratio | % | output_percent, controller_output, speed_ref |
| Count | count, counts up | # | count, cnt, good_count, reject_count, QT |
| Running hours | time, counts up | h | runtime, run_hours, operating_hours |
| Running | yes or no | running, run_sts, is_running, motor_on | |
| Alarm | yes or no | alarm, alm, fault, trip, PAH, PSH, TAH | |
| OK | yes or no | ok, healthy, ready, normal | |
| Machine state | text | state, status, mode |
Each property says what it measures, a unit (a topic's device may send another; you pick it when you give the meaning), a plausible range, how often its values usually arrive, and the names it goes by: plain words, abbreviations and ISA-5.1 instrument letters. A value outside the plausible range is recorded as a rule failure, as on any property (Validation rules on the topic tree): on a branch that only observes or warns, which is the default, nothing is refused. The built-in properties set no alarm limits, and no staleness or frozen threshold: a topic sets its own limits when it is given the meaning, and a copy sets the rest.
The In use column counts the topics you can read that already have each meaning. On a library used by more than 1,000 topics it counts the first 1,000 and shows a +: at least that many use it.
MaestroHub keeps it. The built-in library is read-only: every edit button says so, and the server refuses a change with the way to make it (409). Creating a version of its namespace, or importing its file, is refused as an invalid namespace (400): the maestro namespace is MaestroHub's. A new version of it ships beside the old one, and never changes a topic that already has a meaning: those topics keep the version they were given until you move them (Moving topics to a newer version).
To change it, copy it. Copy into my library on the library creates a draft library of your own (your namespace, for example urn:acme:plant) with every property; on a property page, it copies that one property into a draft of yours. A copy is yours to rename, widen, give alarm limits and names, and publish. Each copied property remembers the built-in one it came from, and the library and property pages say so ("Copied from MaestroHub Common 1.0.0 · Pressure").
Every member of the workspace reads the built-in library, as every other library, unless it is denied to them (Who can do what). Copying it needs what creating a library needs.
Publishing a version
A draft works as it is: its properties can be bound and their alarms run. Publish fixes what the version means, so everything that names it keeps one meaning for good. Topics already bound to it keep working exactly as they are: publishing changes no value and opens nothing new on them.
Click Publish on a draft. Before anything changes, the dialog compares the version with the published version before it in the same namespace (the highest lower version: 1.10.0 comes after 1.9.0) and lists, by key, the properties it adds, retires and changes, and in what: the value type, the unit or quantity, the value rules or the formula. The namespace's first published version lists every property as added.
Publishing Pumps v1.1.0: what it changes against v1.0.0, and what publishing fixes and leaves editable.
| Fixed when published | Stays editable |
|---|---|
| Keys, value types, units and quantities, value rules, formulas, and which properties exist (none is added or retired) | Names and descriptions, of the library and of each property; alarm limits and alarm behaviour; sampling |
Alarm limits and sampling stay editable because operators tune them all the time; a change reaches every bound topic with the next index version, as on a draft. To change anything in the left column, create a new version of the library.
A published version shows when it was published and a short content fingerprint (sha256:…). The fingerprint is taken over the fixed definitions only, never over names, alarms or ids, so the same library version has the same fingerprint on every instance it is installed on. Libraries carried over from data schemas show that they were published by the upgrade.
A published version: Publish and Add property say why they are not offered; Rename and each property's alarm and sampling stay available.
Publish is refused, with the reason, for:
- a version that is not a draft (published already, or retired);
- a version with no property in use: an empty version has nothing to fix;
- a version with a formula that reads a property of another library that is still a draft, unless that draft is published in the same step;
- a version with a formula that reads a retired property, or a property of a retired library. A new version copied from an older one can carry such a formula: the library page warns about it as soon as you open the draft, and Publish says which formula to edit.
When a version's formulas read other drafts, the dialog names them under Published together with it, and Publish fixes all of them in one step, or none: two drafts whose formulas read each other can only be published that way.
On a published property, the Definition tab shows what is fixed and what is not, side by side.
A property of a published version: its definition is fixed in v1.0.0; its name, description, alarm and sampling are not.
Starting a new version
To change a published version, start a new one from it. Click New version: the dialog proposes the version after the namespace's highest one, counting every version of the namespace, retired ones included (change it to any number the namespace has not used), and Start from picks what it begins with:
- A version of the namespace (the latest published one unless you pick another). Every property is copied: its key, name and description, value type, unit and range, value rules, formula, alarm and sampling. The dialog says how many. Retired properties come along as retired, so a key that once meant something is never used for something else.
- Nothing: an empty version. Its properties are not copied: add them to the new version.
A new version starts from the latest published one: three properties copied, and one retired property kept retired so its key is never reused.
A retired version is listed, disabled, as one that cannot be copied. A version of more than 5,000 properties (the most one version may hold) cannot be copied either, and the dialog says so.
The new version is a draft. Change it as any draft: add and retire properties, and edit a formula. What it computes reads the new version's own properties: a formula's input in the version it was copied from is now the property with the same key in the new one. An input from another library stays where it was. When you publish it, the dialog compares it with the published version before it: a copy you have not changed shows no change.
Each property of the new version has an id of its own; the property a version continues is the one with the same key. Topics given a meaning from the earlier version keep that meaning: starting a new version changes nothing on them.
Moving topics to a newer version
Topics keep the version they were given their meaning from until you move them. On a published version, Move topics to this version says how many topics, of the ones you can see, still carry another version of the library, and moves them.
A published version counts the topics still on another version of its library.
The dialog checks every topic before anything moves, and shows, for each meaning:
- the unit values are stored in, and its conversion when the new version stores another unit;
- a change of value type, of range or of value rules;
- the alarm limits before and after: the new version's limits, with the topic's own alarm settings converted into its unit;
- a change of how often values are expected to arrive;
- a computed meaning's formula and its version.
Each row says what changes. A row that cannot move says why; leave it out to move the others.
A meaning moves to the property with the same key in the new version. It keeps its identity, so an alarm that is open stays open and acknowledged, the topic's own alarm settings and description carry over, and nothing pages again. When the new version stores another unit, the alarm is judged in that unit from the next reading: a rate of change is measured again from there, and an alarm waiting out its delay starts the delay again. What an earlier version alarmed with stays in the topic's history. Every meaning of a topic from that version moves together, so a computed meaning and the values it reads change version at the same instant. A set of topics takes effect at one instant.
A topic cannot move when:
- the new version has no property with that key, or has retired it;
- the value would change kind (a number becomes text, a value the device sends becomes a computed one), or the device's unit does not convert to the new unit;
- the topic's own alarm settings would not hold in the new version (for example a line outside its range);
- a change of its meaning is still being applied;
- a computed meaning of another library reads it;
- you may not change its meaning (see below).
Topics you can see but may not change are counted apart, with who moves them; the dialog never includes them. Any topic that cannot move stops the whole set: nothing moves. Tick Leave out the N that cannot to move the others; the topics left out stay on their version, and the version's page keeps counting them.
A library with many topics moves in sets of up to 500 meanings. One click moves them all; the dialog shows each set's progress. A version a topic still uses cannot be retired: its refusal names this move and the newer version.
Libraries as files
A library version travels as one file: a JSON Schema document. Export a version to keep it in Git beside the rest of your configuration, to review a change as a diff, or to carry it to another workspace or instance; import a file to bring it in.
Export file on a library saves the selected version as <namespace>-<version>.schema.json, for example urn-acme-pumps-1.0.0.schema.json. Any version exports: a draft, a published or a retired one. Anyone who can read the library can export it.
The file holds what the version defines and nothing about where it is used:
- each property under
properties, by its key, with its name and description (title,description); - its value:
type,minimumandmaximum(in the property's unit),enum(an enum's states, a text's allowed values), the text rules, the fields of a record, an array's element, anddefault; - what a number measures, in
x-maestrohub-quantity: the quantity kind and the unit, by its UN/ECE code (unece:BAR) where it has one; - a computed property's formula, in
x-maestrohub-formula, its inputs named by key; - the alarm limits, alarm behaviour and sampling, in
x-maestrohub-operations; - a retired property, marked
deprecated; - where a property came from, in
x-maestrohub-source(the library namespace and key it was copied or narrowed from), andx-maestrohub-narrowsfor one made with Give these their own meaning, so it stays a narrower meaning of the built-in one after an import into another workspace.
It never names a topic, an id, a time or who made it. The same version always exports to the same bytes, and a file exported, imported and exported again is identical, so a diff in Git shows only what changed.
Import file opens the import. Pick a file: it is checked whole before anything is stored, and the dialog shows what importing it does, the properties it holds and its fingerprint.
A file exported from MaestroHub, edited as the next version: imported, it becomes version 1.1.0, published.
Import and publish stores the version, published: its definitions are fixed as when you publish a version, and its names, alarm limits and sampling stay editable. Topics on other versions stay where they are; move them when you are ready.
What the dialog says:
| You see | Because |
|---|---|
| A new library | The workspace has no version of this namespace yet. |
| A new version | The workspace holds other versions of the namespace. |
| Already here with the same definitions | The version exists with the same definitions: importing changes nothing, and the button says so. Names, alarm limits and sampling are not definitions: a file that differs only there is the same version, and the dialog lists each difference by property. Change them on the page; an import never does. |
| Refused: other definitions | The version exists with other definitions. A published version never changes: change x-maestrohub-version in the file and import it as a new version. |
| Refused, with where | Something in the file cannot be imported: the message names the place in the file (for example /properties/flow/x-maestrohub-quantity/unit) and what to change. |
An alarm carried over from a data schema keeps the schema's deadband rule (see Alarm and sampling). Its file says "deadbandRule": "legacy", which imports only back to the version it came from. To carry such a library forward, start the next version with New version, which keeps the rule; a file imported anywhere else must say isa or leave the rule out.
A file from MaestroHub is read strictly: a keyword the format does not know (a typo such as minimun) is refused, never ignored. A formula may read the file's own properties, or properties of another library's published version in this workspace: import that library first.
A JSON Schema from another tool
A JSON Schema written by hand or exported by another modelling tool imports too. It names no MaestroHub namespace or version, so the dialog asks for them; its $id is the namespace when you leave it empty.
A third-party schema imports what maps; the rest is listed, with where it appears, before anything is stored.
What maps: type, minimum and maximum, enum (a text's enum becomes a set of states), minLength, maxLength and pattern, the date-time and duration formats (a time), the email and uuid formats, the fields of an object with required and additionalProperties: false, an array's items, default, deprecated, title, description, and references inside the file ($ref to #/$defs/… or #/definitions/…). A number has no unit in JSON Schema, so it is imported as a number without a unit: give it its unit in a new version. Everything else (for example exclusiveMaximum, examples, uniqueItems) is listed under Not imported from this file, with where it appears, and is left out.
After an import, the version is a library like any other:
An imported version: published, its properties with their units and alarms, ready to export again.
Properties
Click Add property on a draft library. A property has:
| Field | Notes |
|---|---|
| Key | Letters, digits and underscores, for example discharge_pressure. Never reused in the library. |
| Value | Number, whole number, yes or no, text, one of a set of states, time, object, list or map. |
| What it measures, Unit, How values add up | For a number or a whole number: the quantity kind (Pressure, Temperature, VolumeFlowRate), the unit values are stored and shown in (bar, degC, m3/h), and whether a value is a reading, a running total, a total per interval or a rate. A unit that does not measure the quantity is refused with the reason. |
| Valid range | Values outside it are stored and marked Bad. |
| Rules | Everything a 2.x data schema could check: an exact type (int16, float32, decimal, uuid, datetime, geo_point and more), text length, patterns and formats, allowed values, an enum's states, a list's length and item type, an object's fields (each with its own rules) and whether other fields are allowed, required, and a default when absent. |
The definition is fixed once the property is created. What a property measures, its unit and its rules never change, so every value stored under it keeps one meaning. On an existing property the Definition tab shows them read-only with that reason, and Create a new property from this one opens a new property with the same definition under a new key (on a draft library). The name and description stay editable unless the library is retired.
An existing property's definition is read-only. The note says why, and offers a new property from this one.
Alarm and sampling
A property's alarm and sampling can be changed at any time, on a draft or a published library. A change reaches every topic bound to the property with the next index version.
Limits, behaviour and sampling of Temperature. Save alarm and sampling writes them together.
- Limits: warning and critical, low and high, the deadband, a message and whether warnings are urgent (Alerts). Limits typed in lets you type them in another unit of the same kind (psi for a pressure in bar); they are converted on save and always stored and shown in the property's unit.
- Deadband rule: an alarm carried over from a data schema of an earlier 3.0 build keeps the schema's rule (raised only once the value is past the limit by the deadband), so it fires exactly where it did. It can be switched to ISA-18.2 (raised as soon as the value crosses the limit; the deadband applies only on the way back). The switch is one way.
- How the alarm behaves: wait before raising and before clearing, keep it on the list until acknowledged, the chattering rule (and whether to page while it chatters), how fast someone must act, and what causes it, what follows if nobody acts and what to do.
- Rate of change and deviation from a setpoint: alarms on how fast the value moves, or how far it is from a setpoint.
- Sampling: the expected period, the staleness threshold and the frozen threshold that drive stale and frozen detection.
An alarm only applies to a number, a whole number, or a time stored as a datetime or a duration; on any other property the page says so and offers sampling only.
Someone who may read the library but not change it sees the tab read-only: every field is disabled and says why, with the same reason as Save.
Validation rules on the topic tree
What happens to a value that breaks its property's rules is decided per branch of the topic tree. In Explore › Data Explorer, right click a topic and choose Validation rule…. The dialog says what you may do there: change the rule, lock it, or only read it, as the server decides; if you cannot read it, it says who can.
pump1 follows the rule set on line1: Enforce, locked, so nothing below line1 can be less strict.
| Mode | Effect |
|---|---|
| Observe | Values that break their rules are recorded. Writers are told nothing. |
| Warn | Recorded, and the writer is told in the answer to its publish. |
| Enforce | A record that breaks its rules is rejected with the reason. |
| Inherit | Nothing set here: the topic follows the branch above. |
The dialog says what is in effect now and where it comes from: set on this topic, inherited from a topic above (named by its path), or the default (observe for topics that existed before validation rules, warn for newer ones).
Lock it makes the rule a floor: no topic below can be less strict, whatever is set there. Below a lock, the less strict modes are disabled and the dialog names the locked topic; when a lock raises a topic's mode, it says so. Choosing Inherit on a locked rule removes the lock too, and the dialog asks you to confirm that first.
Computed properties
A computed property is calculated from other properties of the same topic as each record arrives; no device sends it. A pump's hydraulic power is its discharge pressure times its flow: bind the two on the pump, bind the power next to them, and every record that brings a pressure and a flow also stores the power.
To create one, add a property as usual, give it what it measures and its unit (for the power, Power in kW), and tick Its value is computed from other properties in the Computed section.
Hydraulic power from a pressure and a flow. The check finds the conversion into kW and works a sample through it.
- Inputs. Add an input searches the properties of every library you can read. Each input gets the name the formula calls it (from the property's key; change it to something short like
p) and shows its unit. The sample value next to it is only for the check below; it is never saved. - Formula. Write it with the inputs' names, in their own units:
p * q, not a formula with a conversion constant in it. A plain number next to a quantity in+,-or a comparison is in that quantity's unit; in*and/it is a plain number, like the efficiency inp * q / 0.8. A computed property is a number, a whole number, yes or no, text or one of a set of states, and reads 1 to 16 inputs. - Check. As you type, the server checks the formula and says, in plain words, the unit it works out to and how it is converted into the property's unit (bar × m³/h, converted to kW by × 0.02778), and the value for the sample values. It warns when the formula multiplies a ratio by 100 into a
%property, which the conversion already does. When the formula cannot be saved it says why: two quantities that cannot be added, an input the formula does not use, a name that is not an input. When the server knows where in the formula the problem is, the check marks that character.
A refusal points at its place in the formula.
A computed property has no required rule and no default: nothing sends it. Its other rules, its alarm and its sampling work as on any property, because its value is stored like any other.
When a value cannot be computed, only that value is left out: the record keeps everything else and is never rejected for it. The topic shows why (A computed meaning), and the finding is on the violations list. A record that lacks one of the inputs simply has no computed value.
Changing a formula
Unlike the rest of a definition, a computed property's formula can be changed on its Formula tab while the library is a draft. On a published version the tab is closed and says why: the formula is fixed with the version, and a new formula is a new version (Publishing a version). The names of the inputs it already has are fixed: the topics using it find each input by its name. You can still add and remove inputs.
Before you save, the tab says how many topics switch to the new formula. Values already stored keep the formula they were computed with.
Every topic using the property in force switches to the new formula at the same moment, at most 500 of them. Values already stored keep the formula they were computed with: history is never recalculated. The count comes from the server and includes topics you cannot see.
Because the change reaches topics all over the tree, it needs more than editing the library. Before you save, the server checks every rule the change must pass, and Save formula names each one you fail:
- permission to approve meanings in the whole workspace (looking after one branch is not enough);
- permission to change every topic using the property in force (the tab says how many you may not change, without naming them);
- the limit of 500 topic attributes in one change;
- a library that is still a draft.
What a formula holds on to
A property a formula reads cannot be retired while that computed property is active: retiring it is refused, naming the computed property. Retire the computed property first, or change its formula so it no longer reads that property. On a topic, the meaning of an input cannot be removed or replaced either while a computed meaning reads it (Giving a topic a meaning).
Who can do what
| Action | Needs |
|---|---|
| Read libraries and properties | Being a member of the workspace, however you joined (with the default role, with no role at all, through a group or a custom role). An agent or an API client needs a role that grants semantic_library:read |
| Start from your data: read and group your topics, preview an alarm | Reading libraries; only the topics you can read are read |
| Apply a group | what giving each topic a meaning needs (Who can do what); without approval, the group is proposed |
| One alarm for a group of the built-in library | semantic_binding:update on the workspace, or looking after that part of the tree, with topic:update on each topic |
| Create a library or a new version | semantic_library:create (Data Admin, Workspace Admin); starting it as a copy also needs read on the version it starts from |
| Rename, add, change and retire properties, set alarms and sampling | semantic_library:update (Data Admin, Workspace Admin), or owning the library |
| Check a formula | semantic_library:read |
| Change a computed property's formula while topics use it in force | semantic_library:update, and semantic_binding:review on the workspace (Data Admin, Workspace Admin) with topic:update on every topic using it |
| Move topics to another version | semantic_binding:review on the workspace, or looking after that part of the tree, with topic:update on each topic, and semantic_library:read on both versions. People only: a token is held to its scopes, and no scope grants it |
| Publish a version | semantic_library:publish (Data Admin, Workspace Admin). People only: an agent or a token never publishes, whatever its scopes |
| Export a library file | semantic_library:read |
| Import a library file | semantic_library:publish and semantic_library:create (Data Admin, Workspace Admin): an import publishes. People only, as publishing |
| Retire a library | semantic_library:delete (Data Admin, Workspace Admin) |
| Read a validation rule | semantic_policy:read, or looking after that part of the tree |
| Set a validation rule | semantic_policy:update, or looking after that part of the tree |
| Lock or unlock a validation rule | semantic_policy:update on the workspace (Data Admin, Workspace Admin) |
Library read is a real permission: a deny rule on one library takes it away from anyone, a steward included, whatever their membership or roles say. Looking after part of the topic tree gives no library read of its own.
Every change that gives a topic a property (giving a meaning, to one topic or to many, replacing one, approving a proposal, moving topics to another version) also needs read on that property's library. A refusal names only the field of the request that was refused, never the library you may not read.
Sharing a topic does not let anyone set its validation rule: only the policy permission or looking after the branch (a steward) does.
An action you cannot take is shown disabled, and says what it needs. Someone without access to libraries at all sees who can read them, not an empty list.