Activity structure model

Why activity structures exist

In a multinational organisation, tracking activities can become complex when every country has a “Sales” department. Using overly detailed names (e.g., “Country – City – Sales”) does not scale. Activity structures solve this by defining a hierarchical set of levels such as Company > Country > Location > Department, ensuring uniqueness and enabling filtering at any level.

Hierarchy

An activity structure version contains one or more levels, each holding activity definitions. A definition at a lower level can reference a parent definition at the level above, forming a tree.

Hierarchy is set at creation time. Once an activity definition is created with a parent, the parent assignment is immutable and cannot be changed. Correcting an incorrect parent therefore requires closing the current definition (by setting an end date) and creating a new one under the correct parent, ensuring that references remain consistent.

Data entry codes

Each activity definition can carry a dataEntryCode, primarily used on hardware terminals for quick activity selection. The behaviour of this field depends on the Protime configuration:

• Auto-generated – Protime assigns data entry codes automatically when definitions are created.
• Manual entry – The integrator must provide the dataEntryCode in the request body. Omitting the field results in a 400 Bad Request response.

Data entry codes are limited to 16 characters and must be unique within their structure and level.

Usages

A usage record controls which circles, groups, or people can register time against an activity definition. Each usage has a date range (from / until), and usages cannot have overlapping periods for the same combination of activity definition, usage kind, and usage reference. Attempting to create an overlapping usage returns an error. To modify a covered period, first adjust or delete the conflicting usage record.

Default usage

When an activity structure contains hierarchical levels, the default usage option can be enabled in the structure configuration. This automatically creates a usage with an open-ended period for the organisational chart groups assigned to the structure, removing the need for manual usage assignment on top-level definitions.

Restrictions

A restriction limits which activity definitions a user can select when registering time. Restrictions are defined per activity definition and reference one or more other levels in the same activity structure. For each referenced level, the restriction specifies a set of allowed activity definitions at that level. When a user selects an activity definition that carries restrictions, the system narrows the available choices at the restricted levels to only the specified definitions.

The restrictions endpoint accepts a bare JSON array of restriction objects (not a wrapper object). Each object identifies a level and the activity definitions allowed at that level. Submitting an empty array clears all restrictions for the definition.

Assignment validation

When creating or updating assignments with activity levels, the referenced activity definitions must belong to the same activity structure version and respect the level hierarchy. Mismatched levels or structure versions result in a validation error.

Further reading

• Activity definitions – POST endpoint and request format
• Activity definition usages – manage usage records
• Activity definition restrictions – manage restriction records
• Assignments reference – create and update assignments with activity levels
• Create, update, and delete resources – practical steps for creating and updating activity definitions and assignments
• Your first assignment integration – end-to-end tutorial that works with assignments and activity levels