Open topic with navigation

Action Framework - Customer Actions

Introduction

Customer actions (also called Data Object actions or Unit actions) are system actions which are either triggered manually or by a certain incident concerning a customer, i.e. a customer is deleted or a customer is modified. Customer actions are components of the ConSol CM Action Framework. They can be performed for a customer, i.e., a contact or a company. The actions can be performed automatically by the system or manually, triggered by an engineer (via Web Client) who has the required permissions. You might want to apply customer actions for use cases like the following:

• Load additional data into a company's data set.
• Build an automatic report about company-specific KPIs.
• Transfer ConSol CM data to another system (e.g., an ERP system).
• Create/update a Google Maps (see Trademarks) link within the address data.

You can use the following types of customer actions:

• Automatic actions which are performed by the system after one of the following customer operations:
  • CREATE
  • UPDATE
  • DELETE
  • RELATION
  • SEARCH
• Manual actions which are performed by an engineer using Activities links in the customer page (company or contact page) of the Web Client (similar to Workflow activities for tickets). Which actions are available for manual execution depends on the customer which is currently being displayed, i.e., when the company page is open, company actions will be offered, when the contact page is open, contact actions will be offered.

Figure 262: ConSol CM Web Client - Example for manual customer activities

Customer Actions are based on Groovy scripts which are stored in the Scripts and Templates section of the Admin Tool. Scripts and templates for customers are usually referred to as data object or unit scripts.

The execution of Customer Actions can be controlled using condition scripts, i.e., you can implement a Data Object Condition Script which is run before the execution script of the customer action. The execution script is only run if this condition script returns true.

So there are two types of scripts you have to deal with when you use the ConSol CM Action Framework:

• Data Object Execution Scripts
  Defines the action which should be performed.
• Data Object Condition Scripts
  Defines one or more conditions for the display of the action in the Web Client. Has to return true or false. If false is returned the action is not displayed on the GUI and therefore cannot be performed.

When you want to implement a customer action you have to proceed in three steps:

1. Create a script for the customer action (either an execution script only or an execution script and a condition script).
2. Create the customer action(s) which use(s) the script(s).
3. Assign the customer action(s) to the customer group(s) where they should be available. You can assign the actions to contacts and/or companies of a customer group.

In the following sections, all three steps are explained in detail.

Managing Customer Actions Using the Admin Tool

In this book we will use the terms customer and customer definition. However, the corresponding scripts use the term data object and the names of the corresponding Java classes are Unit and UnitDefinition. All other Java classes which deal with customer objects are also still named Unit... Please keep that in mind if you work as both a ConSol CM administrator and programmer. Please refer to the ConSol CM Java API Doc for details.

Step 1: Write the Data Object Execution Script

Create a new Admin Tool script of type Data object action. If required, create another script of type Data object condition.

For a detailed explanation of Admin Tool scripts, please refer to section Admin Tool Scripts. For an introduction to Admin Tool scripts used for customer actions, please read section Scripts for the Action Framework: Programming Customer Actions in this chapter.

Figure 263: ConSol CM Admin Tool - Scripts for customer actions

Code example 26: Data Object Execution Script for CM version 6.9.4

Code example 27: Data Object Execution Script for CM version 6.10

Step 2: Create Customer Action(s) Which Use the Script

Open the navigation item Actions in the navigation group Customers in the Admin Tool and add (= create) a new action object using the Add button . The same pop-up window appears for both adding and editing a customer action.

Figure 264: ConSol CM Admin Tool - Editing customer actions

In the pop-up window, the parameters for the new action have to be defined:

• Name
  The unique technical name of the action. Can be localized using the Localize button. Localization is required for manual actions because the localized name is displayed under Activities in the Web Client. For details about localization, please refer to section Localization of Objects in General, Type 1.
• Type
  The action type which defines when it should be executed. Select one of the following types:
  
  • Create
    This script will be executed automatically when the contact/company is created.
  • Update
    This script will be executed automatically when the contact/company is updated, i.e., when the data has been modified (either manually or automatically) and is saved again. Starting with CM version 6.10.5.4, the changes which have been performed during the Update action can be monitored using the changesobject. This is explained in detail in section Working with the Changes Object in Customer Update Actions.
  • Delete
    This script will be executed automatically when the contact/company is deleted.
  • Relation
    This script will be executed automatically when a relation to or from a customer of this customer group is
    • created
    • deleted

    (The script will not be executed when the comment of a relation is changed.)

  • Manual
    This script will be available on the contact/company page as a manual activity, provided the engineer has the required access permissions (act permission for the respective customer group).
• Condition Script
  If a condition script should be run before the execution script, the name of the condition script has to be entered here. The execution script is only run if the condition script has returned true. If there is no condition, just leave this field empty.
• Execution Script
  The name of the execution script which should be run. This has to be the exact name under which the script is stored in the Scripts and Templates section of the Admin Tool.
• Description
  Enter the description which should be displayed as mouse-over in the Web Client (for manual actions only).

Save the action. You can then assign it to customer groups, as described in the following step.

Step 3: Assign Customer Actions to Customer Groups

For the customer action to become effective, you have to assign it to a customer group, at which point it will be available for all customers of this customer group. Depending on the initial definition (contact or company action), the action will be available for contacts or for companies in the customer group. To assign a customer action to a customer group, open the navigation item Customer Groups in the navigation group Customers of the Admin Tool. Select the customer group you would like to edit and click the Edit button to open the pop-up window to assign the customer actions. All customer actions which have been stored under Actions (see step 2) will be available here, each for the corresponding action type. For example, an action which has been defined for the type Update during definition (see step 2) will only be available as an Update action.

Figure 265: ConSol CM Admin Tool - Assigning customer actions to a customer group

You can assign the following action types to a customer group:

• Automatic Actions
  
  • Contact Automatic Actions
    The script will be executed for the contact.
  • Company Automatic Actions
    The script will be executed for the company.

  For each type you can determine the system behavior for the following actions:

  • Create
    This script will be executed automatically when the contact/company is created.
  • Update
    This script will be executed automatically when the contact/company is updated, i.e., when the data has been modified (either manually or automatically) and is saved again. Starting with CM version 6.10.5.4, the changes which have been performed during the Update action can be monitored using the changesobject. This is explained in detail in section Working with the Changes Object in Customer Update Actions.
  • Delete
    This script will be executed automatically when the contact/company is deleted.

  • Relation
    This script will be executed automatically when a relation to or from a customer of this customer group is

    • created
    • deleted

    (The script will not be executed when the comment of a relation is changed.)

• Manual Actions
  This script will be available on the contact/company page as a manual activity, provided the engineer has the required access permissions (act permission for the respective customer group).
• Search Actions
  These are explained in section Action Framework - Search Actions.

Using Customer Actions as an Engineer (User)

As an engineer (user), only the customer action type manual is relevant for you. The CREATE, UPDATE and DELETE scripts run in the background.

Manual actions are offered in the Web Client, similar to workflow activities for a ticket. Please see Example 1 in the next section.

Examples for Data Object Execution Scripts

Example 1: Simple Manual Action

A manual action is coded and stored as an Admin Tool script, then a company action is defined using the script, and the action is assigned to a customer group.

Figure 266: ConSol CM Admin Tool - Data Object Execution Script for a company action

Figure 267: ConSol CM Admin Tool - Defining the company action

Figure 268: ConSol CM Admin Tool - Assigning a company action to a customer group

The engineer can use the action manually in the Web Client.

Figure 269: ConSol CM Web Client - Using a manual company action

A script similar to the following could be used:

Code example 28: Data Object Execution Script, CM version 6.10

Example 2: New Ticket for a Customer

The following script opens the Create ticket page for the contact or company the action was performed for. The target queue is ServiceDesk, enabling a new Service Desk ticket to be created in no time for the open contact or company. For an introduction to Admin Tool scripts for the Action Framework, please read the following section.

Code example 29: Customer script (CM version 6.9.4)

Code example 30: Customer script (CM version 6.10)

Please note that in case a ticket should be created with a company as main customer, the checkbox Company as customer must be checked for the customer data model of the respective customer group.

Scripts for the Action Framework: Programming Customer Actions

Customer actions are defined by Admin Tool scripts, i.e., by Groovy scripts which are stored in the Scripts and Templates section of the Admin Tool. The predefined object unit (i.e., an object of class Unit) is available for those scripts. Objects of the class Unit can represent a company or a contact, depending on the context.

There are two types of scripts for the Action Framework:

• Data Object Execution Scripts
• Data Object Condition Scripts

Data Object Execution Scripts

The actions in this script are either triggered automatically by the system operations CREATE, UPDATE, or DELETE or by a manual action of the engineer (using Activities in the Web Client).

Automatic Data Object Execution Scripts

Code example 31: Set a value in customer data and update the unit

When you use unitService.update(unit), as in the example above, you should use a Data Object Condition Script to avoid infinite loops. See the notes in section Data Object Condition Scripts.

Manual Data Object Execution Scripts

For manual Data Object Execution Scripts you can make use of some specific methods and objects.

CM version 6.9:

• Methods (fields of the Interface PostActionType, com.consol.cmas.common.model.scripting.unit)
  
  • CREATE_UNIT
    Open the create unit page.
  • CREATE_TICKET
    Open the create ticket page.
  • GOTO_UNIT
    Open the unit detail page.
  • GOTO_TICKET
    Open the ticket page.
  • GOTO_PAGE
    Open a web page (URL).
• Objects
  
  • UnitActionScriptResult

CM versions 6.10 and up:

• Methods (fields of the Interface PostActionType, com.consol.cmas.core.server.service.action.PostActionType)
  • CREATE_RESOURCE
    Open the create resource page
  • CREATE_UNIT
    Open the create unit page.
  • CREATE_TICKET
    Open the create ticket page.
  • GOTO_RESOURCE
    Open the resource page
  • GOTO_UNIT
    Open the unit detail page.
  • GOTO_TICKET
    Open the ticket page.
  • GOTO_PAGE
    Open a web page (URL).
• Objects
  • actionScriptResult

For a detailed explanation of the PostActionTypes in CM versions 6.10 and up, please refer to section Scripts for the Action Framework.

Create a Unit

(PostActionType.CREATE_UNIT) redirects the user to the create unit page. It uses the optional parameter PostActionParameter.CUSTOMER_GROUP_ID to define for which customer group a new unit has to be created and optionally the map of Data Object Group Fields (PostActionParameter.FIELDS_MAP) to fill the unit's Data Object Group Fields with the values which were passed on.

Code example 32: Company script which fills some unit data, CM version 6.9.4

Code example 33: Company script which fills some unit data, CM version 6.10

Figure 270: ConSol CM Web Client - Manual company action

Figure 271: ConSol CM Web Client - Create Unit page opened and pre-filled by company action

Of course, the names of the Data Object Group Fields which are used in the script have to be the ones from the customer data model which has been assigned to the customer group for which a new contact should be created.

Figure 272: ConSol CM Admin Tool - Script for creating Unit page as company action

Create a Ticket

(PostActionType.CREATE_TICKET) redirects the user to a ticket creation page. It uses the optional PostActionParameter.UNIT_ID with the ID of the main customer, PostActionParameter.QUEUE_ID with the ID of the queue, and the Custom Fields map PostActionParameter.FIELDS_MAP.

Code example 34: Script creates and returns action result that will tell the Web Client to create a new ticket with unit as the main contact, CM version 6.9.4

Code example 35: Script creates and returns action result that will tell the Web Client to create a new ticket with unit as the main contact, CM version 6.10

Please remember that the customer group for which the script should be applied has to be assigned to the queue where the ticket is to be created (HelpDesk_1st_Level in the example).

Figure 273: ConSol CM Web Client - Manual contact action

Figure 274: ConSol CM Web Client - Create ticket page opened and pre-filled by contact action

Open a Unit Page

(PostActionType.GOTO_UNIT) redirects to a unit page. It uses the obligatory parameter PostActionParameter.UNIT_ID with the ID of the unit.

Code example 36: Script which opens the company page, CM version 6.9.4

Example: Go to the contact detail page of an end customer and open the company detail page of the Reseller company which is responsible for this end customer. A company-contact relation has been established before. If more than one reseller relation has been defined, the first relation in the list is used.

Figure 275: ConSol CM Web Client - Customer action on contact detail page (activity opens company detail page of responsible reseller, CM version 6.10)

Code example 37: Script which opens the company page, CM version 6.10

If the action OpenResponsibleResellerPage should only be offered in the Web Client when a relation to the responsible reseller has been set, you can work with a Data Object Condition Script. It has to be created as an Admin Tool script of type Data object condition and has to be assigned to the customer action in the Actions section.

Figure 276: ConSol CM Admin Tool - Assignment of Data Object Condition Script

Code example 38: Data Object Condition Script which checks if reseller relation is present

Open a Ticket Page

(PostActionType.GOTO_TICKET) redirects to a ticket page. It uses the obligatory parameter PostActionParameter.TICKET_ID with the ID of the ticket.

Code example 39: Open a ticket page in view mode, CM version 6.9

Code example 40: Open a ticket page in view mode, CM version 6.10

When you use one of the scripts above, please keep in mind that the ticket search requires that the Data Object Group Fields of the company be indexed (annotation field-indexed = true).

Figure 277: ConSol CM Web Client - Company action available on company page (1)

Figure 278: ConSol CM Web Client - AM page opened after company action Go to AM ticket

Open a Web Page

(PostActionType.GOTO_PAGE) redirects to a URL. It uses the obligatory PostActionParameter.URL with the URL.

The following code shows a simple example with a fixed URL for each company.

Code example 41: Script which opens a certain web site (URL), CM version 6.9.4

Code example 42: Script which opens a certain web site (URL), CM version 6.10

The string error.script.no.url is a label which has been defined in the navigation group Labels, as described in section Labels.

Figure 279: ConSol CM Web Client - Company action available on company page (2)

To open a fixed URL, you can use a Data Object Group Field of type string with the annotation text-type = url. This will automatically create a hyperlink. Thus, the use of the GOTO_URL parameter in Data Object Execution Scripts is only recommended when an URL is built dynamically within a script.

Data Object Condition Scripts

A Data Object Condition Script defines whether an action should be shown in the Web Client or not. It is executed before the Data Object Execution Script. If it returns false, the Data Object Execution Script will not be executed.

Code example 43: Data Object Condition Script

To put a Data Object Condition Script into operation, you have to perform the following steps:

1. Write an Admin Tool script of type data object condition. The script has to define the conditions for the return values true and false, as demonstrated in the example above. At this point you must already know for which customer groups and data models the script will be used, to make sure you reference the correct data fields within the script.
2. Assign the Data Object Condition Script to one or more customer action(s). This is done in the Actions section, navigation group Customers. Once in place, this specific Data Object Condition script will always be executed before the Data Object Execution Script of the same customer action.

That's it. You do not have to assign the condition script to a customer group. This happens implicitly when the respective customer action is assigned to contacts or companies of certain customer groups.

Important Groovy Objects

Object UnitActionScriptResult (CM Version 6.9)

The object UnitActionScriptResult is only taken into account for manual actions. For actions like CREATE, UPDATE, or DELETE it is not available. The UnitActionScriptResult object is created by the unitActionScriptResultFactory.getPostAction(String, Map<String, Object>) method. This class (resp. the object) is used to store information that will influence the process flow of the Web Client after the manual action has been executed. The UnitActionScriptResult object contains the manual action type, the IDs of the ticket, the unit, the queue, and the customer group. After executing the manual action, the user can be redirected to a different page.

Object actionScriptResult (CM Version 6.10 and Up)

Starting with CM version 6.10, the Action Framework offers the classes ActionScriptResult and ActionScriptResultFactory. An object (singleton) of the class ActionScriptResultFactory is available as actionScriptResultFactory in every action script, no matter which type of action script.

See section Scripts for the Action Framework for details.

Working with the Changes Object in Customer Update Actions

Starting with CM version 6.10.5.4, it is possible to monitor the changes which have been performed during a customer update action. (The same applies to resource Update actions, explained in section Working with the Changes Object in Resource Update Actions).

To find out which changes have been performed use the object of class UnitChanges in Unit actions.

Please remember, the Update script will be executed:

• in an explicit Update action
• when additional details (comments and/or attachments) are added
• when additional details (comments and/or attachments) are removed

There are two methods of the unitChanges object which provide information about the changed data: 

• getCustomFieldChangeInfo()
  provides information about changes of unit data (in Data Object Group Fields)
• getContentChangeInfo()
  provides information about changes in the unit history (comments, attachments) 

Since the method return parameters contain rather complex components, we recommend to read the API doc of the UnitChanges class. The following code provides an example for a script where a unitChanges object is used.

Code example 44: Unit Update script where changes are monitored and printed out to server.log

When for a contact in the customer group Resellers changes have been made to the two Data Object Group Fields phone and vip_person, the following text is displayed in the server.log file.

Code example 45: Log output from the script above