⚙️ Scheduler Configuration Guide

📖 Introduction

The Isimio Scheduler is a highly configurable Lightning Web Component that can be adapted to work with virtually any Salesforce data model. Rather than hardcoding behaviour, almost all aspects of the scheduler are driven by declarative configuration stored in custom objects and custom metadata types.

This guide covers the full configuration surface for an Isimio installation, from the basic Lightning page design-time properties through to advanced developer features such as client-side plugins and custom validators.

🧩 The Scheduler Component

When you add the Isimio Scheduler LWC to a Lightning App Page, Home Page, Record Page, or Experience Cloud page, the Lightning App Builder exposes a set of design-time properties in the right-hand panel. These properties control the initial appearance and default behaviour of the scheduler for that specific page.

Display & Layout

These properties control the visual dimensions and initial view of the scheduler.

Behaviour & Interaction

These properties toggle features that affect how users interact with the scheduler.

Advanced & Developer

🗂️ Data Model Configuration

The scheduler does not know which Salesforce objects to display until you tell it. The Schedule_Object__c and Schedule_Field__c custom objects form the schema layer — they describe which objects are queried, what roles they play, and which fields are loaded and surfaced to users.

Object Types

Every Schedule_Object__c record plays one or more roles. All objects defined here are loaded when the scheduler starts, so it is important to filter large objects as appropriate. Understanding these roles is essential before creating any configuration:

Schedule Objects (Schedule_Object__c)

To add an object to the scheduler, create a new Schedule_Object__c record. The Name field must be the Salesforce API Name of the object you want to load — for example Contact, My_Object__c, or a managed-package object such as kruvi_staff__Shift__c.

Core Role Fields

Display Options

Data Loading & Performance

Other Settings

Schedule Fields (Schedule_Field__c)

Once a Schedule Object is created, you define which Salesforce fields are loaded by creating child Schedule_Field__c records. The Name of each Schedule Field record must be the field API name as it appears on the Salesforce object (e.g. Status__c, OwnerId, StartDateTime).

Date/Time Role Flags

Every scheduled object requires exactly one start and one end field. These are identified by ticking the relevant checkbox on the field record:

Visibility & Editing Flags

Aggregation & Organisation Flags

Form Behaviour

Developer Flags

Step-by-Step: Adding a New Object

1. From the App Launcher, open Schedule Objects
2. Click New and set the Name to the object API name (e.g. My_Booking__c)
3. Tick Scheduled Record (and/or Row Record as appropriate)
4. Set Color Code to a distinguishing colour (e.g. #4CAF50)
5. Save the Schedule Object record
6. In the Related section, find Schedule Fields and click New
7. Add a field record for the start date field, tick Start Date
8. Add a field record for the end date field, tick End Date
9. Add any additional fields you want visible, editable, or filterable
10. Refresh the scheduler — the new object should now appear

Filtering Records (SOQL WHERE Clauses)

The Filter field on a Schedule Object accepts any valid SOQL WHERE clause. This restricts which records are loaded into the scheduler at runtime.

-- Only load open cases
Status != 'Closed'

-- Only load shifts in the next year
Start_Date__c >= TODAY AND Start_Date__c <= NEXT_N_DAYS:365

-- Only load records of a particular record type
RecordType.DeveloperName = 'Standard'

-- Combine conditions
Status__c = 'Active' OR CreatedDate >= YESTERDAY

🎨 Custom CSS Styling

Isimio provides two complementary mechanisms for applying custom visual styles to records on the scheduler: declarative Schedule Style Controls (no code required) and developer-facing CSS Plugins (for more advanced rules).

Schedule Style Controls

Schedule_Style_Control__c records are child records of either a Schedule Object or a Schedule Field. They allow you to write CSS property rules that are automatically applied when a record matches the specified condition — all through point-and-click configuration.

Style Control Fields

Example: Highlighting Cancelled Records

1. Open the Schedule Object record for your booking object
2. Ensure the Status__c field has its Attribute checkbox ticked on the Schedule Field record (this is required for value-based styling)
3. Navigate to the Status__c Schedule Field record
4. In the Schedule Style Controls related list, click New
5. Set Value to Cancelled
6. Set Properties to:

background-color: #f5f5f5;
border-left-color: #9E9E9E;
color: #9E9E9E;
text-decoration: line-through;

CSS via Plugins

For styling rules that cannot be expressed through the declarative Style Controls — for example, targeting hover states, nested elements, or using complex CSS selectors — you can write a plain CSS file and deploy it as a plugin. See the Plugins section for instructions on uploading and configuring plugin files.

When writing CSS rules that target records by object type, use the following selector pattern:

.kruviScheduler .isimio-table .UIElement.your_object_api_name {
    /* CSS properties here */
}

Object API names in CSS selectors must be written in lower-case and include the full namespace and __c suffix. For field-value-based rules, combine with HTML attribute selectors (the field must have Attribute ticked in Schedule Fields):

.kruviScheduler .isimio-table .UIElement.my_booking__c[attr-status__c="Cancelled"] {
    background-color: #f5f5f5;
    border-left-color: #9E9E9E;
}

🖱️ Right-Click Actions

When a user right-clicks on a record (or selects multiple records and right-clicks), Isimio displays a context menu. The menu items are driven entirely by Schedule_Action__c records — so you have full control over what options appear, for which objects, and under what conditions.

Overview

Each Schedule_Action__c record defines one menu item. The Name of the record is what appears as the label in the menu. Actions can be:

• Linked to a specific Schedule Object so they only appear for records of that type
• Organised into sub-menus using the Parent lookup
• Hidden when nothing is selected, using Hide if Empty
• Conditionally shown using the Condition field

Action Fields

Standard Methods

The following built-in methods are available without writing any code. All standard method names must be prefixed with window.com.kruvi.actions. in the Method field.

Custom Actions

Beyond the standard methods, you can trigger any JavaScript function defined in a client-side plugin. The function must be attached to the window object.

window.com.myCompany = {
    openInNewTab: function() {
        // Get the first selected HTML element
        let selectedElement = window.com.kruvi.mouse.selected[0];

        // Get the underlying record object
        let item = selectedElement.parent;

        // Open the record page in a new tab
        window.open('/' + item.id);
    }
};

🔌 JavaScript & CSS Plugins

Client-side plugins allow developers to extend the scheduler with custom behaviour and advanced styling. Plugins are plain .js or .css files bundled into a Salesforce Static Resource (as a zip archive), then registered via a Plugin__mdt Custom Metadata record.

Step 1: Upload Your Plugin Files

1. Create your .js and/or .css file(s) locally
2. Zip them into a single .zip archive (the zip can contain one or more files)
3. In Salesforce, go to Setup → Static Resources
4. Click New
5. Enter a descriptive Name for the resource (note this name — you'll need it in the next step)
6. Set Cache Control to Public
7. Click Choose File and select your zip archive
8. Save

Step 2: Create a Plugin__mdt Record

Once your static resource is uploaded, register it as a plugin through Custom Metadata:

1. Go to Setup → Custom Metadata Types
2. Find Plugin in the list and click Manage Records
3. Click New
4. Fill in the fields as described below
5. Save

Plugin__mdt Fields

Plugin Examples

Example 1: Record Background Colours (CSS)

To give all records of a specific object type a custom background colour, create a CSS file containing:

/* All booking records get a teal background */
.kruviScheduler .isimio-table .UIElement.my_booking__c {
    background-color: #E0F7FA;
    border-left-color: #00ACC1;
}

/* Cancelled bookings are shown in grey */
.kruviScheduler .isimio-table .UIElement.my_booking__c[attr-status__c="Cancelled"] {
    background-color: #EEEEEE;
    border-left-color: #9E9E9E;
    color: #9E9E9E;
}

Example 2: Setting Dynamic Default Values (JavaScript)

When a static default value is not enough (e.g. you need the current time, or a value that varies per user), you can intercept the record creation process with a JavaScript plugin:

if (!window.classes.UIElement.prototype.update_orig) {
    window.classes.UIElement.prototype.update_orig =
        window.classes.UIElement.prototype.update;

    window.classes.UIElement.prototype.update = function(data, params) {
        if (this.sObjectType.name === 'my_booking__c') {
            if (params && params.isNew === true && !data['id']) {
                // Set default record type on new records
                data['recordtypeid'] = '012f4000000fZ1aAAE';
            }
        }
        this.update_orig(data, params);
    };
}

The pattern shown above safely wraps the original UIElement.update() method: it stores a reference to the original first, then replaces it with a new function that adds custom logic before calling the original.

✅ Validators

Validators allow you to define business rules that are checked whenever a record is created or modified. When a validation fails, the user is shown a warning or error message, and (depending on severity) the save may be blocked. Validators are configured as child records of Schedule Objects.

Overview

Each Schedule_Validator__c record binds an Apex validation class to a Schedule Object, with configuration, a message, and a severity level. The built-in validators cover the most common scheduling constraints, but custom validators can be written by implementing the Validation Apex interface.

Schedule_Validator__c Fields

Val_Length_Counter

This validator counts the total hours (or number of records) assigned to a group within a rolling time window, and triggers if the total exceeds a specified maximum. Use it to enforce limits like "no more than 40 hours per week per person" or "no more than 8 shifts per day per employee."

Configuration Parameters

Apex Handler:  Val_Length_Counter
Error Message: This employee has too many shifts today.
Severity:      High
Parameters (JSON):
{
  "groupby": ["OwnerId"],
  "max": 8,
  "days": 1,
  "count": true
}

Apex Handler:  Val_Length_Counter
Error Message: This person would exceed 40 hours this week.
Severity:      High
Parameters (JSON):
{
  "groupby": ["OwnerId"],
  "max": 40,
  "cal-weeks": 1,
  "week-start": "Monday"
}

Val_Record_Overlap

This validator detects when two records assigned to the same group have overlapping time ranges. Use it to prevent double-booking a person, room, or piece of equipment.

Configuration Parameters

Apex Handler:  Val_Record_Overlap
Error Message: This person is already booked during this time.
Severity:      Critical
Parameters (JSON):
{
  "groupby": ["OwnerId"]
}

Apex Handler:  Val_Record_Overlap
Error Message: There must be at least 1 hour between this person's shifts.
Severity:      High
Parameters (JSON):
{
  "groupby": ["OwnerId"],
  "padEnd": 1
}

👤 End-User Variables (Personal_Config__c)

Personal_Config__c records allow administrators to define named key/value variables that can be used as merge fields inside SOQL filter expressions on Schedule Objects. This enables the scheduler to load a different set of records for different users — without writing any code.

A common use case is allowing each user to see only records assigned to their own team, their own region, or a record type relevant to their role.

Creating Variables

Personal Config records are created directly in Salesforce. Each record is owned by a specific user and holds a single named value:

Using Variables in Filters

To reference a Personal Config variable in a Schedule Object filter, use the merge syntax {!VariableName}. At runtime, Isimio replaces this token with the value from the current user's Personal Config record (or the Global record if no personal value exists).

-- Filter by a record type stored as a Personal Config variable named "CaseRecordType"
RecordType.DeveloperName = '{!CaseRecordType}'

-- Filter to a specific region
Region__c = '{!MyRegion}'

-- Combine a static filter with a personal config variable
Status__c = 'Active' AND Territory__c = '{!UserTerritory}'

Step-by-Step: Setting Up a User Variable Filter

1. Decide on a variable name, e.g. DefaultTeam
2. Create a Personal_Config__c record owned by a system administrator with Name = DefaultTeam, Value = TeamA, and Global = true — this is the default
3. For each user who needs a different value, create a Personal Config record owned by that user with Name = DefaultTeam and their specific Value
4. On the Schedule Object, set Filter to: Team__c = '{!DefaultTeam}'
5. Each user will now see only records from their own team

🔀 Multiple Schedulers

A single Salesforce org can host multiple independent Isimio schedulers, each with its own data model, actions, plugins, and styling. This is achieved through a mechanism called Filter Sets. Typical use cases include:

• A scheduler for shift management and a separate one for resource bookings, on different Lightning pages
• A manager view with additional columns and actions, alongside a simplified staff-facing view
• Department-specific schedulers each showing a different subset of objects and record types

How Filter Sets Work

The Filter Set attribute on the Isimio LWC component is a plain text string (e.g. ShiftManager or Bookings). When the scheduler loads, it evaluates every configurable element against a simple rule:

This means that any configuration element without a Filter Set is global — it appears in every scheduler in your org. You only need to set a Filter Set on elements that should be exclusive to one particular scheduler instance.

Setting Up Multiple Schedulers

Step 1: Name Your Scheduler Instances

Choose a short, descriptive name for each scheduler instance. These names are case-sensitive and must match exactly between the component attribute and the configuration records. Good examples: ShiftManager, RoomBooking, ProjectTimeline.

Step 2: Set the Filter Set on the LWC Component

1. Open the Lightning App Builder for the page where this scheduler will live
2. Click the Isimio Scheduler component
3. In the properties panel, set Filter Set to your chosen name (e.g. RoomBooking)
4. Save and activate the page

Step 3: Tag Configuration Records with the Filter Set

For each configuration element that should only appear in this specific scheduler, set its Filter Set field to the same name:

Example: Two Schedulers from the Same Object

Suppose you want a Manager view that shows a Shift__c object with all fields, and a Staff view that only shows the name and start/end time:

1. Create two Schedule_Object__c records, both with Name = Shift__c:
   • Record 1: Filter Set = Manager, all fields configured
   • Record 2: Filter Set = Staff, only name and date fields configured
2. Create two Lightning pages, one with Filter Set = Manager, one with Filter Set = Staff
3. Each page will load the correct configuration independently