EMC Documentum xCP 2.0 Design Patterns

xCP 2.0 DESIGN PATTERNS

Abstract

This white paper provides guidelines for designing and configuring an xCP 2.0 application. Intended audiences include xCP 2.0 designers and developers.

August 2013

Version 1.0

Copyright © 2013 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.

xCP 2.0 Design Patterns 2

Table of Contents

......................................................................................................Executive Summary 4

.......................................................................................................................Audience 4

.....................................................................................................Application Patterns 5

...........................................................................Application and project configuration 5

.............................................................................................Sharing projects vs libraries 9

............................................................................Specializing an artifact from a library 10

.........................................................................................................Process Patterns 11

..........................................................................................................Generic processes 11

.........................................................................................................Looping processes 12

........................................................................................Accepting input from a page 14

.........................................................................................................Concatenating lists 14

.....................................................................................Inbound initiation of processes 15

.........................................Managing completion of task assigned to multiple users 16

.................................................................Waiting for process branches to complete 18


Executive Summary With the great flexibility that xCP 2.0 gives developers when configuring applications comes the complexity of understanding the best approaches to take when meeting business requirements.

In some cases there may only be a single design pattern that will meet a business requirement, and in other cases there may be several valid patterns, but only one that is expected to meet performance requirements.

The aim of this white paper is to provides guidelines for designing and configuring an xCP 2.0 application to meet business requirements based on the experience of EMC subject matter experts.

This version of the document focuses on the design and configuration of the application model and business processes.

Audience This white paper is intended for xCP 2.0 designers and developers.


Application PatternsAn xCP 2.0 application can be configured using the idea of projects and libraries to support the grouping of related artifacts into logical groups and the sharing and reuse of those artifacts either as editable projects or read-only libraries.

When working with projects and libraries an application developer needs to be aware of the requirements and restrictions related to the use of projects and libraries, such as dependencies between them, to make best use of this feature.

Application and project configurationBefore an application developer begins to configure anything in an application, it is best to plan whether there will be a need to share any of the artifacts across applications as a project or library. If the developer can be certain that the application will be completely self-contained then it is better not to use any sub-projects because each project has an impact on speed of deployment from xCP Designer.

If there is any likelihood that the developer will want to reuse any artifacts across applications then they should plan the project model in advance (how many projects and what dependencies will be needed between them). The reason for this recommendation is that although the developer is able to move artifacts from one project to another from Designer, the references to the artifact from other artifacts (such as a real-time query that has a reference to its primary object model) are not always updated. In this event the developer then has to manually re-select the model again and reconfigure the query.

Once the developer decides that they do need to use projects in the application, then next decision is how many are needed. The following diagram shows a logical configuration that may be considered.

Application

Common Processes

Data Model

The Application is where the majority of artifacts are created (pages, processes, action flows etc). It is set up to depend on both the Common Processes and Data Model projects.

The Common Processes project contains ‘utility’ processes that will be reused in other applications, such as a stateless process to return a filtered list of usernames from the repository, or a generic case creation process. It is set up to depend on the Data Model project, because it will be creating instances of the case folder and case document objects.

The Data Model project contains all the data model artifacts (Folders, Content etc).

This configuration is reasonable, and will work so long as there is no need to use a business event on an object type that initiates a process where that process has a package defined of the object type, as shown in the diagram below.

Process

Content Object Model

Event

Package

This pattern cannot be created in the logical application and project model because it would require a circular dependency between the Common Processes and Data Model projects, and this is not allowed.


Another possible logical configuration would be the following.

Application

Customer Artifacts

Claim Handling Artifacts

The Application is where top level components such as application pages are created. It is set up to depend on both the Customer Artifacts and Claim Handling Artifacts projects.

The Customer Artifacts project is where artifacts for customer related features of the application are created, such as the business object for the customer, the pages (create, view, edit) for the object, and any processes that act on that object (setup, change of address etc).

The Claim Handling Artifacts project is where artifacts that relate to claim handling features of the application are created, such as the folder object for a case, the pages (view, edit) for the object, and any processes that act on that object (claim creation, escalation, closure). This projects is setup with a dependency on the Customer Artifacts project.

The limitation with this approach is that when the developer wants to configure that a customer can be related to a claim, the relationship cannot be modeled as a two way relationship because circular dependencies are not allowed. The developer can only define that a Claim object can relate to one or more Customer objects.

Considering these restrictions, the simplest approach when needing to share artifacts among applications is to create a single project within the first application like this.


Application

Shared Artifacts

The Application is where all user interface components are created (application pages and instance pages). It is set up to depend on the Shared Artifacts project.

The Shared Artifacts project is where everything else is created (object models, process models, roles etc).

In this way, there are never any limitations with dependencies between artifacts, while still allowing the developer to reuse the common artifacts between applications.

One use of this approach is to build device specific variants of an application, where the pages can be designed with the device form factor in mind in each application and bound to a common set of object types and processes.

Desktop UI

Shared Artifacts

Tablet UI

Shared Artifacts

Phone UI

Shared Artifacts


Another use of this approach is in building discrete application modules, such as Document Functions and Case Functions which can then be exported as libraries for use in the main application.

Document Functions

Shared Artifacts

Case Functions

Shared Artifacts

Document Functions

Case Functions

Correspondence Management

Shared Artifacts

In this case the application can contain pages used for testing the functionality of the module, but these do not get included in the exported library containing the module artifacts.

Sharing projects vs libraries

When exporting a project for reuse the developer has the option to export it as a project or library. In most cases to prevent conflicting edits being made to artifacts the use of libraries is the preferred approach.

In the example from the previous section however where a single developer is building an application that requires three separate user interface designs (desktop, tablet and phone), the use of a library to share the common artifacts between the separate applications becomes very time consuming.

When building the tablet UI for example, if the developer decides that a change is required to the object model then the developer has to

1. Open the application containing the shared artifacts project

2. Make the change


3. Export the project as a library

4. Reopen the application (tablet)

5. Remove the original version of the library

6. Add the new version of the library

An approach that the developer can take is to create the project in the first application and import the project (not the library) into the subsequent applications without importing a copy but a reference to the project.

Desktop UI

Shared Artifacts

Tablet UI Phone UI

In this way a change can be made to the shared artifacts from any application context. Changes that affect the other applications would still require that the applications are opened and the problems fixed but this is a more efficient way of working.

It is important when working like this that the applications all reference the same source artifacts. If the applications each have their own copies of the project, inconsistencies will occur between the applications, and deploying one will deploy that applications instance of the artifacts overwriting what is already deployed in the repository.

Specializing an artifact from a library

There are situations where a library from an application is being used but an artifact from the library such as a business process needs to be specialized for the new application context. In this situation the developer may need to use the project instead of the library, but when the impact is minimal the developer can simply right click the business process in Designer, choose Duplicate from the context menu and enter a name for the new process. When duplicated the new process model becomes editable and can be initiated from a page in the application.


Process PatternsWith xCP 2.0 business processes are not only used to manage business functions that require user input, but to execute actions on objects in the repository in response to defined business events and enrich user interface functionality. To configure the most efficient and reliable application it is worth understanding some of the design patterns that can be used in specific business scenarios.

Generic processesWhen configuring an application that is required to handle many different case types it is very easy to begin by focusing only on the requirements of the initial case type. Once the data model and processes have been configured for the first case type the developer then has to try to fit the next case type in to that design. The result of this approach can be a design that is very hard to extend and adapt for future case types, and in some instances can end up with too complex or many duplicated business processes. Careful design of the object model and the use of modular processes can help in this situation.

Setting up a hierarchical object model, where the common case metadata is defined at the top level of the object model, allows the developer to add a more generic case package to a business process. The result of this is that a single business process is able to accept more that one case type for processing.

General Case Reference Account No

Loan Application Case Loan Type Loan Value

Account Action Case Due Date Action

With the object model for case types shown a process can have a package defined of type General Case, which would allow an object of any of the subtypes to be added to the process.

A generic business process can then be defined that takes a type of General Case and assigns the next reference number based on the account type, regardless of whether it is a type of loan (home, auto , etc.) or account action case (change of address, updated signature, closure , etc.).

Where case type specific handling is required then the process can be broken up into more generic and specialized components, where the process is defined with the generic type for the case package, and each sub-process with a more specific type for the case package.

Begin Case Closure (General Case)

Case Closure (Loan Case)

Case Closure (Account Action

Case)

Finalise Case Closure

(General Case)

Looping processesThere are many occasions when an application will need to apply processing to one or more objects in the repository or an external system. Where a single DQL query will not suffice it is necessary to set up a looping pattern in a business process. The most efficient pattern is the one shown.

The list of items can be stored in process attachments, a repeating process variable or a repeating attribute of a process package.

The first activity Count items uses the Count function in the Set Process Data activity to count the number of items and saves the result in an


integer process variable. If this process is being initiated as a sub-process then it is sometimes possible to pass the count as part of the Initiate Process activity allowing for removal of this activity.

In the Decision Split activity Greater that 0?, if the count is 0 then the process transitions to the Join activity called Done. By placing this decision at the beginning it ensures that if there are no items in the list the process does not fail. The trigger condition on this activity must be set to be 1 of 2 input flows. If there are 1 or more items then the loop begins.

The activity Subtract 1 uses the Subtract function in the Set Process Data activity to subtract 1 from the count. This is necessary because lists are 0 based arrays and so if the count was 5 then the last item is at position 4.

The activity Get next item is also a Set Process Data activity. It uses the Get Value function to get the value of the item at position count. An additional process variable or a package is required to store the single value. If the items are objects in the repository then the developer would probably use a package of the correct type, and use that to store the item.

The activity Process item is simply a placeholder for one or more other activities that will do whatever is required to the individual item. Typically this will be a Set Process Data activity that updates attributes of an object in the repository but it could be a series of activities that validate each value against a web service and then adds the value to a new list of items if valid.

The final Join activity Done is required because the last activity that connects to End can only have one output flow.

It is worth noting that when executing a loop inside a stateless process, the system imposes a limit of 100 consecutive activities. If the looping process results in more than 100 automatic consecutive activities an error will be thrown. In the example shown for example the process will only be able to process 20 items before this limit will be reached. The reason for this imposed limit is to prevent a stateless process linked to an update business event that updates the object itself getting stuck in an endless loop. The only ways to avoid this limitation are to use stateful processes, which will execute slower, or to develop a custom Java Service that can be executed with the Execute Java Service activity.


Another requirement when looping like this is to pass back a single pass or fail value for the set of items. There are many approaches the developer can take to achieve this but when using the looping pattern above all that needs to be added is a Boolean process variable to hold the outcome with a default value of true. Inside the loop where the value is tested, the outcome variable is set to false when the test fails and an extra condition is added in the decision split so that the process ends when the count is 0 OR the outcome is false. In that way the process does not have to test every item before returning whether the batch passed or failed.

Accepting input from a pageOne of the features of the Result List widget on a Page is the ability to let the user select multiple items. Often the developer will need to initiate a business process to act on those items when the user clicks a button on the page. To process the list of items (without resorting to the use of an xCelerator) the developer needs to understand that the list of items is passed into the data service that initiates the process as a comma separated list of values and not an array.

Knowing this, the simplest way to process the selected items from the results list is to add an additional Set Process Data activity into the previous looping pattern that uses the Split function to separate the comma separated list into a repeating process variable. In the example below it is called Split items.

Concatenating listsThere are several ways to join a list of items together, but one of the easiest approaches is to use the Copy function in a Set Process Data activity.

In the example below the output list is a repeating variable called object_formats and the source is a collection of a_content_type values from a DQL query.


Ensure that in the right hand side of the data mapping screen the index of the output is set to LAST and in the Copy function the Input Context is set to All and the Output Context is set to Over-write. This configuration will append a new value onto the end of the list and overwrite the new (blank) value with the left hand value for all values in the left hand side.

Inbound initiation of processesWhen an inbound trigger is required in an application, such as the capturing of an email or a file on an FTP server, there are numerous ways to configure the business processes to handle the saving of the information. In most situations the use of a stateless process is better because it is executed as a single transaction in memory, hence it is fast. The limitation however of a stateless process however is that none of the Start from... activities can be used. These can only be used in a stateful process.

The most appropriate solution in this case is to use a stateful process that has a single Start from... activity to capture the inbound information followed by a Start process activity that initiates the main process which handles the process.


As shown in this example the Join activity is required because the Initiate activity must always be linked to something.

There are two benefits to this design pattern.

1. Most of the Start from... activities delete the information from the source. Because the trigger process is stateful it will always be initiated and even if the subsequent stateless process fails, the trigger process will simply be paused but the information will be captured. Appropriate error handling can be added to cater for a paused trigger process.

2. If the subsequent handling is intended to create more than one object in the repository then using a stateless process ensures that the entire transaction will fail and not leave some objects created and not others.

Managing completion of task assigned to multiple usersA useful process pattern is the assignment of a manual task to one or more users in a group for action. When defining the performer of the task the developer can assign the task to all users in the group, the user with the fewest tasks, or the user who acquires the task first. When the task is assigned to all users in the group this can lead to a delay in the business process if any single user does not complete the task.

There are two common approaches to handling this kind of review. The first involves the use of a timer to enforce that the task assigned to the group of users will auto-complete within a defined period. An example use of this model would be to grant the attendees of a meeting 48 hours to review and comment on the meeting minutes followed by a review of the comments by the meeting organizer, as shown below.


The first activity Select users allows the meeting organizer to select one or more users from a list and the names are stored in a repeating process variable.

The Attendee review activity is assigned to the users whose names were selected in the first activity and allows them to add comments to the meeting minutes document. An Activity Started timer is added with a duration of 2 days, and an action to Complete Task when the time expires.

The Organizer review activity will begin after 2 days and allow the meeting organizer to review the comments and act accordingly.

The second model that can be implemented is to assign the task to one or more users for parallel review but allow another user the ability to complete the task independently. In the meeting minutes scenario this would allow the meeting organizer the ability to decide when enough attendees have reviewed the meeting minutes in order for them to be accepted.

As in the previous case, the first activity Select users allows the meeting organizer to select one or more users from a list and the names are stored in a repeating process variable.

A Decision split activity is used that has no conditions on the transition to initiate the following two activities in parallel.

The Attendee review activity is assigned to the users whose names were selected in the first activity and allows them to add comments to the meeting minutes document.

The Organizer review activity allows the meeting organizer to review the comments in parallel to the Attendee review activity and act accordingly.


The final Join activity will be initiated if ALL attendees review the meeting minutes document and complete the task OR if the meeting organizer completes the task.

It is important in this second instance to invoke this process as a sub-process of another process to ensure that the process completes when either of the two tasks is completed. In this way, if the organizer completes the task the sub-process will complete and all tasks will be removed from the attendees inboxes.


EMC Documentum xCP 2.0 Design Patterns

Technology

Transcript of EMC Documentum xCP 2.0 Design Patterns