Hands on Lab with EMC Documentum xCP - EMC World 2011

Page 1 of 35

xCP Hands-on Lab for Momentum 2011 ©EMC Corporation 2011

Momentum xCP Hands-On Lab

May 2011

Page 2 of 35


Hands-on Lab with EMC Documentum xCP

Concept: Extend the Grants Management Sample Application in a variety of ways to

expose key functionality in xCP. First, configure a call to a web service to perform a

currency conversion and display that on a form (and learn about Process Debugger

along the way). Next, make a control on a form hidden for certain roles in the system.

Third, use “conditionally mandatory” to make a field required under certain

circumstances. Finally, explore styling in a TaskSpace application using CSS theming.

This lab uses the EMC Demo Cloud with single image running xCP Developer Edition 1.5.

Contents Introductions: Presenters and brief summary of the goals (10 minutes) .................................................................. 3

Demo Cloud Access .................................................................................................................................................... 3

Part 1: Configure a call to a web service within a process ......................................................................................... 5

Step 1: Start Process Builder and create your process data model ..................................................................... 5

Step 3: Add two steps to the process .................................................................................................................. 7

Step 4: Configure the new activity templates ...................................................................................................... 8

Step 5: Use Process Debugger to verify web service ......................................................................................... 11

Part 2: Modify a process in Grants Management to call the web service ............................................................... 14

Step 1: Open a process and modify the data model.......................................................................................... 14

Step 2: Add two new steps to the process. ....................................................................................................... 16

Step 3: Configure the new activity templates .................................................................................................... 18

Step 4: Display the value for Euros in a form ..................................................................................................... 22

Step 5: Run the Application ............................................................................................................................... 24

Part 3: Change a Form’s Behavior with Rules ........................................................................................................... 27

Step 1: Conditionally Hidden Fields ................................................................................................................... 27

Step 2: Conditionally Required Fields ................................................................................................................ 28

Part 4: Styling a TaskSpace Application .................................................................................................................... 33

Appendix A: Demo Image Setup ............................................................................................................................... 35

Page 3 of 35


Introductions: Presenters and brief summary of the goals Kenwood Tsai, Distinguished Engineer and Principal Architect xCP

Daniel Ciruli, Group Product Manager xCP

This lab provides a brief introduction to xCP, the xCelerated Composition Platform. We will use the Grants

Management sample application that ships with the xCP Developer Edition as a base. The application allows for

the evaluation and management of applications for grants for funding; however, the subject matter of the

application isn’t nearly as important as the patterns used in creating it. Grants Management exemplifies many of

the best practices that can be used in building an information-centric application on xCP without coding.

The lab has three different parts. They can be completed in any order, though we suggest doing them in the

order they are presented in this manual.

In Part 1, you will use Process Builder and Forms Builder to configure a call to an external web service and use

the resulting data in a process, then display it in a form –all without writing a single line of code. In Part 2, you

will use Forms Builder to explore the ability to modify a form’s look and behavior dynamically using rules –

again, without coding. In Part 3, you’ll see how CSS can be used to modify the look and theming in a TaskSpace

application.

The underlying technologies are cool. xCP provides a model-driven, role-based, task-oriented user interface for

case-based applications. The user interface is provided by TaskSpace, underlying content management by

Content Server, process logic by Process Engine, and integrations are performed by Process Integrator.

Configuration is accomplished using the tools Process Builder, Forms Builder and TaskSpace.

Deployment of xCP was simple and documented in Appendix A. In summary you install xCP Developer Edition

1.5 and follow the post-installation configuration steps. The result is a working development environment for

xCP that includes a useful sample application.

Demo Cloud Access 1. There is a document on the desktop of your lab computer called xCP Hands On Lab.txt. Double-click on that

lab to open the file in Notepad.

2. In that document are two URLs – one is the address of the virtual machine you will use to perform the lab,

and another is a URL you will use during the lab itself. Copy the long URL (it’s the one that starts

http://emc.am2.demoemc.com), then open an Internet Explorer browser and paste the URL into the

http://emc.am2.demoemc.com/

Page 4 of 35


browser and press Enter. The screen will look like this.

3. Click the arrow by the PC icon under Remote Access and choose Full Screen RDP.

4. If you see a popup asking if you’d like to make a Remote Desktop Connection with an Unknown Publisher,

ensure that the Clipboard checkbox is selected and click Connect.

4. Log in to Windows with dmadmin/d3m04doc (think demo for doc)

5. After login has completed, to improve performance you should turn off the indexing service. Do this by

choosing Start Menu->Programs->Documentum->Index Server – Stop.

6. You are ready to begin!

Page 5 of 35


Part 1: Configure a call to a web service within a process One of the most powerful features in xCP is the ability to integrate your xCP application with other applications

and data in your enterprise and beyond. Process Builder ships with 32 “integration” activity templates, enabling

your xCP applications to integrate with everything from web services to Java message queues, from external

databases to email servers.

In Part 1, you will perform a simple integration with an external web service. The scenario is this: when a

potential Grant applicant fills out an online application, they enter the amount of their grant in US dollars.

However, some of the reviewers who need to review the application are in Europe, and they’d like to see the

value of the grant in Euros as well as dollars.

In order to build this functionality, first you’ll build a small test process that performs the web service

invocation, and then you will run that process using Process Debugger to verify that it’s working properly and

that the web service is available.

Your web service activity will call a publicly available web service to get the current exchange rate between

dollars and Euros. You’ll then use that exchange rate to convert a dollar value to Euros.

Step 1: Start Process Builder and create your process data model

In this step, you will build the data model for your process. This test process will have three variables: one to

store the dollar value, one to store the exchange rate, and one to store the Euro value.

1. Launch Process Builder

2. Log into Process Builder as dmadmin / d3m04doc (no value is needed for domain). A new untitled process

template will be displayed.

Page 6 of 35


3. Edit the process data model by opening the Process Properties dialog under the Tools menu and navigating

to the Data tab

and then

4. You are going to add three Process Variables: one to store the value in dollars, one to store the current

exchange rate, and one to store the value in Euros. Add a variable by selecting the Process Variables node

from the Process Data tree and then clicking the “+” button.

Name the variable RequestAmountDollars and give it a type of FLOAT.

5. Repeat that process, adding two more FLOAT variables called RequestAmountEuros and ConversionRate.

Page 7 of 35


6. Click OK.

Step 3: Add two steps to the process

You are going to add two steps to the test process. The first step will call the external web service to fetch the

current exchange rate, and the second step will multiply that by the dollar value in order to determine a number

of Euros.

1. Add a Dynamic Web Services activity template to the process by expanding the Integration folder in the

palette of Activity templates then clicking and dragging the activity template called Dynamic Web Services.

2. Add a Process Data Mapping activity using the same click-and-drag motion.

3. Now you are going to connect the steps in the process. Select the Create Flow tool from the toolbar.

4. Now, connect the activities. Connect the “Initiate” activity to the “Dynamic Web Services” activity by clicking

on “Initiate” and dragging to “Dynamic Web Services.” Let go when you see the activity highlight. Then,

Page 8 of 35


connect “Dynamic Web Services” to “Process Data Mapping,” and “Process Data Mapping” to “End.”

5. Click on the pointer tool

Step 4: Configure the new activity templates

Now that you have added and connected the activities, you are going to configure each of them. The first will be

configured to call the external web service. First, you will fetch the WSDL (pronounced WIZ-dull), which tells

Process Builder the interface (inputs and outputs) for the service. Then, you will wire your process variables to

the appropriate inputs and outputs (in this case, the web service is going to give you the current exchange rate,

so you’ll store it in your process variables). In the second activity, you will multiply the dollar value by the

exchange rate to determine the Euro value.

1. Double-click on the Dynamic Web Services activity template to invoke the Activity Inspector. When you see

the Activity Inspector, click the Web Services Configuration tab.

2. Enter the URL http://www.restfulwebservices.net/wcf/CurrencyService.svc?wsdl and click ‘Read WSDL File’.

At this point, Process Builder is interrogating the web service to determine what operations it supports.

When it returns, select Port Type ICurrencyService and Operation GetConversionRate.

http://www.restfulwebservices.net/wcf/CurrencyService.svc?wsdl

Page 9 of 35


3. Click ‘Next’.

You will now configure the inputs to the web service. On the left side of the screen, you see your process

data model, and on the right side you see the web service interface. In this case, however, we’ll be

hardcoding the inputs to the webservice. To do that, we’ll copy a hard-coded string into each parameter.

4. Expand SOAPBody, parameters and ConversionRate on the right column.

5. Select the Copy function from the dropdown to insert the function, and then click on FromCurrency.

6. Next, double-click on the copy function icon to see the Function Editor.

7. Click the plus sign to add a new function parameter, click in the new parameter end enter USD.

Page 10 of 35


8. Click OK. You have now hardcoded the string USD to the FromCurrency input parameter.

9. Repeat steps 5-8, but map the value EUR to ToCurrency.

You have now hardcoded the call to the web service; you have configured it to return the exchange rate for

USD to EUR.

10. Click Next and configure the return value from the web service (which is the current exchange rate).

Expand SOAPBody, parameters, GetConversionRateResponse and GetConversionRateResponse in the left

column, and expand Process Data and Variables in the right column.

Add a Copy function, and then click Rate in the left column and ConversionRate in the right.

You’ve now mapped the current exchange rate into your process data. Click OK.

11. Double-click on the Process Data Mapping activity to configure it in the Activity Inspector. Select the

Process Data Mapping tab.

Page 11 of 35


12. Expand Process Data, and Variables in the left column, and Process Data and Variables in the right column.

Insert a Multiply function by selecting Multiply in the drop down.

13. Click on RequestAmountDollars and ConversionRate in the left column and RequestAmountEuros in the

right column. This step will now multiply the dollar amount by the exchange rate and store that value in

RequestAmountEuros. Your mapping should look like this:

14. Click Ok.

Step 5: Use Process Debugger to verify web service

Now you will test to see if your process is correctly configured to call the web service and perform the

multiplication. You will use Process Debugger to step through the process step by step, watching what each

activity does to ensure that it is working properly.

1. Set breakpoints on both of your activities by selecting the Dynamic Web Services activity and then clicking

on the “hand with the red dot” icon in the toolbar. Do the same thing for the Process Data Mapping activity.

The system will indicate that the breakpoint has been set by affixing a red dot on each activity

Page 12 of 35


2. Start debugging by clicking the “bug” icon in the toolbar.

3. Set a value of 1000 for the RequestAmountDollars variable, and then click Enter. (If you do not click enter

before starting the workflow, the value will not be stored)

4. Click Start Workflow. The system will indicate that the workflow has started by highlighting the Dynamic

Web Services activity. The following steps might be easier if you make the debugging pane (at the bottom of

the window) bigger by dragging it upwards.

5. Click the “Step into the execution of the current activity” button on the side toolbar (see screenshot). The

system will pause while it makes the web service call (given that we are using a free web service, don’t be

surprised if this takes a long time – it sometimes took more than a minute in testing!). When it returns, the

system will display input and output messages.

6. Click on the Process Data tab. You should see that you now have a value for Conversion Rate.

Congratulations – you just called a web service, retrieved the current exchange rate, and stored it in your

Page 13 of 35


process!

7. Click the green arrow to advance to the next step, and then click the “Step into the execution of the current

activity” button again.

8. The system will perform the multiplication and set the correct value for the Euros.

9. Congratulations! You have correctly configured a web service activity template! Click the red X icon to stop

the debugging session. If you see an error indicating that the system had a problem stopping the process,

don’t worry about it – just click OK.

Page 14 of 35


Part 2: Modify a process in Grants Management to call the web service

Now that you know that you can call this web service in a simple process, it’s time to put it to real work. In Part 2

you will do the same thing that you did in Part 1, but you will do it as part of a larger process. You are going to

modify one of the larger processes in the Grants Management sample application. This process handles the

automatic routing of a grant application through its process – you are going to modify it to convert the dollar

value in the application to Euros prior to processing it.

The first part of this should go very quickly, as you repeat the steps that you did in Part 1.

Step 1: Open a process and modify the data model

This is just like what you did in Part 1, only this time the process already has a variable for storing the dollar

value. So you’ll just be adding one for the exchange rate and one for the Euro value.

1. Open one of the existing processes in the Grants Management application. Under the File menu, choose

Open, and then navigate to Grants Management, Process, Manage Grant Request, and then select the

Manage Grant Request process to open it.

The system will display the following message:

Click “Uninstall.” (For expedience, we are not going to create a new version of this process but will instead

Page 15 of 35


modify the existing version. In a production system, it is generally a better idea to version your processes).

2. The system will display the Manage Grants Request process.

3. Edit the process data model by opening the Process Properties dialog under the Tools menu and navigating

to the Data tab

and then

4. You are going to add two Process Variables: one to store the current exchange rate, and one to store the

value of the grant in Euros. Add a variable (for the grant request case) by selecting the Process Variables

node from the Process Data tree and then clicking the “+” button.

Page 16 of 35


Name the variable ConversionRate and give it a type of FLOAT.

5. Add a second variable to the process called RequestAmountEuros (also a FLOAT).

Click OK.

Step 2: Add two new steps to the process.

This is just like what you did in the test process (only this process already has a variable for storing the dollar

value). In this step, you will insert two new steps into the process: the first will retrieve the current exchange

rate for dollars and Euros. The second will use that exchange rate to calculate the value of the grant in Euros.

The new steps will be inserted between the second and third activities in the process.

1. Click on the connector between the Set Process Variable for Grants Manager Task List activity and the

Process Grants Request activity, and click the Delete button on the toolbar. Click OK when the system

confirms the deletion.

Page 17 of 35


2. Add a Dynamic Web Services activity template to the process by expanding the Integration folder in the

palette of Activity templates then clicking and dragging the activity template called Dynamic Web Services.

3. Add a Process Data Mapping activity using the same click-and-drag motion.

Page 18 of 35


4. Now you are going to connect the steps in the process. Select the segmented Create Flow tool from the

toolbar (it’s the one that looks like a black Z).

5. Connect the Set Process Variable for Grants Manager Task List activity to the Dynamic Web Services

activity by clicking on Set Process Variable for Grants Manager Task List and dragging to Dynamic Web

Services. Let go when you see the activity highlight.

6. Continue by connecting Dynamic Web Services to Process Data Mapping and connecting Process Data

Mapping to Process Grant Request. Your process should look like this:

Step 3: Configure the new activity templates

In step 3, you will configure the new activities. The first will invoke the web service to retrieve the current

exchange rate, and the second will use that value to calculate the value of the grant in Euros.

1. Double-click on the Dynamic Web Services activity template to invoke the Activity Inspector. When you see

the Activity Inspector, click the Web Services Configuration tab.

Page 19 of 35


Enter the URL http://www.restfulwebservices.net/wcf/CurrencyService.svc?wsdl and click ‘Read WSDL File’.

Select Port Type ICurrencyService and Operation GetConversionRate.

Click Next.

You will now configure the inputs to the web service. On the left side of the screen, you see your process

data model, and on the right side you see the web service interface. In this case, however, we’ll be

hardcoding the inputs to the webservice. To do that, we’ll copy a hard-coded string into each parameter.

2. Expand SOAPBody, parameters and ConversionRate.

3. Select the Copy function from the dropdown, and then click on FromCurrency.

http://www.restfulwebservices.net/wcf/CurrencyService.svc?wsdl

Page 20 of 35


4. Next, double-click on the copy function icon to see the Function Editor.

5. Click the plus sign to add a new function parameter, click in the new parameter and enter USD.

6. Click OK. You have now hardcoded the string USD to the FromCurrency input parameter.

7. Repeat steps 3-6, but map the value EUR to ToCurrency.

8. Click Next and configure the return value from the web service.

Expand SOAPBody, parameters, GetConversionRateResponse and GetConversionRateResponse in the left

column, and expand Process Data and Variables in the right column.

Add a Copy function, then click Rate in the left column and ConversionRate in the right.

You’ve now mapped the current conversion rate into your process data. Click OK.

Page 21 of 35


After your process has retrieved the current exchange rate, it can multiply that by the dollar value to obtain

the Euro value.

9. Double-click on the Process Data Mapping activity to configure it in the Activity Inspector.

Expand Process Data, Variables, GrantRequestForTaskList, and grant_request_for_tasklist in the left

column, and Process Data and Variables in the right column.

Insert a Multiply function.

10. Click on funding_amount and ConversionRate in the left column and RequestAmountEuros in the right

column. Your mapping should look like this:

11. Click OK.

Page 22 of 35


12. Save and install your process by clicking Save. The system will ask if you’d like to Validate (click OK) and to

install (click OK again).

Step 4: Display the value for Euros in a form

In this step, you will modify a form to display the value calculated in your process.

1. Start Forms Builder by selecting Start->Programs->Documentum->Development Tools->Forms Builder

2. Log in to the repository called documentum using dmadmin / d3m04doc.

3. Click Open Template to open an existing template.

4. Select the Grant Manager Task Form and click Open.

Page 23 of 35


5. In order to modify the form, you are going to uninstall it by setting it to a draft state. Under the Tools menu,

choose Back to Draft.

6. Add a Number field directly below the Liability Checklist by dragging a Number Field into the Vertical Box.

7. Bind the number field to the /Activity/ProcessData/Variables/RequestAmountEuros value.

Page 24 of 35


8. In the Display tab of the Properties pane at the bottom of the window, set the Name and Label for the new

number field to Euros.

9. Install the form by choosing Tools->Install.

Step 5: Run the Application

Now, you’ll test your changes using the Grants Management xCP application.

To begin, you will take the role of a grant applicant and fill out and submit an application for a grant. Take note

of the amount you enter for a grant value. Submitting that application will automatically start processes in the

application, including the Manage Grant Request process you modified. You will then log into the application as

a grant manager and see the information about the grant, including the value for Euros calculated in your

process and displayed on your form.

1. Open an Internet Explorer browser to the xCP Developer Edition welcome page using the icon on the

desktop.

Page 25 of 35


2. In the Welcome page, select Grants Portal

3. Click the Create New Request button to create a new request. If you are prompted to update the

OpenOffice plug in, please don’t do so – just click “Later.”

4. Fill out all required fields in the form (denoted with red squares). Make sure to set a value in the EIN/TIN

field (the request will be automatically rejected if you do not). You may set any values you like in most fields,

but use the following values for these fields:

Project Start Date 8/1/2011

Project End Date 12/1/2011

Funding Amount 1000000

Email address gmapplicant@localhost

EIN/TIN 123456

5. Submit the form by clicking the Submit button at the top of the screen.

6. Now, log in to the Grants Management application as the grants manager. To get to the application, open a

new browser window. On the xCP Developer Edition home page, click Grants Management Application. Log

in using the credentials mgr1 / mgr1

Page 26 of 35


If you are prompted to select a role, select grants_manager.

7. In the Grants Manager home page (titled “My Grants”), click the Get Next Task button in the lower right

hand corner.

8. The Case View for the application you filled out will open. Notice the Euros field!

9. Leave this window open for the next step!

Page 27 of 35


Part 3: Change a Form’s Behavior with Rules In this part of the lab, you will learn about Forms Builder’s ability to change a form’s look and behavior according

to a set of rules, depending on the data and the user.

Step 1: Conditionally Hidden Fields

First, you will hide some information depending on a user’s role. It is very common to need to restrict certain

users’ ability to see sensitive data – in this case, we will let manager’s see the applicant’s Tax ID, but we’ll hide it

from the grants reviewers.

In the Grants Application window in your browser, look at the Applicant Information subtab in the grant you

filled out, and notice that you can see the SSN.

Now, you’ll use Forms Builder to modify that same form so that Reviewers cannot see that information. Note

that that subtab is in a Folder View form embedded in the Grants Manager Task Form; you’ll modify the folder

view form in this exercise.

1. Back in Forms Builder, choose File->Open, and open the Grant Request Folder Form.

2. Under Tools, set the folder Back to Draft state.

Page 28 of 35


3. Select the SSN/EIN/DUNS field

4. In the Properties tab, select the Rules tab

5. Click Add to add a new rule. Define a rule to make the field Hidden if Role is equal to grants_reviewer.

Your rules for the SSN control will now look like this:

Step 2: Conditionally Required Fields

In addition to dynamically determining the appearance of forms because of role or data, Forms Builder can also

change the behavior dynamically by making certain fields “required” depending on role or data on the form.

Page 29 of 35


To demonstrate this, we’ll alter the behavior of the form to require the Grants Manager to enter Risk Details if

the grant is a High Risk grant.

We’ll modify the same Grant Request Folder Form.

1. Select the Assessments subtab of the form and select the Risk Details control.

2. Click the Rules tab in the Properties window. Notice that this control is already conditionally read-only;

we’re going to make it conditionally mandatory as well.

3. Click the Add button.

Page 30 of 35


4. This Rule will have two clauses. The first clause is “if role = grants administrator”

5. Click the plus button to add a second clause: If grant_risk is High, make the field Required (by selecting the

Required checkbox).

6. Click OK. Your rules now look like this:

One thing to note is that these rules are evaluated in order until one evaluates to true, and then that action

is applied. We would like the conditionally required rule evaluated first. So choose the middle rule, then click

the Move Up button. Your rules should now look like this:

Page 31 of 35


7. Under the Tools menu, click Install.

8. Return to the Grant Application in the browser and close the form by clicking the X in the Open Items Tab.

9. You will see a list of Your Grants – right click on the one you created and choose View.

10. When the Grant Request opens, look at the Assessments subtab. Note that the red asterisk next to the Risk

Details indicates that the field is required. If you did not make the Grant Request value a large number, your

risk might not have been assessed as High. Change the Risk assessment and notice that you are also

changing whether or not Risk Details is a required field.

Next, we’ll make sure that the Reviewers cannot see the sensitive data.

11. Click the Send to Reviewers button on the bottom of the window.

Page 32 of 35


12. Select Reviewer1 as a reviewer and click Send.

13. Log out of the application using the Logout button in the upper right hand corner.

14. Log in again, using the credentials reviewer1 / reviewer1

15. Your Grant Request should be in reviewer 1’s queue. Right-click and choose View.

16. Notice that the SSN is hidden from you in this role.

Page 33 of 35


Part 4: Styling a TaskSpace Application Styling an application in TaskSpace is accomplished through several means, including choosing the fonts and

colors for individual controls and forms in Forms Builder.

However, application-wide theming is also very useful. You can apply this type of formatting by modifying a CSS

(cascading style sheet) file.

In this part, you will change the default font and some colors in the TaskSpace application.

1. Open a Windows Explorer window to

C:\Documentum\jboss4.3.0\server\DctmServer_MethodServer\deploy\taskspace.war\taskspace\theme\do

cumentum\css

2. Make a backup copy of imagemanager.css.

3. Right-click on imagemanager.css and open it in notepad++.

4. Find the node that contains taskspacetopbarbackground and comment it out (by putting a /* in front of it

and a */ after it). If you’ve done it correctly, it will turn green.

Page 34 of 35


5. In both taskspaceTopbarLogoBackground and pagerBackground sections, modify the background color to

be #666

6. At the very bottom of the file, add the following text:

7. Back in TaskSpace, hit Ctrl-F5 to force a reload. Notice the new grey color scheme and the fun font!

Page 35 of 35


Appendix A: Demo Image Setup 1. Base Image Windows 2003 SP2, 5 GB RAM (4 GB is the recommended minimum), 30 GB Disk

2. Install Microsoft.NET 3.5 SP1

3. Reboot

4. Download xCP Developer Edition 1.5

5. Extract Zip

6. Move folder to the C:\temp

7. Run documentumSetup.exe

8. Select all the defaults

9. Follow post installation steps from the xCP Developer Edition Installation Guide to fix the resource agent for

acsAdmin

10. Set JAMES grantnotification user password to grantnotification

11. Created Outlook Express account pointing to localhost as POP server for grantnotification emails

12. Set IE to allow install of the ActiveX Control for High Fidelity Forms

13. Ran through a Grant Management Sample application

14. Installed Flash for BAM dashboards

15. Installed Adobe SVG Viewer 3.03 for process instance viewing

Hands on Lab with EMC Documentum xCP - EMC World 2011

Technology