Action Framework - Customer Actions

Introduction

Customer actions (also called Unit actions, previously called Data Object 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 137: 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.

The execution of customer actions can be controlled using condition scripts, i.e., you can implement a customer condition script which is run before the action script of the customer action. The action 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:

• Customer action scripts
  Defines the action which should be performed.
• Customer 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 action script only or an action 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. In previous versions of ConSol CM, the term data object was used to refer to customers. However, 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 Customer Action Script

Create a new Admin Tool script of type Customer action. If required, create another script of type Customer 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 138: ConSol CM Admin Tool - System, Scripts and Templates: Scripts for customer actions

Code example 9: Script which opens the create ticket page with the customer as the main customer, CM version 6.11 and up

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 139: ConSol CM Admin Tool - Customers, Actions: Editing a customer action

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 changes object. 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 action script, the name of the condition script has to be entered here. The action script is only run if the condition script has returned true. If there is no condition, just leave this field empty.
• Action Script
  The name of the action 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 140: ConSol CM Admin Tool - Customers, Customer Groups: 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 changes object. 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 Customer Action 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 141: ConSol CM Admin Tool - System, Scripts and Templates: Customer action script for a company action

Figure 142: ConSol CM Admin Tool - Customers, Actions: Defining the company action

Figure 143: ConSol CM Admin Tool - Customers, Customer Groups: Assigning a company action to a customer group

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

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

A script similar to the following could be used:

Code example 10: Customer action script, CM version 6.11 and up

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 11: Script which opens the create ticket page with the customer as the main customer, CM version 6.11 and up

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:

• Customer action scripts
• Customer condition scripts

Customer Action 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 Customer Action Scripts

Code example 12: 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 customer condition script to avoid infinite loops. See the notes in section Customer Condition Scripts.

Manual Customer Action Scripts

For manual customer action scripts you can use the methods of the object client (class OperationResponseBuilder) to determine the behavior of the Web Client after the action script is executed. The following list shows some examples, you can find the complete list of available methods in Overview of the Methods.

• goToTicket() / goToResource() / goToUnit()
  Open a ticket, resource page, or customer page
• goToCreateResource() / goToCreateTicket() / goToCreateUnit()
  Open the page to create a resource, ticket, or customer
• openActivityForm()
  Open an ACF
• goToPage()
  Open a web page (URL)
• showMessage()
  Display a message
• rollback()
  Rollback the action

Create a Customer

Use the method client.goToCreateUnit(unit) to open the page to create a new customer. You need to create a new unit object and provide the customer group and customer definition. Optionally, you can pre-fill some data.

Code example 13: Company script which fills some customer data, CM version 6.11 and up

Figure 145: ConSol CM Web Client - Manual company action

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

• (1) The company for which the Create new customer activity has been performed is preselected.
• (2) Some data fields of the contact data are pre-filled

Of course, the names of the customer 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 147: ConSol CM Admin Tool - Customers, Data Models: Script for creating contact as company action

Create a Ticket

Use the method client.goToCreateTicket(ticket) to open the page to create a new ticket. You need to create a new ticket object and provide the queue. Optionally, you can pre-fill some data. If you want to set a customer for the ticket, you can append the method withCustomer(unit). In the example below, unit is the customer on whose page the action is executed.

Code example 14: Script which opens the create ticket page with the customer as the main customer, CM version 6.11 and up

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 (ServiceDesk in the example).

Figure 148: ConSol CM Web Client - Manual contact action

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

Open a Customer Page

Use the method client.goToUnit(unit) to open a customer page. In the example below, unit is the Reseller company which is responsible for the end customer. A company-contact relation has to be set before. If more than one reseller relation has been defined, the first relation in the list is used.

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

Code example 15: Script which opens the company page, CM version 6.11 and up

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

Figure 151: ConSol CM Admin Tool - Customers, Actions: Assignment of customer condition script

Code example 16: Customer condition script which checks if reseller relation is present

Open a Ticket Page

Use the method client.goToTicket(ticket) to open a ticket page. In the example below, ticket is the first ticket in the list of account management tickets which have the current company as a main customer.

Code example 17: Open a ticket page in view mode, CM version 6.11 and up

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

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

Open a Web Page

Use the method client.goToPage(string) to open a URL. In the example below, string is the URL saved in a company data field. You can also use this method to open a dynamically built URL.

Code example 18: Script which opens a certain web site (URL), CM version 6.11 and up

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

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

Customer Condition Scripts

A customer condition script defines whether an action should be shown in the Web Client or not. It is executed before the customer action script. If it returns false, the customer action script will not be executed.

Code example 19: Customer condition script

To put a customer condition script into operation, you have to perform the following steps:

1. Write an Admin Tool script of type Customer 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 customer condition script to one or more customer action(s). This is done in the Actions section, navigation group Customers. Once in place, this specific customer condition script will always be executed before the customer action 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 client

In all action scripts, the object client (class OperationResponseBuilder) is available to determine the behavior of the Web Client after the script is executed. It can be used, for example, to open a ticket page or to display a message.

Programming with the class OperationResponseBuilder is explained in detail in section Scripts for the Action Framework.

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 comments or attachments are added
• when comments 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 customer 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 20: 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 customer fields phone and vip_person, the following text is displayed in the server.log file.

Code example 21: Log output from the script above