8 Using Case Management Scripting

EDQ 12.2.1.4.4 introduces a case management script library that you can use to interact with cases and alerts. This chapter describes how to use the case management script library.

This chapter contains the following topics:

• Overview of the Case Management Script Library

• casemanager object properties

• case bean properties

• case history bean properties

• Source Data Object properties

• Case Management Trigger Environment

8.1 Overview of the Case Management Script Library

You can use the case management script library in EDQ triggers and script processors, to access Case Management data and a number of functions in a supported manner.

To use the library, add this line to the top of the script:

addLibrary("casemanagement")

The library publishes an object named casemanager in the script. See casemanager object properties for more information.

Note:

The case management script library has an implicit dependency on the user cache script library so that the usercache object and functions are available. See Using Scripting for User Cache Queries for more information.

8.1.1 casemanager object properties

The casemanager object exposes the following constant values:

Name	Description	Value
CaseManagement.CASE_TYPE	The internal type for cases.	case
CaseManagement.ALERT_TYPE	The internal type for alerts.	issue
CaseManagement.PRIO_NONE	Integer value corresponding to the None priority setting.	0
CaseManagement.PRIO_LOW	Integer value corresponding to the Low priority setting.	1
CaseManagement.PRIO_MEDIUM	Integer value corresponding to the Medium priority setting.	2
CaseManagement.PRIO_HIGH	Integer value corresponding to the High priority setting.	3
CaseManagement,UNASSIGNED	Use this object to "unassign" a case or alert.	Unassigned user object

The casemanager object exposes the following functions:

Name	Description
bean = casemanager.loadCaseById(id)	Load case or alert by internal ID.
bean = casemanager.loadCaseByExternalId(extid)	Load case or alert by external ID. The external ID is shown in the UI.
bean = casemanager.getChildCases(id)	Return array of alert beans corresponding to the case with the given internal ID.
bean = casemanager.getRelatedCases(bean)	If the bean is a case, return array containing it along with the child alerts. Else return array containing the parent case bean and its child alerts.
bean = casemanager.updateAssignedUser(casebean, user, [dotrigger])	Update assigned user for case/alert. The user object is obtained from the user cache library methods. Use null or CaseManager.UNASSIGNED to "unassign" the case or alert. Execute update triggers if dotrigger is omitted or is true. Return the updated case bean.
bean = casemanager.updateCase(bean, [dotrigger])	Save changes to the case or alert. Execute update triggers if dotrigger is omitted or is true. Return the updated bean.
bean = casemanager.updateState(bean, transition, comment, permission, [dotrigger])	Update the current state of the case or alert. transition is the transition name, comment is the comment to associate with the change and permission is the restricting permission for the comment. Execute update triggers if dotrigger is omitted or is true. Return the updated bean.
bean = casemanager.addComment(bean, comment, restrictingpermission, [dotrigger])	Add a comment to the case or alert. Execute update triggers if dotrigger is omitted or is true. Return the updated bean.
extstate = casemanager.getExternalState(source, casetype, state)	Get the "external" state (such as AWAITING_REVIEW) corresponding to the given source, case type, and case state.
sd = getSD(id)	Load source data for the alert with the given ID. The structure of the result is described in Source Data Object properties.
bool = CaseManagement.isLockError(e)	Check whether an error indicates that a case or alert had been modified elsewhere between loading and saving. You can use this to support retries in a script.

The argument to the isLockError function is an error from a script catch clause.

Example:

var cb = casemanager.loadCaseById(caseid)
 
cb.priority = CaseManagement.PRIO_HIGH
 
try {
  cb.save();
} catch (e) {
  if (CaseManagement.isLockError(e)) {
    ... retry logic  ...
  }
}

8.1.2 case bean properties

The case bean passed to trigger calls and used in casemanager function has the following properties:

Property	Type	Is Writable	Description
id	Number	No	Internal ID of the case/alert.
parentId	Number	No	For alerts, internal ID of the parent case.
version	Number	No	Internal version number of the case/alert.
caseGroup	String	No	Case "group" (such as "match").
caseType	String	No	Type: "case" for cases and "issue" for alerts.
externalId	String	No	The external ID of the case/alert, as seen in the user interface.
sourceName	String	No	Case source name.
sourceId	String	No	Internal source "id".
caseKey	String	No	Case/alert key.
keyLabel	String	No	Display version of case key.
flagKey	String	No	Flag key.
description	String	Yes	Description string.
currentState	String	No	Current state of case/alert.
externalState	String	No	The 'external' state of the case/alert, such as AWAITING_REVIEW.
derivedState	String	No	Derived state.
createdBy	Number	No	ID of user who created case/alert.
createdDateTime	Date	No	Creation timestamp.
modifiedBy	Number	No	ID of user who last modified case/alert.
modifiedDateTime	Date	No	Timestamp of last modification.
assignedUser	Number	No	ID of currently assigned user.
assignedBy	Number	No	ID of user who performed last assignment.
assignedDateTime	Date	No	Timestamp of last assignment.
priority	Number	Yes	Priority number: 0 = None, 1= Low, 2 = Medium, 3 = High
permission	String	Yes	Case/alert permission string.
stateExpiry	Date	Yes	Timestamp of state expiry. Updates are ignored if current state is not enabled for expiry.
stateChangeBy	Number	No	ID of user who last changed state.
stateChangeDateTime	Date	No	Timestamp of last state change.
reviewFlag	Boolean	Yes	Review flag.
updatedBy	Number	No	ID of user who last updated review flag.
updatedDateTime	Date	No	Timestamp of last review flag update.
groupId	String	No	Internal group ID.
groupLevel	Number	No	Internal group level.
extendedAttributeN	String/number/boolean	Yes	The value of extended attribute (flag) N.
extendedAttributeNModifiedBy	Number	No	ID of user who last changed extended attribute (flag) N.
extendedAttributeNModifiedDateTime	Date	No	Timestamp of last modification of extended attribute (flag) N.

The case bean passed to trigger calls and used in casemanager function has the following functions:

Name	Description
value = casebean.getExtendedAttribute(n, [deflt])	Get the value of extended attribute (flag) N. If deflt is omitted or true, return the default value if the attribute has not been set. This function is an alternative to the extendedAttributeN and allows extended attribute value to be returned using a computed index.
casebean.setExtendedAttribute(n, v)	Set the value of extended attribute (flag) N.
userid = casebean.getExtendedAttributeModifiedBy(n)	Get the ID of user who last changed extended attribute (flag) N.
date = casebean.getExtendedAttributeModifiedDateTime(n)	Get the Timestamp of last modification of extended attribute (flag) N.
sd = casebean.getSD()	Load source data for the alert. The structure of the result is described in Source Data Object properties.
casebean.save([dotrigger])	Save the case or alert after modifications. Fire update triggers if dotrigger is omitted or is true.

8.1.3 case history bean properties

The case history bean passed to trigger calls has the following read only properties:

Property	Description
id	Internal ID of case history record.
caseId	Internal ID of associated case or alert.
sourceName	Name of source.
modifiedBy	ID of user making change.
modifiedDateTime	Timestamp of change.
attribute	Attribute name.
oldValue	Internal form of previous value.
newValue	Internal form of new value.
oldValue2	Display form of previous value.
newValue2	Display form of previous value

For string values, the internal and display values are the same. For the priority attribute the internal value is numeric and the display form is the corresponding priority name. For attributes associated with users, the internal form is the user ID and the display form is the user display name.

8.1.4 Source Data Object properties

The source data object returned by the getSD functions has the following read only properties:

Property	Description
datasets	Array of data sets (sources).
storageTime	Timestamp of data storage.

Source datasets are identified by an internal ID (a numeric string or "reln" for relationship data) and by a label as seen in the user interface. The source data object has the following functions to extract datasets and values:

Function	Description
dataset = dataset(id)	Get dataset by internal ID.
dataset = datasetFromLabel(label)	Get dataset by UI label.
values = values(dsid, itemid)	Get values for dataset with internal ID dsid and item with internal ID itemid. The result is an array with one value for each source record associated with the alert.

The functions return null if an unknown ID or label is used.

Each dataset object has the following read only properties:

Property	Description
id	The internal ID of the data set.
label	The UI label for the data set.
items	Array of data items.

Data items within a dataset are also identified by an internal ID (column name or relationship attribute) and a label as seen in the UI.

The dataset object has the following functions to extract data items and values:

Function	Description
dataitem = item(id)	Get data item by internal ID.
dataitem = itemFromLabel(label)	Get data item by UI label.
values = values(itemid)	Get values for the item with internal ID itemid. The result is an array with one value for each source record associated with the alert.

The functions return null if an unknown ID or label is used.

Each data item has the following read only properties:

Property	Description
id	The internal ID of the data item.
label	The UI label of the data item.
values	Array of item values, one for each source record associated with the alert.

The item values are returned as strings, numbers, or dates depending on the source data column type.

8.2 Case Management Trigger Environment

The third argument to all trigger function calls is the trigger "environment". For example, case management update triggers are defined with:

function getPath() {
  return "/casemanagement/update/.*";
}
 
function run(path, id, env, casebean, history, comment) {
  ...
}

The environment object for case management triggers contains the following read only properties:

Property	Description
sourceName	The source name.
caseType	The case type ("case" or "issue").
currentState	The current state of the case or alert.
origin	The origin of the update.
userid	The ID of the user making the update.

The origin property identifies the root cause of the update. It can have one of the following values:

Property	Description
user	Change made by user in case management UI.
api	REST API call.
bulk	Bulk update.
expiry	Change caused by automatic state expiry.
creator	Case creation.
import	Case import.
script	Change originated in call made by this script library.