Scripts for the Action Framework
Introduction to Actions
The ConSol CM Action Framework provides the ability to perform actions which are not related to workflow activities, i.e., they can be executed in another context.
There are three types of actions, which are explained in the respective manual sections in detail.
- Customer actions
Actions for contacts or companies, see section Action Framework - Customer Actions. - Resource actions
Actions for resources, see section CM/Resource Pool - Resource Actions. - Search actions
Actions for the result set of a search, see section Action Framework - Search Actions.
This section includes details about programming action scripts.
Action Types
An action can be of one of the following types:
- Automatic actions
Automatic actions are performed by the system whenever the situation for which they are defined occurs in an object. The following automatic actions are available:- Create: Action performed when an object is created.
- Update: Action performed when an object is modified.
- Delete: Action performed when an object is deleted.
- Relation: Action performed when a relation to the object is created or deleted.
- Manual actions
Manual actions are performed by a user who clicks the respective action in the Web Client. There are two types of manual actions:- Manual: Action performed for a single object.
- Search: Action performed for the results of a Detailed Search.
Script Types
The actions are based on Admin Tool scripts whose types correspond to the purpose of the scripts.
For each action, a condition script can be defined. It has to be associated with the action in the action definition in the Admin Tool. This condition script will be executed before the action script.
Thus, the action script will only be executed in the following situation:
- No condition script is defined.
- The condition script returns true.
The following script types are available for the Action Framework:
- For customer actions:
- Customer condition
- Customer action
- For resource actions:
- Resource condition
- Resource action
- For search actions:
- For actions based on ticket result lists:
- Search condition for tickets
- Search action for tickets
- For actions based on customer result lists, i.e., contact or company result lists:
- Search condition for customers
- Search action for customers
- For actions based on resource result lists:
- Search condition for resources
- Search action for resources
- For actions based on ticket result lists:
- For Control Forms (see section Control Forms):
- Control Form Condition
- Control Form Prefill
Programming with the Action Framework
Available and Deprecated Objects
In all available script types (see section Script Types), the behavior of the system after the script can be defined by using the methods of the class OperationResponseBuilder. An object of this class, named client, is implicitly available in all action scripts, in automatic as well as in manual scripts. This object is also available in workflow scripts.
The client object includes methods for operations like the following:
- open a certain URL
- open the page to create a ticket, customer or resource
Besides those actions, the client object also includes methods to display messages in the Web Client, for example:
- display the info that the action has been executed successfully
- display a warning message if the action has failed, e.g., because certain criteria are not met by the entered data
Furthermore, the client object offers a rollback() method.
Please note:
- The classes and respective objects of ActionScriptResult, ActionScriptResultFactory, PostActionScriptResult, PostActionType and postActivityExecutionHandler are deprecated. Use the new OperationResponseBuilder implementation described above.
- The method workflowApi.addValidationError(), which can be used to display messages in the Web Client, is still valid.
Overview of the Methods
The following methods are available in the client object (class OperationResponseBuilder). For more details, please refer to the ConSol CM API documentation. A mapping to the old/deprecated objects and methods is provided - this might make it easier for you to exchange the code in your scripts.
|
New class/method |
Deprecated class/method |
Note |
|---|---|---|
|
client.failure() |
PostActionType.FAILURE |
Sets the OperationType = FAILURE. |
|
client.goToCreateResource(resource) |
actionScriptResultFactory.getPostAction(PostActionType.CREATE_RESOURCE, resource) |
Opens the create resource page prefilled with data from resource object. |
|
client.goToCreateTicket(ticket) |
actionScriptResultFactory.getPostAction(PostActionType.CREATE_TICKET, ticket) |
Opens the create ticket page prefilled with data from ticket object. |
|
client.goToCreateTicket(ticket).withCustomer(unit) |
actionScriptResultFactory.getPostAction(PostActionType.CREATE_TICKET, ticket, unit) |
Opens the create ticket page prefilled with data from ticket and unit object. |
|
client.goToCreateUnit(unit) |
actionScriptResultFactory.getPostAction(PostActionType.CREATE_UNIT, unit) |
Opens the create customer page prefilled with data from unit object. |
|
client.goToPage("url") |
actionScriptResultFactory.getPostAction(PostActionType.GOTO_PAGE, "url"); |
Opens the given URL. |
|
client.goToResource(resource) |
actionScriptResultFactory.getPostAction(PostActionType.GOTO_RESOURCE, resource); |
Opens the resource page of the given resource object. |
|
client.goToTicket(ticket) |
actionScriptResultFactory.getPostAction(PostActionType.GOTO_TICKET, ticket) |
Opens the ticket page of the given ticket object. |
|
client.goToUnit(unit) |
actionScriptResultFactory.getPostAction(PostActionType.GOTO_UNIT, unit) |
Opens the customer page of the given unit object. |
|
client.goToResource(resource).openActionForm("actionformname") |
- |
Opens the given action form of the resource. |
|
client.goToUnit(unit).openActionForm("actionformname") |
- |
Opens the given action form of the customer. |
|
client.goToTicket(ticket) |
actionScriptResultFactory.getPostAction(PostActionType.GOTO_TICKET, ticket, acfExecutionContext) |
Opens the ACF of the current ticket. |
|
client.rollback() |
- |
Rolls back the action. Optionally, an error message can be provided. |
|
client.showDebugMessage("messageOrLabel") |
actionScriptResultFactory.getPostAction(PostActionType.FAILURE, "messageOrLabel") |
Shows a red message, the message text can be entered as a string or using a label. |
|
client.showErrorMessage("messageOrLabel") |
actionScriptResultFactory.getPostAction(PostActionType.FAILURE, "messageOrLabel") |
Shows a red message, the message text can be entered as a string or using a label. |
|
client.showInfoMessage("messageOrLabel") |
actionScriptResultFactory.getPostAction(PostActionType.SUCCESS, "messageOrLabel") |
Shows a green message, the message text can be entered as a string or using a label. |
|
client.showMessage("messageOrLabel") |
actionScriptResultFactory.getPostAction(PostActionType.SUCCESS, "messageOrLabel") |
Shows a green message, the message text can be entered as a string or using a label. |
|
client.showWarningMessage("messageOrLabel") |
actionScriptResultFactory.getPostAction(PostActionType.SUCCESS, "messageOrLabel") |
Shows a green message, the message text can be entered as a string or using a label. |
|
client.success() |
PostActionType.SUCCESS |
Sets the OperationType = SUCCESS. |
By default, the methods to show messages do not refresh the page. Therefore, any updates to the object performed within the action scripts are not yet visible when the message is displayed. You can append withRefreshContent() to the method to refresh the page before showing the message.
Examples
Open the Page to Create a Ticket
Use one of the following methods:
- client.goToCreateTicket(ticket)
- client.goToCreateTicket(ticket).withCustomer(unit)
The following example opens the page to create a ticket. The queue “Helpdesk” is preselected and some fields are prefilled.
import com.consol.cmas.common.model.ticket.Ticket
Ticket ticket = new Ticket();
ticket.setQueue(queueService.getByName("Helpdesk"))
ticket.setSubject("sample subject")
ticket.set("queue_fields.string", "test")
client.goToCreateTicket(ticket)
//to additionally set the main contact use withCustomer()
//client.goToCreateTicket(ticket).withCustomer(unit)
Code example 62: Open the page to create a ticket
Open a Ticket Page in View Mode
Use the following method:
- client.goToTicket(ticket)
The following example opens the ticket “newtic”. Instead of passing a ticket object to the method, you can also provide the ticket name or ID.
client.goToTicket(newtic)
Code example 63: Open the ticket page in view mode
Open a Ticket Page with ACF
Use the following method:
- client.goToTicket(ticket).openActivityForm("activity path")
The following example opens the ticket with the name “100270” and directly opens the activity form of the Dismiss ticket activity.
client.goToTicket("100270").openActivityForm("defaultScope/Service_Desk/Ticket_dismissed/Dismiss_ticket_")
Code example 64: Open a ticket page with an ACF
Open the Page to Create a Customer
Use the following method:
- client.goToCreateUnit(unit)
The following example opens the page to create a new contact for the company. Some data fields are already prefilled.
// used for companies in end customers group to create new contacts easily
def myunit = new Unit()
def mycustomergroup = customerGroupService.getByName("MyCustomerGroup")
myunit.setCustomerGroup(mycustomergroup)
def mycustomerdefinition = unitDefinitionService.getByName("customer")
myunit.setDefinition(mycustomerdefinition)
myunit.set("company()", unit)
myunit.set("customer.firstname", "CM")
myunit.set("customer.name", "Consultant")
client.goToCreateUnit(myunit)
Code example 65: Company action script (“unit” is the current company) to open the page for creating a new contact
Open a URL
Use the following method:
- client.goToPage(url)
The following example opens the URL which is saved in a company field.
// opens company's web site
def url = unit.get("companyData.url")
if (!url) {
client.showErrorMessage("error.script.no.url")
} else {
client.goToPage(url)
}
Display Result Message in the Web Client: SUCCESS, Green Messages
There are several methods to define messages with a green background:
-
client.success()
Displays the message Action succeeded with green background. Sets operation type to OperationType.SUCCESS. -
client.showInfoMessage(string or label)
Displays the string or the message coded by the label with a green background. -
client.showMessage(string or label)
Displays the string or the message coded by the label with a green background. -
client.showMessage(String pMessageKey, OperationMessage.Severity.INFO)
Displays the string or the message coded by the label with a green background. Another severity level would display the message background in another color. In the following example, a label is used.
By default, the methods to show messages do not refresh the page. Therefore, any updates to the object performed within the action scripts are not yet visible when the message is displayed. You can append withRefreshContent() to the method to refresh the page before showing the message:
client.showMessage("controlForm.info.executionOK").withRefreshContent()
Display Result Message in Web Client: FAILURE, ERROR, Red Messages
There are several methods to define messages with a red background:
- client.failure()
Displays the message Action failed with red background. Sets operation type to OperationType.FAILURE. - client.showErrorMessage(string or label)
Displays the string or the message coded by the label with a red background. - client.showDebugMessage(string or label)
Displays the string or the message coded by the label with a red background. - client.showMessage(String pMessageKey, OperationMessage.Severity.WARN)
Displays the string or the message coded by the label with a red background.
Working with Relation Actions
Relation actions are available for all three main object types and are defined in the Admin Tool. Please see the detailed explanations in the respective sections of this manual.
- customers
explained in section Action Framework - Customer Actions - tickets
- resources
explained in section CM/Resource Pool - Resource Actions
A relation action is executed when the relation is
- created
- deleted
It is not executed if the comment of the relation has been changed.
Please note that a relation action is always executed when the object type for which the relation is defined is involved. As a consequence, two actions will be executed in case the source as well as the target object belong to a type with a relation action!
In scripts which define the relation actions, the following objects are available:
- Relation between to customers:
- unit object
- relation object (UnitRelation)
- Relation between a customer and a ticket:
- unit object
- ticket object
- role object (ContactTicketRole)
- Relation between a customer and a resource:
- resource object
- unit object
- relation object (ResourceUnitRelation)
- Relation between a resource and a ticket:
- resource object
- ticket object
- relation object (ResourceTicketRelation)
- Relation between two resources:
- resource object
- relation object (ResourceResourceRelation)
It is possible to distinguish between operations where a relation has been added and operations where a relation has been removed. Use the context parameter actionType for this purpose. It can be used in the condition script, e.g., to control if the action script should be executed or not, or in the action script itself. The actionType can be either of two values:
- ADD
- REMOVE
Example for a Relation Action
In the following example, the person who is the contact person for an SLA should receive an email whenever a new relation for this SLA to a customer has been established or has been deleted.
Perform the following steps to create the relation action:
- Define a relation, in this example the SLA_to_Company_Relation, with source = resource type SLAs and target = company, several customer groups.
- Write the resource action script, in this example: SLA_CompanyRelationAction.groovy.
- Define a resource action (in this example: SLA_CompanyRelationAction) of type “Relation” which uses the script as action script.
- Assign the resource action to a resource type, in the example to the type SLAs.
- Test the desired use case in the Web Client.
Example relation action script SLA_CompanyRelationAction.groovy:
import com.consol.cmas.common.model.mail.MailSendHolder
def myUnit = relation.targetUnit
def myUnitDef = relation.targetUnit.definition.name
def nameField
def groupField
switch(myUnitDef) {
case "ResellerCompany": nameField = "company_name";
break;
case "company": nameField = "name1";
break;
case "DirCustCompany": nameField = "dir_cust_company_name"
break;
}
def myCustName = myUnit.get(nameField)
def contPersMail = resource.get("SLA_Fields_basic.responsible_person_email")
if (contPersMail) {
// Send an email asynchronuously. Mail object is not available outside workflow context!
def pResName = resource.get("SLA_Fields_basic.SLA_Name")
// alternative to fixed text: use text template, not shown here
// distinguish between ADD and REMOVE of relation
def relOp
if (actionType == "ADD"){
relOp = "added to "
} else if(actionType == "REMOVE") {
relOp = "removed from "
}
def pText = "A relation has been " + relOp + "from resource " + pResName + " to company " + myCustName
def pTo = contPersMail
def pSubject = " new or deleted SLA relation - please take care"
def pHtml = false
def pFromEmail = configurationService.getValue("cmweb-server-adapter","mail.reply.to")
def holder = MailSendHolder.createSelfSendHolder(pText, pHtml, null, null)
holder.setSubject(pSubject)
holder.setTo(pTo)
holder.setFrom(pFromEmail)
mailService.sendMailAsynchronous(holder)
} else {
log.info 'No mail sent to SLA contact person, no email address found'
}
Code example 67: Relation action script to send an email when a resource-company relation has been created or deleted
Working With the Data of Control Forms
Control Form-Specific Objects
Two specific objects are available in scripts which deal with Control Forms (see section Control Forms):
- Action scripts (of the action which is executed when the control form has been filled in)
- Control Form condition scripts
- Control Form prefill scripts
The two objects are:
- formFields (Map<FieldKey, AbstractField>)
The map entries represent the data fields and the respective values of the form. In Control Form condition scripts, the formFields are only available, after the Control Form has been filled for the first time. - controlForm (class TicketActionControlForm, UnitActionControlForm or ResourceActionControlForm, depending on the context)
Represents the action form. It may be null if no action form is used. In Control Form condition scripts, the controlForm object is only available, after the Control Form has been filled for the first time.
The class ControlFormService includes several methods to retrieve Control Forms.
Auto-binding
The auto-binding setting defines whether changes to the values in the form also affect the original object.
Auto-binding disabled
Add the following line to the script to disable auto-binding:
def isAutoBindingEnabled() {
return false;
}
The values of the form are available only within the form. They can be retrieved using the formFields object. The original object, i.e., the ticket, customer or resource for which the form is opened, is not modified upon saving the form.
Auto-binding enabled
Add the following line to the script to enable auto-binding:
def isAutoBindingEnabled() {
return true;
}
The values of the form are used to manipulate the values of the original object, because there is a binding between the data field in the form and the data field in the object. The form values are also available in the formFields object, but the original object, i.e., the ticket, customer or resource for which the form is opened, is also modified upon saving the form.