Alerts in EMC Documentum xCP 2.1

1 Alerts in EMC Documentum xCelerated Composition Platform Version 2.1

White Paper

Abstract

This white paper comprehensively explains the alerts feature that is being introduced in version 2.1 of EMC Documentum xCP. The need for this feature is discussed briefly followed by laying out the concepts of xCP alerts, explaining its various aspects. Comprehensive coverage of the usage of the feature is provided from the perspective of an xCP application developer using xCP designer for alerts. March 2014

Alerts in EMC® Documentum® xCelerated Composition Platform® Version 2.1


Copyright © 2014 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided “as is.” EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is a registered trademark of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners. Part Number h12905


Table of Contents

Executive summary.................................................................................................. 4 Audience ............................................................................................................................ 4

Introduction ............................................................................................................ 4

Concepts ................................................................................................................. 4 Alert Definition ................................................................................................................... 5 Alert Instance ..................................................................................................................... 5 Alert Query ......................................................................................................................... 6

Sample Historical Query .......................................................................................... 6

Using xCP Designer for Alerts ................................................................................... 6 Viewing alert definitions ..................................................................................................... 6 Creating a new alert ............................................................................................................ 7 Configuring/Editing an Alert ............................................................................................... 8

Basics ............................................................................................................................ 9 Triggers ........................................................................................................................ 10 Dataset ........................................................................................................................ 12 Actions ......................................................................................................................... 13

Configuring Alert Query..................................................................................................... 18 Basics .......................................................................................................................... 19 Dataset ........................................................................................................................ 20 User Inputs ................................................................................................................... 20

Alert Result List ................................................................................................................ 21

Conclusion ............................................................................................................ 21


Executive summary This white paper explains the alerts feature that is being introduced with version 2.1 of EMC Documentum xCP. We start with the concept of alerts in the context of an xCP application, the need for alerts and proceed with explaining in details how to use the xCP Designer for configuring the various aspects of alerts. In the course of this we use a really simplified sample application and show how to make use of all the capabilities of alert feature, going through all the paths a typical xCP developer would tread while incorporating alerts into an xCP application.

Audience

This white paper is intended for xCP application developers. It expects the reader to have a fair understanding of the xCP concepts of processes, result list UI control, real time query, historical query and aggregation which are usually employed while designing any fairly non trivial xCP application.

Introduction Any business occasionally runs into situations that require an immediate and special attention and consequent handling of that situation on a priority. xCP alerts feature helps in capturing such scenarios and aiding the business users to handle them. An xCP application modeling a business process allows recording of historical business data using historical queries. xCP application developers can now use the alerts feature to define alerts to be raised when a certain condition is met on that collected historical data. Along with raising an alert one can start a process automatically by associating an action with an alert while designing the alert. The raised alerts can also be viewed on a page in the application UI. All the raised alerts are available as objects of an alert type in the repository and they can be queried using an Alert Query, which is a new query type just like a real time query, but restricted to fetch only objects of an alert type. They can be viewed by tying an appropriately designed alert query to a result list UI control in an xCP application page. The rest of the document details about different aspects of the xCP alert feature.

Concepts xCP alerts intend to model any exceptional scenario during a normal course of business that requires special attention and action. The following are a couple of examples of likely alert scenarios

• Total loan amount disbursed in a quarter exceeds a certain amount

• Time taken to finish an activity exceeds a predefined limit

In the above examples the total loan amount in a quarter and the time taken to finish an activity can be collected in the rows of the data tables of an appropriately


designed historical query. And then the above alert scenarios can be identified by evaluating a boolean expression (alert condition or alert expression) on that historical business activity data. How to design historical queries appropriately to collect the necessary data is very much specific to the business use case being modeled. Here we won’t be covering the myriad real world alert scenarios and how to model a historical query to capture data for evaluating that alert condition. We would be covering a sample case like above and provide a possible design of alert definition for that example, giving an idea of possibilities for use cases of the feature.

Upon successfully meeting the alert condition on a row of a historical query data table, an alert is raised. This creates an object of alert type in the repository. The raised alert can keep with it any data from the historical query table row on which the alert condition has met. Along with creating alert object, one can start one or more processes as part of the actions to be performed when an alert is raised.

At this juncture, it is important to distinguish between an alert instance and an alert definition. Consider the above alert scenario of “time taken to finish an activity exceeds a predefined limit of 10mins”. This can happen multiples times in different instances of process execution, each time raising an alert instance. But, all such alert instances arise out a single alert definition. Going forward, in this document, the term alert will be used to refer to both of them when the reference is obvious from the context.

Alert Definition

An alert definition is configured in the xCP designer by an xCP application developer. The alert definition is where one configures the following aspects of an alert

• Alert conditional expression

• Severity of the alert

• Data source (a historical query data table) on which the condition is evaluated

• Data to be put into the alert instances (called the alert output columns)

• Actions to be performed when an alert is raised

An alert definition is an xCP artifact just like a process definition, BO definition etc. For each alert definition there is a repository type created where its instances are saved. The repository type name is of the form <namespace>_<alert name> and it is a subtype of the documentum type dmc_xcp_alert.

The later sections explain how an xCP application developer can create and configure alert definitions.

Alert Instance

An alert instance corresponds to one occurrence of an alert situation of a particular alert definition. An alert instance is created as an object of the repository type


corresponding to its alert definition, that is, all the alerts arising out of one particular alert definition are all objects of one repository type.

Alert Query

Alert query, theoretically, is a real time query but used to query only objects of an alert type. While creating a real time query the primary model for the query can be any of the business objects, contents and folders, whereas, for an alert query the primary model is restricted to alerts. Just like a real time query, an alert query can be tied to a result list control on an application page on which the alerts can be viewed and edited.

Sample Historical Query Before we go ahead it is necessary to give a little idea about the historical query which is chosen as the primary model for the alert in our running example.

This historical query is designed so that it allows capturing the total loan amount approved quarterly. We need the total quarterly approved loan amount because we intend to fire an alert when this amount exceeds a limit, say $100,000. For simplicity, assume that the application creates a certain BO each time a loan application is approved and that the BO carries the approved loan amount. The historical query listens to the create events of the BO and collects a row of data which contains the loan amount approved for each loan application approved. To accumulate quarterly loan amount across all loan applications we create a level one aggregation, grouping over a dummy column, which is set to the same constant value for all of the rows so that all the rows get grouped in the same group, and summing the loan amount column. Now, the level 1 tables for this historical query will contain total loan approved for Hourly, Daily, Weekly, Monthly, Quarterly and Yearly granularity levels.

Just on an aside, if we wanted an alert to be raised each time there is a loan application is approved for more than $5,000 then there would be no need to define an aggregation level at all. The data is available in the level 0 tables (the instance tables) itself. The loan amount field of each row in the level 0 table corresponds to one loan application approved.

Using xCP Designer for Alerts This section explains the xCP designer features around the alerts functionality.

Viewing alert definitions

All the alerts definitions in an application are listed under the Alerts category in the Object Models tab of xCP Navigator window as shown in Figure 1.


Figure 1

Creating a new alert

To create a new alert, right click on the Alerts category and click on the New Alert menu item as in Figure 2.

Figure 2

This shows a New Alert dialog box as shown in Figure 3.


Figure 3

The name of the alert and the primary model for the alert are chosen here. If there are more than one xCP projects in the application, there will be another field (not shown in the above figure) to choose the project under which this alert would go. The name of the alert is supposed to be a unique string among all the alerts in a project. The primary model is a predefined historical query. It is the rows of the data table of this historical query on which the alert condition is evaluated.

Hitting the finish button closes the dialog and creates an alert, which lists under the Alert category in the Object Model tab of xCP Navigator window. This needs to be further configured as explained in the Configuring/Editing an Alert to completely define the alert.

Configuring/Editing an Alert

Double clicking on an alert definition in the alerts list will open it for configuring rest of the necessary aspects of the alert. Within the designer the configuration of alerts is categorized and thrown under four tabs, namely Basics, Triggers, Dataset and Actions.


Basics

Figure 4

The Basics tab, as shown in Figure 4, has just one editable field for entering a description for the alert definition; a meaningful text describing when this alert would be triggered. Label field shows the name of the alert that was entered while creating the alert, system name shows the auto generated (based on the label field) unique name, the primary model shows the historical query chosen while creating the alert and the source field shows the xCP project under which this alert resides.


Triggers

Figure 5

The Triggers tab, shown in Figure 5, is where the alert condition, a boolean expression, is defined. The variables in the boolean expression will be fields of the historical query which is chosen as the primary data model. Hitting the ellipsis next to the expression text field will show a dialog with the context data, containing the fields of the historical query table, as shown in Figure 6. For this example, we have chosen the variable Sum of Loan Amount which appears in the expression editor in the form of its system name total_loan_amount.s0sum_loan_amount. The condition is designed to check if there is a row in the data table of the historical query whose Sum of Loan Amount column value exceeds 100000.


Figure 6

The Severity field (in Figure 5) provides a set of three values (Low, Medium, and High) to be assigned to any alerts raised for this alert definition, as its severity.

The section under Aggregation in the triggers tab has two important configuration parameters for the alert. This section is applicable only if the historical query which is chosen as the primary model has aggregation levels defined, that is, the historical query has an aggregation level 1 or higher.

Time granularity (in Figure 5) dropdown field is used to choose one of the aggregation granularity levels from the available granularity levels for a historical query, namely Hourly, Daily, Weekly, Monthly, Quarterly and Yearly. For our running example, because we are interested in the quarterly total, we choose the granularity level of Quarterly.

Re-evaluate Trigger on update of data (in Figure 5) is also applicable only if the primary model has aggregation levels defined. Considering our example, a row of data in the level 1 table for Quarterly time granularity will keep getting updated each time a new application is processed within the same quarter. This flag will control if an alert will be raised again upon the row getting updated given that there was an alert raised in the past out of this same row. In our example, it may not make sense to have a re-evaluate because once the total goes over the limit, an alert is raised and any approval of more loan applications after that will only cause the total to further


increase over the limit and raising further alerts may not be necessary. Or is it necessary? For this reason we have this flag, which can be judiciously used by the xCP application developer. Sometimes, in some use case of some other business, the aggregate metric on which the condition is evaluated might be fluctuating over and below limit, that is, falling sometimes and rising sometimes, in which case it makes sense to have this flag checked. Rising above the limit indicates an alert situation and falling below the limit might indicate a business remedy being taken for the alert and rising above again might indicate a fresh situation of alert for which a business remedy might be needed and hence the need for a fresh alert to be raised.

Dataset

Figure 7

The Dataset tab, shown in Figure 7, allows the xCP application developer to choose the output columns for the alert instance. Any of the columns of the historical query data table can be pulled as an output column of the alert from the context data window which shows the historical query columns. Hence, any output column of alert corresponds to one of the columns of the historical query. When a row of the


historical query table satisfies the alert condition, an alert instance is created and its output columns will get values from this row of historical query table, based on the mapping established in the dataset tab.

Actions

Figure 8

Actions tab, as shown in Figure 8, can be used to associate actions to be performed when an alert is raised. An action can be a stateless or a stateful process. As seen above, there can be multiple actions configured which will all be listed in the listing. Hitting the Add button on this tab throws a dialog, as shown in Figure 9, for configuring an action. In the first screen we enter a label which would be the name given to the action.


Figure 9

Hitting the Next button shows the following, as shown in Figure 10, which will allow us to select a process.


Figure 10

Depending on which process (stateless or stateful) we want to start, select one of the two radio buttons in the screen and hit the ellipsis button corresponding to that process type which will show a list of the available processes in the application as shown in Figure 11.


Figure 11

Choose the desired process from the list of processes and hit Finish button and proceed to the next step by hitting the Next button where the process packages and variables, if any, can be configured how they get the data. How the process packages and variables are mapped is nothing different here than anywhere else in xCP application and beyond the scope of this document. The important point to note here is that the context data available is that of the data of the raised alert, that is, any of the properties of the raised alert is available in the context data as shown in Figure 12.


Figure 12

Let’s digress a bit and talk about the fields/properties of a raised alert that are shown in the above figure.

Total Quarterly Loan Approved: This is the output column chosen in the Dataset tab earlier in our example. If there are more output columns chosen they all will be listed here. This is coming here because of the output column configuration we did earlier for this alert definition.

The rest of the following properties are common for all the alerts, irrespective of to which alert definition they belong.

Alert Action Triggered: This is a boolean value which is set to true if only if the processes corresponding to all the actions of the alert are successfully started.

Alert Created on: The datetime value of the time when the alert has been raised.

Alert Failed Actions: A comma separated list of names of the actions which failed to start.

Alert Name: Name of the corresponding alert definition.

Alert Namespace: The namespace to which the corresponding alert definition belongs.


Alert Object ID: r_object_id value of this object which represent the alert instance.

Alert Object type: r_object_type value of this object.

Alert Severity: This carries the value set in the corresponding alert definition for the severity field as explained in the section Triggers, namely Low, Medium and High.

Alert Source name: The name of primary data model (the historical query) of the corresponding alert definition

Alert Status: This can be one of New, Acknowledged and Closed values. Whenever a new alert is created this value is set to New. This value is editable by an xCP application user on an application page listing alerts.

Whenever an alert is raised all the processes associated with the actions configured in this tab will be started.

Configuring Alert Query

Within the xCP designer alert queries are listed in the Data Services tab of xCP Navigator under the Alert Query category as shown in Figure 13.

Figure 13

A new alert query can be created by right clicking on the Alert Query category and choosing the New Alert Query entry in the context menu. This shows up a New Alert Query dialog as shown in Figure 14. Here we enter the name for the alert query and choose the primary model from the listed alert definitions and hit the Finish button to create an alert query, which needs to be further configured. An alert query tied to a particular alert definition can only query for alerts instances of that alert definition. To


query across all the alerts one needs to choose All Alerts [xcp] entry from the list for the primary model.

Figure 14

To complete the configuration of the alert query double click its entry in the xCP navigator which opens it in the work area. The configurations for an alert query are categorized under three tabs, namely Basics, Dataset and User Inputs.

Basics

Figure 15

The fields Label, System name, Description, Source and File Location have the same meaning as the ones for an alert definition as described in the section Basics. Data service type field indicates that this an alert query. Primary model shows the chosen alert definition, which can be edited to change to a different alert definition.


Dataset

Figure 16

Everything in this section has the exact same meaning as that for a real time query, the only difference being the Context Data which shows just the fields/properties of the primary model selected. Output Columns section allows for choosing the columns that will be displayed in the result set. Predefined Inputs section allows choosing predefined filters (on the alert properties) for the result set.

User Inputs

Figure 17


User Inputs tab, shown in Figure 17, allows for configuring alert fields that will be shown on the result set page where the application user can enter values for those fields, based on which the result set is filtered. Again, this has the exact same meaning as the user input filters for real time queries.

Alert Result List

As mentioned earlier an alert query result set can be tied to a result list UI control on an application page. On this application page an xCP application user can view the list of alerts as shown in Figure 18. Our sample application has been run and three loan applications have been approved with amounts $40,000, $35,000 and $25,500 which totals to $100,500 within the same quarter. This satisfies the alert condition and an alert is created which is shown in the list here.

Figure 18

An xCP application user can also right click on an alert entry and edit the Alert Status of that alert. A newly created alert will have its alert status set to New always. From New state, the status can be either set to Acknowledged or Closed as shown in Figure 19.

Figure 19

From Acknowledged state, the status can set to New or Closed and from Closed state, the status can be set to New. Typically a user will set the status of the alert from New to Acknowledged when the alert has been noted and the task of mitigating has been initiated; and from Acknowledged to Closed when the mitigating action has been taken.

Conclusion We have explained the concept of alerts in the context of xCP application and how they can be used to capture exceptional business scenarios. We have discussed in detail about all the aspects of an xCP alert and how they can be configured using xCP designer and the meaning and effect of each of the configuration. Finally we have explained how to view and edit the raised alerts using an alert query.

Technology

Alerts in EMC Documentum xCP 2.1