Document toolboxDocument toolbox

Escalations

Escalations are automated tasks that execute a series of predefined actions once the task is started. The Escalation is initialized by an Event generated from some data change in the system. Escalations are defined by:

  • Start Event (required) – Event that begins the Escalation's life cycle
  • Abort Events (optional) – Events that can interrupt the Escalation to prevent unnecessary actions from occurring
  • Sequences (required) – Actions the Escalation takes during its life cycle
  • Criteria (optional) – A means of narrowing down the conditions under which the Escalation begins

Escalations are useful tools for implementing your Organization's standard policies automatically based on internal PCR-360 activity. For example, if your Organization's policy is for the Customer Service Manager to be notified whenever a new Incident is created, then your Organization could create a special Escalation looking for the "New Incident Created"  built-in PCR-360 Event and set the Escalation to notify the Manager using an Escalation Sequence. In addition to the built-in Events and Notifications, PCR-360 allows the use of custom-made Events and Notifications to implement other possible ways to use Escalations to make your Organization's experience with PCR-360 easier. This article will be a step-by-step process in Creating and Managing Escalations.

If you would like help setting up Escalations, please contact Professional Services.

Adding an Escalation

Escalations Grid example

Navigate to the Escalations grid by going to Admin > Escalations / Notifications > Escalations.

Add New Escalation form example

To add a new Escalation, click the Add button located on the Grid toolbar.

In the Escalation form, must complete the required fields. Enter an "Escalation Name" so that the new Escalation can easily be identified.

Select a "Start Event" from the list of events. The Start Event is the purpose for the Escalation and, when triggered, begins the Escalation's life cycle. For example, a User could select Service Desk Workflow Assigned as the Start Event. In this instance, the Escalation process would begin whenever an SD item's Workflow is assigned to one or more Workers. Notice that the list of possible events includes both System events, those delivered as part of PCR-360 as well as custom Sequence Events which may be created to supplement the base events.

Admins can also select one or more Abort Events. When a specified Abort Event occurs say, "Service Desk Workflow Completed", the Escalation process ends, no further Sequences processes, and no further Notifications are sent. A little later, this article will discuss creating Escalation Sequence Events: Custom Events generated by an Escalation that can be used to abort other Escalations.

Saving the New Escalation

Once all required fields in the Escalation form have been satisfied, click the Save New button. The new Escalation appears as an item on the Escalations grid. If the Escalation is set to "Active", the Escalation commences whenever its Start Event occurs.

Editing Existing Escalation

Users can edit existing Escalations by double-clicking on any item on the Escalations grid or by selecting an item and clicking the Save New button located immediately above the Grid.

In the Escalation form, define the item's inputs by following the protocol established earlier in this section. The 'Start Event' cannot change for an existing Escalation. In order to define an Escalation identical or similar without reproducing all the steps to create it, use the form's Options > Copy to New Form menu to create a copy:
Copy to New Form Menu Option

Admin Users can delete existing Escalations by selecting the appropriate item on the Escalations grid and clicking the  Delete Selected button located immediately above the Grid.

Building an Escalation Sequence

Now the User should add a Sequence of actions that occur once the Escalation process begins. In the 'Add New Escalation' form, see the tab labeled 'Sequence'. To add an action to the Sequence, click the Add button located on the Sequence grid toolbar.

Add New Escalation Sequence form example

In the form complete the Required fields.

The 'Sequence #' determines the order in which each action is performed by the application. For example, if a User were to add three actions to the Sequence and each action had a Sequence # of '100', '200', and '300', the application would execute the '100' action before moving on to the '200', etc. The application lets the User enter arbitrary numbers so they can come back to add Sequences in the middle without having to renumber all the existing ones after it. It is also possible to duplicate the Sequence # to execute two actions simultaneously.

Select a 'Type' of action to define what action is taken for the Sequence:

Generate Incident

A new Incident is added to Service Desk with the supplied CSR, Trouble Code, and Details from this Sequence action.
Add New Escalation Sequence form example

If defining the Type as "Generate Incident", Service Rep and Problem Description fields become available. A good example of a "Generate Incident" notification would be when maintenance for a piece of Inventory is due, an Incident Report can be created so that there is a Notification and Workflow item created to ensure maintenance is started for that item.

Workgroup

Uses the Workgroup from the Service Desk Workflow entry that triggered the Escalation to send Notifications to each person in the Workgroup Sequence tab.
Add New Escalation Sequence form example

If Type is defined as "Workgroup", the User is prompted to select a Notification that is sent. Select a Notification from the list of existing Notifications by clicking on the picker in the Notification field. Available Notifications must match the Escalation's Start Event specified.

Note: For "Workgroup" Type, the selected Notification is sent to all members of the Workgroup on the originating object (Service Desk, Inventory, etc.).

Notify

Sends a selected Notification to a specified list of recipients (Notify To).
Add New Escalation Sequence form example ]
A couple of tips for using this Type:

    1. Leave 'Notify To' field empty to use the Notification's predefined recipients.
    2. If a list of recipients is set here, those recipients are used instead of those set on the Notification.

If Type is defined as either "Notify" the User is prompted to select a Notification that is sent. Select a Notification from the list of existing Notifications by clicking on the picker in the Notification field. Available Notifications must match the Escalation's Start Event specified.

Note: For "Notify" Type, the User must specify who should receive the Notification as it is a Required field.

Esc. Sequence Event

Generate a custom Sequence Event that can abort other Escalations or send out Notifications for specific conditions.
Add New Escalation Sequence form example

Service Host SOAP Escalation

Allows the User to provide raw data structures for a request body to a specific external Host/Method, using the 'Options' field.
Add New Escalation Sequence form example

Service Host REST Escalation

 Allows the User to provide raw JSON data for the request body in the API Options field, to be sent to the external API.

  • POST (Create), PATCH (Change), PUT (Replace), and DELETE are the supported Request Types. By default, Request Type POST will be used.

Add New Escalation Sequence form example

Sequence Events are best used with Criteria so they are only generated when very specific data conditions are met. With these narrowed conditions, more control over aborting certain Escalations or whether to send particular Notifications is provided to an Admin.

Time to Wait (TTW) defines how long the Sequence action waits from the point it is initialized before it executes. For example:

  1. 10:00 : Escalation begins, Sequence 100 has TTW of "5m"
  2. 10:05 : Sequence 100 executes. Escalation increments to Sequence 200 with TTW "15m"
  3. 10:20 : Sequence 200 executes. Escalation increments to 300 with TTW "1h"
  4. 11:20 : Sequence 300 executes. Escalation completes.

Escalation Sequence Events

If the User sets the Type to "Esc. Sequence Event", custom event name is required. Only letters, numbers, and spaces are allowed here. The purpose of a Sequence Event is to make a custom Event that other Escalations can use as one of their Abort Events. Sequence Events can be tricky to understand, but they add even more power to the automation of Escalation actions. This feature needs a little more detail to explain, but it helps to understand Criteria first.

Escalation Criteria

In addition to specifying a series of actions for an Escalation, Users want to restrict the conditions under which those actions are executed. Criteria act as a filter (think of the Grid's Search and Filter mechanisms) that prevent an Escalation from beginning unless the data provided matches its conditions.

On the Escalation form, click the Criteria tab, and click the Add button. On the Criteria form, set a single condition using a piece of Data (that is provided to the Event info) to match against, a Comparison operator, and the Value the data must match to pass and begin the Escalation. Based on the Data field, the Value may be an arbitrary text value, a Picker item, an option from a drop-down, etc.

Escalation Form Data Dropdown

If adding multiple Criteria rows, they are treated with an "AND" connection, meaning all the Criteria must match against the Start Event's data for the Escalation to begin. Be careful constructing Criteria so that they don't end up matching on "nothing" and the Escalation never starts.

Note: If an Escalation is already in progress and the Criteria is altered ( add/change/delete), the changes do not affect the progression of the current instance of the Escalation. Criteria are only tested for starting the Escalation.

Escalation Sequence Events

Sequence Events are most useful when coupled with Criteria (below) so that the custom event is generated when specific conditions for the event's Escalation are met.

There are currently two ways to utilize a Sequence Event once created:

Set it as the Event that generates Notifications. Just as some System Events can automatically generate Notifications (alerting a Worker they have been assigned to a Service Order, sending an Administrator notice when a Purchase Order is approved, etc.), Sequence Events can do the same, utilizing the power of Criteria to generate the Notification to specific conditions. For instance, John Doe requested he not be sent Workflow Assignment emails because he has the Service Desk's "Assigned Workflow" Grid open with an auto-refresh Perspective so he can see new assignments as they come in. Set them as Abort Events on other Escalations. Using System Events to abort an Escalation aborts that Escalation regardless of the situation which is often desirable. However, using Criteria gives control over the conditions under which the Sequence Event is generated so the targeted Escalation only aborts under the defined Criteria. In this use case, the chain of events looks like this:

  • System Event A starts Escalation A that has 3 Sequences.
    • One of the Abort Events for Escalation A is Abort Esc A (defined in Escalation B)
    • Sequence 100 executes, and Sequence 200 is now waiting for its Time To Wait. See Escalation A in the Escalation Log with a Status of 'In Progress'.
  • System Event B is generated and triggered
    • Escalation B is watching for System Event B and, based on the Criteria defined for the Escalation, starts its Sequences
      • Its first Sequence is the Event Abort Esc A with TTW of 0m – it executes immediately.
        • The Sequence Event is triggered: the system looks for any Escalations that should abort because of this custom sequence event. It finds Escalation A is currently running ('In Progress') and waiting to execute Sequence 200.
        • The system marks Escalation A as 'ABORTED', and the Sequence Event completes.
      • Escalation B has no other Sequences, so it is marked COMPLETE.
    • Escalation A Sequence 200 reaches its TTW and attempts to execute
      • The system first checks the status of its Escalation (A) and sees it has been aborted.
        • Sequence 200 is canceled
        • The system does not increment the Sequence for Escalation A. It is finished with Status "Aborted" in the Escalation Log.

Escalation Sequence Events Example

  • A customer emails the Service Desk, and the Inquiry is converted to an Order. The initial Workflow is assigned to Mary.
    • The assignment begins an Escalation ('Workflow Assignment – Action Required') that sends Mary an email.
    • A second Sequence waits 30 minutes before sending a message to her Workgroup Manager.
      • The Escalation already has "Service Desk Item Viewed" selected as an Abort Event. Once anyone opens the Incident, the Escalation stops, and her manager does not get an email.
  • Ten minutes after the Workflow was assigned, the Requester emails again: Please cancel the original request.
    • The CSR opens the Service Desk item and changes its status to "Void".
    • The actual results:
      1. Mary's manager doesn't get an email because the CSR opened the Incident, not Mary.
      2. The Escalation that would send an email to her Manager should be aborted.
      3. Mary should be notified of the Voided item (but only when it's been VOIDED, not just that its status changed).

However, there is a problem here. Anyone who opens the Incident cancels the Escalation, even if it's just the CSR making minor edits. Mary's manager won't get an email if she lets it go too long. Don't remove the Abort Event altogether. The 'Viewed' event should abort this Escalation for a specific person viewing the Incident, Mary. What is desired here is to abort it if the CSR goes in and Voids the Incident, but only for that Status change.

How to accomplish these? Sequence Events. Set up other Escalations with Criteria to generate an event when the SD Status changes specifically to 'Void' or when the person viewing the Incident is specifically Mary. Two other Escalations are needed for this because the conditions needed are exclusive from each other.

  1. Add a new Escalation:
    • Name it "Abort for SD Status Void".
    • Select the ServiceDesk Item Status Changed for the Start Event.
  2. Add a new Sequence:
    • Select a Type of "Esc. Sequence Event".
    • Name the event "SD Item Voided".
    • Set the Time-To-Wait to 0m. This causes it to trigger as quickly as possible.
  3. Save & Close the form.
  4. This Escalation generates the Custom Event any time a Service Desk Item's Status changes. On the Criteria tab, add a new Criteria:
    • Give it a Description like "SD Status is Void".
    • From the Data list, select "SD_STATUS". Use the Equals Comparison option.
    • When the SD Status Value list updates, select "Void".
    • Save the Criteria.
  5. Save and Close this Escalation.

Now, any time a Service Desk Item's Status is changed specifically to 'Void', this Escalation begins. Its only Sequence generates the custom "SD Item Voided" event. Now, make sure the manager's email is only sent if Mary doesn't view the Incident she's assigned.

  1. Click the Add button to start another new Escalation:
    • Name it "Abort for Assigned Worker Viewed".
    • Select "Service Desk Item Viewed" as the Start Event.
  2. Add a Sequence:
    • Name it "Worker Viewed SD Item".
    • Select Type Esc. Sequence Event.
    • Name it "Assigned Worker Viewed SD Item".
    • Set Time To Wait to 0m to make it trigger as soon as possible.
  3. Save and Close the Sequence form.
  4. Click the Criteria tab the click the Add button to start a new Criteria:
    • Give it a Description like "Viewed By Assigned Worker".
    • From the Data list, select the "global" variable "EVENT_CONTACT" – this is the person who initiated the event. In the case of this Escalation, it is the person who viewed the SD Item.
    • Select 'Equals' from the Comparison list.
    • To make this custom Event more reusable, use another Hash Variable for the comparison value rather than specifically picking Mary. Type "##" in the value input and choose "##SDWF_WORKER##". This represents the "Service Desk Workflow Worker" Contact to match the person who viewed the SD Item (EVENT_CONTACT).
  5. Save and Close the Criteria.
  6. Save and Close the Escalation.

Now, use these specialized Sequence Events:

  1. Open the Escalation to abort using the custom sequence event. In our example, "Workflow Assignment – Action Required".
  2. On the Abort Events list, scroll to the bottom. There will be a group called "Esc. Sequence Events" with the new custom events listed. Check them and uncheck the generic "Service Desk Item Viewed" event because more specific conditions are required to abort this Escalation.
  3. Save and Close the Escalation.

There are now two custom events that can cancel this Escalation: one is a System Event, and the other is custom-generated from an Escalation using Criteria.

Exchanging Data With External Data Stores (REST)

Service Host REST Escalations are Specialized Escalation Sequences that can be used to interface with outside data sources. Read more here: Exchanging Data With External Data Stores.

Setting Up Escalations To Utilize The Service Host
Service Host REST Escalation Setup

Add New Escalation form example

This is a sample Escalation that will use the Service Host set up previously. It will execute using the "New Estimate Created" Event. Add a single Sequence and a single Criteria that must match for the Escalation to execute at all.

  1. Go to Admin > Escalations / Notifications > Escalations.
  2. Open a new Escalation.
  3. Select a Start Event before adding Sequences. This is to help the Sequence form know what 'Data Variables' it can use. Select "New Estimate Created" as the Start Event.
  4. Open a new Sequence on the Sequence tab. Set the Sequence # "10", and Time To Wait "0m".
  5. Select "Service Host REST Escalation" from the Type list.
  6. When the form updates, choose the Service Host to use ("Sample REST Host" in the example above).
  7. Set the "Host API Path". This will be the part of the URL that differs from one command to another.
    1. If the API uses a query string (as described above), do not include it in the Host API Path.
    2. If there is no additional path to the API URL, enter "/" as the API Path value.
  8. Set the "Request Type" to match the type of request to make.
    • POST (Create)
    • PATCH (Change)
    • PUT (Replace)
    • DELETE
  9. In the "API Options" use the JSON editor to define the request to be sent to the API. This is a map of field names the API expects with values from PCR-360.
    Compare this sample to the "Add Order" command from our Service Host example:
    Manage Escalation Sequence form example
    Users can also use items from the "Available Template Data" list to append variable placeholders to the Value to send. These variables (formatted as ##VARIABLE_NAME##) will be replaced with the actual value from the Event when the Sequence is executed. The selected item from the list will always be inserted at the current cursor position in the editor, but can be cut/paste them to other positions in the text as needed.
  10. UDFs are also supported in the Event Variables that can be added to the API Value. When selecting one, there will be a variable name like ##UDF_12345## instead of the label. This ensures the unique UDF ID is used for looking up the correct value to replace the variable with. Should we use a label, and the label changes or contains errant characters, the variable substitution would fail.
  11. Save the Sequence and close the Sequence form. To use this Escalation to perform other tasks, including other calls to the same or other APIs, set up separate Sequences for those actions.
  12. Click the Criteria tab and open a new Criteria. However, notice UDFs that apply to the data object the Start Event is generated from are available in the list of data Criteria to can check before the Escalation begins its work. There are also additional Comparison types to choose from for better refinement of acceptable data conditions.
    Add new Escalation Criteria form example
  13. Save a Criteria if desired.
  14. Finally, save the new Escalation.

With this sample, when a new Estimate is created in Service Desk, this Escalation will check any Criteria set in place. If ALL of the criteria pass, the Sequence(s) will execute, sending data to the API set up in Service Hosts.

Service Host SOAP Escalation Setup

Manage Escalation form example

This is a sample Escalation that will use the Service Host set up previously. It will execute using the "New Service Request Created" Event. Add a single Sequence and a single Criteria that must match for the Escalation to execute at all.

  1. Go to Admin > Escalations / Notifications > Escalations
  2. Open a new Escalation.
  3. Select a Start Event before adding Sequences. This is to help the Sequence form know what data variables it can use. Select "New Service Request Created" as the Start Event.
  4. Open a new Sequence on the Sequence tab. Set the Sequence # "10", and Time To Wait "0m".
  5. Select "Service Host SOAP Escalation" from the Type list.
  6. When the form updates, choose the Service Host to use ("Sample REST Host" in the example above).
  7. Set the "Target Host". This will define the Service Host that is going to be interacting with this Escalation.
  8. Set the "Target Method". This will define what endpoint the Escalation is going to be sent to.  The expected fields to be sent will be automatically populated.
    Add New Escalation Sequence form example
  9. Fill in the "API Options" to be sent to the endpoint.
  10. Save the Sequence and close the Sequence form. To use this Escalation to perform other tasks, including other calls to the same or other endpoints, set up separate Sequences for those actions.
  11. Click the Criteria tab and open a new Criteria. This operates the same as previous versions. Notice that UDFs which apply to the data object the Start Event is generated from can be found in the list of data Criteria that can be checked before the Escalation begins its work. There are also additional Comparison types to choose from for better refinement of acceptable data conditions.
    Add new Escalation Criteria form example
  12. Save a Criteria if desired.
  13. Finally, save the new Escalation.

With this sample, when a new Service Request is created in Service Desk, this Escalation will check any Criteria set in place. If ALL of the Criteria pass, the Sequence(s) will execute, sending data to the endpoint set up in Service Hosts.

Escalations Log

To monitor Escalation activity on the Escalation Log Grid navigate to Admin > Escalations / Notifications > Logs > Escalations Log.

Viewing Results

Go to Admin > Escalations / Notifications > Logs > Esc. Sequence Log.

A User can review the results of all Escalation Sequences here. Double-click a Log item to open it, the result data is laid out as a JSON object with various information about the Sequence execution. For an API Sequence, "curlResponse", "curlInfo", and "curlError" message keys are present. These can help identify problems in the setup of the Service Host or Escalations, or indicate successful execution of sending data to the API. Currently, no processing is done to the response data sent back from the API. It is simply logged here for reference.

Escalation Log example


Build an Escalation

To build an Escalation that will use a Notification:

  1. Go to Admin > Escalations/Notifications > Escalations.

  2. Click the Add button to open the Escalation builder form:

    Add New Escalation form example
  3. In the Escalation form, fill in the Required fields:

  4. Escalation Name: Give the Escalation a meaningful name.

  5. "Workflow Assigned & Manager Follow-up".

  6. Start Event: Select a System, User-Defined, or SNMP Event that will begin the Escalation.

  7. Must match the Event for the Notification we'll use: "ServiceDesk Item Workflow Assigned".

  8. Add an Abort Event:

  9. From the Abort Events list, check "'"

  10. Sequences: On the Sequences tab, add at least 1 Sequence:

  11. Click the Add button on the grid's toolbar

  12. Fill in required fields:

  13. Sequence #: Any positive integer used to set the order of Sequence execution.

  14. Type: The type of action taken by the Sequence. (described here)

  15. Time To Wait: A time duration (e.g "1h 20m", "1h", "20m", "1", "1.5") that determines how long the Sequence waits to be executed on its turn.

  16. Depending on the Type you select, other Required and optional fields will appear.

  17. Click the Save New button.

  18. Continue adding Sequences by making changes in the form and clicking the smaller Save New button, or close the form.

  19. Close the form.


Build an Escalation with a Sequence Event

  1. On the Escalations screen, click the Add button to open the Escalation builder form:

  2. Fill in the required fields in the header area:

    1. Escalation Name: "Abort Escalations on SD Void"

    2. Start Event: "ServiceDesk Item Status Changed"

  3. Add a Sequence by clicking the Add button on the Sequence tab's grid.

    1. Set Sequence # of "100"

    2. Select Esc. Sequence Event as the Type

    3. Set a Time To Wait of "5m"

    4. Give the Event a unique name (all Sequence Events must have unique names from each other, regardless whether they appear on different Escalations)

      • "SD Item Voided"

    • NOTE: You may combine Sequence Events with other Sequence items, but keep in mind when using the Sequence Event to abort a different Escalation, timing of execution is a factor.

  4. Save the Sequence & close the Sequence form.

  5. Leave the Escalation form open for the next section.

Adding Criteria to the Escalation

Criteria narrow the conditions that allow an Escalation to begin its Sequence of actions by examining pieces of data from the triggering Event.

Sequence Events are most effective when coupled with Criteria, so you can narrow down the conditions that will generate the custom Event.

  1. Click the Criteria tab & click the Add button on the grid.

    • Description: "ServiceDesk Status VOID"

    • Data: select "SD_STATUS"

    • Comparison: select "Equal"

    • Sd Status Value (appears when you choose the Data option): select "Void".

    • Save the Criteria & close the Criteria form.

  2. Save the Escalation & close the Escalation form.

Using the Escalation Sequence Event

As An Abort Event

When the "Abort Escalations on SD Void" Escalation is started by a Service Desk status change of Void, the custom event will be generated. When that is triggered, it will find any running instances of "Worker Assigned Workflow Message" and mark them to abort.

  1. Re-open the "Worker Assigned Workflow Message" Escalation (double-click or single-click and click the Edit Selected button).

  2. Click the Abort Events list and scroll to the bottom. You'll see the custom "SD Item Voided" Event. Check it.

  3. Save the Escalation & close the form.

As A Notification Event

When the "Abort Escalations on SD Void" Escalation is started by a Service Desk status change of Void, it will send out this Notification. If you've also used the Sequence Event to abort other Escalations, both actions will occur.

You can send Notifications using the Sequence Events, but to do so you'll have to create a new Notification or make a copy of an existing one, because an existing Notification's Event designation can't be changed.

  1. Go to Admin > Escalations/Notifications > Notifications.

  2. Click the Add button or

    1. Double-click an existing to edit.

    2. Click theOptionsmenu, then "Copy to New Form".

  3. Open the Event list and find your Sequence Event at the bottom.

  4. Select it, complete the rest of the Notification, and click the Save New button.

With Custom Events

Escalations can be used with Custom Events, as well as the predefined System Events. For information on creating your own Events, see the article on Custom Events in this wiki.

Build an Escalation for interacting with a REST API

Using Escalations, your Organization can set up an interaction with an external REST API Endpoint.

  1. Create a Service Host for the REST API your Organization wants to communicate with.
    New Service Host Example

  2. Create an Escalation to trigger the REST API. (This Example is using a QuickTick to communicate with the external REST API)
    Escalation Example

  3. Add a Sequence to the Escalation.
    Add New Escalation Sequence Example

  4. Set the Escalation to Active and save.

  5. Create a Custom Event to handle the response data.

  6. Create an Escalation that will trigger from the event Escalations -> Response Received from Escalation REST API.

    Escalation Example
  7. Add a Sequence to the Escalation to refer the response data to a Custom Event.
    Add New Escalation Sequence Example

  8. Set the Escalation to Active and save it.

Once this is complete, whenever the Escalation triggered within PCR-360 occurs, data will be sent to the External REST API Endpoint, and it's response will be handled by a second Escalation. This creates a new communication point between PCR-360 and an external service your Organization desires to add.