IBM Cúram SPM for Developers (ADE) 7.

9D73G – Exercise Help Guide

ERC 1.0
Published: 1-Jul-19

© Copyright IBM Corporation 2019

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Table of Contents

Introduction ___________________________________________________________________ 3

General Help __________________________________________________________________ 4

Exercise 1 – Access Product Documentation ________________________________________ 8

Exercise 2 – Access the ADE _____________________________________________________ 9

Exercise 3 – Read a Person (Server Side)__________________________________________ 12

Exercise 4 – Read a Person (Client Side) __________________________________________ 14

Exercise 5 – Add a Create Page _________________________________________________ 16

Exercise 6 – Add a Search Page _________________________________________________ 18

Exercise 7 – Add a Modify Page _________________________________________________ 20

Exercise 8 – Case Study: Design _________________________________________________ 22

Exercise 9 – Implement Code Tables ______________________________________________ 24

Exercise 10 – Import and Export Data _____________________________________________ 26

Exercise 11 – Configure Application Navigation _____________________________________ 27

Exercise 12 – Add Exception Handling ____________________________________________ 32

Exercise 13 – Implement Modeled and Server-Side Validations _________________________ 33

Exercise 14 – Perform Testing and Tracing _________________________________________ 37

Exercise 15 – Implement the Non-Standard Stereotype _______________________________ 42

Exercise 16 – Use Assignment and Aggregation _____________________________________ 44

Exercise 17 – Add Packages, Exit Points, and Unique IDs _____________________________ 46

Exercise 18 – Add a Select List and Online Help _____________________________________ 48

Exercise 19 – Add a Conditional Cluster ___________________________________________ 52

Exercise 20 – Case Study: Implementation _________________________________________ 55

© Copyright IBM Corporation 2019 2

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Introduction
This document lists overall tips when working with the ADE and sample output and tips for each
exercise. The tips are based on common errors that learners encounter when completing the
exercises.

Each exercise outlines the purpose of the exercise and lists the steps to complete the exercise.
The steps are quite detailed for the early exercises and become less detailed as you progress
through the course. After the initial exercises, if you are confident that you understand the topic
and the purpose of the exercise, attempt the exercises without following the steps. However, use
the recommended artifacts names.

When you need help, refer to the example in course book. Use this guide if you need help in
addition to the exercise steps. You can refer to the artifacts in the sample solutions or load the
solutions if required. The sample solutions are in the C:\LearnerResources folder on the image.

© Copyright IBM Corporation 2019 3

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

General Help
This section outlines some overall tips when using the IBM Cúram ADE for this course.

Area Tips
Modelling • Ensure that you save the model after making changes. This may seem obvious, but it is often
the cause of the problem.

• RSAD distinguishes between deleting an artifact from the model and deleting it from a
diagram. If you delete an artifact from a diagram, it still appears in the package. You may also
need to delete an association. For example, if an aggregation is defined in the wrong
direction, ensure that you delete it from the model and the diagram using CTRL+Del. Check
the Associations package to make sure that the association is deleted from the model. You
can also right-click the association in the Associations package to delete it from the model.

• If a build reports an error that includes an RSAD ID, such as

_3C74D50F032E3F0A8DC40290. If this happens, search for the ID in the .EFX file to find the
name of the element causing the problem. The likely cause is that this is an element that you
deleted, which is still referenced by other artifacts. To fix the error, delete the artefact that
references the missing item (for example, delete an operation that refers to a removed struct
as a parameter), rebuild, and add the item again.

• If the model does not appear to reflect your changes, restart RSAD.

Builds • Many errors are caused by building in the wrong order. Follow the general build order shown
in the course book.

• If you need to go back and fix the model or code, stop Tomcat and StartServer.

• Performing builds out of sequence can lead to unpredictable results. If you are cannot find an
obvious error and are unsure of your build order, perform the above steps using clean builds.
This often resolves the error.

• Check the Debug perspective in Eclipse to ensure that you only have one instance of
StartServer and one instance of Tomcat running.

• Ensure that you get “build warnings 0” in the build generated. Some warnings may affect your
application.

© Copyright IBM Corporation 2019 4

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• During a build client, you may get a message saying that it was not possible to write to
messages.jar. This is because Tomcat is still executing. Stop Tomcat and rebuild the client.

• If you load a solution and get the following error, perform a clean on the ServerWorkshop
project in Eclipse:

• If you cannot remove the CourseWorkshop folder to load a solution, start the Task Manager
and select Resource Monitor. Terminate the tnameserv.exe process:

UIM • It is easy to make mistakes when writing UIM. Therefore, copy sections of UIM from working
pages rather than writing it.

• To prevent mismatches between label names in the UIM and properties file, create a split
screen in the Eclipse editor and copy the label names between the files.

• XML syntax errors or non-conformance with the UIM schema will result in errors in the
Eclipse XML Editor, which are highlighted with red marks on the right of the edit panel. Select
the red mark to see the schema error message.

• The build client usually shows the line number of the incorrect line. You can see the line
numbers in the Eclipse XML editor by right-clicking the left grey margin of the XML Editor and
selecting Show Line Numbers.

Runtime • You may get an error on a page with nothing showing in the StartServer or Tomcat console. If
Errors
so, right-click the page and select View page source or View frame Source. The HTML file
may contain a reference to an error.

• If you get a HTTP 404 Error ApplicationController.do, ensure that Tomcat is

pointing to the correct project, that is, ServerWorkshop or Cúram.

© Copyright IBM Corporation 2019 5

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• If you get a HTTP 500 error, ensure Tomcat is started

• Port in use:

o Check the Debug area to confirm that all projects are stopped. If Tomcat still won’t
start, run netstat –aon from a DOS window and see what is using port 9080. You
can then kill the process ID using the Task Manager

o If it still refuses to work, run a full build clean generated database followed by a build
clean client.
• An un-handled server exception occurred. Please contact your
administrator. Check the StartServer console to see the exception message.

• You may not have sufficient privileges to view this page. Ensure that you
preformed a build database and build client.

• java.lang.NoClassDefFoundError: StartServer. Select ServerWorkshop project in

Eclipse, Select Project – Clean.

• org.h2.jdbc.JdbcSQLException: Cannot change the setting "MVCC" when

the database is already open; SQL statement: SET MVCC true [90133-
159]. If you run StartServer when connected to H2 Console, you may get the above error.
If you do, disconnect from H2.

• The following message occurs if you navigate to a page that does not exist or when there are
runtime errors in your UIM:

Eclipse • Ensure that Eclipse is fully closed before you shut down the image, or end your session.
Otherwise, your workspace may become corrupted.

• You should become familiar with the Eclipse debugger. It is easy to use and handy for solving
coding errors.

• If you have lost a window in Eclipse, select Window – Reset Perspective.

• Use the Eclipse Editor Design view or Eclipse code completion (CTRL+Space) to see the
element and attribute options for each of the navigation file types. The Design view is useful

© Copyright IBM Corporation 2019 6

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

for selecting elements and attributes from the schema. However, you should always check
the Source view to ensure that no extra elements have been created.

General • You should use the artifact names suggested in the exercise steps, particularly the UIM page
names. This is because there are pre-defined navigation files that expect these names.

• Many of the exercises are like the examples in the course material. You should use the
course material as a reference. Sample solutions are available in the resources folder. You
can copy selected parts to your solution, or view the README file for replacing the workshop
with the complete solution.

© Copyright IBM Corporation 2019 7

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 1 – Access Product Documentation

There are no tips for this exercise.

© Copyright IBM Corporation 2019 8

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 2 – Access the ADE

Tips

• When you click IBM Cúram Social Program Management Supported Prerequisites, select the
maintenance level and select Detailed system requirements from the page below:

• When you select Proceed you will get the report for the detailed system requirements. Select
Supported Software. Select Development Tools.

• The ServerWorkshop project structure looks like this:

© Copyright IBM Corporation 2019 9

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• setEnvironment.bat should look like this:

• If you get an error when you run build database, make sure that you started the H2 Server. If the H2
Server is started, stop and start the server again.

• When you run StartServer, you should see the following message in console:

© Copyright IBM Corporation 2019 10

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• When you run Tomcat, you should see the following message after 10 – 60 seconds:

• Check the Debug perspective to ensure that only one instance of Tomcat is running.

© Copyright IBM Corporation 2019 11

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 3 – Read a Person (Server Side)

Tips

• Perform all modeling in the Models package of the Modeling (RSAD) perspective. The generators will
not find your modeling artifacts if they are defined in the wrong place.

• If you enter the wrong length for a domain definition, select Cúram from the Properties panel and edit
the Maximum_Size.
• If you enter the wrong name, right-click the item and select Refactor > Rename.

• When modeling an operation parameter, you must specify the ShadowType field whenever the Type
field contains an entity name. Do not specify a Shadow Type if the Type field does not refer to an entity.
(Remember, a Shadow Class is a key struct or details struct that is automatically created for an Entity
Class.)

• The first part of the build generated parses the model and reports errors and warnings. If there are
warnings, the build will still show BUILD SUCCESSFUL when it completes. However, the warnings may
prevent your exercise from working correctly. Always check the console to ensure that build generated
displays “0 warnings”.

• Have you refreshed Eclipse after the build generated? The Eclipse refresh brings in the generated
artifacts and compiles them.

• Ensure that you have created the serverworkshop.impl package in the correct source folder, namely,
components/core/source.

• Enter the following values when creating the new Java class using the New Class wizard:

© Copyright IBM Corporation 2019 12

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

© Copyright IBM Corporation 2019 13

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 4 – Read a Person (Client Side)

If your solution works correctly, you should see the following page:

© Copyright IBM Corporation 2019 14

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• The following tip reduces errors caused by incorrect labels: In Eclipse, drag the tab for the property file
under the UIM file tab so that you have a split screen, as shown below. Copy and paste the labels
between the files.

• The FIELD element has a LABEL attribute and a LABEL element. Ensure that you have added the
LABEL attribute rather than the LABEL element to your UIM page.

• Verify that the names of the properties used in the source elements match the unique names of the
properties in the bean documentation.

• Ensure that the page parameter is called concernRoleIDParam. This is the name of the parameter that
is populated by the sending page.

• Ensure that you stop Tomcat before building the client. Otherwise, the messages.jar file cannot be
updated.

• Check that you do not have multiple instances of StartServer or Tomcat running.

• If you get the ‘Unhandled Server Exception’ message, look in the StartServer console for the stack
trace. For example, the following exception means that you did not add a record with a key of 101:
infrastructure:RUN_ID_RECORD_NOT_FOUND: Record not found.

© Copyright IBM Corporation 2019 15

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 5 – Add a Create Page

If your solution works correctly, you should see the following page:

Once you have entered data and clicked Save, you should see the read page, as in the following
example:

© Copyright IBM Corporation 2019 16

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• Step 3: The input parameters and return type for the insertPerson façade operation are as follows:

Parameters Type Shadow Type

personDtls
Name Person dtls

Object Type Shadow Type

Person key

• Step 6: Your insertPerson method may not appear when you select the Override/Implement methods.
If so, ensure that you have saved the model before performing the build generated and refreshed the
ServerWorkshop project in Eclipse.

• Step 7: The implementation of your insertPerson operation should look like this:
public PersonKey insertPerson(PersonDtls personDtls) throws AppException,
InformationalException {
serverworkshop.intf.Person personObj =
serverworkshop.fact.PersonFactory.newInstance();
personObj.insert(personDtls);
PersonKey personKey=new PersonKey();
personKey.concernRoleID=personDtls.concernRoleID;
return personKey;
}

• Step 14: Your ACTION_SET should look like this:

<ACTION_SET ALIGNMENT="CENTER" TOP="false">
<ACTION_CONTROL TYPE="SUBMIT" LABEL="Action.Save">
<LINK PAGE_ID="PersonDemo_readPerson">
<CONNECT>
<SOURCE PROPERTY="result$concernRoleID" NAME="InsertPersonBean" />
<TARGET PROPERTY="concernRoleIDParam" NAME="PAGE" />
</CONNECT>
</LINK>
</ACTION_CONTROL>
<ACTION_CONTROL LABEL="Action.Cancel" TYPE="ACTION"></ACTION_CONTROL>
</ACTION_SET>

• Before building the client, check for schema errors in your UIM file (indicated by red marks in editor).

• Ensure that you have not confused the NAME and PROPERTY attributes.

• Ensure that the names of the page parameter on the sending and receiving pages are the same.

• If you have copied the read page to create the Insert page, then make sure that you modified the
PAGE_ID attribute of the Insert page.

• Select View – Frame Source from the page to see if there are page errors.

© Copyright IBM Corporation 2019 17

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 6 – Add a Search Page

If your solution works correctly, you should see the following page:

When you select the ConcernRole ID, you should see the read page for the person.

Tips

• Add a new operation called readmulti to the Person entity. This new operation should be stereotyped as
<<readmulti>>. In the pop-up, select lastName from the New Key Struct Attributes list and click Finish.
This is the first entity operation where you must specify an input parameter. For other operations that
you modeled, such as insert(), the generators can determine the input and output structs.

• The implementation required by this exercise is like that shown in the Search example in the course
material.

• The implementation code for the searchByLastName looks like this:

public PersonDtlsList searchByLastName(PersonByLastNameKey lastName)
throws AppException, InformationalException {
serverworkshop.intf.Person personObj =
serverworkshop.fact.PersonFactory.newInstance();
return personObj.readmulti(lastName);
}

© Copyright IBM Corporation 2019 18

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• If you get a schema error in your search page, ensure that your ACTION_SET is defined as the first
element inside the CLUSTER.

• Ensure that your search page is called PersonDemo_findPeople.uim.

• The UIM should be like the UIM in the example in the course manual.

© Copyright IBM Corporation 2019 19

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 7 – Add a Modify Page

If your solution works correctly, you should be able to link to the modify page from the search
results:

Your modify page should allow you to edit all fields except the key field, ConcernRole ID:

When you select Save, you should see the read page with your modifications.

© Copyright IBM Corporation 2019 20

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• The implementation code for modifyPerson should look like this:

public void modifyPerson(PersonDtls personDtls) throws AppException,
InformationalException {
serverworkshop.intf.Person personObj =
serverworkshop.fact.PersonFactory.newInstance();
PersonKey personKey=new PersonKey();
personKey.concernRoleID=personDtls.concernRoleID;
personObj.modify(personKey, personDtls);
}

• On the modify page, the SERVER_INTERFACE for readPerson must have PHASE=”DISPLAY”. The
SERVER_INTERFACE for modifyPerson must have PHASE=”ACTION”.

• When an ACTION_SET is defined inside a CLUSTER or LIST element, it must be the first element.
Otherwise, you will get a schema error for the page.

• In your search page, ensure that the ACTION_CONTROL within the LIST_ROW_MENU is of type
ACTION.

• Ensure that the link to the modify page from your search page includes OPEN_MODAL=”true”.

• If you have difficulties implementing the UIM for the modify page, refer to the example in the course
material and refer to the sample solution.

• Step 12: For changes to PersonDemo_findPeople, locate the LIST element and add a new child
element, ACTION_SET of type LIST_ROW_MENU. Add an ACTION_CONTROL to the ACTION_SET,
setting its LABEL text to Edit.To link to new modify page follow next tips given below.

• Step 12: ACTION_CONTROL requires a LINK child element that specifies PersonDemo_modifyPerson
as the navigation target when it is clicked. In the IBM Cúram application, Edit pages are opened as
modal pages. You need to ensure that the target page is opened as a modal page. In turn, the LINK
requires a CONNECT child element that meets the following specifications:
i. SOURCE must specify the Concern Role ID attribute for the current Person.
ii. TARGET must specify the name of the parameter expected on the PersonDemo_modifyPerson
page.

© Copyright IBM Corporation 2019 21

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 8 – Case Study: Design

Tips
Here are some of the questions that you need to address when designing your solution:
1. Design pages
• What will the pages look like?
2. Modeling
• You may find it useful to review earlier exercises and the PersonDemo solution to determine what
needs to be modeled.
• What domain definitions do you need?
• What entity do you need? What are its attributes and minimum operations?
• You will need a façade. What operations are required? What signatures do the operations require?
3. Server
• What code do you need to define in your façade class?
4. Client:
• What UIM pages are required?
• What server interfaces and phases does each page require?

© Copyright IBM Corporation 2019 22

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Sample Design

© Copyright IBM Corporation 2019 23

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 9 – Implement Code Tables

If your solution works correctly, your create page should appear as follows. Note that the drop-
down list is selected for Gender.

Your read and modify pages should display the descriptions for the codes.

© Copyright IBM Corporation 2019 24

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• Check that your modeling is correct:

o Check that PERSON_GENDER and PERSON_TITLE are based on the CODETABLE_CODE
domain definition by first selecting the domain definition and then the Attributes property tab:

o Check that the Cúram properties tab has the correct code table name: It should match the
‘name’ attribute in the CTX file. Also check that the Maximum_Size is 0. For PERSON_TITLE,
these values will appear as follows:

• If the Title and Gender fields do not appear as drop-downs on the create page, ensure that you have
performed the necessary builds in the right order.
o build generated (followed by a refresh of the server project in Eclipse)
o build database
o build client

• Do you get an exception when you try to load your create page? If so, check the StartServer console
for the exception message. For example, this is the exception you will see if your code table name is
incorrect in the model:
Caused by: infrastructure:RUN_ID_RUNTIME: A runtime exception occurred:
No such code table 'CT_PersonTitle.CTX'..

• Ensure that you changed the package in the CTX file to serverworkshop.codetable.

• Note: You must use these exact names, as the generator will need to match them with the names
specified in the CTX files copied in step 1.

© Copyright IBM Corporation 2019 25

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 10 – Import and Export Data

Tips

• build extractdata –Dtablename=Person

• If build database fails, review the new entry that you created in Person.dmx. Check that all
elements are present and formatted correctly. In addition, ensure that the concernRoleID is unique.

• You do not need to change datamanager_config.xml because it is configured to load all DMX files from
the data/test folder.

© Copyright IBM Corporation 2019 26

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 11 – Configure Application Navigation

Part A

WorkshopHome.tab

DefaultApp PersonDemo_home.uim

DefaultApp.app WorkshopSection.sec

WorkshopSectionShortcuts.ssp
PersonDemo_home.uim

CT_APPLICATION_CODE.ctx PersonDemo_findPeople.uim
PersonDemo_createPerson.uim

PersonDemo_home.uim

Part B

If your solution works correctly, your search page and read page should open in separate tabs:

Part C

If your solution works correctly, your Person tab should display an actions menu:

© Copyright IBM Corporation 2019 27

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Part D

If your solution works correctly, your Person tab should include a navigation bar with two
navigation tabs:

Part E

If your solution works correctly, your Person tab should have the person’s name as the tab name
and contain a context panel:

© Copyright IBM Corporation 2019 28

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Part F

If your solution works correctly, when you edit the name fields, your changes should be reflected
in the context panel without having to refresh the page:

After clicking save:

© Copyright IBM Corporation 2019 29

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

Part C

• Open PersonHomeMenu.mnu in Eclipse, select Design view, right-click menu-bar, and select Add
Child – menu-item. Add the following attribute-value pairs to the new menu-item:
Attribute Value
Id ModifyPerson
page-id PersonDemo_modifyPerson
Title MenuItem.Title.Person.Edit
open-as modal

• Create another menu-item child element beneath menu-bar and configure it with the following attributes
and values:
Attribute Value
Id DeletePerson
page-id PersonDemo_modifyPerson
Title MenuItem.Title.Person.Delete
open-as modal

• Note that this second menu-item is cosmetic. It does not take the user to a delete page, just to the
same PersonDemo_modifyPerson page as the first menu-item.

Part D
• Right-click nodes and select Add Child – navigation-page. Configure the new child element to have
the following attributes and values:
Attribute Value
page-id PersonDemo_readPerson
Id PersonHome
Title PersonHome.title

• Right-click nodes again and add another child navigation-page element with the following:
Attribute Value
page-id PersonDemo_dummy
Id PersonDummy
Title PersonDummy.title

© Copyright IBM Corporation 2019 30

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Part E

• Perform a build client to build the new UIM file. The provided UIM file assumes that you have
used the attribute names recommended so far. If you get UIM build errors, change the names in the
UIM file to suit your bean doc.

• Do a build inserttabconfiguration and restart the server and client applications.

• After Part E, your Person.tab file should look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>

<tc:tab-config
xmlns:tc="http://www.curamsoftware.com/curam/util/client/tab-config"
id="Person">

<tc:context page-id="PersonDemo_details" height="80" />

<tc:navigation id="PersonNavigation" />
<tc:page-param name="concernRoleIDParam" />
<tc:menu id="PersonHomeMenu" />
</tc:tab-config>

• Your navigation files are validated against their respective schemas when you perform a build
inserttabconfiguration. However, the validation will not discover references to artifacts that do
not exist. Such errors will only be discovered at runtime and usually generate an exception message in
the page or StartServer console.

• You will get build errors in Part E if your operation and attribute names do not match those expected by
PersonDemo_details.uim. Verify that the operation and attribute names in PersonDemo_details.uim
match the names in the generated bean documentation.

© Copyright IBM Corporation 2019 31

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 12 – Add Exception Handling

If your solution works correctly, you should see the following message:

Tips

• build msggen is the minimum build.

• Ensure that the message text in the PersonDemo.xml message file is on one line.

• Your try/catch block should look like this:

try{
personObj.insert(personDtls);}
catch(DuplicateRecordException e){
AppException appException=new
AppException(serverworkshop.message.PERSONDEMO.ERR_DUPLICATE_KEY);
appException.arg(personDtls.concernRoleID);
throw appException;
}

• If you do not see your message on the create page, rebuild the client. Ensure that Tomcat is not
running when building the client.

© Copyright IBM Corporation 2019 32

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 13 – Implement Modeled and Server-Side

Validations
Part A

If your solution works correctly, you should get the following results:

Part B

If your solution works correctly, you should see the three mandatory fields. You will get an error
message if the mandatory fields are not entered.

© Copyright IBM Corporation 2019 33

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Part C

If your solution works correctly, you should see you error message when the date of birth or
registration date is incorrect. In addition, the record will not be added to the database.

© Copyright IBM Corporation 2019 34

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

Part A
• The Minimum_Size and Pattern_Match options for PERSON_NAME should be modeled as follows:

• Note that there are no spaces in the pattern match expression.

Part B
• The mandatory fields are defined for the argument to insertPerson and must specify the exact attribute
names:

• If your fields do not display as mandatory on the create page, ensure that you have built the client.

Part C
• In components/core/message, open the PersonDemo.xml message file and add a new message entry
as follows:
<message name="DOB_MUST_NOT_BE_AFTER_CURRENT_DATE">
<locale country="US" language="en">The date of birth must NOT be after today's
date.</locale>
</message>

• Perform the following steps to change the Java code and test your changes:
o Stop StartServer and Tomcat
o Change the code and save to recompile
o StartServer and Tomcat
o Refresh the browser

• Your code for validating the date of birth will look like this:
if (personDtls.dateOfBirth.after(Date.getCurrentDate())) {

© Copyright IBM Corporation 2019 35

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

LocalisableString localisableString = new LocalisableString(

PERSONDEMO.DOB_MUST_NOT_BE_AFTER_CURRENT_DATE).arg(personDtls.dateOfBirth);
TransactionInfo.getInformationalManager().addInformationalMsg(
localisableString, "",
InformationalElement.InformationalType.kError);
}

• Add the following line to roll-back the transaction:

TransactionInfo.getInformationalManager().failOperation();

• If you get the following message, ensure that you built the client when you changed a message:

© Copyright IBM Corporation 2019 36

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 14 – Perform Testing and Tracing

Part A

If your solution works correctly, you should see the following in the JUnit panel:

Tips

• Your new JUnit Test Case is defined as follows:

© Copyright IBM Corporation 2019 37

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• To run JUnit from Eclipse, you can right-click the class or method from the package explorer
perspective and select Run As – JUnit Test. From the JUnit perspective, you can select the following
icon to re-run tests:

• Your test method should look like this:

public void testInsertPerson() {
try {
MaintainPerson person = MaintainPersonFactory.newInstance();
PersonDtls personDtls = new PersonDtls();

personDtls.concernRoleID = 123L;
personDtls.firstName = "Jane";
personDtls.lastName = "Doe";

PersonKey personKey = person.insertPerson(personDtls);

personDtls = person.readPerson(personKey);

Assert.assertEquals("Wrong Name", "Jane", personDtls.firstName);

Assert.assertEquals("Wrong Name", "Doe", personDtls.lastName);

} catch (Exception e) {
e.printStackTrace();
Assert.fail();
}
}

• If you remove fail() from the catch block, JUnit will assume that the test has passed, even though there
was an exception thrown.

• CuramServerTestJUnit4 creates a transaction for the test and rolls it back at the end. Therefore, you
will not see any changes to the underlying tables after testing.

• Note that the OOTB PersonTitle code table does not have Java identifiers defined. If you want to define
this field, just set the actual code.

© Copyright IBM Corporation 2019 38

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Part B – Perform tracing and debugging

If your client tracing is active, you should get output like this in your Tomcat console:

If your server tracing is working, you get output like this in your StartServer console:

When you run your class in debug mode, you output will look like this:

© Copyright IBM Corporation 2019 39

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• Select the Console for Tomcat to see client tracing.

• When tracing on the client, you may see messages specifying that your page is not found, as shown
below. However, these are not errors and can be ignored.

• There are several entries in Application.prx that begin with curam.trace. Ensure that you change the
entry called ‘curam.trace’.

• Ensure that you changed the <value> element rather than the <default-value> element for curam.trace:
<property dynamic="true" name="curam.trace">
<type>STRING</type>
<value>trace_ultra_verbose</value>

© Copyright IBM Corporation 2019 40

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

<default-value>trace_verbose</default-value>

• Select the console for StartServer to see server tracing.

• If your server trace does not appearing, ensure that you entered a valid value for curam.trace,
performed a build insertproperties, and restarted StartServer.

• When tracing on the server, you will see messages in your StartServer console stating that pages are
not found. These are not errors and can be ignored.

• You may want to turn off tracing when you are finished, as it will flag exceptions in later exercises.

• Set the breakpoint as follows:

© Copyright IBM Corporation 2019 41

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 15 – Implement the Non-Standard

Stereotype
If your solution works correctly, you should see the number of records on the Home page.
Register another person and check that the count is incremented.

Tips

• For server development follow the steps below.

1. Create a domain definition called COUNT that is based on SVR_INT32.

2. Create a struct called PersonCount that contains an attribute called counter, based on domain
definition COUNT, to hold the number of people.

3. Add an operation with the appropriate stereotype (ns) to the Person entity called countPeople. This
operation should return PersonCount. Define the following SQL for this method:
SELECT count(*) INTO :counter FROM person;

4. Add a new operation called countPeople to your facade class, which returns the PersonCount
struct.

• Ensure that the SQL query is defined for the entity operation as follows. You must have ‘;’ at the end of
the query and the semicolon in front of ‘counter’.

© Copyright IBM Corporation 2019 42

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• The code for countPeople() is as follows:

public PersonCount countPeople() throws AppException, InformationalException {

serverworkshop.intf.Person personObj = serverworkshop.fact.PersonFactory

.newInstance();

return personObj.countPeople();
}

© Copyright IBM Corporation 2019 43

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 16 – Use Assignment and Aggregation

If your solution works correctly, your search page should operate as it did prior to the changes
made for this exercise.

Tips

• Your aggregation should be modeled like this:

• Alternatively, you can model FindPeopleDetails and specify List in the return type to generate
FindPeopleDetailsList.

• If you need to delete an aggregation (if it is defined in the wrong direction), ensure that you delete it
from the model and the diagram using CTRL+Del. Check the Associations package within your
MaintainPerson to ensure that the association is deleted from the model. You can also right-click the
association in the Associations package to delete it from the model.

• Your searchByLastName operation should look like this:

public FindPeopleDetailsList searchByLastName(PersonByLastNameKey lastNameKey)throws

AppException, InformationalException {

serverworkshop.intf.Person personObj = serverworkshop.fact.PersonFactory

.newInstance();
FindPeopleDetailsList dtlslist=new FindPeopleDetailsList();
dtlslist.assign(personObj.readmulti(lastNameKey));

return dtlslist;
}

• If you are get errors while building the client, ensure that the attribute names in the UIM match those in
FindPeopleDetails, which, in turn, should match the attribute names in the Person entity. If you used
different attribute names in the Person entity, do one of the following:

© Copyright IBM Corporation 2019 44

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

o Change the names used in FindPeopleDetails to match the entity.

o Model an explicit assignment to map the names between the entity and FindPeopleDetails.

© Copyright IBM Corporation 2019 45

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 17 – Add Packages, Exit Points, and

Unique IDs
If your solution works correctly, your create page should look like this:

After you have entered data for a person you should see the generated ID on the read page as in
the following example:

© Copyright IBM Corporation 2019 46

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips

• To change a domain definition, select the artefact under <<domain_definition>> and select the type:

• Ensure that you have selected the Pre_Data_Access option for the insert() operation on the entity.

• The code for your preinsert() operation in the Person class should look like this:
protected void preinsert(PersonDtls details) throws AppException,
InformationalException {

details.concernRoleID=curam.util.type.UniqueID.nextUniqueID("PERSON");

• Note that the line personObj.insert(personDtls) calls the preinsert operation, which adds the generated
concernRoleID to the personDtls struct. This makes it available to the insertPerson() operation.

• If the Person entity is not generated correctly in the new package, then perform a build clean
generated.

• If you specified the concernRoleID as a mandatory field in insertPerson operation, you need to remove
it.

• The UIM for your create page should no longer include a FIELD element for concernRoleID. The LINK
element should pass the generated concernRoleID to the read page as follows:
<LINK PAGE_ID="PersonDemo_readPerson">
<CONNECT>
<SOURCE PROPERTY="personKey$concernRoleID" NAME="InsertPersonBean" />
<TARGET PROPERTY="concernRoleIDParam" NAME="PAGE" />
</CONNECT>
</LINK>

© Copyright IBM Corporation 2019 47

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 18 – Add a Select List and Online Help

This sample solution assumes that the optional features were implemented. Your create page
should look like this. Select the name from the list of related people.

The read page list the concernRole ID for the related person:

Click on the help icon to get the help page:

© Copyright IBM Corporation 2019 48

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips
Modeling
• There are several ways to model the solution. You can write a handcrafted SQL query by using
<<nsmulti>>, or use <<readmulti>>, <<nsreadmulti>>, or <<nkreadmulti>>. This solution uses
<<nkreadmulti>> to return all records.
• The realAllPeople operation orders the returned records:

• Two structs are modeled to return the concernRole ID and full name only to the client page:

© Copyright IBM Corporation 2019 49

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

• Alternatively, you can model RelatedPersonDetails and specify List in the return type to generate
RelatedPersonDetailsList.

• The façade operation getRelatedPeople returns a list of RelatedPersonDetails:

Server Coding
• The façade operation can be written as follows:
public RelatedPersonDetailsList getRelatedPeople() throws AppException, InformationalException {

serverworkshop.entity.intf.Person personObj =
serverworkshop.entity.fact.PersonFactory.newInstance();

PersonDtlsList personDtlsList = personObj.readAllPeople();

RelatedPersonDetailsList relatedPersonDetailsList = new RelatedPersonDetailsList();

// Create a list of concatenated names.

for (PersonDtls personDtls : personDtlsList.dtls) {
RelatedPersonDetails relatedPersonDetails = new RelatedPersonDetails();
relatedPersonDetails.concernRoleID = personDtls.concernRoleID;
relatedPersonDetails.fullName = personDtls.firstName + ' ' + personDtls.lastName;
relatedPersonDetailsList.dtls.add(relatedPersonDetails);
}
return relatedPersonDetailsList;
}

Client Development
• The create page uses the INITIAL element and HIDDEN_PROPERTY:

© Copyright IBM Corporation 2019 50

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

<FIELD USE_BLANK="true" LABEL="Field.Label.RelatedPerson">

<CONNECT>
<INITIAL HIDDEN_PROPERTY="concernRoleID" PROPERTY="fullName" NAME="readAllPeopleBean" />
</CONNECT>
<CONNECT>
<TARGET PROPERTY="relatedPersonID" NAME="InsertPersonBean" />
</CONNECT>
</FIELD>

• The help text is defined in the properties file:

Page.Title=Insert Person
Help.PageDescription=To register a new Person account
Cluster.Title.PersonDetails=Person Details
Field.Label.FirstName=First Name
Field.Label.FirstName.Help=Enter Person's First Name
Field.Label.LastName=Last Name
Field.Label.FirstName.Help=Enter Person's Last Name
Field.Label.Title=Title
Field.Label.Gender=Gender
Field.Label.DateOfBirth=Date Of Birth
Field.Label.Address=Address
Field.Label.RegistrationDate=Registration Date
Field.Label.RelatedPerson=Related Person
Field.Label.RelatedPerson.Help=Select Related Person's Name
Action.Save=Save
Action.Save.Help=This is to Save Person Record.
Action.Cancel=Cancel
Action.Cancel.Help=To Dismiss this Registration Form

• If you do not see the Help icon , ensure that you set the following in curam-config.xml and build
client:

• The read page simply displays the relatedPersonID:

<FIELD LABEL="Field.Label.RelatedPerson">
<CONNECT>
<SOURCE PROPERTY="relatedPersonID" NAME="ReadPersonBean" />
</CONNECT>
</FIELD>

© Copyright IBM Corporation 2019 51

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 19 – Add a Conditional Cluster

If your solution works, you should get a conditional cluster when the person is 18 or older:

© Copyright IBM Corporation 2019 52

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips
Modeling
• Create a new struct that includes isAdult and the PersonDtls struct.

• Select the aggregation. Set the multiplicity to 1:1

• In the Cúram tab, set the right shadow type to Dtls.

• The readPerson operation returns the new struct:

© Copyright IBM Corporation 2019 53

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Server Coding
• The façade operation can be written as follows:
public PersonDisplayDetails readPerson(PersonKey personKey) throws
AppException, InformationalException {

serverworkshop.entity.intf.Person personObj =
serverworkshop.entity.fact.PersonFactory.newInstance();

PersonDisplayDetails personDetails = new PersonDisplayDetails();

personDetails.dtls = personObj.read(personKey);

if (calculateAge(personDetails.dtls.dateOfBirth) >= 18)

personDetails.isAdult = true;
else
personDetails.isAdult = false;

return personDetails;
}

Client Development
• The read page contains the conditional cluster as follows. Note that the value for the field in the
conditional cluster can be any hard-coded value:
<CLUSTER TITLE="Cluster.Title.Adult">
<CONDITION>
<IS_TRUE PROPERTY="isAdult" NAME="ReadPersonBean" />
</CONDITION>
<FIELD LABEL="Field.Label.Adult">
<CONNECT>
<SOURCE PROPERTY="Field.Value.Adult" NAME="TEXT" />
</CONNECT>
</FIELD>
</CLUSTER>

• When you regenerate your Bean Doc, you’ll notice that the full name for each attribute is updated to
reflect the aggregated attributes. If you used the full name rather than the recommended unique name
in your read page, you will get errors. Update the UIM properties with the unique names.

© Copyright IBM Corporation 2019 54

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Exercise 20 – Case Study: Implementation

If your solution works, you should be able to add and list cases. For example:

© Copyright IBM Corporation 2019 55

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

Tips
Modeling
• Your modelling should look like this:

• Set the Code_Package=entity for the Entity package.

• Set Pre Data Access = Yes for the <<insert>> operation if you want to generate the key as you did for
Person.
• The PersonKey struct can be reused to access the entities for a person.

Server Coding
• You will need to create the following server artifacts:
o MaintainCase.java: Containing the implementation of the façade operations.
o Case.java: If you want to generate the caseID from a preinsert()
o Update KeyServer.dmx with an entry for the CASE keyset
o CT_CaseType.ctx with the case type codes.

• The façade operation to insert a case and to list cases simply call the entity operation:
public void insertCase(CaseDtls caseDtls) throws AppException, InformationalException {

serverworkshop.entity.intf.Case caseObj =
serverworkshop.entity.fact.CaseFactory.newInstance();
caseObj.insert(caseDtls);

Client Development
• You will need to create the following UI artifacts:

© Copyright IBM Corporation 2019 56

IBM Cúram SPM for Developers (ADE) 7.X – Exercise Help Guide
_________________________________________________________________________________________________

o PersonDemo_createCase.uim and properties

o PersonDemo_listCasesForPerson.uim and properties
o You need to change PersonNavigation.nav to show the cases navigation tab
o You need to change PersonHomeMenu to add the Create Case entry

• If you use build uimgen to create uim pages, make sure that the following environment variable is set
first:
ANT_ARGS=-Djava.jvmargs="-Xmx512m"

© Copyright IBM Corporation 2019 57