Schedule Dispatch Service¶

The purpose of the Schedule Dispatch Service is to look at schedules produced by the Dynamic Scheduling Engine and, according to defined rules, decide when to commit activities to particular resources. The process of committing an activity fixes the activity within the schedule and the software will no longer alter the resource it is allocated to. The external application has taken ownership of that activity and the updating of its status.

Decisions to commit will be based on plans (schedules) read from the scheduling database. This will be done as new plans are available, but subject to a maximum frequency specified by an application parameter.

The Schedule Dispatch Service enables the logic for deciding when an activity should be committed to a resource to be defined as part of the standard installation and removes the need for complex logic to be developed by the external application.

For further information and advanced configuration details, please see the Scheduling Schema Guide.

Deciding when to Commit Activities¶

Periodically, the Schedule Dispatch Service will review the current schedule for all resources, and decide whether any activities should be committed (see later sections for details of how these decisions are made).

If the Schedule Dispatch Service decides that one or more activities should be committed, it will generate a Suggested_Dispatch record for this activity. If the commit is to be acted upon this needs to be turned into an Activity_Status with the resource_id filled in and status_id set to 30 (committed).

Depending upon the chosen parameter values, the Schedule Dispatch Service may uncommit activities when a resource logs off – in this case the status_id will be set to 0. However, the Schedule Dispatch Service will never set the status to anything other than 30 or 0 for the Suggested_Dispatch.

Once all resources have been considered, the Suggested_Dispatch records will be added to the schedule output data. The Schedule Dispatch Service does not itself commit or uncommit any activities: it only suggests activities to commit. It is the responsibility of the External Application to actually send in the correct data in order to commit the activities.

If the External Application wishes to accept the Schedule Dispatch Service's commit suggestions, it should convert the Suggested_Dispatch records into Activity_Status records and add an Input Reference “CHANGE” record with the appropriate date and time, and send in the data in the normal way.

The Schedule Dispatch Service will assume that the External Application is going to accept its suggestions, and so for the next 15 minutes (configurable) of schedule time it will make its decisions accordingly.

Commitment Rules¶

This section describes in detail the rules which may be used to determine which activities are committed by the Schedule Dispatch Service.

The rules can be quite complex; so a simple subset of the rules is presented here first, followed by the full list of rules in the “advanced” section below.

Basic Rules¶

The basic rules are:

1. MaximumCommittedActivities: how many activities should be committed to a resource at any one time
2. TimeHorizon: a resource must be due to start travelling to an activity within this amount of time, in order for it to get committed.
3. SendExternalCommitsMode: defines when Suggested_Dispatch records will be created

So, if MaximumCommittedActivities is 2, then at the start of a shift the Schedule Dispatch Service will commit the first two calls of the day to a resource. Once it has completed the first activity, the Schedule Dispatch Service will commit the third activity of the day, etc.

As a general rule, it is best to set MaximumCommittedActivities to 1, or as low as possible, so that the Dynamic Scheduling Engine has the maximum flexibility to change the schedule as a result of new activities, job overruns/underruns, travel delays etc. during the day. If, however, there is often a delay in getting the next activity sent to a resource's mobile device for any reason, then it may be best to set MaximumCommittedActivities to 2, so that the resource always has a new call to start on once they finish the previous one.

In order for an activity to be committed by the Schedule Dispatch Service, both the MaximumCommittedActivities rule and the TimeHorizon rule must be obeyed.

SendExternalCommitsMode has the following options:

• NONE: which is the normal behaviour as defined above.
• ALL: the Schedule Dispatch Service will write a Suggested_Dispatch row whenever an activity is committed or uncommitted, if the Schedule Dispatch Service did not suggest the dispatch in the first place.
• MANUAL: the Schedule Dispatch Service will only do this for activities which have been manually committed or uncommitted via the Scheduling Workbench (identified by Activity_Status.source = 1). Suggested_Dispatch.source will be set to 2 for suggestions made by the Schedule Dispatch Service itself, and will use the value given on the Activity_Status row for external commits (so this will be 1 for Scheduling Workbench manual commits). Note the Schedule Dispatch Service is only looking for committed status or less - if an activity is set straight to travelling on the Scheduling Workbench this will not generate a Suggested_Dispatch record.

Rules for Specific Datasets¶

The default values for the various rules in the database may be overridden on a dataset-by-dataset basis within the organisation rules. For example, to change the TimeHorizon for a dataset, submit an Input Reference for the organisation and dataset and specify a Rule and a Rule_Parameter for the TimeHorizon.

Rules for Specific Resources¶

It is possible to specify that a specific resource type or resource have different values for MaximumCommittedActivities, TimeHorizon, or any of the other rules. Again, this is done using a Rule and a Rule_Parameter. Also, it is possible to specify rules on a shift-by-shift basis. Any rule defined at resource shift overrides the rule with matching rule type defined directly on a resource or resource type. Any non matching rule types are merged to the existing list of rules to be validated.

Breaks and Private Appointments¶

Private appointments will never be committed by the Schedule Dispatch Service. Breaks will be committed provided that the parameter “CommitBreaks” is true; see the section on 'Handling of breaks' for full details of this. Fixed allocated activities may be committed, provided they do not finish in the past.

Advanced Rules¶

The full set of rules is as follows:

As an example, for a resource rule being overridden by a shift rule, consider a resource directly linked to COMMIT and COMMIT_ACTIVITY_TYPE rules with maximum committed activities set to 2 and 3 respectively. But the resource shift is linked to a COMMIT rule with maximum committed activity set to 4. Since the rules set at resource and resource shift both have COMMIT rule in common, the COMMIT rule set at resource shift level will take precedence over the rule set at resource level. Since the COMMIT_ACTIVITY_TYPE is not defined at shift level, this is not overridden. So the rules used for validation are the COMMIT rule specified at shift level and the COMMIT_ACTIVITY_TYPE rule specified at resource level.

Handling of Breaks¶

The three rules CommitBreaks, CountBreaks and IgnoreBreakTime govern how the Schedule Dispatch Service handles breaks. The best settings to use will depend on whether breaks are handled by the mobile application used by resources, and if so, how.

As an example, suppose that the current time is 12pm, and that a resource is scheduled to start a 45 minute break immediately, followed by travel to an activity. There are no activities already committed to the resource. The table below details what suggestions will be made with different settings for these parameters, and for the basic parameters MaximumCommittedActivities and TimeHorizon.

Future Shifts¶

There are two ways to commit activities into future shifts. One way is to set NextDayCommit to true, which will allow the Schedule Dispatch Service to make suggestions into the next shift only. Alternatively, ShiftsInFuture can be used to define the number of shifts into the future to make suggestions for.

These two methods operate in different ways (for example, setting NextDayCommit to true will not have exactly the same effect as setting ShiftsInFuture to 1). The differences will be outlined below. Note that some parameters may be ignored depending on the method in use.

Next Day Commit¶

When setting NextDayCommit, the parameters TimeBeforeShiftStart and NextDayCommitBuffer also affect when activities are suggested for commit in shifts that have not yet started.

• A few hours before the shift starts.
• The evening before.
• Shortly before the end of the previous shift.

The rule TimeBeforeShiftStart sets a limit on how long before the shift starts the Schedule Dispatch Service will consider committing activities into it. For example if this is set to 3 hours then for a shift starting at 9am the Schedule Dispatch Service can start making suggestions for this shift from 6am. Importantly, the TimeHorizon rule is then applied as if the time was the shift start time, so a 30 minute time horizon would allow activities whose travel started before 9:30am to be committed. Note that other rules - in particular LogonRequired and MaximumCommittedActivities - are still applied as usual.

To allow the Schedule Dispatch Service to suggest commits for a shift before the end of the previous shift, we also we also need to set the NextDayCommitBuffer. Suppose, for example, our resource is working 9am to 5pm shifts, and we wish to start committing work to him for the next day from 4pm, 1 hour before his shift ends. We then need to set the parameters as follows:

• TimeBeforeShiftStart = 24 hours (17 hours would also be OK)
• NextDayCommit = true
• NextDayCommitBuffer = 1 hour

Shifts In Future¶

Setting ShiftsInFuture to a value greater than zero can be used to specify the number of shifts beyond the current shift to make suggestions for. When using this method, the Schedule Dispatch Service will ignore the NextDayCommit, NextDayCommitBuffer and EndShiftHorizon parameters. Instead it will make suggestions for the number of shifts specified without waiting for the current shift to end/reach the time specified by the NextDayCommitBuffer.

The number of shifts that suggestions will be made for can vary depending on whether or not there is a current shift that is active. This will be demonstrated in the following examples, which will all assume ShiftsInFuture is set to 4, and that the resource has a 9am-5pm shift every day:

• The current time is 9am. Suggestions can be made for 5 shifts (today's current shift, and then the 4 future shifts).
• The current time is 6am. The TimeBeforeShiftStart parameter is set to 2 hours. Suggestions can be made for 4 shifts, since there is no currently active shift, so we only get suggestions for the 4 future shifts.
• The current time is 8am. The TimeBeforeShiftStart parameter is set to 2 hours. Suggestions can be made for 5 shifts, since even though it has not started yet, the shift starting at 9am is considered to be currently active according to the TimeBeforeShiftStart parameter. Thus we have one current shift and 4 future shifts receiving suggestions.

Rule Overrides¶

Rule overrides can be configured to tell the Schedule Dispatch Service of any rule changes that should occur under a certain special circumstance. Rule overrides can override the MaximumCommittedActivities and TimeHorizon rules whilst also allowing setting of additional rules.

Co-requisite Override¶

The commit override 'rule_type_id' value is COMMIT_COREQUISITES.

The co-requisites override is applied when the Schedule Dispatch Service is about to commit an activity that has co-requisites. The override will ensure that all co-requisite activities are suggested for commit at the same time. The override applies to the value of the MaximumCommittedActivities rule, and there are 2 options:

• Set the override value to -1. The Schedule Dispatch Service will then only suggest committing a co-requisite activity once all co-requisite activities are ready to be committed under their normal rules. Be aware however that this could lead to delays if, for example, one resource has a long travel to get to the activity.
• Set the override to a value greater than 0. The Dynamic Scheduling Engine will then apply this value when checking whether the other co-requisite activities are ready for commit - i.e. you can allow extra activities than normal to be committed in order to ensure the co-requisite activities get committed together. This is the option we would recommend using.

Parallel Resource Override¶

The commit override 'rule_type_id' value is COMMIT_PARALLEL_RESOURCE

The parallel resource override applies to activities that begin at the same time as each other when scheduled to the same parallel resource. This can be used to allow suggestions to be made for more activities than normal when beginning simultaneously. This kind of override rule is only applied to parallel resources.

Activities at the Same Location Override¶

The commit override 'rule_type_id' value is COMMIT_SAME_LOCATION.

Activities at the same location are identified by the Activity entities having the same location_id attribute, or the same locality attribute if this is specified. Note that two Location entities with the same latitude and longitude are not considered to be the same for the purpose of this rule: only two activities referring to the same Location or Locality entity count as “same location” for the purpose of this rule.

Lack of Coverage Override¶

The commit override 'rule_type_id' value is COMMIT_LACK_OF_COVERAGE.

Lack of coverage is identified by an attribute 'lack_of_coverage' on the Location and/or Location_Type entities. An example of this could be if at a location there is no mobile reception.

Activity Type Override¶

The commit override 'rule_type_id' value is COMMIT_ACTIVITY_TYPE.

The activity type override is applied when the Schedule Dispatch Service is about to commit an activity of matching activity type. An additional rule parameter MaximumCommittedActivitiesOfMatchingType can be set for this rule type. This parameter is similar to MaximumCommittedActivities but only applies to activities that match the type specified on the rule.

As an example, suppose we have the following:

• Four activities of two types (TypeA and TypeB)
• A basic COMMIT rule with MaximumCommittedActivities set to 2
• An override rule of type COMMIT_ACTIVITY_TYPE against TypeA with MaximumCommittedActivitiesOfMatchingType set to 2 and MaximumCommittedActivities set to 4.
• A shift that has four activities scheduled of types: TypeA, TypeB, TypeA, TypeB

When the Schedule Dispatch Service checks the first activity, the override rule is used. We have 1 activity and 1 activity of matching type at this point. We can therefore make a suggestion.

When we check the second activity, the COMMIT rule is used. We have 2 activities at this point. We can make a suggestion as the rules are still valid.

When we check the third activity, the override rule is used. We have 3 activities and 2 of matching type at this point. Even though we have exceeded the MaximumCommittedActivities of the COMMIT rule, we are still valid when checking the override rule, so a suggestion is made.

When we check the fourth activity, the COMMIT rule is back to being used. We have 4 activities at this point, so no suggestion is made.

Long Travel Override (lowest precedence)¶

The commit override 'rule_type_id' value is COMMIT_TRAVEL_TIME.

The "TravelTime" override rule requires an additional rule parameter to be specified, which determines when a journey should be regarded as a long travel. The parameter name for this is 'OverrideThreshold', and it should be specified as a TimeSpan.

The main use case for this is to delay committing activities to resources who would need to travel a long way to carry out the activity. This then gives more time for the schedule to change and for a closer resource to become available.

For example, suppose the default rules specify that activities should be committed 1 hour in advance (i.e. a TimeHorizon of 1 hour). A travel time override could be set up so that if the travel is greater than 90 minutes then the activity should only be committed 15 minutes in advance. In this case the rule parameters for the override would set the TimeHorizon to 15 minutes and the OverrideThreshold to 90 minutes.

Handling Bucket Resources¶

The Schedule Dispatch Service can make commit suggestions for bucket resources. However, since activities scheduled to bucket resources do not have a defined start time and therefore no order, suggestions for all of the activities scheduled to a bucket shift will be made at once.

If using the DSE parameter AllowPartiallyCommittedBucketRoutes then more activities may be scheduled to a bucket shift after commits to the shift have already been made. The Schedule Dispatch Service may then make commit suggestions for these "extra" activities, again, all at once.

Commit To Availability Window¶

If the parameter 'CommitToAvailabilityWindow' is enabled, activities that are scheduled within an availability window will have the start of the window set in the 'date_time_earliest' column in the table 'Suggested_Dispatch' when the DSP is making a commit suggestion for that activity.