Welcome to our blog where will be sharing tip, tricks and detailed walk-throughs covering all areas of Dynamics 365 but primarily focused on the Field Service and Project Service Apps, Scheduling and integration using Microsoft Flow and the Common Data Service (CDS). We hope you find the blog posts useful and please feel free to comment if you would like us to elaborate on any particular area. 

Extending the booking process using Booking Rules

Updated: Apr 7, 2018

This blog post is aimed at giving Dynamics 365 developers with a knowledge of JavaScript an insight into one of the lesser known Schedule Board features of Dynamics 365, Booking Rules.

In a nutshell Booking Rules allow you to invoke additional processing via JavaScript functions whenever a booking is added to, or amended on, the Schedule Board, whether it be via Drag & Drop, Find Availability and Book or any other available mechanism.

This allows you to perform additional checks prior to making the booking such as, does the engineer have enough stock in their van to perform the job, or prompt for additional information to be captured via custom JavaScript dialogs.

As an example, we have used it to present a dialog to the scheduler to support the booking of multiple resources for a job which may require different skills per resource when an applicable job/requirement is selected for booking.

In our simple example, I'm going to show you how to prevent the booking of a work order if the Billing Account is flagged as being Credit On Hold, which should then give you enough knowledge to go away and build your own. The final outcome of trying to schedule a Work Order for an Account which is on Credit Hold is shown below:

You need to do a couple of things to implement Booking Rules:

1) Create one or more JavaScript libraries and associated functions to perform the required processing

2) Create one or more Booking Rule records which will refer to those libraries and functions created in 1)

Let's work through the creation of the main JavaScript function which will be invoked by the Schedule Board. So, first, you need to create a new JavaScript library in your Dynamics 365 solution.

Create your booking rule function and ensure you add one parameter, typically named 'context' or similar, which will be passed in by the Schedule Board and will contain some details about the requirement being booked.

Let's go into more detail regarding the 'context' parameter. It contains the properties illustrated in the screenshot below which are populated automatically by the Schedule Board. These properties are fairly self-explanatory and the only "gotcha" is that in version 9, the ResourceRequirement has changed to ResourceRequirementId in both the newValues and oldValues object.

  • isCreate – is this a new booking request. ​

  • isUpdate – is someone attempting to adjust an existing booking e.g. dragging an existing scheduled booking ​

  • newValues – contains information about the booking being attempted​.

  • oldValues – only populated when isUpdate is true and will contain the same properties as for the new values only they will be the original values before the booking change was attempted. ​

In addition, the Schedule Board is expecting a parameter to be returned from this function in the following format:

If this is not returned or it is in an incorrect format an error will be displayed by the Schedule Board. We will see this 'result' parameter in operation below.

So, now we have the basic function definition, we need to flesh it out with our processing, in this case I'm simply going to execute a FetchXML query using Web API to check if the Billing Account on the Work Order linked to the Requirement is flagged as being Credit On Hold, if so, prevent the booking from being completed and alert the user. Typically I tend to use Advanced Find to build my FetchXML and CRM Rest Builder to test it.

IMPORTANT NOTE: Due to the way the process has been implemented the Schedule Board will process the result (if any) as soon as the JavaScript function returns which can be problematic if you need to make Web API calls, present dialogs requiring user input etc. At this point you have a number of choices, block the JavaScript function from returning until such time as the processing has completed OR use synchronous Web API calls etc. In this example, I will be using synchronous Web API calls but you could also look at using async/await along with Promises to build using an asynchronous approach.

The completed function looks like the screenshot below and I have annotated with comments to explain the code.

Now we have completed our function we have to add a Booking Rule record so that is invoked by the Schedule Board when a booking attempt is made.

Booking Rules records can be found via the Administration section if Field Service App is installed or via Advanced Find if only Project Service Automation App is installed. For this blog, I will focus on the Field Service App implementation.

You can have multiple rules configured pointing to one or more JavaScript libraries and associated functions.

Note, only "active" booking rule records will be executed by the Schedule Board.

Once the booking rule record has been created if a booking is attempted for a requirement which is associated with a Work Order whose Billing Account is flagged as "Credit On Hold" then the user will be presented with the following message and the booking will not be completed.

531 views0 comments