Alerts in EMC Documentum xCP 2.1

1Alerts 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.

Alerts in EMC Documentum xCP 2.1

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a Alerts in EMC Documentum xCP 2.1

Semelhante a Alerts in EMC Documentum xCP 2.1 (20)

Último

Último (20)

Alerts in EMC Documentum xCP 2.1