Skip to main content
Kinetic Community

Combining Calendar Into Request

Downloads

PDF

Powerpoint

This presentation uses an example to detail how to combine calendar into request. This example case is allows a customer to select a specific deployment time from a list of available time slots using a Kinetic Calendar embedded within a Kinetic Request.

Community Article

This page contains files and instructions necessary to set up a Kinetic Calendar 2.0 that will allow customers to book a deployment time for their request directly within the request from available times configured by the deployment team. This functionality is accomplished in three steps: Setting up/configuring the available times for deployment. Displaying these times in two calendars: an available times calendar used for booking times and a reserved time calendar used by fulfillment to see the deployments booked. Embedding the available time calendar in the service item to allow the customer to select a time when submitting the request. User Interaction Details of the user interaction will be theme dependent, but if these instructions are followed, it will initially appear much like this to the user: And when “Select a Time” is clicked, the embedded calendar will display along with a date field that allows the user to select a date other than the one shown by default. When the user clicks on an available slot, the selected time is entered in the deployment time and the calendar is removed.

Setting Up the Deployment Calendar Available Times

The code provided in this example uses Remedy forms to store the data for the time slots for deployment. Once the initial configuration is done, an escalation keeps the desired number of days of slots available and deletes old/expired slots. A new permission group, KS_CAL_DeploymentManager, has been created for management of these Remedy forms. This is necessary to allow the desired individuals access to manage their deployment calendars, including in production, without giving them additional access. Someone with these permissions can call up the form CUSTOM:KS_CreateTimeSlots to set up or manage a deployment calendar dataset, or the form CUSTOM:KS_TimeSlots to remove or update individual slots (eg. for a vacation day).
 
Note that these Remedy forms are not Kinetic Data product, but are a custom solution you can choose to employ. You will likely want to rename the forms and workflow to your naming conventions. You may change the permission groups used and the functionality to suit your purposes. If you are not using remedy, you can set up similar functionality in another tool/database to be accessed by Kinetic Calendar 2.0 and follow the rest of the instructions to similarly set up the embedded calendar in the request.

Creating Deployment Calendar Data/Time Slots

To create a new calendar with time slots for deployment, pull up the CUSTOM:KS_CreateTimeSlots form in new mode and fill in the Calendar Name, Time Slot Name, Delete Available Time Slots Older than, and Create Entries for This Many Days.

The Calendar Name here is really just for reference, and doesn’t need to be the visible name that users will see. The Time Slot Name is the name that will be given to available time slots (that the customer will be able to choose from). Delete Available Time Slots Older than should be an integer. Example: 10 would be ten days in the future, -10 would be ten days in the past. This will control when time slots that are marked available will be deleted. This can be used, for example, to prevent someone from scheduling something less than 10 days out by setting it to 10. Create Entries for this Many Days is also an integer. This is how many days in the future will contain available time slots. If it contains 90, there will be 90 days of available time slots (from now) created. Escalations will maintain this weekly, creating additional time slots periodically.

CalendarSetup.png

Do not select the “Create Available Time Slots on Save” at this point, because the time slots haven’t been created/specified yet. Then save the record. 

Adding Time Slots

Search for the Calendar entry you created and add the desired time slots by specifying a Day of Week, Slot Start Time, Slot End Time, and Number of Entries for that slot, then click Add Slot.

AddSlots1.png

This example will have the calendar show two available/bookable time slots, both of which span 9-11 AM on Mondays. Once you add the slot it will appear in the table below.

AddSlots2.png

Continue this process until all of the desired slots/bookable times are in place. This table (below) reflects one possible schedule, where there are two staff available for deployments from 9 – 11 AM five days a week, one staff available to deploy Monday, Wednesday, and Friday at Noon – 2 PM, and two staff available to deploy Tuesday and Thursday from 1-3 PM.

AddSlots3.png

Each entry will a time available to be booked on the calendar visible from within the service item/work order.

Activating the Entry and Creating the Time Slots

The last steps to prepare the time slots for the calendars (available and booked) are to activate the record in CUSTOM:KS_CreateTimeSlots and to actually create the time slots. Change the status to active, check the “Create Available Time Slots on Save” checkbox, and save the record. This will create the specified time slots for the specified number of days and will indicate the date the time slots are created until. The data will now exist to be viewed in the calendars.

Creating the Available and Booked Calendar

To create calendars for Kinetic Data’s Calendar 2.0.x product, directories are placed in the WEB-INF/configuration/calendars directory. Each Directory contains a calendar.json and a et_events.json file. More documentation about Calendar 2.0 is available here. This page will only review the details specific to setting up the calendars for this project. 

Booked Time Calendar

The booked time calendar is the calendar visible to the fulfillers and shows all booked appointments.

Example Booked calendar.json

{
    "name": "Desktop Reserved Times",
    "id": "ScheduleDesktop",
    "description": "Reserved Times for Desktop Appointments",
    "status": "Active",
    "defaultView": "Week",
    "displayPage": "/themes/default/calendar.jsp",
    "visibleInListing": true,
    "clickHandler": {},
    "eventTypeOrder": [
    "Completed"
    ]
} 

The Name, ID, and Description don’t need to match anything already created. The ID should match the folder name containing the booked calendar. The Name and Description are visible to the users. Note that the defaultView is Week. Some deployment teams may prefer to see the entire month as the default view.

Note that the deployment team will want to access the booked time calendar directly, so it should probably be included in the listing (visibleInListing). If it is not included there, the link should be sent to the deployment team.

Example et_events.json

{
    "name": "Completed",
    "status": "Active",
    "defaultFilter": "",
    "detailsPage": "/themes/default/event.jsp",
    "color": null,
    "source": {
        "connectionName": "ITSM ARS",
        "configuration": {
            "Form": "CUSTOM:KS_TimeSlots",
            "Qualification": "'Status' = \"Reserved\" AND 'CalendarName' = \"My Deployment Calendar\""
        },
        "coreMappings": {
            "Id": "{{1}}",
            "Name": "{{700006001}}",
            "Description": "{{700006001}}",
            "Start": "{{700006053}}",
            "End": "{{700006054}}"
        },
        "detailMappings": {
            "SlotName": "{{700006001}}",
            "SlotStartTime": "{{700006053}}",
            "SlotEndTime": "{{700006054}}",
            "Service Item Details": "{{700006005}}"
        },
        "filterMappings": [
            {
                "name": "Duration",
                "value": "{{700006052}}",
                "values": {}
            }
        ]
    }
}

The source form for the booked and available calendars is the same: CUSTOM:KS_TimeSlots. This, the booked time calendar, displays the slots/entries with a status of Reserved. The example mapping displays the provided slot name for both the name and description, and uses the Start DateTime and End DateTime fields to correctly display the entry on the calendar. The detail mappings use the Slot Name, Start DateTime, End DateTime, and Service Item Details provided when the time slot was reserved.

Available Time Calendar

The available time calendar is the calendar visible to the customers within the service item and allows the user to book a time.

Example Available calendar.json

{
    "name": "Desktop Available Times",
    "id": " ScheduleDesktopAvailable",
    "description": "Available Times for Desktop Appointments",
    "status": "Active",
    "defaultView": "Day",
    "displayPage": "/themes/default/calendar.jsp",
    "visibleInListing": true,
    "clickHandler": {},
    "eventTypeOrder": [
    "Completed"
    ]
}

 

Because this is an embedded calendar, the default view is generally set to Day. Once things with this calendar are debugged, it may be preferred to change the visibleInListing to false.

Example Available et_events.json

{
    "name": "Available",
    "status": "Active",
    "defaultFilter": "",
    "detailsPage": "/themes/default/event.jsp",
    "color": null,
    "source": {
        "connectionName": "ITSM ARS",
        "configuration": {
            "Form": "CUSTOM:KS_TimeSlots",
            "Qualification": "'Status' = \"Available\" AND 'CalendarName' = \"My Deployment Calendar\""
        },
        "coreMappings": {
            "Id": "{{1}}",
            "Name": "{{700006001}}",
            "Description": "{{700006001}}",
            "Start": "{{700006053}}",
            "End": "{{700006054}}"
        },
        "detailMappings": {
            "SlotName": "{{700006001}}",
            "SlotStartTime": "{{700006053}}",
            "SlotEndTime": "{{700006054}}"
        },
        "filterMappings": [
            {
                "name": "Available",
                "value": "{{700006001}}",
                "values": {}
            }
        ]
    },
      "clickHandler": {
            "type":"js",
            "callback":"window.parent.setEventDetails",
            "parameters": {}
      }
}

 

The available calendar also pulls data for the desired calendar name (same calendar name as the booked calendar) from CUSTOM:KS_TimeSlots, but pulls the entries with a status of Available. The Core Mappings are the same as for the booked calendar, and the Detail Mappings are the same except for not including the Service Item Details (because there aren’t any yet). The critical part to making this calendar work to allow users to book by clicking an entry is the click handler. This calls a function that returns the event details to the service item.

Activating Updates to Calendar Configuration

It is important to note that the calendar configuration needs to be reloaded (in the calendar configuration console) by someone with permissions to do so once the files have been created and placed out on the Calendar server.

Service Item

There are elements, events, additional supporting code and tree updates necessary for the service items.

Section Elements

A section will need to be added to the service item the calendar is to be embedded within.

SetUp1.png

Pictured above is the example from the Deployment Calendar Project. This section can be copied to begin the implantation of this feature in another service item. This item is the example service item.

The section needs to contain a Deployment Time question (to display the selected time to the user), a text element that contains a button used to display the calendar, a text element to clear the floats, a hidden event ID field (used to actually reserved the slot on service item submission), instructions on how to select/book a time, and a text element that contains the frame for the calendar.

To allow the button to be beside the Deployment Time question, the Deployment Time question has a style of

float: left;

SetUp2.png

The Select a Time button has an event on click to show the embedded calendar:

SetUp3.png

This event references a javascript function in the Custom Header Content for the item. This function (included below) determines what date the embedded calendar should default to, sets that date into the Select a Date question, fires the change on that question (to display the selected date), and inserts the appropriate elements. Note that the setDateFields function uses the Select a Date question’s instance ID (from the Advanced Tab of the question). This function can be copied into a new service item for reuse, but you may wish to update the number of days from today that is displayed by default (14 in the example below) and to update the names of the elements if you have changed them for the new item.

function showCalendar() {
// nowDate holds the current date
var nowDate = new Date();

// Add days to nowDate
nowDate.setDate(nowDate.getDate()+ 14) ;

// The array builds up the values needed by the setDateFields function if it is called
var nowDateArray = new Array();
nowDateArray[0] = nowDate.getFullYear();
nowDateArray[1] = nowDate.getMonth() + 1;
nowDateArray[2] = nowDate.getDate();

// Sets the QuestionID with the new value.
KD.utils.Action.setQuestionValue("Select a Date", nowDateArray);
var DateElem = KD.utils.Util.getQuestionInput("Select a Date");
KD.utils.Action._fireChange(DateElem);

//The questionID above must have single quotes.
KD.utils.Action.insertElement('Instructions');
KD.utils.Action.insertElement('Select a Date');
KD.utils.Action.insertElement('Calendar Frame');

}

The click event on the Select a Date question is what actually displays the calendar within the frame.

SetUp4.png

This event also references a javascript, but this time it is in a file timeSlots.js, which needs to be included in the Custom Header Content of the item.

<script type="text/javascript" src="/kinetic/themes/klean/common/resources/js/timeSlots.js"></script>

No customization of this function or any others included in timeSlots.js are necessary. These functions can be called as is. For the setCalendarURL function, you pass it the date to use and the name of the frame set up to contain the calendar.

The Calendar Frame text element contains the details of the calendar to be embedded, including the name given to the calendar (which calendar is being called).

<div class="calContainer">
<iframe id="calFrame" height="700px" width="97%" data-src="/kineticCalendar/calendar?id= ScheduleDesktopAvailable&embedded=true&debugjs=true"><p>Your browser does not support iframes.</p> </iframe>
</div>

The height used in the example shows the times from 8 AM to 5 PM without having to scroll within the calendar frame.

Additional Supporting Code

There is one more critical javascript in the Custom Header Content. This is the javascript called when a user clicks on a time. This setEventDetails function is passed the calendar event details by the click handler set up in the calendar and calls setCalendarEventDetails (from timeslot.js) to actually do the work of setting the details into the questions passed to it (first the Deployment Time and then the Event ID) and then removes the appropriate elements. Setting the event details in this manner allows the heavy lifting to be done by shared code, while allowing developers to customize the names of all of the section elements.

function setEventDetails(calendarEvent) {
    //Set date/time from the clicked calendar event
    setCalendarEventDetails(calendarEvent, 'Deployment Time', 'Event ID');
    //Show/Remove appropriate fields
    KD.utils.Action.removeElement('Instructions');
    KD.utils.Action.removeElement('Select a Date');
    KD.utils.Action.removeElement('Calendar Frame');
}

Additional Support Events

There is an event needed to re-display the deployment date on the page the customer selects a deployment date on for review request. This is necessary because the fulfiller may change the deployment date, and the customer should always be displayed the current deployment date. Note that this does not change the value in the database for this field. The original date the customer selected is retained, but the customer is displayed the up to date information. This event is a set fields external event that pulls the date (StartDate) from CUSTOM:KS_TimeSlots for the record where the OriginalInstanceID on the time slot record matches the original instance ID for this record. 

SetUp5.png

Because this data isn’t stored in the database in the same format the user should view it in, there is a change event on the Deployment Time question that only fires when the page is loading that uses a function from timeSlots.js (formatSavedDeploymentDateTime(questionName)) to format the date.

SetUp6.png

There is also an event necessary on beforeSubmit on the Review Page to actually submit the time slot. This event uses the timeSlot.js function called reserveSlot that is defined as:

reserveSlot(slotID, status, name, details, originatingID, originatingKSR, workOrderID)

To most effectively utilize this function, you’ll want to create some hidden fields with defaults that set each of these values to what you want. Note these are examples with specific question IDs in them. You will have to use the Add Fields functionality to create you entries. In this example, the Review Page is the third page, so these hidden/removed fields are

Question

Default

wrk3 Time Slot ID

<FLD>Event ID;KScbf42db316a39d506b1480ee246ce14c0;ANSWER</FLD>

wrk3 Name

Deployment for <FLD>ReqFor_First Name;KS41d1fd673676b41c02edc653fbcc84c28;ANSWER</FLD> <FLD>ReqFor_Last Name;KSa8670aa64d6f35fd53fc7f37cb77c90cf;ANSWER</FLD> for <FLD>Originating ID-Display;700088607;BASE</FLD>

wrk3 Details

Request: <FLD>Originating ID-Display;700088607;BASE</FLD>

Requested For: <FLD>ReqFor_First Name;KS41d1fd673676b41c02edc653fbcc84c28;ANSWER</FLD> <FLD>ReqFor_Last Name;KSa8670aa64d6f35fd53fc7f37cb77c90cf;ANSWER</FLD> ; 

Due Date (if specified): <FLD>Due Date;KS4e29722c69508bf22603cfe629f5fea94;ANSWER</FLD>

wrk3 ID

<FLD>Originating ID;600000310;BASE</FLD>

wrk3 KSR

<FLD>Originating ID-Display;700088607;BASE</FLD>

 

The Name is what will display as the name of the calendar entry and the Details are what will display when that entry is opened by the deployment team. Note that you can copy these fields to a new service item, but the references for the questions will need to be updated to the correct references for the new service item. You could also create a different name/details convention for your new deployment calendar. Using these fields for the data, the event to reserve the slot looks like this:

SetUp7.png

Tree Set Up

The Timeslot needs to be released on Denial, Expiration, or Cancellation. This can be done by using the KS Timeslot Record Update handler.

 

Tree1v2.pngFor the case of denial, once the submission is closed, if there was a time slot reserved, it should be released.

Tree2.png

Tree3v2.png

The same handler can be used to release any reserved time slot upon cancellation. Where and how exactly this would be done would depend on the method used for cancellation.

Resources

Remedy Deployment Time Slot Code def file

New Remedy Group arx file

Handler to Update Time Slot

Supporting code/Callbacks for common folder of bundle; Note: This should be unzipped into the bundle directory. This includes files that need to be added to various directories in the common folder. Folder structure is included.

Example Service Item; Note: This service items do not come with a catalog and will need to be moved into a catalog of choice.

Approval Service Item that uses this approval handler; Note: This comes with a message template. You'll want to make sure that gets moved into the desired catalog too

Calendar 2.0

Example Available Time Calendar

Example Booked Time Calendar

Possible Extensions

One possible desired extension of this solution is, once a time is approved, pushing that time with a handler to the requested for's calendar. Which handler would be used to do so would depend on the program being used, like Exchange or Google Apps.

Another possible extension is allowing fulfillers to (re)schedule deployments from within a work order. This may also require releasing time pushed to the individual's calendar.

Other Presentation Resources