Nodes and locations - KayanOS Documentation

Nodes and locations answer two different questions. A node answers “which organizational unit is responsible?” A location answers “where does the service take place?” Keep both records accurate before adding positions, assignments, shifts, or project-linked time. Throughout this guide, the Syrian Citizen Services Directorate has a central directorate, a Damascus Regional Service Centre, and a mobile intake point. Those are operational examples only; use your organization’s approved names and codes.

When to use it

Use a node when you need to represent an organizational unit such as a directorate, department, regional office, or service team. Use a location when you need to represent a physical or service place such as a counter, office, regional centre, or mobile point. Create these records before creating positions. A position can reference a node, a location, or both. That relationship later helps KayanOS present the organizational context of an assignment and resolve an inherited shift. Do not use a location to model reporting lines, and do not use a node as a substitute for a role or permission scope.

Configuration

Record	Core information	Relationship and operational use
Node	Code, multilingual name, and configured type	May have a parent node. Use the parent relationship to represent the unit hierarchy. A node can have a default shift.
Location	Code, multilingual name, configured type, country, governorate/state, city, and address	May have a parent location. A location can have a default shift and optional orientation/overview information.
Position	Name and code, then a node and/or location where appropriate	Connects organizational and physical context to staffed work. It can also carry a shift and a parent position.
Assignment	A member linked to a position	May use a direct shift or inherit one from its position, node hierarchy, or location hierarchy.

The type choices shown in Nodes and Locations are organization configuration. Use the choices visible in your workspace; do not assume that another directorate’s type list is available.

Build the hierarchy deliberately

Start with the highest meaningful unit.
Add child nodes only when they represent a real operating responsibility.
Add locations separately, even when their names resemble a node.
Link a position to the node and location that describe where the role belongs and works.
Add a default shift only after shift definitions have been reviewed.

Avoid duplicate records such as a node called “Damascus Regional Service Centre” and a location with the same code when one record was intended to describe both concepts. It makes assignment, reporting, and shift review harder.

Workflow

Open the Nodes or Locations area available to your current organization and capability.
Search for the code first. Reuse an existing parent only when it represents the correct unit or place.
Enter the required code, name, and type. For a location, complete the address fields that your organization requires.
Select the parent record. Check that the parent is the same kind of record: node-to-node or location-to-location.
Save and open the record again. Confirm its parent, type, and any default shift before creating or moving positions.
Create or update the related position only after the node/location record is correct.

Worked example

The directorate wants to open a regional counter without confusing the responsible unit with the building.

Node: CS-REG-DAM — Damascus Regional Citizen Services Parent node: CS-HQ — Citizen Services Directorate Location: LOC-DAM-COUNTER-01 — Damascus Service Counter Parent location: LOC-DAM-CENTRE — Damascus Regional Service Centre Position: POS-INTAKE-01 — Intake Adviser Position links: CS-REG-DAM and LOC-DAM-COUNTER-01

This gives the adviser’s later assignment both an organizational context and a service-place context. It does not give the adviser permission to view every regional record. Access remains a separate capability-and-scope decision. If the regional centre uses a default day shift, record it at the level your operating model intends. An assignment can then inherit it through its position. Do not add an assignment-level override merely because a shift is available; use an override only for a genuine exception.

Testing

Test the model in a training or draft workspace that contains no live citizen, employee, or payment data.

Create one child node and one child location with unambiguous temporary codes.
Attach a temporary position to both records.
Open the node and position hierarchy views to confirm the parent path is correct.
If a default shift is used, create a test assignment and verify the expected shift context before relying on it operationally.
Remove or clearly retire the temporary test records according to your organization’s data-management procedure.

Use a clear test naming convention such as TEST-STRUCTURE-YYYYMMDD; never ask staff to use a shared sample organization or a special test member.

Troubleshooting

Situation	Check	Resolution
A unit appears under the wrong part of the hierarchy	Parent node	Correct the node parent, then review positions linked to that node.
A counter is displayed as an organizational unit	Record type	Keep the unit as a node and create or correct the counter as a location.
A position has no service context	Node/location links on the position	Attach the appropriate records; do not put a location name only in free text.
An assignment receives an unexpected shift	Position, node, and location shift settings	Review the inheritance path and add a direct override only when the exception is intentional.
A user cannot find Nodes or Locations	Entity capability	Ask an administrator to review the member’s list/create capability; hierarchy membership alone does not expose a page.

Permissions and data-quality limits

Seeing Nodes or Locations in navigation requires the relevant entity capability. Editing or deleting an existing record can additionally depend on scopes attached to that record. A person’s title, group, position, or place in the hierarchy is not proof of access. Keep location addresses and orientation files limited to information appropriate for the intended audience. A node/location hierarchy is an operational model, not an authorization model, payroll record, or legal establishment register. KayanOS example public-service organization node and service-centre location.

KayanOS example public-service organization node and service-centre location.

Continue with Workforce members to create the people who will hold positions.
Use Groups, positions, and assignments to connect staffing to the new structure.
See Shifts and timesheets before setting a default service window.

​When to use it

​Configuration

​Build the hierarchy deliberately

​Workflow

​Worked example

​Testing

​Troubleshooting

​Permissions and data-quality limits

​Related guides