Reference
Reference
The following section contains the primary reference for all the main system functions.
Create an Application
The first step in creating a Colabmacs application is to register for an account at Colabmacs.app and select a subscription plan. From this account, you will be able to create as many individual applications as you need. Once created, your application instances will be accessible at url similar to
https://<your-app-name>.colabmacs.app
Each Colabmacs application can serve multiple physical locations, but you may also create multiple applications if required. Each application is completely isolated, using a separate database and URI. Once you have created your application, head to your new URL to login.
Info
Colabmacs is currently in pilot phase. Early adopters should contact us directly to assist in setting up your application instance.
Admin User
When creating an application instance, an admin user will be created using the same credentials that you use to login to your application dashboard. You may also create a secondary admin user at this time.
Application Configuration
- Registration
- 2-Factor Authentication
- API Keys
Authentication & Authorization
There are multiple ways to authenticate with your Colabmacs application. Traditional registration is offered via username (email) and password, as well as OAuth authentication via Google and GitHub. If you would like to enable Google Authentication, an extra step is required to setup your subdomain after creating your new Application.
Setup
Options
Options are used to configure the details of each Colabmacs application. We provide sane defaults as a starting point - but these should be reviewed and set to your needs.
| Option | Default | Description |
|---|---|---|
timezone | UTC | Set's the Applications local timezone. This must be set for the correct application Business Hours used in Access Rules. Business Hours will be provided to web browsers with an offset for their local timezone. This should be a valid time zone ex: America/Toronto |
TermsOfService | none | The contents of this option will be rendered at {site}/terms-of-service with a link provided during registration and a checkbox to accept the terms upon registration. The field supports Markdown for styling |
PrivacyPolicy | none | The contents of this option will be rendered at {site}/privacy-policy with a link provided during registration and a checkbox to acknowledge the policy upon registration. The field supports Markdown for styling |
Broadcast Messages
Broadcast messages provide a mechanism to display a message on specific pages, during a specified period. Broadcast messages are displayed at the top of the page and may or may not be dismissed on a per-user basis depending on the configuration. Each notification requires a start and end date. Messages may contain markup.
An optional path can be specified to limit the scope of the notification to specific pages within an application. When specifying a path, the message will also be displayed on any sub-pages of the path. To display a message on a single Resource page, include the full page slug in the path parameter. If there are multiple active notifications they will be stacked.
Path Examples
| Path | Message displayed on |
|---|---|
| - | all pages |
| resources | resources/* |
| resources/tool-1 | resources/tool-1/* |
| resources/tool-1/schedules | resources/tool-1/schedules/* |
| user/schedule | user/schedule |
Upgrading
If you have an existing legacy LMACS application, please see the upgrade guide
Teams
Teams are used to represent the top level of an organizational user unit. Typically, these may be a research group, company, or any other entity that will be responsible for Users operating in the space. If using the Billing features of the application, Teams are fiscally responsible for any Charges incurred as a result of Usage.
Each Team has 1 owner, who is an active User. The team may have any number of other members. Teams may create Projects to contain their work.
Projects
Projects are used to contain work done within a facility. When working within a Colabmacs application, a User will always have a current project context. Projects are managed by Teams and can be configured with spending caps or expiration dates. Users are added to Projects, and a User may be a member of any number of Projects.
Project Types
Each Project has a Project Type that can be used to determine the Rate Group when Billing features are enabled.
Locations
Locations represent physical spaces within a facility. This may be a room, building or even a logical group. Resources are grouped within Locations which allows for the application of Access Rules and Training requirements to all Resources within a Location.
Addresses
Locations, Teams and Users can all have Addresses. It is possible to reuse the same address for multiple Locations.
Business Hours
Business hours define the boundaries for "after-hour" access control features. Business hours are defined for Locations. To ensure that reservations must be made within business hours, combine this setting with a Booking Rule. Business hours are defined by an open and close time, and the days that are considered open. It is possible to create a variety of business hours and apply them differently to each location.
For holidays, winter shut-downs, or any other non-regular closures you may create Schedules to refine availability.
Capacity Limits
You may set a capacity limit on Locations. Capacity limits can be enforced through Booking Rules to ensure that the number of users in a given Location is kept below the specified limit. The system will assume 1 user per reservation.
Physical Access Control
See Interlocks.
Trainings
Access to Resources can be restricted using Trainings. Trainings are implemented using the following model concepts:
Training
A Training is used to describe a type of training at a high level. This can be something like "Safety Orientation" or "Basic Operator Training" . Trainings are combined with Resources, Locations or Processes to create a Training Configuration.
Provided Roles
Key Concept
The use of provided roles is a key concept in access control. Roles are tied to valid training and when used in conjunction with Access Rules provide a powerful, and highly configurable mechanism for controlling access.
Each training session may provide one or more roles to users who hold a valid Training Record. These roles may be used to specifically exclude, or include the application of Access Rules. If the training is applied to a location, the role will be available to the user for any Resources within that location.
Training Configuration
A Training Configuration is unique combination of a Training, and a Resource, Location or Process. The configuration specifies the following parameters:
| Parameter | Type | Description |
|---|---|---|
| Required | Boolean | Determines if the training is required for access |
| Renew on Use | Boolean | Determines if the Training will automatically be renewed each time the Resource or Location is accessed |
| Days Valid | Number | Determines how long the Training is valid for. |
Using these parameters, you can create a variety of configurations for each Training. If Renew on Use is true, the Days Valid will be from the last time the training is validated. Validation occurs after a successful usage of a Resource or Process.
Example Case
Given a Safety Orientation Training. Multiple configurations can be created, one for a "General Lab Space" Location that does not require formal retraining, as long as the user visits the lab every month. The configuration would look like:
| Parameter | Value |
|---|---|
| Training | Safety Orientation |
| Location | General Lab Space |
| Required | true |
| Renew on Use | true |
| Days Valid | 30 |
And another for a "Cleanroom Lab" Location that does require annual retraining, regardless of how often the space is used, the Safety Orientation Training may be reused in a new configuration as follows.
| Parameter | Value |
|---|---|
| Training | Safety Orientation |
| Location | Cleanroom Lab |
| Required | true |
| Renew on Use | false |
| Days Valid | 365 |
Training Session
A Training Session is an instance of a Training Configuration, with a specific capacity & trainer. Trainings sessions may be scheduled, and support multiple participants in the event that group training is required. Once a user has successfully completed a Training Session, a Training Record may be created for the associated configuration. This record can be used to validate the User's access using a Booking Rule. Training records are tied back to Training Sessions.
Training Record
A Training Record is created to represent the state of a User training for a given Training Configuration. There are 3 possible states for a Training Record:
| State | Considered Valid |
|---|---|
| Valid | true |
| Expired | false |
| Revoked | false |
If training is required for a Location, Resource, or Process, and a Booking Rule is in place for enforcement, users will not be able to book or use the resource without completing the required training. Trainings will expire after the number of days specified in Days Valid. If a configuration is set to Renew on Use, it will reset the days to expiration after each use of the resource.
Training Records will automatically expire if configured to do so, but may also be manually revoked or revalidated at any time.
Resources
Resources are at the core of the system and represent the things you want to manage access to. They reside in a Location and have rules that define their ability to be booked and used. Schedules can be applied to resources in order to apply holiday closures or indicate regular maintenance. Access to Resources is gated through Training Sessions and Access Rules.
Reservations
Key Concept
Business logic used to determine the rules used in managing Reservations is contained within, and configured through Access Rules.
One of the core features of the Colabmacs system is to manage access to shared resources - reservations are a key component of this workflow. Reservations are gated through Access Rules which provide powerful, and flexible configuration options to suit the needs of your facility policies.
State Monitoring
The system records the duration that Resources spend in available and unavailable states. This information is used to determine overall Up Time of a resource. States are classified according to the table below:
| State | Classification |
|---|---|
| Available | Available |
| InUse | Available |
| Maintenance | Unavailable |
| Unavailable | Unavailable |
Infrastructure
Resources often depend on infrastructure components to operate properly. Examples might be power, cooling water, N2, Process Gasses, House Vacuum, etc.. Infrastructure can be defined in order to establish this dependence. Through the use of Rules, access can be restricted if required infrastructure is unavailable. Infrastructure component can also be associated with Locations. Through this relationship, all Resources in a given location may become unavailable if that Location's infrastructure is down.
Schedules can be used to configure advanced outage of infrastructure components - this can be combined with Booking Rules to prevent Resources from being booked during a scheduled outage period.
Configurations
Resources may often have various configurations that require some physical changes to me made to the resource. These can be represented through Configurations. Configurations are specific to a resource and may be selected at the time of reservation (and enforced through booking rules or activation rules). When creating a configuration, the available options are created as a list of key-value pairs. You may optionally specify the amount of notice required (in hours) for the configuration change to be made. This duration can then be enforced through the rules. It is important to maintain the correct current configuration in order for the Rules to be applied accurately. After creating a new Configuration, you can select the current configuration from the available options.
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 on order to use the Buddy Required Activation Rule. Any Value may be used. |
Usage Records
Each time a resource is actually "used" a Usage Record is created. Usage Records can be used to generate a Charge for the usage. If a Usage Record is associated with a reservation event, it will include additional information about the difference between the scheduled start time and end time, and the actual start and end times. The Usage Record also contains information about any Parameters or Materials that are associated with the usage.
Before a Charge can be generated for a Usage Record, the Resource must first have an associated Rate that is in the Rate Group associated with the Project that the Usage is captured in. If there is no Rate, no charge will be generated. If a Usage Record already has an associated Charge, it will be skipped when generating Charges.
Parameters
Parameters are associated with Resources and can be configured to capture additional information which is then associated with the specific Usage Record. When associating a Parameter with a Resource, it is necessary to indicated if the Parameter is Required Before or Required After the usage event. It may also be required for both.
| Require | Behaviour |
|---|---|
| Before | Prompt user for parameter prior to Activating Resource |
| After | Prompt user for parameter when completing usage |
Parameters values are associated with the Usage Record and can be visualized for a given Resource.
Resource Team Members
Resource Team Members allow for the specification of specific Users who have a relationship to a given Resource. Typically, this may include maintenance, process or training staff. Each Team member may be assigned one or more roles that determine their relationship to the Resource. These roles may then be used to determine participation in Requests based on the Request-type.
Physical Access Control
See Interlocks.
Requests
Requests are generally the entry point for Users who which to access Training or Resources within a facility.
Request Types
Request Types help to classify requests but also provide the opportunity to configure automatic assignment. You can specify roles or individual users to be auto-assigned to each request type. When specifying a role, you must select whether to apply the assignment to any user who has the role, or only to Resource Team Member Roles. In this case, only Users who have that role associated with their Resource Team Member relationship. You may also select both options. No assignments will be made unless one of these two options are selected.Assignments are made by including the appropriate users as participants in the request.
| Role Assigment | Assigned To |
|---|---|
| User Roles | Any User who has the role at the System level |
| Resource Team Member Roles | Any User who has the specified role associated with their Resource Team Membership |
Request States
Requests implement state machine logic and can only progress through the states in a specific manner. Upon creation - the default state is Submitted
| State | Allowed Transitions |
|---|---|
| Submitted | Pending Approval, Declined, Approved |
| Pending Approval | Approved, Declined |
| Approved | In Progress |
| In Progress | Complete |
Participants
A request can have any number of participants. Participants can be added automatically or manually. When using Request Types to automatically assign Requests, Users are added as Participants when assigned.
Samples
Information about Samples may be collected within a specific Request. Samples allow for the specification of a Name, internal Tracking Number and an arbitrary number of Parameters that can be used to describe the Sample.
Quotes
See Billing - Quotes
Child Requests
Requests may be nested, creating Child Requests. This may be used to created complex, multi-step requests with different participants at different stages.
Media
Requests may contain any number of media files. Each request has the ability to manage its own media library.
Auto Generated Requests
If a user selects a configuration when creating a reservation, a new request will be automatically created and assigned to the appropriate participants to ensure that the configuration change request is recorded.
Schedules
Two types of schedules can be created: Available and Unvailable. Events added to an Unvailable Schedule define periods of time in which Resources are not available for use. Events added to an Available Schedule define period of time when Resources are available for use. This can be used to create specific time slots to constrain availability.
Schedules can be applied to Locations or Resources. Using schedules, you can easily define events that apply to multiple Resources. You can use schedules to define Holidays, regular Maintenance, or specific availability slots. If a schedule is attached to a Location, it will be applied to all Resources in that Location. Schedules are enforced using the Enforce Schedule Booking Rule.
Colabmacs includes built in support for creating Canadian holiday schedules. Holiday data is acquired from Canada Holidays and can be added by province in the application admin panel.
Events
Key Concept
Events are a key component of managing access to Resource. Events can be created in a number of ways, the primary method being through the graphical calendar interface - typically referred to as a Booking or Reservation.
You may view the events for a given Resource on the Schedule page of the Resource, or you may view the events of a collection of Resources by viewing the Schedule in your user profile. By default, all of your favourite Resource schedules will be listed. You may toggle on/off additional Resources to add to the view. Schedule events are also displayed in these views
Recurring Events
Recurring Schedule events may be created in the Admin section. When creating a recurring event - the sequence of discrete events will be generated and added and may then be manipulated individually. Note that a Schedule must exist before Events can be added.
Downtimes
Downtimes can be used to schedule future outages in the facility. They can be applied to Resources, Infrastructure, or Locations. When a Downtime is initially created, you can enter the start_date and expected_end_date. This will create an initial Schedule with a single Event that corresponds to the initial period. You may add additional Events as necessary to accurately describe your Downtime if necessary. For example, if you plan to take a system offline each day after hours, you can add Events to the Schedule that correspond to the planned outage.
Once you have defined the Schedule, you can attach the affected Resources, Infrastructure, or Locations to the Downtime. The system will then determine and notify any impacted users. An impacted user is one who has a Reservation that intersects with one of the Resources that will be impacted by the Downtime events. Each time you add or remove a Resource, Infrastructure, or Location, or update the Events, the impacted User list will be updated. Users will also be notified if the Downtime is modified in a way that they are no longer impacted.
A Downtime can be in one of three states - when a Downtime is Active, all affected Resources will automatically have their state updated.
| State | Affected Resources |
|---|---|
| Scheduled | Available |
| Active | Unavailable |
| Resolved | Available |
The system will check the status of Downtimes each 15 minutes. If the system detects that an Event is currently active for any of the Downtime Schedules, is will update the status to Active. If there are no more future events found, the system will set the status to Resolved if the auto_resolve flag is set to true, otherwise it will return the state to Scheduled. Once a Downtime has been Resolved, it can no longer me set to Active. You can also force the system to update the status of all Downtimes via the admin panel.
Processes
Colabmacs also supports the management of Processes. Processes may be defined and then added to various Resources. In addition to standard training for Resources and Locations, training may also be required for specific processes on a given Resource. Process training is managed similar to other Training by using a Training Configuration to define the training requirements of a given Process on a given Resource.
Process Areas
Process Areas allow grouping of Processes and Resources by given Process Area.
Interlocks
Premium Feature:
Interlock features require a premium plan
An Interlock is a hardware device that can physically restrict access to a Location or Resource. Colabmacs supports the following interlocks out of the box:
| Manufacturer | Supported Models |
|---|---|
| ControlByWeb | WebRelay, WebRelay-Quad, WebRelay10, WebRelay10+ |
Materials
Materials, or sometimes referred to as consumables, provide a mechanism to track additional items that may be used in conjunction with a resource, or possibly sold apart from any usage. Materials are charged according the associated rate configuration for the material and project.
Tags
Tags provide a way to arbitrarily classify and organize various elements of the Colabmacs system. Tags can be used on teams, projects, users, resources and requests. Access Rules can also be applied to tags in order to apply rules in a more flexible manner.
Billing
Premium Feature:
Billing features require a premium plan
Given the range of possible billing models that a facility may choose to implement, it is not possible to cover the exhaustive list of scenarios. The approach taken is to provide a set of flexible rules to cover the majority of cases. If your application requires additional flexibility, you can access usage data directly through the provided API and implement an external billing model.
Quote
Quotes may be used to provide an estimate of costs associated with work to User before proceeding. Quotes may be attached to a Request, or generated independently. Only privileged Users may generate Quotes. Quotes may have any number of Quote Items and will be in 1 of three states. Once a Quote has been Accepted or Rejected it cannot be modified.
Invoices
Invoices represent a collection of charges for a given Project and period. Once an invoice has been generated, all the associated charges will change to the billed state and can no longer be modified.
Charges
Charges are generated from Usage Records. Both Materials and Resources are capable of generating Usage Records. The charge generated from a given usage is based on the Rate configuration for the item being billed. This allows for flexibility, providing a framework for different rates based on the associated Project. Each Material or Resource that is intended to generate Charges must have an associated Rate available for the Rate Group associated with the Project that will be Charged. If there is no Rate, no Charge will be generated.
When a Charge is generated, it will include the Rate that was used, the derived quantity to be charged, as well as the actual quantity that was recorded. These quantities may differ due to adjustments made from the application of any Billing Rules. The units used for the Charge will always be the units that the Rate is defined in. If these differ from the units used to record the Usage, they will be automatically converted. For example, if a Usage is recorded in Minutes and a Rate is specified in Hours the resulting Charge will be in Hours.
Generally the system will attempt to use the units associated with the Rate when creating the Usage Record, but in some cases (ex: if the Rate is added after the Usage was recorded, or a Usage Record is manually added) this is not possible.
Invalid Unit Conversions
Because the system uses the Rate Units when generating charges, it is possible to create incompatible rate configurations. For example, resources usages are recorded in time based units such as Minute, Hour, and Day. The system will not prevent the assignment of a Rate with the units of Each to a resource. This is an invalid configuration, and the same as having no Rate specified. In this case, no Charges will be generated for that Rate configuration.
If it is desirable to charge for resources on a per-use basis (ie. EACH use), this behaviour can be achieved through the use of Charge Rules. For example, setting both the Min Quantity and Cap Quantity to 1 will always result in a quantity of 1.
States
Charges may be in one of two possible states pending or billed. A Charge is considered billed once it has been attached to an invoice. At this point the charge can no longer be modified. Only 1 Charge can be generated for a given Usage Record.
Rates
Rates are used in the generation of Charges. Rates are group together in Rage Groups, and each Rate must belong to 1 Rate Group. Rates are then attached to billable items such as Materials and Resources. Each billable item may have multiple Rates, but may only have 1 rate per Rate Group. The Rate applied when generating a Charge is determined by the Rate Group associated with the Project that the Usage Record is associated with. Charges are generated in the units of the Rate.
Rates require at least a Name, Rate, Unit, and Rate Group; however, you may also provide a description to help describe the rate. Once a Rate has been created, it must be attached to the Material or Resource in order for Charges to be generated. No Charges will be generated for items that do not have an associated Rate.
Rate Groups
Rate groups provide a simple way to specify which rates should be applied when generating Charges. Image there are two Rate Groups - Academic and Industrial. This allows the creation of two different Rates for a given billable item. Each Project is associated with a given Rate Group which will be used to determine which Rate should be applied when a Charge is generated.
| Project | Rate Group | Resource | Rate |
|---|---|---|---|
| Research | Academic | 3D Printer 1 | $50 / Hour |
| Manufacturing | Industrial | 3D Printer 1 | $150 / Hour |
Billing Rules
Billing rules allow for the automatic adjustment of Charges and Invoices. At the Charge level, rules can be used to modify the billed quantity (the actual quantity is never modified and retained for analytics). At the Invoice level, rules can be used to modify the total of the Invoice. In both cases, the modification activity is logged.
Group, Project or Project Type Based Rule Application
In addition to the parameters listed for each individual Rule below - ALL BILLING RULES accept the following parameters
These parameters can be used to explicitly control rule application based the Group, Project, or Project Type associated with the Charge or Invoice. Using both includex and excludex parameters in the same rule is not recommended.
Charge Rules
Charge Rules
Are applied at the time a Charge is generated from a Usage Record. These Rules can be associated with Rates or Rate Groups and are used to modify the billed quantity used for the generated Charge.
Charge Rules allow for variable application of the quantity associated with a Charge based on the rules, and their parameters. Charge rules are only applied to quantities with time based units (Minute, Hour, Day). All rules can be selectively applied during business hours, after hours or on the weekends. The Business Hours of the underlying billable Resource, and the usage record date will be used to determine if the charge period falls with Business Hours.
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.
| Rule | Description | Parameters |
|---|---|---|
| Cap Quantity | Cap the quantity that will be charged. The Rule accepts a cap parameter which accepts any valid interval. If the actual quantity exceeds the specified cap, the generated charge will be the cap. | cap |
| Cap Quantity Per Interval | Cap the quantity that will be charged for a given interval. For example, given the following: cap = 8 hours interval = 1 day. A 76 Hour Usage Record would result in a Charge of 28 Hours (3*8 + 4) | cap interval |
| Min Quantity | Set the quantity to the minimum, if the actual quantity is less than the provided value. The minimum parameter accepts any valid interval format | minimum |
| Round Up To Booking Time | Round the charged quantity up to the booked time if the actual used time is less. Applying this rule will cause the generated charge to be the greater of a) the booked time or b) the actual used time. | |
| Scale Quantity | Scales the quantity by the provided factor if it would exceed the cap value. If no cap value is specified, the scale will always be applied. Note that after the application of the scaling factor it is possible that the final quantity will still be greater than the cap. | factor cap |
Invoice Rules
Invoice Rules
Are applied at the time an Invoice is generated from a collection of Charges for a given period. These rules can be associated with Teams, Projects, or Project Types and are used to modify the total used for the invoice.
Invoice Rules allow the final total to be modified. Discrete totals of individual Charges are not modified, only the final Invoice total.
Potential Discrepancies
Because Invoice Rules modify the total for the invoice, and not the discrete, individual totals for Charges, it is possible to end up with an invoice where the total does not match the sum of all the charges.
| Rule | Description | Parameters |
|---|---|---|
| Cap Total | Caps the Invoice total. If the actual total would exceed the specified maximum, the generated invoice total will be set to the maximum. | maximum |
| Scale Total | Scales the total by the provided factor if it would exceed the maximum value. If no maximum is specified, the scale will always be applied. Note that after the application of the scaling factor it is possible that the final total will still be greater than the maximum. | factor maximum |
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 Resource 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 |
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.
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