Access Rules
Access Rules
Key Concept
Access rules are key components in managing access to Resources and/or Processes. Rules are highly configurable, stackable and when used in conjunction with Training Records provide a powerful and flexible system to manages access.
The system provides three types of Access Rules that can be applied in order to enforce internal policies. All rules can be selectively applied during business hours, after hours or on the weekends. The Business Hours of the relevant Resource will be used to determine if the period falls with Business Hours. By default, no rules are applied, allowing each facility to restrict access according to individual policy.
For the purposes of rule applications, After Hours does NOT include weekends. This is to allow rule application to be explicitly controlled on the weekends or during the week after hours separately.
Rules may be applied to a Location, Tag or specific Resource. Any rules applied to a Location will be applied to all Resources in that Location, and any Sub-Locations. Rules are chained together and all must pass for the action to be allowed. The means that you may further restrict access to Resources within a Location; however, you may not relax rules for individual Resources. For this reason, the Location rules should define the least restrictive rules within a Location.
Role Based Rule Application
In addition to the parameters listed for each individual rule below - ALL ACCESS RULES accept the excludeRoles and includeRoles parameters. These parameters can be used to explicitly control rule application based on roles provided through training. Using both include and exclude parameters in the same rule is not recommended.
Role names should not include spaces. If you desire a multi-word role, use a slug-format-name.
Multiple roles can be provided in the following formats:
| Separation | Format |
|---|---|
| Space Separated | role1 role2 role3 |
| Comma Separated | role1, role2, role3 |
| Pipe Separated | role1 | role2 | role3 |
Activation Rules
Activation Rules
Are enforced at the time a user attempts to activate a reservation.
| Rule | Description | Parameters |
|---|---|---|
| Buddy Required | Ensure that the minimum number of required users are in the associated Location before activation. This rule will be applied to any Resource that has a buddy-required setting. Use the minimum parameter to specify the number (integer) of others that must be present. | minimum |
| Enforce Schedule Period | Ensure that the reservation is only activated during the actual reserved period. The startBuffer parameter may be used to allow activation before the actual start time of the event. | delay startBuffer endBuffer |
| Infrastructure Is Operational | Ensure that all infrastructure associated with the Resources and Location are available before activation | strict |
| Requested Configuration Is Current | Ensure that any requested Configurations for the Resource are currently configured. | |
| Restrict Concurrent Use | Restrict concurrent usage of the resource. Use the maximum parameter to specify the maximum number of maximum concurrent activations that are allowed. By default, maximum = 1 | maximum |
| Enforce Event State | Ensure that the reservation event is in an activatable state. This is one of confirmed or active |
Settings
Settings are key-value pairs that allow for additional, optional Resource configuration. Below is a list of valid settings.
| Key | Value | Description |
|---|---|---|
buddy-required | any | This setting is required in order to use the Buddy Required Activation Rule. Any value may be used. |
Booking Rules
Booking Rules
Are enforced at the time a user attempts to create a new reservation.
| Rule | Description | Parameters |
|---|---|---|
| Does Not Overlap | Ensure that the reservation does not overlap any other events. Optional Start and End buffers can be set to provide a buffer period between reservations. | delay startBuffer endBuffer |
| Enforce Resource State | Ensure that the current state of the resource can be booked. For the purposes of booking, any resource that is in the unavailable state will fail this rule test. N.B. This rule will also fail if the Resource Type does not allow booking | |
| End In Business Hours | Ensure that a Booking Period ends withing the given business hours for a bookable resource | delay |
| Enforce Infrastructure Schedule | Ensure that there are no scheduled outage events for any Infrastructure components associated with the Resource during the requested reservation period. This differs from the Infrastructure Is Currently Operational rule as it will allow a reservation for Infrastructure that is currently unavailable. | strict |
| Enforce Schedule | Determine if the submitted event must be fully encapsulated by, or avoid scheduled events - based on the type of Schedule (available / unavailable). By default, this rule will ensure that events may not be booked during unavailable times. Set available = true to ensure that any reservations fall within an active schedule event (ideal for reservation blocks). | available startBuffer endBuffer |
| Enforce Valid Training | Ensure that all required training for the resource and location are currently valid for the user. | |
| Enforce Valid Process Training | Ensure that all required process training is currently valid for the user. This rule is invoked only if a process is selected during the Event Confirmation step. To trigger the rule validation, a required training configuration must be in place for the associated process. | |
| Infrastructure Is Currently Operational | Ensure that all infrastructure associated with the Resource and Location is currently operational before allowing the reservation. | strict |
| In The Future | Ensure the reservation period is in the future. If specified, the interval determines how far in the future the booking must be. | delay interval |
| Location Capacity Limit | Ensure that the reservation would not cause the location capacity limit to be exceeded | delay maximum startBuffer endBuffer |
| Max Duration | Ensure that a Booking Period is less than a maximum duration | delay interval |
| Max Per Day | Limit the number of reservations a user, or project can make for a resource on any single day. To apply the rule to a single user, select the user_id attribute, project_id to restrict by project. | delay maximum |
| Min Duration | Ensure that a reservation period meets a minimum time duration | delay interval |
| Require Valid Project | Ensure that the provided project is currently valid | |
| Start In Business Hours | Ensure a reservation starts within the business hours of a bookable resource | delay |
| Sufficient Configuration Notice | Ensure that sufficient notice has been provided for a configuration change as specified in the Configuration settings | delay |
| Within Business Hours | Ensure a reservation is completely contained (starts and ends) within the business hours of a resource. For this rule to pass, a reservation must be contained within a single day. To allow overnight reservations that start & end in within the business hours, use a combination of Start In Business Hours and End In Business Hours | delay |
| Within Horizon | Restrict future reservations to a within a given horizon. The end time must fall within the horizon period | delay offset round interval |
| Within Quota Limit | Ensure that the reservation would not exceed the specified quota for a Project or User within the given interval. | delay interval quota |
Cancellation Rules
Cancellation Rules
Are enforced at the time a user attempts to cancel a reservation. Cancellation rules are also applied when a reservation is modified as the system will cancel the original reservation, and create a new one for the modified time. This allows the system to retain information of cancelled events for analytics.
| Rule | Description | Parameters |
|---|---|---|
| Beyond Horizon | Restrict reservations from being cancelled unless beyond a given horizon. The start time must fall beyond the horizon period | offset round interval |
| Do Not Allow Cancellation | Disable cancellations completely. | |
| Enforce Event State | Ensure that the current Event state can be cancelled. |
Rule Parameters
Rule Parameter
Parameters are used to configure the properties of specific rules. These can be used to create a variety of unique rule combinations. The following parameters are used for the various types of Rules in the system. Parameters are entered as key-value pairs using the parameter name as the key in the Rule configuration.
available
Type: Boolean
Default: False
Used for Schedule Rules. By default, the system will loop through all unavailable schedules relevant to the reservation, and check for overlapping events. By setting available to true the system will ensure that the reservation is contained within a defined event of an available type schedule.
cap
Type: String
The cap parameter is an interval and accepts the same values as the Interval parameter.
delay
Type: String
If a delay is set, the system will not enforce the rule on reservations that are made within the delay period. For example, if user attempts to book a tool at 11:50 for 12:00, and there is a delay of 15 minutes, the rule will not be applied.
When specifying a delay, you may use all the modifiers available to the interval parameters.
endBuffer
Type: String
Used to set a buffer to be applied for overlapping or schedule event rules. If set, the system will ensure the specified interval is maintained at the end of a reservation. The parameter accepts all the available interval modifiers.
excludeTeams
Type: String
Used to exclude specific Teams from the application of a Billing Rule. The given rule will not be applied to any Projects of the specified Teams. The parameter will accept either a single Group, or list of Teams. Teams must be specified by their slug. You can find the slug in the administrative detail panel for the Group. In the rare case where a Group is listed in both the excludeTeams, and includeTeams parameters of a Rule, excludeTeams will take precedence and the Group will be excluded.
excludeProjects
Type: String
Used to exclude specific Projects from the application of a Billing Rule. The given rule will not be applied to any of the specified Projects. The parameter will accept either a single Project, or list of Projects. Projects must be specified by their slug. You can find the slug in the administrative detail panel for the Project. In the rare case where a Project is listed in both the excludeProjects, and includeProjects parameters of a Rule, excludeProjects will take precedence and the Project will be excluded.
excludeProjectTypes
Type: String
Used to exclude specific Project Types from the application of a Billing Rule. The given rule will not be applied to any Projects of the specified Types. The parameter will accept either a single Project Type, or list of Project Types. Type must be specified by their slug. You can find the slug in the administrative detail panel for the Project Type. In the rare case where a Project is listed in both the excludeProjectTypes, and includeProjectTypes parameters of a Rule, excludeProjectTypes will take precedence and the Project Type will be excluded.
excludeRoles
Type: String
Used to exclude application of an Access Rule to users with a given role on the associated Resource. In short - if a user has any one of the specified roles, the rule will not be applied. A user is determined to have the role, if they have a valid Training Record for a Training that provides the Role. The parameter will accept either a single role, or list of roles. If the rare case where a user has roles which are both excluded and included, excludedRoles take precedence over includedRoles.
factor
Type: Float
Used to specify a scaling factor for Rule applications. Negative numbers will be converted to absolute values.
grace
Type: String
The grace parameter is an interval and accepts the same values as the Interval parameter.
includeTeams
Type: String
Used to include specific Teams in the application of a Billing Rule. The given rule will only be applied to Projects of the specified Teams. The parameter will accept either a single Group, or list of Teams. Teams must be specified by their slug. You can find the slug in the administrative detail panel for the Group. In the rare case where a Group is listed in both the includeTeams, and includeTeams parameters of a Rule, excludeTeams will take precedence and the Group will be excluded.
includeProjects
Type: String
Used to include specific Projects in the application of a Billing Rule. The given rule will only be applied to the specified Projects. The parameter will accept either a single Project, or list of Projects. Projects must be specified by their slug. You can find the slug in the administrative detail panel for the Project. In the rare case where a Project is listed in both the includeProjects, and includeProjects parameters of a Rule, excludeProjects will take precedence and the Project will be excluded.
includeProjectTypes
Type: String
Used to include specific Project Types in the application of a Billing Rule. The given rule will only be applied to Projects of the specified Types. The parameter will accept either a single Project Type, or list of Project Types. Type must be specified by their slug. You can find the slug in the administrative detail panel for the Project Type. In the rare case where a Project is listed in both the includeProjectTypes, and includeProjectTypes parameters of a Rule, the excludeProjectTypes will take precedence and the Project Type will be excluded.
includeRoles
Type: String
Used to limit application of an Access Rule to only those users with a given role on the associated Resource. In short - the rule will only be applied if the user has any of the specified roles. A user is determined to have the role, if they have a valid Training Record for a Training that provides the Role. The parameter will accept either a single role, or list of roles. If the rare case where a user has roles which are both excluded and included, excludedRoles take precedence over includedRoles
interval
Type: String
The interval parameter is used to specify a time interval and is created by attempting to parse a human friendly string. The available modifiers are listed below.
You may also specify delays using PHP's date interval syntax.
| Valid Modifier | Example | PHP Interval Format Example |
|---|---|---|
| year, years, y | 1 year | P1Y |
| quarter, quarters | 1 quarter | P3M |
| month, months, mo | 2 mo | P2M |
| week, weeks, w | 1 week | P1W |
| day, days, d | 4 days | P4D |
| hour, hours, h | 4 hours | PT4H |
| minute, minutes, m | 45 m | PT45M |
| second, seconds, s | 55 seconds | PT55S |
| millisecond, milliseconds, ms | milliseconds | N/A |
Multiple modifiers may be chained together to create exact intervals. For example 1w 3d 4h 32m 23s is converted to 10 days 4 hours 32 minutes and 23 seconds.
NB:
To be thorough, you may also use millennia, centuries and microseconds as well should you wish.
maximum
Type: Integer
This value is used to set the number of maximum items for a rule application. Setting a value of null indicates no limit.
minimum
Type: Mixed
This value is used to set the number of minimum items for a rule application. Depending on the rule, the value should be either an Integer or a valid Interval format.
offset
Type: String
Allows for an additional offset provided to a Horizon Booking rule. This will be applied to the end of the attempted reservation period before checking if the event falls within the specified interval. The system will attempt to create this using Carbon's magic date parser. All comparisons are made using UTC.
round
Type: String
Default: seconds
Specifies the rounding unit (precision) for Horizon reservation rules. This can be used to avoid arms races to capture rolling reservation horizons. For example, if set to days, it will not matter what time of day a reservation is attempted on the last day approaching the horizon, the system will round to full days.
Click to expand valid rounding modifiers
'y' => 'years',
'yr' => 'years',
'yrs' => 'years',
'year' => 'years',
'years' => 'years',
'm' => 'months',
'mon' => 'months',
'month' => 'months',
'months' => 'months',
'd' => 'days',
'day' => 'days',
'days' => 'days',
'h' => 'hours',
'hr' => 'hours',
'hrs' => 'hours',
'hour' => 'hours',
'hours' => 'hours',
'i' => 'minutes',
'min' => 'minutes',
'mins' => 'minutes',
'minute' => 'minutes',
'minutes' => 'minutes',
's' => 'seconds',
'sec' => 'seconds',
'secs' => 'seconds',
'second' => 'seconds',
'seconds' => 'seconds',startBuffer
Type: String
Used to set a buffer to be applied for overlapping or schedule event rules. If set, the system will ensure the specified interval is maintained at the start of a reservation. The parameter accepts all the available interval modifiers
strict
Type: Boolean
Default: False
If set to True, any Infrastructure components that are unavailable will cause the validation rule to fail. By default, only required infrastructure components will cause a failure.
quota
Type: String
Used to set the total quota for a given interval. If set, the system check the total duration of all reservations in the supplied interval and reject the reservation if the new duration would cause the quota to be exceeded. This can be applied to a User or Project. The parameter accepts all the available interval modifiers