Notifications: Configuration
for
Version 15.8
Part Number E65798-01
Oracle, 2015
Table of Contents
1 Introduction...............................................................................................................5
1.1 Document Purpose and Scope...............................................................................5
1.2 Target Audience...................................................................................................5
1.3 Glossary.............................................................................................................5
2 General Overview.......................................................................................................7
2.1 Notification-Specific Terminology............................................................................8
2.2 Notification Workflow..........................................................................................10
3 Creating a Scenario...................................................................................................12
3.1 Defining General Scenario Information..................................................................12
3.2 Editing General Scenario Information....................................................................14
3.3 Filling Scenario with Steps...................................................................................16
3.3.1 'Add notification scenario step' Window..........................................................16
3.3.2 'Settings' Tab..............................................................................................16
3.3.2.1 Number of Attempts on 'Sent' and 'Failed' Statuses...................................20
3.3.3 'Patterns' Tab..............................................................................................20
3.3.4 'Events' Tab................................................................................................24
3.3.5 'Conditions' Tab ..........................................................................................25
3.3.5.1 Message Sending Interval......................................................................29
4 Triggers...................................................................................................................31
4.1 'Day Before' Trigger............................................................................................32
4.2 'Reminder' and 'Change' Notification Triggers.........................................................32
4.3 Triggers Related to Route and Activity Actions........................................................35
4.4 Escalation Message Triggers................................................................................37
4.5 'Manual' Trigger.................................................................................................39
4.6 'Call Ahead' Trigger............................................................................................40
4.7 External Trigger.................................................................................................40
4.8 Inventory-Related Triggers..................................................................................40
4.9 Visit-Related Triggers..........................................................................................42
5 Notification Methods .................................................................................................44
6 'Set property' Method................................................................................................44
6.1 Actions.............................................................................................................46
6.1.1 'cancel_activity' ..........................................................................................46
6.1.2 'unschedule_activity' ...................................................................................47
7 Setting Properties Based on Message Status Received from Agent..................................48
8 Message Removal Cases ...........................................................................................50
9 Message Content......................................................................................................52
9.1 Placeholders......................................................................................................52
9.2 Blocks...............................................................................................................58
9.2.1 Block Examples...........................................................................................59
9.3 Formatting........................................................................................................62
9.3.1 Date and Time Formatting............................................................................62
9.4 Encoding Placeholder Values................................................................................64
9.5 Suppressing of Unassigned Variables Printing........................................................64
10 Blocking Conditions.................................................................................................65
11 PAS: Submitting Survey Results ...............................................................................73
Appendix: Message Examples........................................................................................75
Inventory Blocks......................................................................................................75
Message Examples....................................................................................................75
Notification Module Description
Copyright © 2015 Oracle Corporation. All rights reserved.
Oracle Field Service Cloud is a registered trademark of Oracle Corporation.
This software and related documentation are provided under a license agreement containing restrictions on use and
disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or
allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit,
perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or
decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find
any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of
the U.S. Government, the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including
any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered
to U.S. Government end users are “commercial computer software” pursuant to the applicable Federal Acquisition
Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on the
hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.
No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications that may create a risk of
personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take
all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its
affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their
respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro
Devices. UNIX is a registered trademark of The Open Group. This software or hardware and documentation may
provide access to or information on content, products, and services from third parties. Oracle Corporation and its
affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content,
products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages
incurred due to your access to or use of third-party content, products, or services.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc .
Access to Oracle Support: Oracle customers have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Page 4 of 79
Confidential || Oracle
Introduction
1
Notification Module Description
Introduction
1.1 Document Purpose and Scope
This document is intended to give a general understanding of the Notification Functionality, implemented
in Oracle Field Service Cloud (hereinafter – OFSC), and to describe the basics of its operation and
configuration.
The document provides an overview of the messaging mechanism and scenarios, including the scenario
creation process, triggers to be used to invoke scenarios, blocking conditions to stop the message
generation, formatting and message content-related issues.
1.2 Target Audience
This document is intended for practicing OFSC users as well as professionals who support integration of
OFSC with external client company systems and messaging applications.
It is assumed that the reader is familiar with the basics of OFSC functionality.
1.3 Glossary
Below is the list of terms and concepts that may be mentioned in the document and will provide a better
understanding of the functionality. Please note: The reader, hereinafter, may be addressed as "you".
Term
Description
Activity
Any time-consuming work performed by a resource
API
Application Programming Interface – a particular set of rules and specifications
that software programs follow to communicate and interact with each other
Entity appearing on the resource tree which can contain resources of a defined
Bucket
type and be assigned activities
Capacity
Workforce possessing the necessary work skills available at a certain moment of
time
Capacity bucket
Bucket used for Quota management
Capacity category
Predefined set of work skills, work skill groups and time slots within which they are
considered by the Capacity API
Context
OFSC or API screen showing all available properties and action links
Daily Extract
Functionality used to extract data from OFSC for further analysis and reporting
(previously referred to as DWH)
Delivery window
Statistically calculated time period in which a resource is expected to start an
activity
Dynamic Routing
Routing option allowing to assign only a predefined number of activities to
resources and/or assign activities only for a predefined period of time
Confidential || Oracle
Page 5 of 79
Notification Module Description
Glossary
Term
Description
ETA
Estimated time of arrival. Predicted time at which a resource will arrive at an
appointment and start an activity, calculated dynamically for current and historical
data
Field
Property present in the system by default
Forecasting
Oracle Field Service Forecasting Cloud Service. Feature of OFSC allowing to
forecast the company workload on the basis of historical data
Geocoding
Process of finding geographic coordinates from street addresses or postal codes
Group
Feature on the resource tree identifying a particular type of resource
GUI
Graphical User Interface, allows to use software by manipulating images rather
than by issuing text commands
Historical data
Data of the past periods available in the database or from other sources
Inventory
Equipment that can be installed or deinstalled during an activity
Linked activities
Two separate activities related so that the completion or start of one is dependent
on the completion or start of the other
Manage
Oracle Field Service Core Manage Cloud Service (former Manage Application).
Serves as the command center for field operations and the central hub for viewing
real-time information about resources and their activities across the entire field
organization
Mass activity
Activity involving 2 or more resources
Message
Communications within software (which may or may not be readable by humans),
(Notification)
as well as person-to-person communications delivered via computer software
Mobility
Oracle Field Service Mobility Cloud Service (former Mobility Application). A webbased application for mobile resources to execute and manage work-related
activities and ongoing communications
Not scheduled
Activity not assigned to a specific date
Not ordered
Activity with an unspecified order of execution in a route, so that it can be
executed at any time during the working day. Not-ordered activities do not have
defined ETAs or delivery windows
Ordered
Activity with a defined place in a route, which must be performed at a specified
time of day. The order of activities can be changed; ordered activities can be
changed to not-ordered activities and vice-versa
PCC
Predictive Customer Communications. Notification solution of OFSC used to
proactively communicate with the customer in relation to activities. PCC includes
such features as day before notifications, change, reminder and post appointment
survey calls. It is the part of the Oracle Field Service Customer Communication
Cloud Service.
Penalty
Relative scale representing the expected increase of total cost which a particular
factor brings into routing result
Planning
Page 6 of 79
Company's estimation of the workforce or workload required at a certain moment
Confidential || Oracle
Glossary
Term
Notification Module Description
Description
Preassigned activity Activity which was assigned to a specific resource before the routing run
Property
Field and field value, assigned to an entity in OFSC (to user, resource, activity or
inventory). There are fields and custom properties
Quota
Amount of work that can be accepted for the bucket
Repeating activity
Activity recurring with a predefined frequency in a predefined period
Resource
Element in the resource tree representing a defined company asset
Resource Tree
Hierarchy of company resources, showing “parent-child” relationships
Route
List of activities assigned to a resource for a specific date, or a list of nonscheduled activities assigned to a resource
Routing
Process of assigning activities to resources (usually automated)
Service Window
Time frame expected by the customer for an activity as scheduled by the company
SLA window
Interval of time (that may involve a range of dates) within which certain work has
to be performed according to the Service Level Agreement
Teamwork
Feature that allows resources to assist each other in an activity or on an on-going
basis
Time Slot
1) Fixed service window, defined with a name and label, specifying when certain
types of activities can be performed
2) Service Window (if the activity type does not support time slots)
User
1) Person using OFSC
2) Entity used for authentication and authorization, allowing people or external
software to access OFSC
Work Skill
1) Activity that a resource is qualified to perform (resource property)
2) Qualification required to perform an activity (activity property)
Work Zone
2
Defined geographical area in which a resource can perform an activity
General Overview
OFSC supports generation and sending of messages with the help of the Notification Functionality.
Using the activity information as the basis, OFSC employs triggers, scenarios, blocking conditions
to generate messages that can be delivered to company's customers, resources, administrators, etc., as
well as to external systems and internal properties.
OFSC messaging mechanism is a highly configurable engine that can initiate sending of different types of
messages on different events and situations that occur in the OFSC system.
Basic list of notification-specific terms along with a brief description of the notification workflow is
presented below to give an overall understanding of the Notification Functionality.
Confidential || Oracle
Page 7 of 79
Notification Module Description
Notification-Specific Terminology
2.1 Notification-Specific Terminology
Term
Description
Notification
Process of delivering a message to one or many recipients
Message Agent
Standalone application intended for processing messages initiated by
OFSC
Message Engine
Part of the application server that generates and processes messages
Message Trigger
Event or condition in the system, which when occurs, triggers a message
scenario
Message Scenario
Branching event-driven algorithm that consists of one or more steps. A
step corresponds to one message and defines when and how this
message should be generated, and when and how it should be sent to a
message agent
Scenario Event
Set of rules used to generate further steps following the completion of the
current scenario step
Start Step
Initial step of a message scenario that is actually invoked by the relevant
message trigger upon a certain predefined action or situation in OFSC
(there can be more than one start step)
All start steps are performed at the beginning of a message scenario and
there should be at least one start step in every message scenario.
Inner Step
Step of the scenario that is invoked after the message generated at the
previous start or inner step is deleted from the message queue (i.e. after
the previous step message receives its final status)
Message Status
Dynamic message property that defines its state in terms of sending. The
following message statuses are possible:
•
'New' status is set in the Message Engine for a successfully
created message that is not yet being sent to the message agent
•
'Falsemethod' status is set by the Message Engine if a message
cannot be created due to invalid configuration or missing data
•
'Obsolete' status is set by the Message Engine if a message is
invalidated as the result of an activity-related operation in OFSC
(delete, move, suspend, etc.) or another message creation
•
'Sending' status is set by the message engine when a message is
being sent to and initially processed by a message agent
•
'Sent' status is returned by a message agent when there is no
confirmation that the final recipient (person or system) has
received the message, e.g. it is commonly used when the
message was received by an answering machine)
•
'Delivered' status is returned by a message agent if a message
has been delivered successfully and the final recipient (person or
system) has received the message
Page 8 of 79
Confidential || Oracle
Notification-Specific Terminology
Term
Notification Module Description
Description
Note: As there is no way to check that an email has been read by
the customer, the 'Delivered' status is not usually set for email,
though it is subject to the agent and client-specific rules.
•
'Failed' status is returned by the message agent if a message
cannot be delivered
Final Message Status
Message status that requires no further processing. The following possible
final statuses may apply: 'Falsemethod', 'Obsolete', 'Sent', 'Delivered' and
'Failed'
Note: Messages with the 'Sent' or 'Failed' status can be returned to the
'Sending' status and sent again (this is an adjustable predefined option).
These statuses are only considered final after all applicable attempts and
retries (if any) have taken place.
Message Description
Customer specific message details that along with the message status can
influence the message scenario flow. For example, the 'Failed' message
status can invoke different scenario steps with the 'no_answer' and
'hang_up' descriptions
Message Queue
Pool of messages for which the final status is not set. When the final
status is set, its information is processed by the Message Engine and the
message is deleted from the queue and saved in the message log. All
messages, regardless of their status, are displayed in the 'Messages' tab
of the 'Activity details' and in the 'Messages Report' screen. The messages
that obtained their final status are exported to the Daily Extract
Message Blocking Conditions Message blocking conditions can be defined for a scenario step, and, if
such conditions are met, the relevant message is blocked. In this case the
message is either generated with a final status or not generated at all
Confidential || Oracle
Page 9 of 79
Notification Module Description
Notification Workflow
2.2 Notification Workflow
Below is the Notification workflow diagram (Figure 1) and its brief description.
Figure 1: Notification workflow
•
OFSC provides a set of APIs to receive data from different sources, agents and external systems
like CRM, Inventory Management and Human Capital Management systems.
•
If, as the result of the received data, a certain condition is met, relevant trigger is activated.
•
The trigger invokes a start step/s of a message scenario in the Message Engine.
•
At the end of every message scenario step a message is generated and saved in the message
queue.
•
Each message is processed and eventually receives the final status.
•
If a blocking condition is met, the message is not generated or generated but not sent, and its
final status is set.
•
In addition to the start steps there can be inner steps included in the message scenario. An inner
step is invoked in accordance with a final status of the message received as the result of the
previous step processing.
•
Upon fulfillment of the predefined conditions, the message from the queue is sent to the
corresponding message agent via the Outbound API.
•
The scenario is completed as soon as there are no more further steps to be executed.
Page 10 of 79
Confidential || Oracle
Notification Workflow
Notification Module Description
The example of a possible scenario flow is illustrated below (Figure 2):
Figure 2: Notification scenario flow
Confidential || Oracle
Page 11 of 79
Notification Module Description
3
Creating a Scenario
Creating a Scenario
A message scenario can be set up by either creating a new scenario or modifying an existing one. In both
cases the following steps are to be performed:
1. The general scenario information is to be filled in or modified
2. The defined scenario is to be filled with steps.
3.1 Defining General Scenario Information
To create a message scenario open the 'Message
Scenario' screen ('Company Settings' → 'Message
Scenarios') and click 'Add new' (Figure 3).
Figure 3: 'Add new' button
The 'Add notification scenario' window will appear
(Figure 4).
Fill in the fields with the scenario information:
•
'Scenario Name' field – the name of the
scenario
•
'Scenario Label' field – a unique scenario
identifier
•
'Scenario From' field – the date of the
scenario start (selected from the drop-down
calendar)
•
'Scenario To' field and checkbox – the date
of the scenario end (selected from the dropdown calendar) if the checkbox is not
checked and no date is selected, the
scenario will run indefinitely
Page 12 of 79
Figure 4: 'Add notification scenario' screen
Confidential || Oracle
Defining General Scenario Information
Notification Module Description
For example, a scenario can be created with the
following parameters (Figure 5):
'Scenario's Name' – 'Example'
'Scenario's Label' – 'Ex'
'Scenario's From' – 04/07/13
'Scenario's To' – 04/14/13
Clicking 'Add' creates the new scenario.
Figure 5: Example of a Notification Scenario
The scenario will appear in the 'Message Scenarios' screen.
Confidential || Oracle
Page 13 of 79
Notification Module Description
Editing General Scenario Information
3.2 Editing General Scenario Information
In order to edit an existing scenario go to 'Company Settings' → 'Message Scenarios' (Figure 6).
Figure 6: 'Message Scenarios' screen
If there are many scenarios on the list you can use the 'View' button to find the scenario that has to be
modified.
The filters window will appear containing the 'Find' field
where the scenario name can be entered, and the number
of rows the 'Message Scenario' screen is to contain. The
'Rows' field is mandatory. The default number of rows is
'20' (Figure 7).
Figure 7: The filters window
Enter the scenario name in the 'Find' field and click
'Apply' (Figure 8).
Figure 8: Scenario search
Page 14 of 79
Confidential || Oracle
Editing General Scenario Information
Notification Module Description
Those scenarios that match the search key will be shown in the 'Message Scenarios' screen (Figure 9).
Figure 9: 'Message Scenarios' screen filtered
An existing scenario data can be modified using
the 'Modify' link in the 'Actions' column (Figure 10).
Figure 10: 'Modify' link
The 'Edit notification scenario' window similar to
the 'Add notification scenario' window will appear
(Figure 11).
Figure 11: 'Edit notification scenario' window
Confidential || Oracle
Page 15 of 79
Notification Module Description
Filling Scenario with Steps
3.3 Filling Scenario with Steps
Each scenario consists of one or more start steps
and can contain several inner steps.
In order to fill the newly created scenario with
steps or edit the steps, click the 'Steps' link in the
Figure 12: 'Steps' link
'Actions' column (Figure 12).
The 'Scenarios Steps > '[Scenario name]' screen
will appear (Figure 13).
Figure 13: Scenario steps screen
If no steps have been added to the scenario, the 'There are no steps for this scenario in the system'
message will be shown (Figure 14).
Figure 14: Notification scenario with no steps
If this is the case, click the 'Add new' button for the 'Add notification scenario step' window to open.
3.3.1 'Add notification scenario step' Window
The 'Add notification scenario step' window includes four tabs which contain the settings related to
message generation, namely:
•
'Settings' tab contains the basic parameters of the message generated at a certain scenario
step, i.e. how, when and where it should be sent
•
'Patterns' tab defines the content of the message to be sent
•
'Events' tab defines the conditions of the subsequent steps execution
•
'Conditions' tab sets the blocking conditions, i.e. the conditions under which the message should
not be generated at this step
3.3.2 'Settings' Tab
The 'Settings' tab contains the basic parameters of the message generated at the current message
scenario step, i.e. how, when and where it should be sent (Figure 15).
Page 16 of 79
Confidential || Oracle
'Settings' Tab
Notification Module Description
Figure 15: 'Settings' tab of 'Add notification scenario step' window
Below is the list and a brief description of the fields included in the 'Settings' tab:
Field name
Description
Possible values
Name
The name of the step
Name of the step (up to 64 characters)
Type
The type of the step
Start, Inner
Recipient
The addressee of the message
Customer, Dispatcher, Resource,
use static address
Notification
Method
The message sending method
Send at
The time when the message is
to be sent
day of event – the day of the event triggering
the scenario step
time of event – the time of the event triggering
the scenario step
day of route – the day of the resource's route
All options can be set a number of days before or
after the corresponding event (+/-).
from
The time when the scenario step
can start
Not applicable when the 'time of
event' is selected as the 'Send
at' value
(00:00 – 23:59) or (12:00AM – 11:59PM)
depending on the user time format settings
within
The time range during which the
message can be delivered (in
hours and minutes)
00:01 – 99:59
Note: the methods used are
company-specific. They
correspond to the list of
Notification Methods configured
for the company.
Email: used for sending email messages
External System: used to customize outgoing
interfaces that transfer information from OFSC to
the back-office system
Set Property: used to set new values for
properties within OFSC
External Trigger: created as the result of an
incoming IVR request initiated by the customer
Confidential || Oracle
Page 17 of 79
Notification Module Description
'Settings' Tab
Field name
Description
Possible values
Delay sending
by
Time period between message
creation and sending (in
minutes)
0-999
Block
messages for
specific days
The checkboxes define days of
the week when the messages
should not be sent.
This parameter is intended to be
used for PCC messages.
checked: messages will not be sent on the
selected day(s) of the week
not checked: messages will be sent on such
day(s) of the week
Block
messages for
holidays
The checkbox defines if the
messages can be sent on
company-specific holidays. This
parameter is intended to be
used for PCC messages.
checked: messages will not be sent on holidays
not checked: messages will be sent on holidays
Note: the list of holidays can be
configured in
'Company Settings' → 'Holidays'.
Shift blocked
messages up
to [..] days
earlier
The number of days to shift the
messages back in the calendar,
if such messages are assigned
for a day of the week/holiday for
which the block is set.
This parameter is intended to be
used for PCC messages.
0-10
Note: if a message cannot be
sent because it falls on a nonworking day or a holiday and
cannot be shifted to a working
day, it will be blocked with the
'falsemethod' status and the
'NONWORKING_DAY'
description.
Number of
attempts on
'failed' status
The maximum number of resend attempts (including initial)
if the notification status returned
is 'Failed'
numerical non-zero value without special
characters (1-999)
Not applicable for 'Set property'
and 'External Trigger'
notification methods
For further details, please, refer
to the 'Number of Attempts on
'Sent' and 'Failed' Statuses'
section.
Page 18 of 79
Confidential || Oracle
'Settings' Tab
Notification Module Description
Field name
Description
Possible values
Number of
attempts on
'sent' status
The maximum number of resend attempts (including initial)
if the notification status returned
is 'Sent'
numerical non-zero value without special
characters (1-999)
Not applicable for the 'Email',
'Set property' and 'External
Trigger' notification methods
For further details, please, refer
to the'"Number of Attempts on
'Sent' and 'Failed' Statuses'
section
Interval [...]
min
The time interval between the
re-send attempts
numerical non-zero value without special
characters (1-999) that must be specified if the
'Number of attempts on 'Failed' and/or 'Sent'
status is greater than '1'
Customer
notification
time
The time range which is to be
communicated to the customer
Service Window, Delivery Window, ETA
If a message final status is
'Sent' or 'Delivered', the
'Customer notification time' is
stored in the 'time delivered
start/end' activity fields
Applicable only for the
'Customer' recipient
Time Zone
The time zone to be used
any time zone applicable to the company
Applicable only for the 'use
static address' recipient used
with the 'External System',
'Email', and 'Set property'
notification methods
Language
The language to be used
Applicable only for the 'use
static address' recipient used
with the 'External System',
'Email', or 'Set Property'
notification methods
Static address
The static address to be used
a company-specific language chosen from the
drop-down list
any valid email address
Applicable only for the 'use
static address' recipient used
with the 'Email' notification
method
Reply address
The email address to send the
reply to
any valid email address
Applicable only for the 'Email'
notification method
Confidential || Oracle
Page 19 of 79
Notification Module Description
Field name
Description
Email address
source
The field containing the email
address to be used in the 'Email'
notification method
'Settings' Tab
Possible values
any field to be selected from the drop-down list of
the email address sources available in the system
Not applicable for the 'use static
address' recipient
Survey
3.3.2.1
The field containing the survey
to be used
a company-specific survey chosen from the dropdown list
Applicable only for the 'External
system' notification method
For further details on survey configuration refer to
the 'PAS: Submitting Survey Results' section
Number of Attempts on 'Sent' and 'Failed' Statuses
Attempts on 'Failed' status
This functionality is available for all messages except 'Set property' and 'External trigger'.
The 'Failed' attempts are ignored if:
•
Further processing of this scenario is stopped (for more information, refer to the 'Message
Removal Cases')
•
The next attempt cannot be scheduled prior to expiration of the message.
•
It is not reasonable to make further attempts. For example, if email address is invalid.
Note: an agent can also stop further 'Failed' attempts or change their number using the 'fault_attempt'
and 'stop_further_attempts' fields in a 'send_message' response or a 'set_message_status' request.
Attempts on 'Sent' status
This functionality is only available for the 'External system' messages.
The 'Sent' attempts are ignored if:
•
further processing of this scenario is stopped (for more information refer to the 'Message Removal
Cases' section)
•
the next attempt cannot be scheduled prior to expiration of the message.
3.3.3 'Patterns' Tab
The 'Patterns' tab defines the content of the message sent, i.e. sets the message pattern to be used
according to the notification method chosen. In general, for every pattern there is a subject and body.
Some patterns can be defined for several languages, though 'English' message patterns are the default
ones, and they are used if the message step provides no pattern in the client's language .
Following are the examples of the message patterns for different notification methods (Figures 16-18,
20):
•
Email Notification Pattern
Page 20 of 79
Confidential || Oracle
'Patterns' Tab
Notification Module Description
Figure 16: Email notification pattern example
When the step is performed, an email with the subject and body set above will be sent, where the
placeholders (inside the brackets) will be replaced with the actual values.
•
External System Notification Pattern
In the example, the message body that will be sent upon the step execution is represented in XML
(Figure 17).
Figure 17: External System notification pattern example
•
Set Property Notification Pattern
Confidential || Oracle
Page 21 of 79
Notification Module Description
'Patterns' Tab
Figure 18: Set Property notification pattern example
As the result of this step (Figure 18), the 'CANCEL_REASON' property will get the value with index '14' –
'CUSTOMER REQUEST', as is defined in the property settings.
Note: values of the properties should be defined in an internal format. In particular, 'property_label'
should be used to define the subject value.
For enumeration properties the 'index' value should be used in a message body (rather than translation).
To see the translations for enumeration property values, go to 'Properties' → 'Modify' (Figure 19).
Figure 19: Value settings for enumeration properties
•
External Trigger Notification Pattern
In the example below, the body defines the activity information to be passed to an external application
(Figure 20).
Page 22 of 79
Confidential || Oracle
'Patterns' Tab
Notification Module Description
Figure 20: External Trigger notification pattern example
In addition to defining the content of the message in the 'Patterns' tab, there is an ability to define when
the message content is to be generated.
There are the following two options:
•
Generate content on message creation
•
Generate content on message sending
(Figure 21).
Figure 21: Selecting time for content generation
The "immediate" generation of content is mainly intended for messages related to synchronization of
activity statuses and assignments. In some cases, if multiple operations related to the same activity are
performed within a short period of time, it is necessary to generate a separate message for each of the
performed operations. A particular message should contain activity details at the moment of its creation.
For example, if several sequential move operations are performed, it might be necessary to include
correct 'from' and 'to' values into all intermediate messages.
The second option is preferable for messages that are generated in advance. This option is used for the
'Day before' and other customer-related notifications.
Confidential || Oracle
Page 23 of 79
Notification Module Description
'Events' Tab
3.3.4 'Events' Tab
The 'Events' tab is used to define the next steps to be invoked upon the specified final status and/or
description of the message (Figure 22).
Figure 22: 'Events' tab
The 'Events' tab contains the following fields:
'Status' – the drop-down list of available statuses; includes all final statuses of the message, i.e. 'Sent',
'Delivered', 'False Method' or 'Failed'
'Description' – any client-specific description (e.g. 'Confirmed')
'Next step' – the step to be invoked if the specified conditions are met.
When the conditions are defined, they can be added by clicking the 'Add' button. The 'Change' and
'Delete' buttons can be used to manage the added conditions.
For example, if the message gets the 'Sent' status,
the next message step will be Step 3 (Figure 23).
Figure 23: Scenario event creation - no description set
Page 24 of 79
Confidential || Oracle
'Events' Tab
Notification Module Description
Or, if the message gets the 'Sent' status and the
description is empty, the next message step will be
Step 4 (Figure 24).
Figure 24: Scenario event creation - empty description
Or, if the message gets the 'Sent' status and the
description is the 'answering machine', the next
step will be Step 2 (Figure 25).
Figure 25: Scenario event creation - description added
To add an event, click 'Add' and the event will
appear in the area on the right (Figure 26).
Figure 26: Adding a scenario event
To change or delete an event, select it from the list
on the right, and then click the 'Edit' or the 'Delete'
button, respectively (Figure 27).
Figure 27: Changing or deleting an event
3.3.5 'Conditions' Tab
The 'Conditions' tab is used to define the set of blocking conditions under which the message should not
be sent (Figure 28).
Confidential || Oracle
Page 25 of 79
Notification Module Description
'Conditions' Tab
Figure 28: 'Conditions' tab
The fields defining the conditions are described as follows:
Field name
Description
Example
Field
The value of the property selected from
the drop-down list will be used as the
blocking condition (Figure 29).
The drop-down list includes of all
available properties related to activity,
resource, inventory, service request,
route, visit, user, shifts and calendars.
Also, there are several 'other' fields
available (interface, day of week, etc.)
that can be used for blocking condition
logic.
Note: in order to see the complete list
of available system blocking conditions,
refer to the 'Blocking Conditions'
section.
Page 26 of 79
Confidential || Oracle
Figure 29: 'Field' drop-down list
'Conditions' Tab
Notification Module Description
Field name
Description
Example
Condition
The drop-down list of comparison
functions to be fulfilled for the 'Field'
property (Figure 30):
'in' – value of 'Field' is any value from
those listed in the 'Value' field
'not in' – value of 'Field' is any value
except those listed in the 'Value' field
'is null' – value of 'Field' is empty or
undefined
'is not null' – value of 'Field' is not
Figure 30: 'Condition' drop-down list
empty
'Does not contain' – the property
does not contain the specified value;
should not be used for enumerated
properties
'Contains' – the property contains the
specified value; should not be used for
enumerated properties
(>, >=, < and <=) – used to compare
the property values. These operators
are applicable to integer, string,
enumeration properties and the
date/time fields.
Value
The value for 'not in', 'in', 'Does not
contain', 'Contains', >, >=, < and <=
functions (Figure 31).
One or more values can be entered
separated by the ',' character. However,
for the >, >=, < and <= functions only
one value can be entered. CSV format
is supported.
Figure 31: 'Value' field
Confidential || Oracle
Page 27 of 79
Notification Module Description
Field name
Description
Result
Sets the message final status that
'Conditions' Tab
Example
should be set for this message when the
defined conditions are met (Figure 32).
This way, even though the message
creation is blocked, its final status can
be processed further in the scenario.
If no 'Result' is selected, the message is
not created at all.
Figure 32: 'Results' drop-down list
Description
Sets the message Description (Figure
33).
This way, even though the message
creation is blocked, its description can
be processed further in the scenario.
The 'Description' field becomes active
only after the 'Result' value is selected.
Figure 33: 'Description' field
Check on
Defines the time when the system
message
should check the blocking conditions of
creation/
a message (Figure 34).
sending/
'On creation' – the conditions are
creation and
checked at time of the message
sending
generation and not checked again.
'On sending' – the message is
generated and stored in the message
queue. The blocking conditions are
checked at time of the message sending
which allows the system to account for
any changes since the message
Figure 34: Selecting the time for blocking conditions check
generation.
'On creation and sending' – the blocking
conditions are checked at time of both
message creation and sending.
Page 28 of 79
Confidential || Oracle
'Conditions' Tab
Notification Module Description
For example, if the customer with the phone
number [12345] never wants to receive any
messages and has confirmed the appointment in
any other manner, the blocking condition can be
set as shown (Figure 35). Therefore, if the
'Phone' property contains the value '12345', the
message will not be sent, its final status will be
set as 'Obsolete' with the 'Confirmed' description.
Figure 35: Blocking condition example
When the condition is defined it should be added to
the list of conditions by clicking 'Add' (Figure 36).
Figure 36: Adding a condition to list
After clicking the 'Add' button, the new blocking
condition appears in the list of conditions (Figure
37).
Figure 37: Blocking condition added to list
The conditions selected from the list can be edited,
moved up and down the list, or deleted by means
of the corresponding buttons (Figure 38).
The system processes condition rules one by one
downwards, and the checking stops after the first
Figure 38: Condition editing buttons
blocking condition is met. Thus, the order of the
conditions may change the message sending logic.
Note: for those scenarios containing steps, the screen will display the list of steps. Clicking the 'Modify'
link, the 'Modify notification scenario step' screen similar to the 'Add notification scenario step' screen,
described above, will appear.
3.3.5.1
Message Sending Interval
Each message has its own time interval within which it should be sent. The corresponding time
boundaries are called 'Send from' and 'Send to'. They are displayed as the 'Time range of notification' in
'Activity details' → 'Messages' tab →'[Activity name] - Message Content' (Figure 39).
Confidential || Oracle
Page 29 of 79
Notification Module Description
'Conditions' Tab
Figure 39: Message sending interval
The interval is initially determined on message creation and is automatically adjusted when the recipient's
time zone is changed. Also, the 'Send from' value can be updated for a message that supports multiple
'Failed' or 'Sent' attempts. In this case, if the current attempt is 'Failed' (or 'Sent'), the 'Send from' is set
to the time when the next attempt should performed.
The 'Send from' value is calculated using the following algorithm:
1. Determine the start time of the message sending interval without day shift (in the time zone of
the recipient). One of the three options apply depending on the value selected (Figure 40):
Figure 40: Start time of message sending interval
•
Time of event: the current time in the recipient's time zone
•
Day of event: the current date in time zone of recipient + the 'from' value
•
Day of route: the route date + the 'from' value
2. Apply day shift for the message (if needed)
•
Get a date part of the value determined at the previous step
•
Add day shift, which is the number of days before or after the corresponding event
(Figure 41)
•
Apply 'Block messages for specific days', 'Block messages for holidays', and 'Shift blocked
messages' rules
Page 30 of 79
Confidential || Oracle
'Conditions' Tab
Notification Module Description
Figure 41: Day shift for message sending
Note: the 'Delay sending by' parameter is not involved in the 'Send from' calculation. It is checked on
message sending.
The 'Send to' value is calculated using the following formula:
•
'Send to' = 'Send from' + the 'within' value
The 'New' messages are checked against the 'Send to' constraint. If the message has not been processed
in time, the server updates it with the 'Failed' status and the 'MESSAGE_STEP_EXPIRED' description.
The system also checks the 'Send to' value for messages with the 'Sending' status. Maximum time to
keep expired ('Send to' <= current time) messages in the 'Sending' state is 60 minutes. If the delay time
has elapsed for a message, it is removed with the 'Failed' status and the 'MESSAGE_STEP_EXPIRED'
description.
Also, the same 'Send to' logic is implemented in all notification methods. It is especially necessary for the
messages that might remain in the 'Sending' state for a long time (e.g. customer notifications that
require message delivery confirmation).
4
Triggers
Start step of a scenario is invoked with a trigger. All triggers in OFSC can be divided into two categories:
action-driven and condition-driven triggers.
Action-driven triggers invoke a scenario as soon as the triggering action occurs in OFSC.
The OFSC system is periodically polled, and, as soon as the poll result shows that certain conditions are
fulfilled, the condition-driven triggers invoke a scenario. The triggers available in OFSC can be viewed
and/or configured in 'Company Settings' → 'Notification Triggers' (Figure 42).
Confidential || Oracle
Page 31 of 79
Notification Module Description
Triggers
Figure 42: 'Notification triggers' screen
The available triggers are listed below together with their description.
4.1 'Day Before' Trigger
The 'Day before' trigger is intended to be used for PCC messages. It allows to generate messages to
customers that should be sent before the activity within the predefined time period (Figure 43). This
action-driven trigger is invoked at the time of a new activity creation or an existing activity reschedule.
The trigger is not invoked for non-scheduled, reopened, and 'prework' activities.
The 'Day before' trigger generates messages only for the activities for which the "Enable 'day before'
trigger" feature is enabled in 'Company settings' → 'Activity types'.
Figure 43: 'Day before' trigger
The 'Day before' messages become obsolete after the following activity-related actions: cancel, delete,
start, suspend, reschedule, as well as upon the creation of the 'Reminder' and the 'Change' messages
(this only affects the messages with the 'Customer' recipient). No 'Day before' messages are generated
on the activity move between resources within the same day.
4.2 'Reminder' and 'Change' Notification Triggers
The 'Reminder' and 'Change' are condition-driven triggers intended to be used for PCC messages. They
invoke message scenarios at the moment of time set in the trigger configuration. The time is calculated in
Page 32 of 79
Confidential || Oracle
'Reminder' and 'Change' Notification Triggers
Notification Module Description
relation to the 'Notification base' that is configured in the 'Reminder and change notifications' selector
(Figure 44); it can be one of the following activity fields:
•
ETA
•
delivery window start
•
service window start
Figure 44: Selecting the 'Notification base'
The 'Reminder' trigger is intended to generate a reminder message to a customer which is to be sent
within a fixed time prior to an activity (Figure 45).
Figure 45: 'Reminder' notification trigger
The 'allowed reminder time' values (e.g. '45, 60, 90') will be shown as the 'Reminder' field values in the
'Activity details' screen (Figure 46).
Note: subject to user visibility settings, the 'Reminder' field may appear in Read-only mode.
Figure 46: 'Reminder' selector in 'Activity details' screen
Confidential || Oracle
Page 33 of 79
Notification Module Description
'Reminder' and 'Change' Notification Triggers
And, there are up to five 'Change' triggers which can be used to send a message if the activity delivery
time has changed (Figure 47).
Figure 47: 'Change' notification triggers
In order for the 'Reminder' and 'Change' messages to be sent the "Enable 'reminder' and 'change'
triggers" feature should be enabled for the corresponding activity type.
At the same time both triggers can be invoked only for a pending ordered activity ('regular' or 'reopened')
in an activated route on the current working day.
The 'Reminder' message is generated within the time period from ['Reminder Time' + 'Reminder Time
Adjust'] to ['Reminder Time' – 'Reminder Silent Interval'] before the activity 'Notification base' (Figure
48).
Figure 48: 'Reminder' interval
The 'Reminder time' is defined on the activity level ('Reminder' field in the 'Activity details' screen). When
the 'Reminder time' is set to 0, the 'Reminder' trigger is disabled for the selected activity. The 'Reminder
Time Adjust' is the system predefined time shift for the reminder, that is used to eliminate the delay in
message processing.
Page 34 of 79
Confidential || Oracle
'Reminder' and 'Change' Notification Triggers
Notification Module Description
For example: if 'Reminder Time Adjust' = 3 minutes and 'Reminder Time' = 60 minutes, the reminder will
be generated 63 minutes prior to the 'Notification base'.
The value of ('Reminder Time' – 'Reminder Silent Interval') defines the minimal time before the
'Notification base' to generate the 'Reminder'.
The 'Reminder' trigger can be invoked only once for the same activity.
Each of the 'Change' triggers is defined by its own time interval, based on the time remaining to the
'Notification base', and the threshold value (in minutes).
The 'Change' message is initiated when the current time is within a specific Change trigger time interval,
and the difference between the current value of the 'Notification base' and the time previously reported to
the customer is equal or higher than the threshold.
The time intervals of different 'Change' triggers should be configured in a way that they do not overlap.
The 'Change' trigger is not invoked if:
•
'Reminder' is not sent and the current time is within the Reminder Silent Interval
•
Incomplete 'Reminder' exists
•
'Change' message has already been sent and the last 'Change' message was sent by the same
change trigger
Before generating messages, the 'Reminder' and 'Change' triggers try to cancel all existing customer
messages (if any). They use the 'drop_message' SOAP function to cancel messages that are in the
'Sending' status. If the corresponding agent is not accessible, or it returns a result indicating that the
message is under processing and cannot be dropped, the generation of the 'Reminder' and 'Change'
messages is stopped and will repeat during the next cycle.
'Change' and 'Reminder' messages are removed from the message queue if one of the following events
occurs after their generation and actual sending:
•
Activity status is changed
•
Activity becomes not ordered
•
Activity is moved.
4.3 Triggers Related to Route and Activity Actions
This set of triggers belongs to the action-driven category, most of them are invoked by the resource's
manual action (Figure 49).
Confidential || Oracle
Page 35 of 79
Notification Module Description
Triggers Related to Route and Activity Actions
Figure 49: Triggers related to route and activity actions
Following is the brief overview of the triggers:
•
Activate – invoked on a route activation
•
Deactivate – invoked on a route deactivation
•
Reactivate – invoked on reactivation of a previously deactivated route
•
Add – invoked when a new activity is added or an existing activity is moved to a different
day/resource; this trigger is not invoked for 'prework' activities ('regular' and 'reopened' only)
•
Start – invoked on activity start; this trigger is not invoked for 'prework' activities ('regular' and
'reopened' only)
•
Complete – invoked on completion of a started activity
•
Cancel – invoked when an activity is canceled
•
Not done – invoked when the status of a started activity is changed to 'notdone'
•
Delay – invoked on activity execution delays, if the activity duration after the 'Delay' action
exceeds the threshold value (in minutes)
•
Suspend – invoked when a started or a pending activity is suspended; this trigger is not invoked
for 'prework' activities
Note: if the 'suspend' action is performed for a started activity, a new 'suspended' activity is
created, and the trigger is invoked for such newly-created activity (with the 'suspended' status).
In this case both the 'pending' and the 'suspended' activities have the same property values, and
the 'suspended' activity has no inventory.
•
Move activity – invoked when an existing activity is moved to another resource or day (Figure
50). This trigger is not invoked for 'prework' activities.
Figure 50: 'Move activity' trigger
Page 36 of 79
Confidential || Oracle
Triggers Related to Route and Activity Actions
Notification Module Description
The messages generated by the 'Move activity' trigger refer to the 'origin' resource. In order to
retrieve information about the 'destination' resource, use the following block:
•
destination_resource
In order to retrieve information about the 'destination' resource and date, use the following
placeholders:
•
destination_resource_id
•
destination_resource_external_id
•
destination_resource_name
•
destination_date
For further details on using blocks and placeholders, see the 'Message Content' section.
The 'Resource changed?' and the 'Day changed?' message blocking conditions can be used to
determine if the move is to be performed to another resource or to another day.
4.4 Escalation Message Triggers
This group belongs to the condition-driven triggers and is intended to notify about the activities not
started on time (Figure 51):
•
Not started 1 – is invoked when an activity has not been started within certain time after ETA
•
Not started 2 – similar to 'Not started 1'; allows setting the second message with a different
delay time
Figure 51: 'Not started' triggers
The 'Not started' trigger can only be invoked for a pending ordered activity ('regular' or
'reopened') in an activated route which belongs to the current working day.
The "Enable 'not started' trigger" feature should be enabled for the corresponding activity type.
The 'Not started 1' and 'Not started 2' messages are independent and can be generated for the
same activity at the same time.
•
Not activated – sent if the resource has not activated their route the defined number of minutes
Confidential || Oracle
Page 37 of 79
Notification Module Description
Escalation Message Triggers
after the planned start of the working day, according to the calendar (Figure 52).
Figure 52: 'Not activated' trigger
It works only once a day for a specific route. The messages are not generated again if the
calendar has been changed. If any 'not activated in time' messages are present for the resource
at the moment of route activation, these messages become obsolete. For a new resource the 'Not
activated in time' messages are only generated on the next day (in the company time zone) after
its creation.
This trigger is only invoked for resources with the "Enable 'Not activated in time' alert and trigger"
feature enabled.
•
Service window warning – intended to notify of a possibility to lose the service window (Figure
53). It is sent in either of the following two cases:
•
Activity is scheduled after the service window end
•
Activity has not been started the defined number of minutes before the service window
end.
Figure 53: 'Service window warning' trigger
It is only invoked for pending ordered activities ('regular' or 'reopened') in an activated route with
a service window that belongs to the current working day. This trigger is invoked only once per
activity.
Also the "Enable 'SW Warning' trigger" feature should be activated for the corresponding activity
type.
Configuration
There is a threshold parameter near the 'Service window warning' trigger selector on the
'Notification Triggers' screen. It defines the number of minutes before the end of service window
that is used in the condition.
•
SLA window warning – intended to notify of a possibility to lose the SLA window (Figure 54).
This trigger is only invoked for pending or started activities ('regular' or 'reopened'). The warning
Page 38 of 79
Confidential || Oracle
Escalation Message Triggers
Notification Module Description
is sent if the activity has not been started (for pending activities) or completed (for started
activities) the defined number of minutes before the SLA window end.
Figure 54: 'SLA window warning' trigger
It is invoked only once per activity. But, if 'SLA window end' has changed after the generation of
the 'SLA window warning' messages, the trigger can be invoked again.
Configuration
There is a threshold parameter (hours/minutes) near the 'SLA window warning' trigger selector
on the 'Notification Triggers' screen. It defines the number of minutes before the end of the SLA
window that is used in the condition.
4.5 'Manual' Trigger
'Manual' is an action-driven trigger generating messages on creation of a service request (Figure 55).
When creating a service request, a user should select the service request type and fill in the fields related
to it. The message subject/body pattern for the 'Manual' trigger can contain placeholders that are related
to the service request itself and to all its parent objects. For example, if the request is created on the
activity level, the content can contain placeholders related to request, activity, route and resource.
Figure 55: 'Manual' trigger
The trigger can be used in the following cases:
•
Inventory tracking and hardware testing
•
Initiating SRO or sending any other form
•
Initiating support requests
•
Manually generated cases when transaction is initiated by a person and is not related to the
activity
•
Other activity or inventory requests
Confidential || Oracle
Page 39 of 79
Notification Module Description
'Call Ahead' Trigger
4.6 'Call Ahead' Trigger
'Call Ahead' is an action-driven trigger intended to be used for PCC messages. This trigger is initiated in
Mobility when a technician completes a previous activity (Figure 56).
Figure 56: 'Call ahead' trigger
The trigger is used to:
•
Inform the customer
•
Initiate provisioning or hardware test while the resource is on the way.
When configured, the 'Complete activity' screen has the mandatory 'Next Activity' field. The resource is to
select the next activity and as soon as the 'Complete activity' form is submitted in Mobility, the system
generates the 'Call ahead' for the next activity (selected by the resource).
Note: The 'Call ahead' trigger works for Mobility only.
4.7 External Trigger
'External' is an action-driven trigger invoked by HTTP request from the client's external application via the
External Trigger API (Figure 57).
Figure 57: External trigger
The 'External Trigger' is used to:
•
Associate incoming voice requests with the message scenario
•
Transfer activity data to the incoming request script
•
Record results of the interaction
4.8 Inventory-Related Triggers
'Inventory-Related' is a set of action-driven triggers used to communicate inventory operations to an
enterprise resource planning system and perform automated provisioning (Figure 58):
Page 40 of 79
Confidential || Oracle
Inventory-Related Triggers
Notification Module Description
Figure 58: Inventory-related triggers
•
Install inventory – invoked when the inventory is moved from the 'resource' pool to the 'install'
pool or when a new 'install' inventory record is created (other than those in the resource pool)
•
Deinstall inventory – invoked when the inventory is moved from the customer pool to the
'deinstall' pool or when a new 'deinstall' inventory record is created (other than those in the
customer pool)
•
Exchange inventory – invoked when an inventory exchange between the resource and the
customer pool is performed
•
Undo install inventory – invoked when the inventory is moved from the 'install' pool to the
resource pool
•
Undo deinstall inventory – invoked when the inventory is moved from the 'Deinstalled' pool to
the customer's pool
•
Move inventory – invoked when inventory is moved between different resources. It is invoked
when an inventory item that belongs to a resource of a current user is moved by this user to
another resource via SmartCollaboration. Please note, that the destination resource can be
invisible to the current user due to visibility restrictions.
The messages generated by this trigger refer to the 'origin' resource. In order to retrieve
information about the 'destination' resource, use the following block:
•
destination_resource
The following placeholders can be used to retrieve information about the 'destination' resource:
•
destination_resource_id
•
destination_resource_external_id
•
destination_resource_name
See the 'Message Content' section for more details on using blocks and placeholders.
Confidential || Oracle
Page 41 of 79
Notification Module Description
Visit-Related Triggers
4.9 Visit-Related Triggers
OFSC can send messages not only for a single activity, but can also generate messages related to groups
of activities, called 'Visits'. This option is very convenient if several related activities have to be performed
for the same customer.
The following group of condition-driven triggers is intended to be used for PCC messages to prevent the
same notifications sent to the same customer on different activities within the same visit (Figure 59):
Figure 59: Visit-related triggers
•
Visit day before – similar to the activity 'Day before' trigger but is applied to a visit. The only
difference is that the message is created with a 5-minute delay after the visit creation to let the
system accept other activities that compose the visit. The delay is also useful to prevent
generation of messages for temporary visits, which may be created when visit activities are
moved between resources one by one.
•
Visit reminder – similar to the activity 'Reminder' trigger, but is applied to a visit. This trigger is
intended to generate a reminder message to a customer which is to be sent a fixed time prior to a
visit.
The 'Visit reminder' trigger can be invoked only for pending visits and only once for the same
visit. In addition, the first customer-related activity in the visit must be an ordered activity in an
activated route for the current working day.
The 'Visit reminder' message is generated within the time period from ['Visit Reminder Time' +
'Reminder Time Adjust'] to ['Visit Reminder Time' – 'Visit Reminder Silent Interval'] before the
'Notification base'.
Parameters:
'Notification base' – ETA/delivery window start/service window start from the first customerrelated activity in the visit. A certain field selection is configured in the 'Notification Triggers'
screen using the 'Visit reminder and change notifications' selector.
'Visit Reminder Time' is the time before the 'Notification base' to send the reminder. As opposed
Page 42 of 79
Confidential || Oracle
Visit-Related Triggers
Notification Module Description
to the regular triggers, this parameter is defined on the company level.
'Reminder Time Adjust' is the system predefined reminder time shift to be used to eliminate the
messages processing delay.
For example: if 'Reminder Time Adjust' = 3 minutes and 'Visit Reminder Time' = 60 minutes, the
reminder will be generated 63 minutes prior to the 'Notification base'.
The value of ('Visit Reminder Time' – 'Visit Reminder Silent Interval') defines the minimal time
before the 'Notification base' to generate the reminder.
•
Visit change 1...Visit change 5 – similar to the activity 'Change' triggers, but applied to a visit.
There are up to five 'Visit change' triggers which can be used to send a message if the visit
delivery time has changed.
The 'Visit change' trigger can be invoked only for pending visits. In addition, the first customerrelated activity in the visit must be an ordered activity in an activated route for the current
working day.
The 'Visit change' message is initiated when the current time is within the time interval of a specific
'Visit change' trigger, and the difference between the current value of the 'Notification base' and the time
previously reported to the customer is equal or higher than the threshold.
The time intervals of different 'Visit change' triggers should be configured in a way that they do not
overlap.
The 'Visit change' trigger is not invoked if:
•
'Visit reminder' is not sent and the current time is within the Visit Reminder Silent Interval
•
Incomplete 'Visit reminder' exists
•
'Visit change' message has already been sent and the last 'Visit change' message was sent by the
same visit change trigger
Before generating messages, the 'Visit reminder' and 'Visit change' triggers try to cancel all existing
customer messages (if any). They use the 'drop_message' SOAP function to cancel messages that are in
the 'Sending' status. If the corresponding agent is not accessible, or it returns a result indicating that the
message is under processing and cannot be dropped, the generation of the 'Visit reminder' and 'Visit
change' messages is stopped and will repeat during the next cycle.
•
Visit cancel – initiated when the last of the activities in a visit is canceled (none are pending,
completed, or not done). This trigger can be invoked several times for the same visit when new
activities are added to an existing canceled visit.
•
Visit complete – initiated when the last pending activity in a visit gets a final status, and at least
one activity is 'completed' or 'notdone'. This trigger initiates the PAS scenario and is invoked only
once, when the visit becomes 'completed' or 'notdone' for the first time.
Confidential || Oracle
Page 43 of 79
Notification Module Description
Visit-Related Triggers
Visit triggers are designed to be used mostly for customer interactions reducing the number of day before
calls, reminders, change messages and PAS messages to the same customer.
5
Notification Methods
The following table contains the list of supported notification methods and their functional features:
Functionality/Method
Email
External Trigger
External
system
Set Property
Recipient
Yes
No; always 'Customer'
Yes
Yes
Send at
Yes
No; always 'time of
event'
Yes
Yes
within
Yes
Yes
Yes
Yes
Block messages for
specific days
Yes
Yes
Yes
Yes
Block messages for
holidays
Yes
Yes
Yes
Yes
Shift blocked messages
Yes
Yes
Yes
Yes
Number of attempts on
'failed' status
Yes
No
Yes
No
Number of attempts on
'sent' status
No
No
Yes
No
Customer notification
time
Yes
Yes
Yes
No
Email address
source'/'Phone number
source
Yes
No
No
No
Reply address
Yes
No
No
No
'Survey'-PAS survey
support
No
No
Yes
No
Default encoding method for substituted parameter
values in subject/body of
messages
XML
XML
-
Time zone of date/time
based on recipient
values in subject/body of
messages
based on recipient
based on
recipient
based on
recipient
6
'Set property' Method
The 'set_property' method provides the ability to update all custom properties (except the 'file'
properties) for the following entities:
•
activity
•
inventory
•
resource
Page 44 of 79
Confidential || Oracle
'Set property' Method
•
Notification Module Description
user
Note: values of the properties should be in an internal format. In particular, use the 'index'
values for enumeration properties, rather than their translations.
Also, a label of the property to be assigned should be specified in the 'Subject' field without any prefix
("pr_" or "prnum_").
It also supports the predefined list of activity fields:
•
cemail
•
ccell (sms)
•
cphone
•
appt_number
•
customer_number
•
customer_name (cname)
•
caddress
•
ccity
•
cstate
•
czip
•
apoints
After processing, such message gets one of the following statuses/descriptions:
Status
Description
Data
delivered
ALREADY_SET
The property is not changed. It is
already assigned to the given value
delivered
INSERTED
An empty property is assigned to the
given value
delivered
DELETED
An existing property is assigned to
empty
delivered
UPDATED
An existing property value is changed
failed
WRONG_CONFIGURATION
Unknown label
failed
WRONG_CONFIGURATION
Not supported entity An attempt to update a property for an
entity that is not supported
failed
WRONG_CONFIGURATION
Not supported field
The given field cannot be updated
using this method
failed
WRONG_CONFIGURATION
Parent entity
mismatch
The message has no relation to the
requested entity
failed
WRONG_CONFIGURATION
Unknown ID of the
parent object
The system is unable to find an object
by ID retrieved from the message
failed
WRONG_CONFIGURATION
Invalid integer value Th given value of an integer property
cannot be converted to 'signed int32'
failed
WRONG_CONFIGURATION
Invalid lookup value
The given value of a lookup property
cannot be found in the list of items for
this property
failed
WRONG_CONFIGURATION
Invalid value
Surveys: The system is unable to
Confidential || Oracle
Comments
The given label of a property/field is
not found in the dictionary
Page 45 of 79
Notification Module Description
Status
Description
'Set property' Method
Data
Comments
validate the value of a 'Checkbox' or
'Radiogroup' property
failed
WRONG_CONFIGURATION
Missing survey take
Surveys: The system is unable to find
a corresponding 'survey take' record
the message refers to
failed
INTERNAL_ERROR
Unknown result code A result of the property update is not
handled properly
6.1 Actions
The following actions are supported at the moment:
•
cancel_activity
•
unschedule_activity
'Subject' of the corresponding message should contain the 'action' word. The name of the action to be
performed should be stored in the 'Body' field.
6.1.1 'cancel_activity'
This action cancels a 'pending' activity. If this activity is non-scheduled, it is moved to the current
resource's day and then canceled.
Note: 'cancel_activity' action is not intended to perform the 'notdone' and 'deleted' actions depending on
the activity and the route status.
After processing, such message gets one of the following statuses/descriptions:
Status
Description
delivered
Comments
The action is performed successfully.
failed
INVALID_RESOURCE_TYPE
This action is not supported for this type of
resource.
For example, the resource or its type is
reconfigured, and activities cannot be assigned to it
anymore.
failed
NO_PERMISSION
This user has no access to the specified resource or
activity.
failed
RESOURCE_NOT_FOUND
The system is unable to find the resource which the
message refers to.
failed
ACTIVITY_NOT_FOUND
The system is unable to find the activity which the
message refers to.
failed
INACTIVE_RESOURCE
The resource is inactive.
failed
NON_WORKING_DAY
The resource has a non-working day.
For example, this error can appear for a non-
Page 46 of 79
Confidential || Oracle
'cancel_activity'
Status
Notification Module Description
Description
Comments
scheduled activity.
failed
ACTION_ON_PAST
The activity is located in the route for the day in the
past, that cannot be changed.
failed
MISCONFIGURED_CALENDAR
The system is unable to determine if the resource is
working because its calendar is misconfigured.
For example, this error can appear for a nonscheduled activity.
failed
MISCONFIGURED_TIME_ZONE
The system is unable to determine a current time
for the resource because its time zone is
misconfigured.
For example, this error can appear for a nonscheduled activity.
failed
INVALID_ACTIVITY_STATUS
This action is not supported for an activity with such
status.
Only 'pending' activity can be canceled.
failed
NON_MOVABLE_ACTIVITY
This type of activity cannot be moved to another
resource or a day.
For example, this error can appear for a nonscheduled activity.
failed
RESCHEDULE_IS_NOT_ALLOWED
This type of activities cannot be rescheduled to
another day.
For example, this error can appear for a nonscheduled activity.
failed
NOT_SCHEDULED_IS_NOT_ALLOWED This type of activities cannot be non-scheduled.
For example, this error can appear for a nonscheduled activity.
failed
DEACTIVATED_ROUTE
The route is deactivated.
For example, this error can appear for a nonscheduled activity if it cannot be moved to the
resource's route for the current day because this
route is deactivated.
6.1.2 'unschedule_activity'
This action makes a 'pending' activity 'non-scheduled'.
After processing, such message gets one of the following statuses/descriptions:
Status
Description
delivered
failed
Comments
The action is performed successfully.
INVALID_RESOURCE_TYPE
This action is not supported for this type of
resource.
For example, the resource or its type are
reconfigured and activities cannot be assigned to
it anymore.
Confidential || Oracle
Page 47 of 79
Notification Module Description
'unschedule_activity'
Status
Description
Comments
failed
NO_PERMISSION
This user has no access to the specified resource
or activity.
failed
RESOURCE_NOT_FOUND
The system is unable to find the resource which
the message refers to.
failed
ACTIVITY_NOT_FOUND
The system is unable to find the activity which the
message refers to.
failed
INACTIVE_RESOURCE
The resource is inactive.
failed
ACTION_ON_PAST
The activity is located in a route for the past day
that cannot be changed.
failed
INVALID_ACTIVITY_STATUS
This action is not supported for an activity with
such status.
Only 'pending' activity can be unscheduled.
failed
INVALID_ACTIVITY_TYPE
This action is not supported for an activity of such
type.
Only 'regular' and 'reopened' activities can be
unscheduled.
failed
NON_MOVABLE_ACTIVITY
This type of activities cannot be moved to another
resource or day.
For example, this error can appear for a nonscheduled activity.
failed
RESCHEDULE_IS_NOT_ALLOWED
This type of activities cannot be rescheduled to
another day.
For example, this error can appear for a nonscheduled activity.
failed
NOT_SCHEDULED_IS_NOT_ALLOWED
This type of activities cannot be non-scheduled.
For example, this error can appear for a nonscheduled activity.
7
Setting Properties Based on Message Status Received from Agent
This functionality is intended to allow agents to update properties and perform actions without adding
additional scenario steps.
It is based on the same engine as the 'set property' messages and provides similar functionality:
•
updating all activity and inventory properties (by label) and the predefined set of activity fields:
cemail, ccell, cphone, etc.
•
performing 'cancel_activity' and 'unschedule_activity' actions.
Examples
The functionality allows the ability to:
•
Update properties based on processing the result of a PAS scenario message and control further
scenario flow based on these properties
Page 48 of 79
Confidential || Oracle
Setting Properties Based on Message Status Received from Agent
Notification Module
Description
•
Set the 'ICOMS' result property directly from the ICOMS agent without additional 'set property'
steps (for ICOMS)
•
Cancel activity based on a customer selection during an IVR call, etc.
Format
The fields to be assigned and the corresponding values are passed in the 'data' field.
The '#params?' string is used as the delimiter between 'data' itself and the passed parameters. The
format of the parameter line is similar to URL. The "&" character is used as the delimiter between
different parameters.
data = OK#params?cconfirmed=1&phone=12345678912
data = #params?icoms_eta_status=1
data = DONE#params?pas_requires_feedback=1
data = #params?action=cancel_activity&notes=Rescheduled
Encoding
Names and values of the parameters are encoded as the URL parameters. So, if the "URL" property needs
to be assigned to 'http: //localhost/v41/wwwroot/?param1=value1&param2=value2', the result data
value should be as follows:
data = OK#params?CANCEL_REASON=0&URL=http%3A%2F%2Flocalhost%2Fv41%2Fwwwroot%2F
%3Fparam1%3Dvalue1%26param2%3Dvalue2
The encoding requires that all non-ASCII and non-alphanumeric characters (with some exceptions) must
be represented as hexadecimal values with leading '%'. Exceptions: the '.', ',', '-', '_' characters should be
provided as is, and the ' ' (space) symbol is replaced with the '+' (plus).
Maximum length
There is a restriction of 255 characters on the total length of the 'data' field. If a submitted 'data' value
exceeds the limit, it can be processed correctly, but will be truncated.
Confidential || Oracle
Page 49 of 79
Notification Module Description
8
Message Removal Cases
Message Removal Cases
There is a number of actions in the system which, under certain conditions, might remove the existing
messages if the messages have not yet been sent.
The table below provides the list of such actions, the messages each action will remove, and the statuses
set to those messages.
Event/Action
Removed Messages
Status/Description
Activity start
Reminder
Change
Day before
Status = obsolete
Description = ACTIVITY_WAS_STARTED
Activity cancelation
All
Status = obsolete
Description = ACTIVITY_WAS_CANCELED
Activity 'notdone'
All
Status = obsolete
Description = ACTIVITY_WAS_NOT_DONE
Deletion of a pending
activity
All
Status = obsolete
Description = ACTIVITY_WAS_DELETED
Activity suspend
Reminder
Change
Day before
Status = obsolete
Description = ACTIVITY_WAS_SUSPENDED
Activity reschedule
All, except 'SLA Warning'
Status = obsolete
Description = ACTIVITY_WAS_RESCHEDULED
Activity move
Reminder
Change
Not started
Service window warning
Call ahead
Add
Status = obsolete
Description = ACTIVITY_WAS_MOVED
Convert an activity to
not ordered
Reminder
Change
Status = obsolete
Description = ACTIVITY_IS_NOT_ORDERED
Reminder message creation
'Customer' messages:
Recipient = Customer
Status = obsolete
Description =
NEW_CUSTOMER_MESSAGE_WAS_CREATED
The 'Reminder' trigger is not invoked if the
existing customer messages cannot be
dropped using the 'drop_message' call (if
required).
Change message creation
'Customer' messages:
Recipient = Customer
Status = obsolete
Description =
NEW_CUSTOMER_MESSAGE_WAS_CREATED
The 'Change' trigger is not invoked if an
incomplete 'Reminder' exists, or if the existing
customer messages cannot be dropped using
the 'drop_message' call (if required).
Cancel visit
All (visit-related)
Status = obsolete
Description = VISIT_WAS_CANCELED
Delete visit
All (visit-related)
Status = obsolete
Description = VISIT_WAS_DELETED
Page 50 of 79
Confidential || Oracle
Message Removal Cases
Notification Module Description
Event/Action
Removed Messages
Status/Description
Start visit
Visit reminder
Visit change #
Visit day before
Status = obsolete
Description = VISIT_WAS_STARTED
Applying new visit formulas
All (visit-related)
Status = obsolete
Description = VISIT_WAS_RECALCULATED
The messages are only removed if the visit is
removed as the result of applying formula
changes.
Block/Shift messages
Status = false
Method description = NONWORKING_DAY
This removal is performed if message sending
of is not allowed for a non-working day (or a
holiday) and such message cannot be shifted
to an appropriate working day.
Confidential || Oracle
Page 51 of 79
Notification Module Description
Message Content
Message Content
9
This section is intended to describe the rules used to create the message content, including the following
aspects:
•
Placeholders – field names replaced with the actual information for a specific entity
•
Blocks – statements used to process a set of similar objects
•
Formatting rules – patterns and functions used for the message content formatting.
9.1 Placeholders
Placeholder is the field name, that, when included in a message, is replaced with the actual field value for
a particular message instance. The use of placeholders enables creation of a single message pattern for
different instances.
For example, if a message "Technician 'provider_name' will come to you between 'delivery_window_start'
and 'delivery_window_end'", then for each specific activity the actual message will contain the name of
the corresponding resource and time frame of the delivery window.
The server supports the following placeholders, grouped by entity:
Placeholders for activity:
Placeholder
Description
activity_number
ID of the corresponding work order in an external system
activity_type
Activity primary type (regular, reopened, prework)
activity_status
Activity status
activity_worktype
Activity work type (name)
activity_worktype_id
Activity work type (id)
activity_worktype_label
Activity work type (label)
activity_workzone
Activity work zone (name)
activity_workzone_id
Activity work zone (id)
activity_travel_area
Activity travel area (name)
activity_travel_area_id
Activity travel area (id)
activity_travel_area_label
Activity travel area (label)
activity_workskill
Activity work skill (name)
Can only be used in the 'activity_workskills' block
activity_workskill_id
Activity work skill (id)
Can only be used in the 'activity_workskills' block
activity_workskill_label
Activity work skill (label)
Can only be used in the 'activity_workskills' block
activity_workskill_required_level
Required work skill level for an activity
Can only be used in the 'activity_workskills' block
activity_workskill_preferable_level
Preferable work skill level for an activity
Can only be used in the 'activity_workskills' block
activity_start_time
Estimated start time of the activity ("HH24:MI" format)
activity_end_time
Estimated end time of the activity ("HH24:MI" format)
Page 52 of 79
Confidential || Oracle
Placeholders
Notification Module Description
Placeholder
Description
activity_duration
Estimated activity duration
activity_service_window_start
Service window start ("HH24:MI" format)
activity_service_window_end
Service window end ("HH24:MI" format)
activity_sla_window_start
SLA window start ("YYYY-DD-MM HH24:MI" format)
activity_sla_window_end
SLA window end ("YYYY-DD-MM HH24:MI" format)
activity_delivery_window_start
Delivery window start ("HH24:MI" format)
activity_delivery_window_end
Delivery window end ("HH24:MI" format)
activity_time_delivered_start
Start of the time window delivered to customer ("hh24:mm"
format)
activity_time_delivered_end
End of the time window delivered to customer ("hh24:mm" format)
activity_traveling_time
Estimated travel time from the previous activity (minutes)
activity_time_slot
Activity time slot (name)
activity_time_slot_id
Activity time slot (id)
activity_time_slot_label
Activity time slot (label)
activity_time_zone
Name of the time zone defined for the activity
activity_time_zone_id
ID of the time zone defined for the activity
activity_time_zone_label
Label of the time zone defined for the activity
activity_time_zone_diff
Time difference of the time zone defined for the activity
activity_customer_name
Customer's name
activity_customer_number
ID of the corresponding customer's account in an external system
activity_phone
activity_email
Activity/customer contact information
activity_cell
activity_address
activity_city
activity_state
Location of the activity
activity_zip
activity_coord_status
Whether or not the activity coordinates were found
activity_coordx
Longitude of the activity (of customer's location)
activity_coordy
Latitude of the activity (of customer's location)
activity_language
Customer's messaging language (name)
activity_language_id
Customer's messaging language (id)
activity_language_label
Customer's messaging language (label)
activity_reminder_time
Customer's reminder notification time
activity_position_in_route
Sequential position (starts from "1") of the corresponding activity
in a route
activity_time_of_booking
Time when the activity was booked (customer activities) or created
(internal activities).
("YYYY-DD-MM HH24:MI" format)
activity_time_of_assignment
For the activity currently assigned to a resource, the placeholder
Confidential || Oracle
Page 53 of 79
Notification Module Description
Placeholder
Placeholders
Description
returns the time when the corresponding move/reschedule/create
operation was performed.
For the activity in a bucket, the placeholder's value is empty
("YYYY-DD-MM HH24:MI" format).
activity_link_min_interval
Minimum and maximum duration of the time interval between
linked activities.
activity_link_max_interval
These placeholders can only be used in the 'linked_activities' block.
Placeholders for route:
Placeholder
Description
route_date
Route date ("YYYY-MM-DD" format)
route_start_time
Route activation time ("YYYY-MM-DD HH24:MI:SS" format)
route_end_time
Route deactivation time ("YYYY-MM-DD HH24:MI:SS" format)
route_reactivation_time
Route reactivation time ("YYYY-MM-DD HH24:MI:SS" format)
Placeholders for visit:
Placeholder
Description
visit_id
ID of the visit
visit_status
Allows to retrieve the current status of the visit
visit_confirmed
Allows to retrieve ID of the visit
visit_time_delivered_start
Allow to retrieve the time delivered to a customer for companies
that use visits
visit_time_delivered_end
Placeholders for resource:
Placeholder
Description
resource_external_id
Resource id
resource_language
Resource messaging language (name)
resource_language_id
Resource messaging language (id)
resource_name
Resource name
resource_phone
Resource phone number
resource_email
Resource email address
resource_type
Resource type (name)
resource_type_id
Resource type (id)
resource_type_label
Resource type (label)
resource_time_zone
Name of the resource's time zone
resource_time_zone_id
ID of resource's time zone
resource_time_zone_label
Label of resource's time zone
resource_time_zone_diff
Time difference of the resource's time zone
parent_resource_external_id
Parent resource external id
parent_resource_name
Parent resource name
Page 54 of 79
Confidential || Oracle
Placeholders
Notification Module Description
Placeholder
Description
destination_resource_id
ID of the current resource for an activity (or inventory)
Destination resource for the move activity/inventory operations
destination_resource_external_id
External ID of the current resource for an activity (or inventory)
Destination resource for the move activity/inventory operations
destination_resource_name
Name of the current resource for an activity (or inventory)
Destination resource for the move activity/inventory operations
destination_date
Current date the activity is assigned to
Destination date for the reschedule activity operation
Placeholders for inventory:
Placeholder
Description
inventory_serial_number
Serial number of the inventory
inventory_type
Inventory type (name)
inventory_type_id
Inventory type (id)
inventory_type_label
Inventory type (label)
inventory_ex_serial_number
Serial number of the exchanged inventory. This placeholder is only
available inside of the 'exchanged_inventory' block.
inventory_quantity
Quantity of the non-serialized inventory.
Note: This placeholder can also have "zero" or negative value.
In case with serialized inventory, it always equals "1".
inventory_model_property_value
Value of the 'Model' property
Placeholders for required inventory:
Note: This placeholder group can only be used in the 'required_inventory' block.
Placeholder
Description
required_inventory_type_id
Required inventory type ID
required_inventory_type_name
Required inventory type name translated into message language
required_inventory_type_label
Required inventory type label
required_inventory_model
Required inventory model
required_inventory_quantity
Quantity of the required inventory
Placeholders for service request:
Placeholder
Description
request_date
Service request date
request_type
Service request type (name)
request_type_id
Service request type (id)
request_type_label
Service request type (label)
request_time_of_creation
Time when the service request was created.
It is printed using the time zone of the message (based on the
selected 'Recipient').
Confidential || Oracle
Page 55 of 79
Notification Module Description
Placeholders
Placeholders for message:
Placeholder
Description
prev_status
Status of the previous message step
prev_desc
Description of the previous message step
prev_data
Data of the previous step
prev_subject
Subject of the previous step
prev_body
Body of the previous step
message_time_zone
Name of the time zone from the corresponding scenario step
message_time_zone_id
ID of the time zone from the corresponding scenario step
message_time_zone_label
Label of time zone from the corresponding scenario step
message_time_zone_diff
Time difference stored in the message
message_time_of_creation
Time when the message was created.
In case of 'inner' steps, value might differ from the time of the
event that resulted in the creation of this message. It is printed
using the time zone of the message (based on the selected
'Recipient').
message_time_of_content_generation Time when content was generated for this message.
It is printed using the time zone of the message (based on the
selected 'Recipient').
Placeholders for user:
Placeholder
Description
user_name
Name of the user who created the message
user_login
Login of the user who created the message
Placeholder for properties:
Placeholder
Description
[ex]pr[num]_<label>
Value of the property identified by the <label>.
It works with 'string', 'int', 'enum' and 'file' properties. It does
not support properties of the 'field' type.
In case of a 'file' property the printed value contains a name of
the file.
By default the text representation of an 'enum' property is
printed. The [prnum_] prefix allows to retrieve ID of a lookup
for an 'enum' property.
The [ex_] prefix is only applicable to the 'inventory_exchange'
trigger or in the 'exchanged_inventory' block. It provides access
to properties of the deinstalled inventory in case of an exchange
operation.
Placeholders for calendars:
Note: this placeholder group can be used in subject/body templates of messages that have reference to
a route. Also, they work for the 'manual' (service request) trigger.
Page 56 of 79
Confidential || Oracle
Placeholders
Notification Module Description
The message engine retrieves the data from the 'regular' calendar by default. But, it also allows to switch
to the 'on-call' calendar type using a special BLOCK statement.
The calendar is retrieved for the date of the corresponding route (if applicable) or the service request.
Placeholder
Description
calendar_time_from
Start of resource's working day ("HH24:MI" format)
calendar_time_to
End of resource's working day ("HH24:MI" format)
calendar_points
Points from the resource's calendar
calendar_comments
Comments from the resource's calendar
calendar_record_type
Type of the resource's calendar record
(e.g. shift, working, non-working)
calendar_shift
Resource's shift (name)
calendar_shift_id
Resource's shift (ID)
calendar_shift_label
Resource's shift (label)
calendar_work_schedule
Resource's work schedule (name)
calendar_work_schedule_id
Resource's work schedule (ID)
calendar_work_schedule_label
Resource's work schedule (label)
calendar_non_working_reason
Resource's non-working reason (name)
calendar_non_working_reason_id
Resource's non-working reason (ID)
calendar_non_working_reason_label
Resource's non-working reason (label)
Confidential || Oracle
Page 57 of 79
Notification Module Description
Blocks
9.2 Blocks
'Block' statements are the Message Engine tools used to iterate through a list of similar objects (visit
orders, activity inventory) and print the same section of the pattern for every object from the list.
For example:
<visit>
<BLOCK type="visit">
<work_order number="{appt_number}"status="appt_status"comments="{pr_comments}"/>
</BLOCK>
</visit>
The available block types are listed in the following table:
Block
Description
installed_inventory
This block allows to retrieve the list of inventory from the 'install' pool
deinstalled_inventory
This block allows to retrieve the list of inventory from the 'deinstall' pool
customer_inventory
This block allows to retrieve the list of inventory from the 'customer' pool
resource_inventory
This block allows to retrieve the list of inventory from the 'resource' pool
exchanged_inventory
This block allows to retrieve the list of exchanged inventory
required_inventory
This block allows to retrieve the list of required inventory
visit
This block allows to include information related to work orders that belong
to a visit into a single message.
Note: this block can only be used in scenarios attached to the visit-related
triggers.
team-members
This block allows to retrieve the list of team-members for a given
teamholder and a given day.
It can be used in messages that are related to a route. Also it works for
the 'Manual' (service request) trigger.
regular_calendar
oncall_calendar
These two blocks are intended for switching between the 'regular' and 'oncall' calendar types.
The 'regular' calendar is selected by default and it is not required to use
the block in this case.
The following placeholders can only be used in this block:
activity_workskills
destination_resource
linked_activities
•
•
•
•
•
activity_workskill
activity_workskill_id
activity_workskill_label
activity_workskill_required_level
activity_workskill_preferable_level
This block allows to retrieve values of the resource-related fields and
custom properties for a destination resource within the following triggers:
•
•
'Move activity' trigger
'Move inventory' trigger
This block allows to retrieve activities linked to the current one.
The block has the following syntax:
Page 58 of 79
Confidential || Oracle
Blocks
Notification Module Description
<BLOCK type="linked_activities: label of activity link type">
Note:
– This block cannot be used without the label of activity link type.
– All 'related' activity links are also handled as 'ordered' even if the
corresponding activity link type has two identical labels.
forbidden_resources
required_resources
These blocks allow to retrieve preferred resources.
preferred_resources
multiday_activity
This block allows to temporarily switch the context to the related multi-day
activity. It can be used in scenarios related to both multi-day activities and
their segments.
Note: if this block is invoked for a single-day activity, it will not process
any records and the result will contain no data.
multiday_activity_segments This block allows to print information about all existing segments of a
multi-day activity regardless of their statuses (except 'deleted' segments).
It can be used in scenarios related to both multi-day activities and their
segments.
Note: if this block is invoked for a single-day activity, it will not process
any records and the result will contain no data.
9.2.1 Block Examples
•
Visit
<visit>
<BLOCK type="visit">
<work_order number="{activity_number}" status="{activity_status}"
comments="{pr_comments}"/>
</BLOCK>
</visit>
•
Team
<team>
<BLOCK type="team-members">
<team-member
resource_external_id ="{resource_external_id}"
resource_name = "{resource_name}"
teamwork_start = "{activity_start_time:+{activity_start_time}}
{activity_start_time:-{activity_service_window_start}}"
teamwork_end = "{activity_end_time:+{activity_end_time}}
{activity_end_time:-{activity_service_window_end}}"
teamwork_activity_number = "{activity_number}"
teamwork_activity_worktype = "{activity_worktype}"
teamwork_activity_duration = "{activity_duration}"
teamwork_activity_time_slot = "{activity_time_slot}"
Confidential || Oracle
Page 59 of 79
Notification Module Description
Block Examples
/>
</BLOCK>
</team>
•
Oncall_calendar
regular_shift = "{calendar_shift}"
<BLOCK type="oncall_calendar">
oncall_shift = "{calendar_shift}"
</BLOCK>
•
Activity_workskills
Pattern:
<desc><BLOCK type="activity_workskills">{activity_workskill},</BLOCK></desc>
<details>
<BLOCK type="activity_workskills">
<skill label="{activity_workskill_label}"
required="{activity_workskill_required_level}"
preferable="{activity_workskill_preferable_level}"/>
</BLOCK>
</details>
•
Linked activities and preferred resources
Pattern:
<linked_activities>
<BLOCK type="linked_activities: start-before">
<activity link = "predecessor" min_delay = "{activity_link_min_interval}"
max_delay = "{activity_link_max_interval}" date = "{date}" resource = "{resource_name}"
number = "{activity_number}" worktype = "{activity_worktype}"/>
<forbidden_resources>
<BLOCK type="forbidden_resources">
<resource resource = "{resource_name}"/>
</BLOCK>
</forbidden_resources>
<required_resources>
<BLOCK type="required_resources">
<resource resource = "{resource_name}"/>
</BLOCK>
</required_resources>
<preferred_resources>
<BLOCK type="preferred_resources">
<resource resource = "{resource_name}"/>
Page 60 of 79
Confidential || Oracle
Block Examples
Notification Module Description
</BLOCK>
</preferred_resources>
<resource_inventory>
<BLOCK type="resource_inventory">
<inventory serial = "{inventory_serial_number}" type="{inventory_type}"/>
</BLOCK>
</resource_inventory>
</activity>
</BLOCK>
<BLOCK type="linked_activities: start-after">
<activity link = "successor" min_delay = "{activity_link_min_interval}" max_delay
= "{activity_link_max_interval}" date = "{date}" resource = "{resource_name}" number =
"{activity_number}" worktype = "{activity_worktype}"/>
</BLOCK>
<BLOCK type="linked_activities: start-together">
<activity link = "simultaneous" date = "{date}" resource = "{resource_name}"
number = "{activity_number}" worktype = "{activity_worktype}"/>
</BLOCK>
</linked_activities>
Required inventory
•
Pattern:
<required_inventory>
<BLOCK type="required_inventory">
<item
type="{required_inventory_type_label}"
model="{required_inventory_model}"
quantity="{required_inventory_quantity}"
/>
</BLOCK>
</required_inventory>
Confidential || Oracle
Page 61 of 79
Notification Module Description
Formatting
9.3 Formatting
9.3.1 Date and Time Formatting
The message content generator allows to use date and time formatting patterns. The list of all available
patterns is provided in the following table:
Format:
Description:
%A
replaced with the national representation of the full weekday name
%a
replaced with the national representation of the abbreviated weekday name
%B
replaced with the national representation of the full month name
%b
replaced with the national representation of the abbreviated month name
%C
replaced with (year / 100) as decimal number; single digits are preceded by a zero
%c
replaced with the national representation of time and date
%D
equivalent to %m/%d/%y
%d
replaced with the day of the month as a decimal number (01-31)
%E, %O*
POSIX locale extensions. The sequences %Ec %EC %Ex %EX% Ey %EY %Od %Oe
%OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy are supposed to
provide alternate representations.
Additionally, %OB is implemented to represent alternative months names (used
Standalone, without day mentioned).
%e
Replaced with the day of month as a decimal number (1-31); single digits are preceded
by a blank
%F
Equivalent to %Y-%m-%d
%G
Replaced with a year as a decimal number with century
This year is the one that contains the greater part of the week (Monday as the first day
of the week).
%g
Replaced with the same year as in %G, but as a decimal number without century (0099)
%H
Replaced with the hour (24-hour clock) as a decimal number (00-23)
%h
Same as %b
%I
Replaced with the hour (12-hour clock) as a decimal number (01-12)
%j
Replaced with the day of the year as a decimal number (001-366)
%k
Replaced with the hour (24-hour clock) as a decimal number (0-23); single digits are
preceded by a blank
%l
Replaced with the hour (12-hour clock) as a decimal number (1-12); single digits are
preceded by a blank
%M
Replaced with the minute as a decimal number (00-59)
%m
Replaced with the month as a decimal number (01-12)
%n
Replaced with a new line
%O*
Same as %E*
%p
Replaced with national representation of either "ante meridiem" or "post meridiem" as
appropriate
%R
Equivalent to %H:%M
Page 62 of 79
Confidential || Oracle
Date and Time Formatting
Notification Module Description
Format:
Description:
%r
Equivalent to %I:%M:%S %p
%S
Replaced with the second as a decimal number (00-60)
%s
Replaced with the number of seconds since the Epoch, UTC (see mktime(3))
%T
Equivalent to %H:%M:%S
%t
Replaced with a tab
%U
Replaced with the week number of the year as a decimal number (00-53) with
Sunday being the first day of the week
%u
Replaced with the weekday as a decimal number (1-7) with Monday being the first day
of the week
%V
Replaced with the week number of the year as a decimal number (01-53) with Monday
being the first day of the week
If the week containing January 1 has four or more days in the new year, then it is week
1; otherwise it is the last week of the previous year, and the next week is week 1.
%v
Equivalent to %e-%b-%Y
%W
Replaced with the week number of the year as a decimal number (00-53) with
Monday being the first day of the week
%w
Replaced with the weekday as a decimal number (0-6) with Sunday being the first day
of the week
%X
Replaced with national representation of the time
%x
Replaced with national representation of the date
%Y
Replaced with the year with century as a decimal number
%y
Replaced with the year without century as a decimal number (00-99)
%+
Replaced with national representation of the date and time (the format is similar to that
produced by date(1))
%-*
Suppress padding when performing numerical outputs
%_*
Explicitly specify space for padding
%0*
Explicitly specify zero for padding
%%
Replaced with '%'
To use the pattern, write it after the placeholder, using the '|' sign as the delimiter.
For example:
{date} = 2006-07-19
{ETA} = 16:00
{ETA|%R} = 16:00
{ETA|%H:%M} = 16:00
{ETA|%r} = 04:00:00 PM
{ETA|%I:%M %p} = 04:00 PM
{ETA|%I:%M:%S %p} = 04:00:00 PM
{date|%A, %d %b %G} = Wed, 19 Jul 2006
{ETA|%A, %d %b %G %I:%M} = Wednesday, 19 Jul 2006 04:00 PM
Confidential || Oracle
Page 63 of 79
Notification Module Description
Encoding Placeholder Values
9.4 Encoding Placeholder Values
The message content generator allows to define the type of encoding to be applied to a placeholder value
before printing.
The encoding can be specified after a name of the placeholder. The '|' character is used as the delimiter in
this case.
Examples:
CSV: "{pr_address|csv_item}","{pr_comments|csv_item}","{pr_notes|csv_item}"
URL: address={pr_address|cgi}&comments={pr_comments|cgi}&notes={pr_notes|cgi}
The following encoding types are supported:
•
none
•
xml/html
•
slashes/cslashes
•
cescape
•
url
•
cgi
•
csv_item
•
json
•
sql_slashes
9.5 Suppressing of Unassigned Variables Printing
This functionality is mainly intended to decrease the size of the message body for internal messages.
It allows to avoid printing of empty values in messages.
The syntax is as follows: {var:+text}
This means the *text* will not be inserted into result if *var* is empty.
Example of the message pattern:
{pr_ch_note:+<f n="pr_ch_note">{pr_ch_note}</f>
}{ch_drop_bury:+<f n="ch_drop_bury">{ch_drop_bury}</f>
}
Result for pr_ch_note="" and ch_drop_bury="0" is
<f n="ch_drop_bury">0</f>
The following syntax is also supported: {var:-text}
It provides a functionality opposite to the previous operation, and this means *text* will be inserted into
result if *var* is empty.
Page 64 of 79
Confidential || Oracle
Suppressing of Unassigned Variables Printing
Notification Module Description
Example of the message pattern:
{pr_ch_w_o_notes:+<f n="notes">{pr_ch_w_o_notes}</f>
}{pr_ch_w_o_notes:-<f n="notes">{pr_ch_notes}</f>
}
Result for pr_ch_w_o_notes="wo notes" and pr_ch_notes="" is
<f n="notes">wo notes</f>
Result for pr_ch_w_o_notes="" and pr_ch_notes="notes" is
<f n="notes">notes</f>
10
Blocking Conditions
Message blocking conditions can be defined for a scenario step, and, if such conditions are met, the
relevant message is blocked. In this case the message is either generated with a final status or is not
generated at all. Any field used in the system can serve as a blocking condition.
Note: condition value supports CSV format, e.g. 1, 2, 3, 4, "1,1,1", "2,s", "(""test"")"
The following comparison functions are available: IS NULL, IS NOT NULL, IN, NOT IN, CONTAINS,
DOESN'T CONTAIN, >, <, >=, <=.
Following, is the list of available system blocking conditions, grouped by entity:
Blocking conditions for activity
Condition
Description
Value Format
Comments
Activity Status
[appt_status]
Checks activity
status
started,
completed,
suspended, etc.
Case-insensitive
Suggested functions: IN, NOT IN
Account Number
[customer_number]
Checks the account
number
Text value
Activity Type
[appt_type]
Checks the activity
type
regular, reopened, Case-insensitive
prework
Suggested functions: IN, NOT IN
Activity Time of
Assignment
[atime_of_assignment]
This condition allows
to check the time of
activity assignment.
The time is checked
in a time zone of the
resource, to which
activity is assigned.
YYYY-MM-DD
HH24:MI:SS
Suggested functions: IS NULL, IS
NOT NULL, CONTAINS, DOESN'T
CONTAIN,<, >
Example:
Condition: 'Time of assignment'
CONTAINS '2012-05-21'
Result: blocks all activities that
were assigned during '2012-05-21'
Condition: 'Time of assignment' <
'2012-05-21'
Result: blocks all activities that
were assigned before '2012-05-21'
Confidential || Oracle
Page 65 of 79
Notification Module Description
Blocking Conditions
Condition
Description
Value Format
Comments
Activity Time of Booking
[atime_of_booking]
This condition allows
to check the time of
activity booking.
The time is checked
in the time zone of
the resource, to
which activity is
assigned.
YYYY-MM-DD
HH24:MI:SS
Suggested functions: IS NULL, IS
NOT NULL, CONTAINS, DOESN'T
CONTAIN,<, >
Activity Type
[aworktype]
Checks the activity
work type
IDs of activity
types
Address [caddress]
Checks the activity
address
Text value
Calendar Days from
Activity Assignment
[calendar_days_from_ac
tivity_assignment]
It is calculated as the 0, 1, 2,...
number of calendar
days from the
activity assignment
date to the current
date of the resource.
Note: both dates
have the same time
zone difference.
Suggested functions: IN, NOT IN,
<, <=, >, >=
It is calculated as the 0, 1, 2,...
number of calendar
days from the date
of the activity
booking to the
current date of the
resource the activity
is assigned to.
Note: both dates
have the same time
zone difference.
Suggested functions: IN, NOT IN,
<, <=, >, >=
This condition allows IDs of capacity
to select activities
categories
that belong to the
given capacity
category.
The same rules apply
as in Quota
Management.
Suggested functions: IN, NOT IN
Calendar Days from
Activity Booking
[calendar_days_from_ac
tivity_booking]
Capacity Categories
[activity_capacity_categ
ories]
City [ccity]
Coordinate Status
[acoord_status]
Page 66 of 79
Checks the city of
the activity location
Checks the current
coordinate status –
whether or not the
Example:
Condition: 'Time of booking'
CONTAINS '2012-05-21'
Result: blocks all activities that
were booked during '2012-05-21'
Condition: 'Time of booking' <
'2012-05-21'
Result: blocks all activities that
were booked before '2012-05-21'
Text value
found, not_found,
invalid
Confidential || Oracle
The system allows to use both
activity types and their groups in
this condition.
Example:
Condition: 'Calendar days from
activity assignment' <= 1
Result: blocks all activities that
were assigned yesterday (1) or
today (0)
Example:
Condition: 'Calendar days from
activity booking' <= 1
Result: blocks all activities
booked/created yesterday (1) or
today (0)
IN – activity belongs to all provided
categories
NOT IN – activity belongs to none
of the categories provided in the
list
Blocking Conditions
Condition
Notification Module Description
Description
Value Format
Comments
activity coordinates
were found
Coordinate X [acoord_x] Checks the longitude Longitude
of the activity
location
Example: '37.40562', '-79.42639'
Coordinate Y
[acoord_y]
Example: '-22.831438'
Checks the latitude
of the activity
location
Latitude
Days from Activity
It is the number of
0, 1, 2,...
Assignment
days elapsed since
[days_from_activity_assi activity assignment.
gnment]
It is calculated as the
number of full days
between the time of
activity assignment
and the current time.
Suggested functions: IN, NOT IN,
<, <=, >, >=
Example:
Condition: 'Days from activity
assignment' = 0
Result: blocks all activities assigned
within last 24 hours
If the current time is '2012-09-27
08:28:22', the condition will return
the activity that was assigned on
'2012-09-26 19:17:00'.
Days from Activity
It is the number of
0, 1, 2,...
Booking
days elapsed since
[days_from_activity_boo activity booking.
king]
It is calculated as the
number of full days
between the time of
activity booking and
the current time.
Suggested functions: IN, NOT IN,
<, <=, >, >=
Example:
Condition: 'Days from activity
booking' = 0
Result: blocks all activities booked
within last 24 hours
If the current time is '2012-09-27
08:28:22', the condition will return
the activity booked on '2012-09-26
19:17:00'.
Days to Activity
[days_to_appt]
Returns the number
of days from the
message creation to
the activity
Activity Scheduled?
[is_activity_scheduled]
Checks if the activity
is scheduled
Suggested functions: IN, NOT IN
0, 1, 2, 3,...
1, <empty>
Suggested functions: IS NULL, IS
NOT NULL
Note: this condition cannot be
used in the 'cancel activity'
scenario.
This constraint is related to the
two-phase nature of the 'Cancel
non-scheduled activity' action.
This action consists of two steps:
– making activity 'scheduled'
(moving it to the current day)
Confidential || Oracle
Page 67 of 79
Notification Module Description
Condition
Description
Blocking Conditions
Value Format
Comments
– performing the 'cancel' action.
According to this scenario the
trigger is invoked when the activity
is already 'scheduled'.
Therefore, the condition is always
'False'.
Message Language
[clanguage]
Checks the language Language IDs
of the message to be
sent to the customer
Multi-Day Activity
[multiday_activity]
Checks if the activity 1, 0
is of a type with the
'Multi-day activity'
feature enabled
Name [cname]
Checks the customer Text value
name
Not Ordered Activity
[all_day_flag]
Checks if the activity 1, <empty>
is not ordered
Pending Activity Order
Checks the offset of
[pending_activity_order] a pending activity
from the start of the
route, to which this
activity belongs.
-1, 0, 1, 2,...
Suggested functions: IS NULL, IS
NOT NULL
Note: this condition is true for both
multi-day activities and multi-day
activity segments which can be
distinguished by the value of the
'Type' field. For multi-day activities
the 'Type' value is
'multiday_activity', while for
segments it is
'multiday_activity_segment'.
Suggested functions: IS NULL, IS
NOT NULL
Suggested functions: IN, NOT IN,
<, <=, >, >=
The following logic applies:
– "1..." pending ordered activity in
the route (offset from the route
start)
– "1" pending ordered in the bucket
– "1" pending ordered nonscheduled activity
– "-1" pending not ordered activity
– "0" started, completed, canceled,
notdone, suspended activity
Example:
Condition: 'Pending activity order'
=1
Result: blocks the first pending
activity in the route
Phone [phone]
Checks the
customer's phone
number
Text value
Email Address [email]
Checks the
customer's email
address
Text value
Page 68 of 79
Confidential || Oracle
This block also takes into account
whether the contact can be used
with messages.
Blocking Conditions
Notification Module Description
Condition
Description
Value Format
Cellular Phone [cell]
Checks the
customer's cell
number
Text value
Points [apoints]
Checks the number
of points assigned to
the activity
Integer value
Position in Route
[position_in_route]
Checks the activity
position in the route
Reminder
[cmessagetime]
Checks the number
Integer value
of minutes before
the 'Notification
base' when reminder
notification is to be
generated
SLA Start
[sla_window_start]
Checks the start of
the activity SLA
window start
YYYY-MM-DD
HH24:MI:SS
SLA End
[sla_window_end]
Checks the end of
the activity SLA
window
YYYY-MM-DD
HH24:MI:SS
Service Window End
[service_window_end]
Checks the end of
the activity service
window
HH24:MI
Service Window Start
[service_window_start]
Checks the start of
the activity service
window
HH24:MI
Start [ETA]
Checks if the activity YYYY-MM-DD
has ETA
HH24:MI:SS
State [cstate]
Checks the area
name of the activity
(state, county, land,
etc.)
Time Slot [time_slot]
Checks the label of
the activity time slot
Time Zone [c_zid]
Checks the activity
time zone
Time Notified
[time_delivered]
Checks the start time HH24:MI
of arrival interval
communicated to the
customer
Comments
0, 1, 2,...
Suggested functions: IS NULL, IS
NOT NULL
Text value
Time zone IDs
Suggested functions: IS NULL, IS
NOT NULL
This condition works both for a
single activity and a visit.
If the message is based on a visit,
it refers to the visit's field instead
of the activity's field.
Travel Area [atravelarea] Checks the activity
travel area
Travel area IDs
Traveling Time [travel]
Integer value
Checks the travel
time from the
previous
activity/location to
the current activity
Confidential || Oracle
Page 69 of 79
Notification Module Description
Blocking Conditions
Condition
Description
Value Format
Comments
Work Order
[appt_number]
Checks the activity
order ID
Text value
Example: 'NR728292'
Work Skill
[activity_workskills]
This condition allows
to check the activity
work skills.
Work skill IDs
Suggested functions: IS NULL, IS
NOT NULL, IN, NOT IN
The following logic applies:
– IS NULL – activity doesn't require
any work skills
– IS NOT NULL – activity requires
at least one work skill
– IN – activity requires ALL the
provided work skills
– NOT IN – activity requires none
of the provided work skills
Groups of work skills
are also supported.
In this case a group
is handled as any
work skill it includes.
Example:
Activity #1 work skills: 'Install
IPTV' (1), 'English' (10)
Activity #2 work skills: 'Install
IPTV' (1), 'Spanish' (11)
Condition: 'Activity work skill' IN
(1)
Result: 'Activity #1', 'Activity #2'
Condition: 'Activity work skill' IN
(1, 10)
Result: 'Activity #1'
Condition: 'Activity work skill' NOT
IN (1, 10)
Result: <NONE>
ZIP/Postal Code [czip]
Checks ZIP (postal
code)
Text value
Time Delivered End
[ctime_delivered_end]
Checks the end time YYYY-MM-DD
of arrival interval
HH24:MI:SS
communicated to the
customer
Suggested functions: IS NULL, IS
NOT NULL
Time Delivered Start
[ctime_delivered_start]
Checks the start time YYYY-MM-DD
of arrival interval
HH24:MI:SS
communicated to the
customer
Suggested functions: Is NULL, IS
NOT NULL
Delivery Window End
[delivery_window_end]
Checks the delivery
window end
HH24:MI
Delivery Window Start
[delivery_window_start]
Checks the delivery
window start
HH24:MI
Blocking conditions for inventory:
Condition
Description
Value Format
Changed Inventory ID [inv_change_invid] Checks ID of the changed inventory
IDs of the changed
inventory
Inventory Pool [invpool]
customer, install,
Page 70 of 79
Checks the inventory pool
Confidential || Oracle
Blocking Conditions
Notification Module Description
deinstall, provider
Inventory Type [invtype]
Checks the inventory type
Inventory type IDs
Serial Number [invsn]
Checks the inventory serial number
Text value
Blocking conditions for resource:
Condition
Description
Value Format
Date Format [pdate_fid]
Checks the date format of the
resource
Date/time format IDs
Email Address [provider_email]
Checks the resource's email
address
Text value
External ID [external_id]
Checks the resource's external ID Text value
Message Language [planguage]
Checks the language set for the
resource
Language IDs
Name [pname]
Checks the resource's name
Text value
Phone [provider_phone]
Checks the resource's phone
number
Text value
Resource Type [provider_type]
Checks resource's type
IDs of resource types
Routing Profile [p_rprid]
Checks ID of the routing profile
assigned to the resource
IDs of the routing profiles
Status [pactive]
Checks the resource's status
(whether the resource is active)
Suggested functions: IS NULL, IS
NOT NULL
1, 0
Time Format [ptime_fid]
Checks the resource's time
format
Date/time format IDs
Time Zone [time_zone]
Checks the time zone assigned to
the resource
Time zone IDs
Blocking conditions for service request:
Condition
Description
Value Format
Request Type
Checks the service
[service_request_type] request type
ID of the service request types
Blocking conditions for route:
Condition
Description
Value Format
Suggested Functions
Activated
[activated]
Checks if the route is activated
YYYY-MM-DD HH24:MI:SS IS NULL, IS NOT NULL
Deactivated
[deactivated]
Checks if the route is deactivated YYYY-MM-DD HH24:MI:SS IS NULL, IS NOT NULL
Reactivated
[reactivated]
Checks if the route is reactivated
YYYY-MM-DD HH24:MI:SS IS NULL, IS NOT NULL
Confidential || Oracle
Page 71 of 79
Notification Module Description
Blocking Conditions
Blocking conditions for visit:
Condition
Description
Value Format
Comments
Based on Visit
[is_visit]
This condition allows to
determine if the message is
related to a visit.
1, <empty>
Suggested functions: IS
NULL, IS NOT NULL
Visit Status
[visit_status]
This condition allows to check
pending, started,
the current visit status.
canceled, notdone,
It is mainly intended for the PAS completed
scenario.
Suggested functions: IS
NULL, IS NOT NULL, IN,
NOT IN
Blocking conditions for user:
Condition
Description
Value Format
User Type [user_type_label]
Checks if the user which created the
message belongs to the specified user
type
Labels of user types
Blocking conditions for shifts and calendars:
Condition
Description
Value Format
Calendar Record Type
[calendar_record_type]
Checks the type shift, extra_shift,
of the 'regular'
working,
calendar record extra_working, nonworking
Suggested
functions:
IN, NOT IN
Non-Working Reason
[calendar_non_working_reason]
Checks the
'regular' nonworking reason
On-Call Calendar Record Type
[calendar_oncall_record_type]
Checks the type shift, extra_shift,
of the 'on-call'
working,
calendar record extra_working, nonworking
Suggested
functions: IN,
NOT IN
IDs of the nonworking reasons
On-Call Non-Working Reason
Checks the 'on[calendar_oncall_non_working_re call' nonason]
working reason
IDs of the nonworking reasons
On-Call Shift
[calendar_oncall_shift]
Shift IDs
Checks the 'oncall' shift
On-Call Work Schedule
Checks the 'on[calendar_oncall_work_schedule] call' work
schedule
IDs of the work
schedules
Shift [calendar_shift]
Checks the
'regular' shift
Shift IDs
Work schedule
[calendar_work_schedule]
Checks the
'regular' work
schedule
IDs of the work
schedules
Page 72 of 79
Confidential || Oracle
Comments
The calendar is retrieved for
the date of the corresponding
route (if applicable), or the
service request.
Blocking Conditions
Notification Module Description
Other blocking conditions:
Condition
Description
Value Format
Day of Week
[day_of_week]
Checks the day of sun, mon, tue, wed,
the message
thu, fri, sat
Comments
Suggested functions: IN, NOT IN
Case-insensitive
Interface [interface]
Checks the
interface where
the message was
created
web, soap, wap,
xhtml, file_upload
These conditions
are mainly
intended to be
used in the
'move' scenario.
1, <empty>
Message Day
[message_day]
Checks if the day
of the message is
a holiday
holiday, regular
Previous Message Data
[prev_data]
These conditions
allow to check the
status/description
/data of the
previous
message.
new, sending, failed,
sent, delivered,
falsemethod,
obsolete
Day changed?
[is_day_changed]
Resource changed?
[is_provider_changed]
Previous Message
Description [prev_desc]
Previous Message Status
[prev_status]
property
Checks the
property value for
an entity related
to the message.
It supports
resource, activity,
inventory, and
support request
properties.
Case-insensitive
The interface will be empty if the
message is initiated by the server.
Suggested functions: IS NULL, IS
NOT NULL
Note: these conditions cannot be
used to detect the
move/reschedule actions for the
'Add' trigger messages.
Case-insensitive
Suggested functions: IN, NOT IN
These conditions can be used to
implement the following
condition:
all 'failed' except
'failed/INVALID_PHONE_NUMBER'
Format according to
a property type.
Note: use 'index'
values for
enumeration
properties, rather
than their
translation.
In addition to the blocking conditions, the system allows to block/shift messages that fall on a nonworking day or a holiday. This functionality is configured in the 'Settings' tab of the 'Add notification
scenario step' window.
11
PAS: Submitting Survey Results
Post appointment surveys are part of Oracle Field Service Customer Communication Cloud Service and
are intended to collect customer feedback upon the activity completion.
The following parameters of the post appointment surveys can be configured in the system:
•
survey – a set of questions. It should be linked to the corresponding 'Customer' step of a PAS
Confidential || Oracle
Page 73 of 79
Notification Module Description
PAS: Submitting Survey Results
message scenario
•
survey_question – a definition of a particular question. Questions are identified by labels. The
following types of questions are supported: 'Checkbox', 'Checkbox group', 'Input area', 'Input
text', 'Radio group'
•
survey_answer – a definition of a particular option that can be selected as an answer to the
question: 'Checkbox group', 'Radio group'). Answers are identified by labels
•
survey_take – a set of answers related to a particular message and survey. This record is inserted
at an attempt to send a PAS message
•
survey_result – an answer to a particular survey question submitted as the result of the message
processing.
Configuration of the post appointment surveys can be done in the 'Surveys' screen in Manage.
The system allows to use several different sets of PAS questions for different steps/scenarios within the
same company.
A created survey can be linked to a PAS message step (Recipient = 'Customer', Method = 'External
System').
PAS results should be submitted from the External System Agent as a part of the 'data' field. This
approach is the same as described in the 'Setting Properties Based on Message Status Recieved from
Agent' section.
Format
The questions (labels) and the corresponding answers (labels or values depending on the question type)
are passed in the 'data' field.
The '#params?' string is used as the delimiter between the 'data' itself and the passed parameters. The
format of the parameter line is similar to URL. The "&" character is used as the delimiter between
different parameters.
Example:
PAS survey:
•
q1: Radio group (Y: Yes, N: No, O: Other)
•
q2: Checkbox (1: Confirmed, 0: Not confirmed)
•
q3: Checkbox group (IN: Install, DE: Deinstall, R: Repair, TC: Trouble call)
•
q4: Input text
PAS result:
data = OK#params?q1=Y&q2=1&q3=IN&q3=TC&q3=R&q4=reschedule
Page 74 of 79
Confidential || Oracle
Appendix: Message Examples
Notification Module Description
Appendix: Message Examples
Inventory Blocks
Deinstall inventory:
<external_id>{resource_external_id}</external_id>
<cust_number>{activity_customer_number}</cust_number>
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<ETA>{activity_start_time}</ETA>
<aworktype>{activity_worktype_label}</aworktype>
<deinstalled_inventory>
<inventory>
<invsn>{inventory_serial_number}</invsn>
<invtype>{inventory_type}</invtype>
<eta_inventory_id>{invid}</eta_inventory_id>
<status>{invpool}</status>
</inventory>
</deinstalled_inventory>
Install inventory:
<external_id>{resource_external_id}</external_id>
<cust_number>{activity_customer_number}</cust_number>
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<ETA>{activity_start_time}</ETA>
<aworktype>{activity_worktype_label}</aworktype>
<installed_inventory>
<inventory>
<invsn>{inventory_serial_number}</invsn>
<invtype>{inventory_type}</invtype>
<status>{invpool}</status>
<resource_id>{inv_pid}</resource_id>
<eta_inventory_id>{invid}</eta_inventory_id>
</inventory>
</installed_inventory>
Message Examples
'Start Activity' Message Example:
<acoord_x>{activity_coordx}</acoord_x>
Confidential || Oracle
Page 75 of 79
Notification Module Description
Message Examples
<acoord_y>{activity_coordy}</acoord_y>
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<aworktype>{activity_worktype_label}</aworktype>
<caddress>{activity_address}</caddress>
<cphone>{activity_phone}</cphone>
<ccity>{activity_city}</ccity>
<cemail>{activity_email}</cemail>
<date>{destination_date}</date>
<eta>{activity_start_time|%F %H:%M}</eta>
<external_id>{resource_external_id}</external_id>
<activity_time_slot_label>{activity_time_slot_label}</activity_time_slot_label>
<user_name>{user_name}</user_name>
'Delay Activity' Message Example:
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<aworktype>{activity_worktype_label}</aworktype>
<caddress>{activity_address}</caddress>
<ccity>{activity_city}</ccity>
<date>{destination_date}</date>
<eta>{activity_start_time|%F %H:%M}</eta>
<external_id>{resource_external_id}</external_id>
<delay_comments>{pr_delay_comments}</delay_comments>
<delay_reason>{pr_delay_reason}</delay_reason>
<user_name>{user_name}</user_name>
'Cancel Activity' Message Example:
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<aworktype>{activity_worktype_label}</aworktype>
<caddress>{activity_address}</caddress>
<ccity>{activity_city}</ccity>
<cphone>{activity_phone}</cphone>
<cemail>{activity_email}</cemail>
<date>{destination_date}</date>
<external_id>{resource_external_id}</external_id>
<cancel_reason>{pr_cancel_reason}</cancel_reason>
<cancel_notes>{pr_cancel_notes}</cancel_notes>
<user_name>{user_name}</user_name>
'Notdone Activity' Message Example:
Page 76 of 79
Confidential || Oracle
Message Examples
Notification Module Description
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<aworktype>{activity_worktype_label}</aworktype>
<cname>{activity_customer_name}</cname>
<caddress>{activity_address}</caddress>
<ccity>{activity_city}</ccity>
<czip>{activity_zip}</czip>
<cstate>{activity_state}</cstate>
<cphone>{activity_phone}</cphone>
<date>{destination_date}</date>
<eta>{activity_start_time|%F %H:%M}</eta>
<end_time>{activity_end_time|%F %H:%M}</end_time>
<external_id>{resource_external_id}</external_id>
<work_skills><BLOCK
type="activity_workskills">{activity_workskill_label},</BLOCK></work_skills>
<not_done_notes>{pr_not_done_notes}</not_done_notes>
<not_done_reason>{pr_not_done_reason}</not_done_reason>
<activity_time_slot_label>{activity_time_slot_label}</activity_time_slot_label>
<user_name>{user_name}</user_name>
'Suspend Activity' Message Example:
<appt_number>{activity_number}</appt_number>
<aid>{aid}</aid>
<astatus>{activity_status}</astatus>
<aworktype>{activity_worktype_label}</aworktype>
<caddress>{activity_address}</caddress>
<ccity>{activity_city}</ccity>
<date>{destination_date}</date>
<eta>{activity_start_time|%F %H:%M}</eta>
<end_time>{activity_end_time|%F %H:%M}</end_time>
<external_id>{resource_external_id}</external_id>
<suspend_notes>{pr_suspend_notes}</suspend_notes>
<suspend_reason>{prnum_suspend_reason}</suspend_reason>
<activity_time_slot_label>{activity_time_slot_label}</activity_time_slot_label>
<user_name>{user_name}</user_name>
'Complete Activity' Message Example:
<MessageItem>
<ActivityId>{aid}</ActivityId>
<LegacyServiceId>{activity_number}</LegacyServiceId>
<CustomerId>{activity_customer_number}</CustomerId>
<CustomerZip>{activity_zip}</CustomerZip>
<ActivityStatus>{activity_status}</ActivityStatus>
<ActivityType>{activity_worktype_label}</ActivityType>
Confidential || Oracle
Page 77 of 79
Notification Module Description
Message Examples
<ScheduleDate>{route_date}</ScheduleDate>
<BeginTime>{activity_start_time|%F %H:%M}</BeginTime>
<EndTime>{activity_end_time}</EndTime>
<DurationInMinutes>{activity_duration}</DurationInMinutes>
<PositionInRoute>{activity_position_in_route}</PositionInRoute>
<TechnicianId>{user_login}</TechnicianId>
<ResourceId>{resource_external_id}</ResourceId>
<ResourceType>{resource_type}</ResourceType>
<EventDateTime>{message_time_of_creation}</EventDateTime>
</MessageItem>
'Complete Activity' Message Example, Different Format:
<values>
<appt_number>{activity_number}</appt_number>
<external_ID>{resource_external_id}</external_ID>
<date>{route_date}</date>
<site_id>{pr_SITEID}</site_id>
<p>
<l>astatus</l>
<v>{activity_status}</v>
</p>
<p>
<l>TECH_DEPARTURE_TIMESTAMP</l>
<v>{pr_TECH_DEPARTURE_TIMESTAMP}</v>
</p>
<p>
<l>JOURNAL_ENTRY_DATE</l>
<v>{message_time_of_creation}</v>
</p>
<p>
<l>JOURNAL_ENTRY_TYPE</l>
<v>Work Log</v>
</p>
<p>
<l>JOURNAL_ENTRY_DESCRIPTION</l>
<v>{pr_JOURNAL_ENTRY_DESCRIPTION}</v>
</p>
<p>
<l>JOURNAL_NOTE_ENTRY</l>
<v>{pr_JOURNAL_NOTE_ENTRY}</v>
</p>
<p>
<l>INCIDENT_CASE_ID</l>
<v>{pr_INCIDENT_CASE_ID}</v>
Page 78 of 79
Confidential || Oracle
Message Examples
Notification Module Description
</p>
<p>
<l>SITEID</l>
<v>{pr_SITEID}</v>
</p>
<p>
<l>INVOICE</l>
<v>{pr_INVOICE}</v>
</p>
<p>
<l>CABLE_FOOTAGE</l>
<v>{pr_CABLE_FOOTAGE}</v>
</p>
<p>
<l>DROP_DIRECT_BURY</l>
<v>{pr_DROP_DIRECT_BURY}</v>
</p>
<p>
<l>CLOSURE_CODE</l>
<v>{prnum_CLOSURE_CODE}{prnum_CLOSURE_CODE1}</v>
</p>
</values>
Confidential || Oracle
Page 79 of 79