EikHub · Guide
EikHub basics
EikHub is where buildings branch, get reviewed and merge, the way software does. This guide explains its core ideas as they work today.
The idea
An OpenEik building is stored as a code base: one small text record per element, in folders. That makes it possible to work on a building the way software teams work on code. EikHub is the place where that happens between people and firms.
EikHub coordinates; it never edits the model. Models are changed in the authoring tools: Stomra, Femra, Varmra, the ek command line and the assistants that work through them. On EikHub people look, compare, comment, review, approve, merge and send. A review, a sign-off or a receipt kept on EikHub is offered as a file, and the authoring tool saves it into the building.
Buildings and organisations
A building is one project: its model, drawings and analyses, with all their history. Each building belongs to an organisation, a firm or a client, and has an address on EikHub of the form organisation/building.
- A building is public or private. Anyone can open a public building's model and history without an account. A private one opens only for its people.
- You sign in to EikHub with Google, or with your Stomra account.
- The dashboard shows your buildings as cards, each with a small picture of the building.
Versions and history
A version is a snapshot of every record of the building at one moment, saved by an authoring tool. A version never changes; it is named by a hash of its content, so the same building state always has the same name.
- History lists the versions, newest first, with who saved them and what changed. Find a change, an element or a person; issues of drawings are marked in the list.
- Open a version to see its model in 3D, what changed from the version before, its comments, its analyses and its drawings.
- Compare any two versions. The 3D view has two ways of looking: X-ray, where the building turns to glass and only what changed is lit, and Before | After, both versions whole with a divider to drag. Step from change to change with [ and ]. Below the view every record that differs is listed, field by field.
- Print as IFC makes an IFC file of a version. The IFC names the version it came from and says it is a print: the OpenEik building stays the record.
Lines of work: main and alternatives
Main is the building's agreed line of work. An alternative is a line of work to try something on, such as a wider south window or a second stair. Main stays as it is until an alternative is merged into it.
- In History, pick the version to start from and choose Start an alternative here. Give it a name.
- Work on the alternative in the authoring tool. Its versions build up on its own line.
- Compare it with main whenever you like. When it is the one, propose it into main.
Each line of work has its own drawings and analyses, so an alternative can be judged on the drawings and numbers people actually read.
Proposals
A proposal asks to bring a change into a line of work, usually main. It is EikHub's equivalent of a pull request. A proposal comes from an alternative of the building, or from a fork: a copy of the building in another organisation that remembers where it came from, as a supplier or a consultant uses.
A proposal shows:
- Changes: every record it adds, changes or removes, field by field, and the same change in 3D;
- Checks: automated results posted on it; a building can require named checks, and a number of approvals, before a proposal merges;
- Drawings: which issued drawings it would put out of date (see Drawing review on EikHub);
- Conversation: comments, reviews and attachments, such as a supplier's quote tied to the version it priced.
How a proposal is merged
- The proposer opens the proposal and asks reviewers.
- Reviewers comment, then approve or ask for changes. A change after a review asks them to look again.
- Where the building has owners, every owner whose part the change touches approves it (see Owners by discipline).
- An admin of the building merges it on EikHub's confirm page, signed in in the browser. The merge goes record by record and field by field; where both sides changed the same field, the admin chooses which to keep.
- EikHub signs a receipt of the merge. Other open proposals against the same line are closed, and can be reopened.
Agents propose, people merge. An app or an assistant can open a proposal for you, but no token merges one: a merge is always a person's act on the confirm page. If your own agent opened it, another admin merges it, unless you are the building's only admin, in which case EikHub asks you to confirm once more.
A proposal is seen only by its parties: the building's admins and the organisation that proposes. That holds on public buildings too, so a supplier never sees another supplier's offer.
Reviews and comments
- Comments go on a version and its elements, or on a proposal, with replies and mentions. People are notified in the app and by email, as they choose in their settings.
- Review rounds review one revision of a drawing, or one version of the model in 3D (Review this version): reviewers, notes pinned to elements, states and decisions. Open notes follow their element into the next round. See Drawing review on EikHub.
- Sign-offs and receipts are signed files about issued drawings. See Signed receipts on EikHub.
Owners by discipline
A building can say who owns which part of the model in an owners file, project/owners.json, as OpenEik Part XVI defines it. It names the parties, such as the architect, the structural engineer and the heating and plumbing engineer, and the paths each owns: the structure's folders to the structural engineer, for example. In OpenEik's owners' layout each discipline's records sit in its own folder, so the rules stay short.
- A change needs the approval of one owner of each part it touches, or of every owner where a rule says all. Making the change counts as approving it.
- A proposal is not merged while an owner's approval is missing; the merge preview says whose.
- A save straight to main that leaves an owner's approval open is refused. A Stomra project being edited live saves as people work and is never refused; the version is marked Joined without its owners, and the owners are told.
- An admin links each party to the EikHub organisations that act for it, under Owners in the building's settings. The people of those organisations can then approve for their party, even without write access to the building.
People, roles and sharing
| Role | Can |
|---|---|
| read | See the model, history, drawings and analyses; comment and review. |
| write | Also save versions, start alternatives, open proposals, plan issues and send drawings. |
| admin | Also manage people and settings, and merge proposals. |
| supplier | Read, fork and propose from its own fork; never write to the building. |
In Stomra, sharing a project by discipline writes the owners file that EikHub enforces; see Sharing by discipline.
- Invite people by email from the building's People page.
- A building can be shared with an organisation: every member of it reads the whole building. Writing stays per person, and per party where the building has owners.
- A member's read can be narrowed to parts of the model, such as the balconies and railings and the records they stand on.
The notice board
The Notices tab is a board for things everyone working on the building, people and agents, should know:
- a notice: something everyone should know;
- a claim: which part of the model you are working on, so others steer clear. A proposal touching it gets a warning, not a block;
- a hold: stop merges into a line of work until it is lifted, by you or an admin. Saves to it are refused too.
The tabs of a building
| Tab | What it holds |
|---|---|
| Model | The latest version on main in 3D, with its records and comments. |
| History | Versions, lines of work, and comparing two versions. |
| Drawings | The register of issued drawings, issues and reviews. |
| Analyses | Analyses kept beside the model, such as Femra's structural and Varmra's energy results, each marked when what it was computed from has changed. |
| Proposals | Open, merged and closed proposals you are a party to. |
| Notices | The notice board: notices, claims and holds. |
| People | Members, invitations and the organisations it is shared with. |
| Settings | For admins: public or private, the rules a proposal must meet before it merges (required approvals and checks), and the owners. |