Introduction to Domain Modeling

Overview#

Domain modeling is how you build a structured, queryable representation of your plant, facility or process in Atlas. You describe the kinds of things that exist, you describe which real ones exist and where their values come from, and Atlas turns that into a World: a live graph you can query and subscribe to.

You do not need to write code. All the work happens in the Atlas browser interface, with an AI assistant called Ask Gage on hand throughout. What you author is stored as open, version-controlled files in a Git repository that Atlas manages for you.

This article introduces the workflow, walks you round the interface, and takes you end to end through a first domain. The articles it links to own the detail; this one owns the map.

Before you start, read Timebase Atlas Key Concepts. It defines every term used here - domain, library, branch, ontology, instance map, binding path, compile, World, draft session - and this article does not redefine them.

Who builds domain models#

Domain modeling is primarily done by domain experts and data engineers: people who understand the plant or process being modelled and the data sources it generates. You do not need to be a software developer. The knowledge you bring is:

• What assets, equipment or processes exist in your domain
• What measurements, statuses and settings matter
• How assets relate to each other (containment, process flow, dependencies)
• Where the data comes from (OPC UA servers, historians, databases, MQTT topics)

Ask Gage can translate that operational knowledge into a formal model, which shortens the trip from concept to working graph considerably.

Before you start#

Three things catch people out on the very first click.

1. The address is 4551 or 4552, not 3100#

Atlas listens on 4551 for HTTP and 4552 for HTTPS.

http://localhost:4551 answers with an HTTP 307 redirect to https://localhost:4552, so both addresses land you in the same place as long as 4552 is reachable. Replace localhost with your server's host name for a shared installation.

2. You have to sign in#

Authentication is on by default. Pulse:Auth:Enabled is true in the shipped settings.config, and the interface resolves your identity before it renders anything, so an unauthenticated session is redirected to the Timebase Pulse sign-in page. You will see Pulse, not Atlas, until you have signed in.

That means a working Atlas needs a reachable Pulse instance with a client registered for Atlas. Setting that up is covered in Start Here for Docker: How to Deploy and Secure Timebase 2.0.

3. A fresh installation has no domains#

Atlas installs two libraries of reusable types, offers a catalogue of others you can import, and ships no domains at all. Creating the first one is step 5 of the walkthrough below. The Domains panel on the Home page will read "No domains yet - create one in the Model workspace to get started." until you do.

How the workspace is laid out#

Atlas is a single tabbed workspace. There is one sidebar on the left, a strip of tabs across the content area, and the Ask Gage panel docked on the right.

The sidebar#

Git sits above Domains and Libraries, because branches are the frame everything else lives inside. Domains and Libraries are two pages of the same shape: a list of what exists on one branch, with a Branch select beside the filter box, Create and Import at the top right, and a Pin button on every row.

Your working set#

Pinning a domain or library (the Pin button on its row, or creating one) adds a Version to your working set: a (name, branch) pair that appears as its own entry beneath Domains or Libraries in the sidebar. Clicking a row opens the Version's Overview without pinning it. Expand a pinned entry and you get a flat list of screens.

A Library Version gets only Overview, Types and Canvas. A library holds types and nothing else, so it has no instances and no compile.

Each screen you open becomes a tab. The top bar carries a split-view toggle (so you can put two screens side by side), a light/dark toggle, and the Ask Gage button. Every screen also has a shareable web address of the form /model/{domain}/{branch}/{view}, so you can send a colleague a link straight to the screen you are looking at.

Ask Gage#

The AI assistant is called Gage, and it lives in a resizable panel docked to the right of the workspace. On a fresh session the panel is already open. If you close it, the Ask Gage button in the top bar brings it back.

Gage is not one assistant but a set of agents, each with a job. Press + (Spawn agent) in the panel's tab strip to open the Start an agent picker, which lists agents under Built-in and User-defined.

Branches come first#

Everything in Atlas lives on a Git branch, and almost every screen is scoped to one. A fresh repository has a single branch called main.

• The Domains and Libraries pages each have a Branch select beside the filter box, and the page header names the branch it is showing. Every row acts on that branch; there is no per-row branch picker.
• Creating a domain asks you which Branch to create it on.
• Every pinned Version shows its branch under its name in the sidebar.

Creating, comparing and merging branches is done on the Git page, titled Git Management. See Branch Management.

The modeling workflow#

Every domain model follows the same four stages.

1. Define: describe your types#

You start with the ontology: the kinds of things that exist, the values they carry, and how they connect. You author this on the Types screen, using one Create menu that offers five kinds.

Two things differ from ordinary object modelling. A property is authored standalone and then attached to the types that should carry it, from the entity type's Properties tab, so the same property can be attached to any number of unrelated types. And relationship participation is unconstrained: there is no one-to-one or one-to-many setting, so enforce a rule of that kind in how you build your instance maps.

Before you define anything, check whether it already exists. atlas-core is always present, atlas-common, isa95-equipment and the other supplied libraries are copied in during commissioning, and a domain can import any of them plus any library you build yourself. atlas-common alone gives you TVQ, the abstract Tag base and its four typed Tags (AnalogTag, DiscreteTag, IntegerTag, StringTag), Folder, contains, connectsTo and the standard Timestamp / Value / Quality / UOM / Description properties. Imports are managed in the Library imports section on the domain's Overview.

The ontology is stored as a single JSON-LD file per domain, at domains/<your-domain>/ontology.jsonld.

The full authoring reference is Defining Types and Schemas.

Ask Gage

Ask the designer agent: "Design an ontology for a pump station with PumpStation and Pump entity types. PumpStation should relate to the pumps it contains. Each Pump should carry Speed, FlowRate and MotorTemperature as properties. Sketch out the hierarchy and which properties attach where."

It produces a plan and writes nothing. Hand the plan to the builder agent when you are ready to create the types.

2. Map: create instances and bind data#

An instance map is a recipe that turns one type into real things. It says which type to create, how many, what each one is called, and where each property's value comes from. You author instance maps on the Instance Builder screen, and they are stored as .map.json files under domains/<your-domain>/instances/.

A map can produce one instance, a fixed set, or one instance per row a connector returns. You do not pick a mode; Atlas works it out from what you filled in.

Each property gets a sourcing strategy, chosen per map on the Mappings tab from a segmented Static / Bound / Calculated selector:

• Static is a fixed value you type: a unit of measure, nameplate data, a set-point.
• Bound is a live value from a connector, identified by a Binding path.
• Calculated is a value worked out by a function when something reads it.

A Binding path is a slash-delimited path whose first segment is the connector instance id. The field's placeholder shows the shape: connector/path, or connector/path/[Variable] where the map expands over several instances.

The full authoring reference is Instance Maps, and the strategies are covered in Property Sourcing Strategies.

Ask Gage

Ask the instance-builder agent: "Create a single PumpStation instance called pump-station-north with instance id pump-station-north. Set all properties to Static for now (no connectors yet). Use the instance label North Pump Station."

Requires the pulse:administrator role. Without it the write tools are filtered out before the agent runs, so it will simply say it cannot do this rather than returning a permission error.

3. Compile: the step that makes the model real#

Compile is the gate between "I authored it" and "I can query it". Atlas validates the whole domain, expands every instance map, and builds the World: the compiled, queryable form of your model, held by Atlas itself.

The Compile section sits on the domain's Overview screen and has exactly one button. It reads Compile the first time and Recompile afterwards, and it greys out while the World is current. On success you get three counts, Entities, Edges and Archetypes, plus the time it completed and any Function compilation errors.

There is nothing after this. No deploy, no publish-to-runtime, no separate engine. Atlas stores, compiles, caches and queries your domain in one service.

Because a compile is a full rebuild, it is safe to repeat as often as you like. And types are not frozen once compiled: edit anything at any time. See Iterating on a domain.

Ask Gage

Ask the reviewer agent: "Check the compiled domain and report: does every entity type have at least one instance? Are there any property types that are not attached to any entity type? List any validation errors or warnings."

It reads the domain without writing.

4. Consume: query and subscribe#

Once a World exists you can read it. The Instances screen browses it, nested by containment, and its inspector shows each instance's property values. Turn the inspector's Live switch on and Atlas opens a live subscription for the selected instance, returning current values immediately and then streaming changes as they arrive.

Saved views keep the Cypher filters your team uses regularly on the Types and Instances trees, the graph-query agent answers questions in plain language by writing Cypher for you, and external applications subscribe to live property updates over the Atlas value hub.

Starting your first domain#

The whole path, one action per step. It assumes Atlas is running and reachable, per Before you start.

1. Open https://localhost:4552 in your browser, or your Atlas server's address.

2. Sign in at the Timebase Pulse page that appears. Atlas loads once you are authenticated.

3. In the sidebar, select Domains.

4. In the Branch select beside the filter box, choose the branch you want to work on. On a new installation this is main.

5. Select Create Domain at the top right of the page. The New Domain drawer opens on the right.

   

6. Enter a Name. It must be lowercase letters, numbers and single hyphens, for example pump-station-north. The field's own help text reads "Lowercase letters, numbers, and single hyphens."

7. Confirm the Branch. It defaults to the branch you are browsing.

8. In Libraries, add atlas-common. It gives you the TVQ measurement shape and the Tag entity types, both of which you will want. Add isa95-equipment too if you are modelling an ISA-95 equipment hierarchy.

9. Write a one-line Description of what this domain models, then select Save domain.

   Atlas adds the new Version to your working set under Domains and opens its Overview tab.

10. In the sidebar, expand your new Version and select Types.

11. Select Create, then Entity Type, and create your first type. Fill in Name (PascalCase, for example Pump), an optional Label and a Description, then Save. Repeat for the three to five asset types you need.

    

    Important

    Name is locked after creation on every kind of type. Label and description can be changed freely afterwards; the name cannot.

12. Select Create, then Property Type, to create the values those types carry, for example Speed, FlowRate and MotorTemperature. Set each one's Value type: use xsd:double for measurements, and TVQ from atlas-common for anything that comes from a historian or an OPC UA server.

13. Attach each property to the type that should carry it: select the entity type in the tree, open its Properties tab, select the add control (the drawer opens titled Add Property, and the empty-state link reads "Create property"), and save. Attaching to a parent type shares the property down the whole subtree.

14. Select Create, then Relationship Type, to connect your types. Choose the Contains root for physical containment (that is what makes the Instances tree nest), or the Relationship root for everything else. atlas-common already gives you contains, so import and reuse it rather than defining a near-duplicate.

15. In the sidebar, select Instance Builder.

16. Select Create, then one of Single Instance, Entity Instance Map (Bulk), Single Relationship or Relationship Instance Map (Bulk). For a first pass, Single Instance for a one-off asset such as the pump station, and Entity Instance Map (Bulk) for the pumps themselves.

    

17. On the drawer's General tab, fill in Definition ID, Definition name, Type, Instance ID and Instance label. Use [Name] placeholders in Instance ID to vary it per instance, for example Pump-[Num, 00].

    Important

    The placeholder syntax is [Name]. It is not {i}. A pattern written pump-{i} has no variables at all, so you get exactly one instance literally named pump-{i}, and nothing warns you.

18. On the Variables tab, select + Add variable and give the variable that drives the count its data, for example a variable named Num with the data 1-6.

19. Open the Mappings tab, select a property, and choose Static, Bound or Calculated on the Sourcing strategy selector.

20. For a Bound property, type the connector path into Binding path, using the same placeholders, for example historian-juice-factory/The Juice Factory/131-TT-[Num].PV. If you have no live data yet, leave the properties Static and come back later; the model still compiles and is still queryable.

21. Select Save instance map.

22. In the sidebar, select Overview.

23. Read the Outstanding items panel if it is showing. Its body copy reads, verbatim:

    Your changes are saved. These items don't block saving - fix them in any order - but this Domain Version can't be compiled until they're resolved.

    Items are split into To fix (errors, which block the compile) and Advisory (warnings, which never block anything). Each line begins with its rule ID. Clear everything under To fix before you go on.

24. Look for a panel headed Unpublished changes. If it is there, your work is sitting in a private draft and the branch has not moved. When its chip reads Ready to publish, select Publish to {branch}. If the chip reads "{n} to fix first", clear Outstanding items first.

    Note

    a save with outstanding violations is held in your own draft session rather than written to the branch, and compiling from a draft builds your copy. If something you saved is not appearing for other people, publish it here first.

25. In the Compile section, select Compile.

26. Read the result. Three cards show Entities, Edges and Archetypes, followed by the time it completed. If validation failed instead, work through the listed violations and compile again.

    

27. In the sidebar, select Instances. Your instances appear, nested by containment.

    

28. Select an instance, then turn on the Live switch in the inspector header to stream its current values. Live starts off, and is remembered per tab.

Doing the same thing with Ask Gage#

Steps 10 to 21 can be handed to the assistant instead.

1. Open the Ask Gage panel. It is open by default; if you closed it, use the Ask Gage button in the top bar.

2. Press + (Spawn agent) and pick atlas from the Start an agent dialog.

3. Describe your plant in plain language, and be concrete. Actual asset names, actual measurement units, actual relationships. For example: "I have a pump station with six pumps. Each pump has a speed in RPM, a flow rate in cubic metres per hour and a motor temperature in Celsius, all from the historian. The pump station contains the pumps and has an overall flow rate that is the sum of the pump flow rates."

4. Review what it produced on the Types screen and in Instance Builder before you compile. The agent writes to your branch exactly as you would, so its output goes through the same validation and the same Outstanding items panel.

5. Ask for changes in plain words ("attach FlowRate to PumpStation as well", "add a description to the contains relationship type") rather than starting again.

Iterating on a domain#

Domain models are meant to evolve, and nothing has to be torn down first.

• Edit types and instance maps at any time. Nothing is frozen by a compile. The World keeps serving the last compiled result while you work.
• Atlas marks the World stale for you. Once the content no longer matches the compiled World, the Overview header swaps its grey Compiled chip for an amber Needs recompile chip, the Compile section shows the callout "This domain has uncompiled changes. Recompile to apply them.", and the Recompile button becomes available again. The Domains page shows the same two chips on the domain's row.
• Recompile when you are ready. Every compile is a full rebuild that replaces the previous World entirely.
• You do not need to recompile after a restart. Atlas recompiles every domain it knows about when the service starts. The one exception is a domain whose instances are driven by a connector: Atlas waits for that connector to connect and advertise its paths, so if the connector never appears, that domain stays uncompiled.
• Use branches for bigger changes. Create a branch on the Git page, open your domain on it from the Domains page, model there, and merge when you are happy. Both Versions can be open side by side in the workspace.

For commit history, diffs, comparison and merges, use Git, titled Git Management. To recover an earlier version of a file, restore it from the Git page and recompile.

Troubleshooting#

Related articles#