Rule Engine
About the rule engine
By default, every appointmentAppointmentA task scheduled to a resource for a specific period - the scheduled instance you see on the planning board. assigned to a resourceResourceAn entity that can carry out work - a person, vehicle, tool, or room - that you schedule on the planning board. that syncs with Exchange ends up in that person's Outlook calendar. Planners usually want finer control over which appointments reach the calendars. Temporary appointments or placeholders, for example, add no value there and should stay out.
The rule engine in the Exchange connector, introduced in Dime.Scheduler 2022.2.0, lets you define those filtering rules and change them without recompiling the system. The first iteration of the rule engine is configured in the "Rules" section of the application settings file for the service and the web app (appsettings.json).
Example
The simplified example below shows how this works. Two conditions must both pass before an appointment is sent to Exchange:
- The categoryCategoryA visual indicator (a color) applied to appointments to classify or label them. name (the background of the appointment in the planning boardPlanning boardThe main graphical scheduling surface where dispatchers drag tasks onto resources across a timeline.) must be “SERVICE” and a certain field on the task needs to be set to true. In this case, a free boolean field is used to indicate whether to synchronize the record to Exchange.
- The time markerTime markerA visual indicator on an appointment, separate from its category, used to flag a status or condition at a point in time. (the line below the subject of the appointment in the planning board) name must be “IN PROCESS” and a certain field on the task needs to be set to true. In this case, a free boolean field is used to indicate whether to synchronize the record to Exchange.
Suppose the planner schedules the four appointments below. Edit any of them - change the category, the time marker, or the sync flag - and watch which ones the rules let through to Outlook:
Out of the box, only appointment #1 is sent to Exchange, because it is the only one that meets both requirements: the category name is “SERVICE”, the time marker name is “IN PROCESS”, and the free boolean field is “TRUE”.
This is a deliberately simple example. You define what each rule must check. The rule engine understands a dedicated syntax for building powerful queries, and when requirements change, you update the rules and they take effect immediately. The syntax also gives you access to the entire data graph, so you can filter on data from the appointment, the planning lines, the service orders, customer data, and more.
Visual workflow builder
The Exchange rules page also includes a visual workflow builder that lets you control which appointments synchronize with Exchange, without writing rule expressions by hand.
- Drag-and-drop interface: build sync rules visually instead of editing JSON.
- Conditional logic: define conditions and branches to control exactly which appointments get synced.
- Real-time preview: see how your rules will affect synchronization before applying them.
The visual builder produces the same underlying rule definitions described below, so you can switch between the two views as needed.
Constructing rules
As the example above shows, one rule can hold multiple conditions. You decide how to split the filter, but breaking a rule into several expressions makes problems easier to diagnose. Because each condition has a name, you can quickly pinpoint why a given appointment wasn't synchronized to (and from) Exchange.
For each condition, define a unique name, a descriptive message for when the condition isn't met, and the rule itself. The rule uses a syntax for writing expressions that the engine parses into expression trees. In other words, it is a predicate that the application parses and executes at runtime every time an appointment is to be synchronized. An expression has three components.
The appointment
The expression reads like the body of a filter function found in many programming languages. The appointment field is where it all starts: it represents the appointment, and through it you can access the entire appointment graph. Common properties include:
- Category.Name
- TimeMarker.Name
- StartDate
- EndDate
- Subject
- Body
- Task.Taskno
- Task.Job.JobNo
Operator
Once you have the property you want, compare its value to another value so the expression can decide whether to pass the appointment on to Exchange. Supported operations include:
==oreqorequal: Equals!=or<>orneorneqornotequal: Does not equal<orltor<=orlte: Less than (or equal)>orgtor>=orgte: Greater than (or equal)x && yorx and y: Logical ANDx || yorx or y: Logical OR
Reference value
Finally, compare the appointment to a reference value using the operator. This value is usually static, as in the examples, but you can also compare it to another value within the same appointment graph.
Null reference checks
Some navigation properties in the graph might be missing (for example, appointments without a time marker, category, or linked task). To prevent null reference errors while the rule is applied, include the additional checks shown in the examples below.
Additional examples
Each rule is a named expression. A few common ones:
- Do not sync appointments marked "TO BE CONFIRMED" (appointments without a time marker can still be sent):
appointment.TimeMarker == NULL OR appointment.TimeMarker.Name <> "TO BE CONFIRMED" - Only sync appointments linked to a task:
appointment.Task <> NULL - Sync everything except ABSENCES that are not confirmed yet:
appointment.Task == NULL OR (appointment.Task.Job <> NULL AND appointment.Task.Job.JobNo == "ABSENCES" AND (appointment.TimeMarker == NULL OR appointment.TimeMarker.Name <> "TO BE CONFIRMED"))