Service Optimization
Date Time Violation Detector
Product ClickApp by ClickSoftware
For use with ClickMobile Touch
ClickSoftware Confidential
Legal Notice
The software with this guide is furnished under a license agreement and may be used only according to
the terms of that agreement.
Copyright
Copyright © ClickSoftware Technologies Ltd. All rights reserved.
No part of this publication may be copied without the express written permission of ClickSoftware
Technologies Ltd.
Patent and Trademark
US Patent Number 6,985,872 B2
ClickAnalyze, ClickFix, ClickForecast, ClickMobile, ClickPlan, ClickRoster, ClickSchedule, and
ClickSoftware are registered trademarks of ClickSoftware Technologies Ltd.
Contact Information
Contact information is available from the ClickSoftware web site: http://www.clicksoftware.com.
For general information, email to sales@clicksoftware.com.
For ClickSoftware Worldwide Support, email to support@clicksoftware.com or see the support page on
the ClickSoftware web site.
For Partner Enablement, email to partnerenablement@clicksoftware.com.
Publication Notice
This guide has been carefully compiled. The information in this guide does not constitute a warranty of
performance. Furthermore, ClickSoftware reserves the right to revise this publication and make changes
from time to time in the content thereof, without obligation to notify any person of such revisions or
changes. ClickSoftware assumes no liability for losses incurred as a result of out-of-date or incorrect
information in this guide.
Version
Date Time Violation Detector
App number: 1172
App version: 1.0
Date: February 2014
Date Time Violation Detector
3
Contents
DATE TIME VIOLATION DETECTOR ................. 4
Use ............................................................................................................. 4
How the App Works .............................................................................. 5
Legitimate Clock Discrepancies............................................................ 5
Disabling Detection for an Engineer ..................................................... 5
Prerequisites .............................................................................................. 6
Time-Zone Configuration Requirement ................................................ 6
Installation .................................................................................................. 6
Configuration .............................................................................................. 6
Step 1. Creating the PolicyViolation Collection .................................... 7
Step 2. Adding Engineer Property ........................................................ 9
Step 3. Configuring SXP Message ....................................................... 9
Step 4. Creating User Templates ....................................................... 10
Step 5. Configuring the PolicyViolation Business View ...................... 11
Step 6. Configuring Loading Criteria .................................................. 12
Step 7. Configuring the App Event and Settings ................................ 13
Comments ................................................................................................ 18
4
Date Time Violation Detector
Date Time Violation Detector
The Date Time Violation Detector helps prevent false time reports, whether
deliberate or inadvertent, that are caused by setting the mobile device clock to an
incorrect time. The app detects and warns if the clock of a mobile device is set
differently from the server clock.
Use
Under various circumstances, ClickMobile automatically records the current clock
time of the mobile device. Depending on the ClickMobile configuration, this can
occur when:

In the Schedule view, an employee reports the start or finish of an assignment

In the Timesheets view, an employee clocks in or out of a shift
To ensure accurate reporting, it is critical that the clock of the mobile device be set
to the same time as the Service Optimization server within an acceptable tolerance.
The Date Time Violation Detector detects clock discrepancies and helps mitigate
their consequences.
Date Time Violation Detector
5
How the App Works
The Date Time Violation Detector verifies that the system clock of the mobile
device is synchronized with the Service Optimization server clock. If the clocks are
set to different times, the app detects a clock violation.
The system implementer can configure the app to behave in any combination of the
following ways when it detects a violation:

The app can detect the violation silently and generate a violation report. The
supervisory staff can view the violation reports in either ClickSoftware
Workspace or ClickMobile.

The app can display a warning to the user about the violation.

The app can prevent the user from saving the assignment form. The user cannot
save the incorrect time data.

The app can immediately close the assignment form. The user cannot view or
edit the assignment details.
Legitimate Clock Discrepancies
A clock discrepancy might be legitimate. Optionally, you can enable the employees
or the supervisors to report the reason for a clock discrepancy.
Disabling Detection for an Engineer
By default, violation detection is enabled for all ClickMobile users. To disable
detection for a specific user, set the
Engineer.DisableDateTimeViolation property to True.
You might do this, for example, if the user is a technician who tests and repairs the
mobile devices, or if the user frequently crosses time-zone boundaries. Such users
might legitimately need to reset the clock of the mobile device.
6
Date Time Violation Detector
Prerequisites
This app requires ClickMobile Touch. For information about the certified versions,
see the ClickSoftware AppStore page of this app.
Time-Zone Configuration Requirement
The app requires that you enable time-zone support in the Service Optimization
system. You must define the engineer time zones in the District dictionary. The
clock of each mobile device must be set to the engineer time zone.
To verify the configuration, open the Service Optimization Administration tool and
examine the following setting:
Central Settings/Parameters/Time Zones/Identifiers/
EngineerTimeZone
The setting value must be District. If the setting has any other value, you cannot
use the app.
The app does not support time-phased engineer time zones.
For more information about the time-zone configuration, see Time Zones in the
ClickPlatform Configuration Guide.
Installation
1.
On each ClickMobile middle tier, copy the following file to the
ClickMobileWEB\CustomScripts directory.
W6.CM.Web.CheckForDateTimeViolation.js
2.
On each computer where you run the Mobility Studio, copy the following file
to the Service Optimization\Bin directory:
W6.CM.DateTimeValidationAdmin.dll
3.
On each Service Optimization server, copy the following file to the Service
Optimization\Bin directory:
W6.CM.DateTimeViolationCustomSXP.dll
Configuration
To configure the app, you must perform the following main steps.
Date Time Violation Detector
7
In the Service Optimization Structure tool:
1.
Create a user-defined collection called PolicyViolation.
2.
Add a user-defined property to the Engineer collection.
In the Service Optimization Administration tool:
3.
Configure an SXP message that the app uses to communicate with the server.
In the Mobility Studio:
4.
Create user templates for the supervisors and the employees.
5.
Configure a PolicyViolation business view. Optionally, you can hide the
view.
6.
Configure loading criteria for the PolicyViolation objects.
7.
Configure the app event and settings, such as the behavior when a violation is
detected.
The following sections provide detailed instructions for each step. The instructions
are for ClickMobile version 8.1.9. The instructions might vary slightly for other
versions.
Step 1. Creating the PolicyViolation Collection
Note:
This step is required only if you configure the app settings
Violation Report option (see Step 6. Configuring Loading Criteria
If you display the PolicyViolation view, configure loading
criteria for the PolicyViolation objects.
For example, the following criteria enable the supervisors to
view the violations of their employees. For detailed
instructions, see the ClickMobile Configuration Guide.
1. On the Home page of the Mobility Studio, click System
Settings > General Loading Criteria.
2. On the first wizard page, select the PolicyViolation object.
3. On the next page, select Using Groups.
8
Date Time Violation Detector
4. On the left side of the next wizard page, right-click the
Users Group and add the following engineer criteria:
EngineerType equals 'Supervisor'
Engineer.LoginID equals Parameter 1
This example assumes that you use the EngineerType
property to identify supervisors, and that you have set the
ClickMobile login property to LoginID. Vary these criteria
as required in your system.
5. On the right side of the same page, right-click the
PolicyViolation group and add the following criterion:
EngineerApproverLoginID equals Parameter 1
6. On the next wizard page, drag the items as illustrated.
This operation matches the Engineer.LoginID property
with the PolicyViolation.EngineerApproverLoginID
property. The effect is to load a PolicyViolation object if it
pertains to the supervisor's employees.
Date Time Violation Detector
9
7. On the Time Criteria page, configure the time interval over
which to load the PolicyViolation objects.
For example, load the objects that were created during the
last seven days.
8. Click Next and finish the wizard.
If the supervisor template displays a business view of
engineers, you must also configure loading criteria for the
Engineer objects. This is not necessary if the supervisor
template displays My View.
Step 7. Configuring the App Event and Settings below). If you do
not plan to generate violation reports, you can omit this step.
The app uses the PolicyViolation collection to store the violation data.
1.
In the Service Optimization Structure tool, create a user-defined collection with
the following characteristics:
- Collection name: PolicyViolation
- Size: Depends on the quantity of data that you expect to store. Small is
adequate for most organizations.
- Not cached
- Create string identifier property: do not select this option
For detailed instructions, see User-Defined Properties, Dictionaries, and
Collections in the ClickPlatform Configuration Guide.
2.
Within the collection, add the following user-defined properties. Do not change
the property names.
Longitude
Latitude
String of 64 characters. In these properties, the app records the location
where the violation occurred, in millionths of a degree.
ViolationInfo
String of 1024 characters. The app stores a description of the violation in this
property, for example:
10
Date Time Violation Detector
Violation was detected because the device's clock
has been moved backwards. Client-side time: Mon Nov
15 2013 11:24:10 GMT-0500 (Eastern Standard Time)
MobileKey
String of 128 characters. An internal identifier that the ClickMobile client
assigns to new objects.
3.
Add one or more properties that identify the engineer who committed the
violation. The following properties are suggested:
EngineerName
String of 255 characters. The employee's name.
EngineerPhone
String of 64 characters. The employee's phone number.
EngineerApproverLoginID
String of 64 characters. The ClickMobile login name of the employee's
supervisor. You can use this property to alert the supervisor to a violation.
In the app settings, you can configure the app to copy the corresponding
Engineer properties into the PolicyViolation properties.
4.
Optionally, you can define additional properties such as:
Reason
String of 256 characters. On the ClickMobile PolicyViolation form,
you can display this property and enable the engineer or the supervisor to
enter a reason for a violation.
5.
Define an index on the MobileKey property of the PolicyViolation
collection.
6.
Optionally, configure a ClickSoftware Workspace search view that displays
PolicyViolation objects. This enables the dispatchers or supervisors to
review the violations conveniently. For instructions, see ClickSoftware
Workspace Views in the ClickPlatform Configuration Guide.
Step 2. Adding Engineer Property
The app uses a user-defined property to specify whether violation detection is
enabled for each engineer:
1.
In the Service Optimization Structure tool, add the following property to the
Engineer collection:
Date Time Violation Detector
11
DisableDateTimeViolation
Boolean. If false (default), the app detects violations for the engineer. If true,
the app ignores violations.
2.
Provide a means for dispatchers and supervisors to assign the
DisableDateTimeViolation property.
For example, add the property to the engineer form of ClickSoftware
Workspace. For instructions, see ClickSoftware Workspace Forms in the
ClickPlatform Configuration Guide.
Note: If desired, you can also add the property to the ClickMobile engineer
form of the supervisors. For instructions, see the ClickMobile Configuration
Guide.
Step 3. Configuring SXP Message
You must configure a custom SXP message that the app uses to retrieve the server
time.
1.
In the Service Optimization Administration tool, edit the following setting:
Central Settings/Integration & Services/Web Services
& SXP Messages
2.
Click the Add button.
3.
On the first wizard page, select Add New SXP Message.
4.
On the next page, enter the following options:
Name
SXPMobileGetServerTimeParameters
Type
W6.CM.DateTimeViolationCustomSXP.
W6CMDateTimeViolationGetServerTimeSXP,
W6.CM.DateTimeViolationCustomSXP
12
Date Time Violation Detector
5.
On the next page, select Enable Integration and click the Add button. Make no
other entries.
6.
On the next page, enter a comment such as SXP message for Date
Time Violation Detection app, and finish the wizard.
Step 4. Creating User Templates
You must create or edit the ClickMobile Touch user templates.
In the following discussion, we assume that you configure independent templates for
the supervisors and the employees. In the supervisor template, you can display the
PolicyViolation objects of the employees. In the employee template, you can
hide the PolicyViolation objects.
For each template, perform the following steps. For detailed instructions, see the
ClickMobile Configuration Guide.
1.
In the Mobility Studio, edit a ClickMobile Touch user template, or create a new
template.
2.
Verify that the template contains the following views:
- Schedule view
- Either My View or a business view of engineers (but not both)
3.
Click the Additional Properties button, and add the following properties:
Engineer.DisableDateTimeViolation
Date Time Violation Detector
13
Engineer.ApproverLoginID
4.
Click Apply to save your editing.
Step 5. Configuring the PolicyViolation Business View
Note:
This step is required only if you configure the app settings
Violation Report option (see Step 6. Configuring Loading Criteria
If you display the PolicyViolation view, configure loading
criteria for the PolicyViolation objects.
For example, the following criteria enable the supervisors to
view the violations of their employees. For detailed
instructions, see the ClickMobile Configuration Guide.
5. On the Home page of the Mobility Studio, click System
Settings > General Loading Criteria.
6. On the first wizard page, select the PolicyViolation object.
7. On the next page, select Using Groups.
8. On the left side of the next wizard page, right-click the
Users Group and add the following engineer criteria:
EngineerType equals 'Supervisor'
Engineer.LoginID equals Parameter 1
This example assumes that you use the EngineerType
property to identify supervisors, and that you have set the
ClickMobile login property to LoginID. Vary these criteria
as required in your system.
9. On the right side of the same page, right-click the
PolicyViolation group and add the following criterion:
EngineerApproverLoginID equals Parameter 1
14
Date Time Violation Detector
10. On the next wizard page, drag the items as illustrated.
This operation matches the Engineer.LoginID property
with the PolicyViolation.EngineerApproverLoginID
property. The effect is to load a PolicyViolation object if it
pertains to the supervisor's employees.
11. On the Time Criteria page, configure the time interval over
which to load the PolicyViolation objects.
For example, load the objects that were created during the
last seven days.
12. Click Next and finish the wizard.
If the supervisor template displays a business view of
engineers, you must also configure loading criteria for the
Engineer objects. This is not necessary if the supervisor
template displays My View.
Step 7. Configuring the App Event and Settings below). If you do
not plan to generate violation reports, you can omit this step.
To enable the ClickMobile client to report violations, you must configure a
PolicyViolation view and form. The view can be either visible or hidden:
Date Time Violation Detector

15
To enable the user to view and/or edit the violation reports, make the view
visible and the form read-write.
You might do this, for example, in the user template of the supervisors. In this
way, you can enable the supervisors to view the violations of their employees,
and to edit properties such as PolicyViolation.Reason.

To disable viewing or editing, you can hide the view, remove the Edit button
from the view, or make the form read-only.
To configure the view:
1.
In the Mobility Studio, edit the user template of the supervisors.
2.
From the toolbox, drag a Business View to the template. At the prompt, select
the PolicyViolation object.
3.
Configure the following attributes of the business view:
Title Description
The display title of each PolicyViolation. For example, you might set
the title to [EmployeeName] Clock Discrepancy.
Sort & Search
Select one or more search properties. Set an ascending or descending sort on
exactly one search property.
Visible
Select true to display the view, or false to hide the view.
If you display the view, also set the following attributes:
Short Description
The PolicyViolation description, displayed below the Title
Description.
Show Delete Button
Show New Button
Set these properties to false. This prevents the user from deleting violation
reports or creating reports manually.
Show Edit Button
If you display the view, consider setting this attribute to false. This prevents
the user from altering the violation reports.
4.
Click the Edit Form button. This displays the PolicyViolation form.
5.
Set the Mobile Key Property Name attribute to MobileKey.
16
Date Time Violation Detector
6.
If you display the view and you enable the Edit button of the view, drag
PolicyViolation properties to the form and configure their layout.
To make a property read-only, set its EnabledControl attribute to false. To
make the entire form read-only, select the form and set ReadOnlyForm to
true.
7.
Click Apply and close the form.
8.
Return to the user template and click Apply. This saves the view configuration.
9.
Click the Additional Properties button. Add all the PolicyViolation
properties, except the ones that you added to the form.
10. Repeat the preceding steps for the user template of the employees.
Step 6. Configuring Loading Criteria
If you display the PolicyViolation view, configure loading criteria for the
PolicyViolation objects.
For example, the following criteria enable the supervisors to view the violations of
their employees. For detailed instructions, see the ClickMobile Configuration Guide.
11. On the Home page of the Mobility Studio, click System Settings > General
Loading Criteria.
12. On the first wizard page, select the PolicyViolation object.
13. On the next page, select Using Groups.
14. On the left side of the next wizard page, right-click the Users Group and add
the following engineer criteria:
EngineerType equals 'Supervisor'
Engineer.LoginID equals Parameter 1
This example assumes that you use the EngineerType property to identify
supervisors, and that you have set the ClickMobile login property to LoginID.
Vary these criteria as required in your system.
15. On the right side of the same page, right-click the PolicyViolation group
and add the following criterion:
EngineerApproverLoginID equals Parameter 1
Date Time Violation Detector
17
16. On the next wizard page, drag the items as illustrated.
This operation matches the Engineer.LoginID property with the
PolicyViolation.EngineerApproverLoginID property. The effect
is to load a PolicyViolation object if it pertains to the supervisor's
employees.
17. On the Time Criteria page, configure the time interval over which to load the
PolicyViolation objects.
For example, load the objects that were created during the last seven days.
18. Click Next and finish the wizard.
If the supervisor template displays a business view of engineers, you must also
configure loading criteria for the Engineer objects. This is not necessary if the
supervisor template displays My View.
Step 7. Configuring the App Event and Settings
You must add an event component to the ClickMobile user templates, and you must
configure its settings.
1.
In the Mobility Studio, edit the employee user template.
2.
From the toolbox, drag an Event to the miscellaneous pane, under the client
display.
3.
Configure the following attributes of the Event.
Name
Enter a name such as Date Time Violation Event.
18
Date Time Violation Detector
App ID
Enter the file name
W6.CM.Web.CheckForDateTimeViolation.js. Enter the class
name W6.CM.Web.CheckForDateTimeViolation.
CheckForDateTimeViolation.
App Admin ID
Enter the file name W6.CM.DateTimeValidationAdmin.dll. Enter
the class name W6CMDateTimeValidationAdmin.
4.
Click Apply.
5.
Edit the App Admin Settings attribute, and configure the options as described
in the following paragraphs.
6.
Click Apply and close the template.
7.
If you want to enable clock discrepancy detection on the supervisors' mobile
devices, repeat steps 1-6 for the supervisor user template.
The app is now activated. It runs on the mobile devices, detecting date-time
violations if they occur. The users do not need to perform any operation to
launch the app.
Client Time Settings Tab of the App Admin Settings
On this tab, configure how often the app retrieves the server time.
Compare device time with server time every ___ minutes
Set a frequency such as 60 minutes.
Disregard comparison responses older than ___ minutes
Set a timeout of several hours. To prevent false violation detections, the client
ignores server times that are older than this timeout.
Allow time difference between device and server of up to ___ minutes
There might be discrepancies between the server time and the mobile device
because of slow network transmission or because the clock settings are
imprecise. To prevent false violation detections, allow a reasonable discrepancy
such as 5 minutes.
Compare device time with server time if ClickMobile was not in use for longer than
___ minutes
Set a timeout such as 60 minutes. If ClickMobile was closed or in the
background for longer than this period, and then the user returns to
ClickMobile, the app retrieves the server time.
Date Time Violation Detector
Note:
19
If the users usually work online, you can set relatively short times in the
above options. If the users work offline for extended periods, you might
need to increase the values because the client-server connection is often
unavailable.
Daylight Saving Tab of the App Admin Settings
The server and device clocks might be out of sync during a Daylight Saving Time
transition. If this problem might occur in your system, disable violation detection on
the dates when Daylight Saving Time switches to Standard Time, and vice versa.
20
Date Time Violation Detector
Violation Report Tab of the App Admin Settings
On this tab, you can enable violation reports:
When a violation happens, submit the following details automatically to the back
end system
If selected, the app creates a PolicyViolation object for each violation,
and it sends the object to the server.
From property ... To property
Select properties of the Engineer object. The app copies them to the
indicated properties of the PolicyViolation object.
For example, you can map:
- Engineer.Name to PolicyViolation.EngineerName
- Engineer.MobilePhone to PolicyViolation.EngineerPhone
By default, the app copies Engineer.ApproverLoginID to
PolicyViolation.ApproverLoginID. You do not have to map these
properties explicitly.
Date Time Violation Detector
21
Violation Handling Tab of the App Admin Settings
On this tab, configure the ClickMobile client behavior when the app detects a
violation:
Block the assignment updates when a violation was detected
If selected, the app prevents the user from saving the assignment form. The user
can open the form and view an assignment, but ClickMobile ignores any
editing that the user performs in the form, until the user corrects the clock
discrepancy and refreshes ClickMobile.
Close the assignment form when violation is detected
If selected, the app immediately closes the assignment form without saving.
The user cannot view, edit, or save the assignment form, until the user corrects
the clock discrepancy and refreshes ClickMobile.
Show the following warning message to the user when a violation was detected
If selected, the app displays a message to the user about the violation. Enter the
message text.
22
Date Time Violation Detector
Comments
The ClickMobile appearance is configurable. The layout might differ on your
device.