caclarityppm studio developerguide enu

Studio Developer's Guide

v12.1.0

CA Clarity™ Project & Portfolio

Manager

This documentation and any related computer software help programs (hereinafter referred to as the

"Documentation") are for your informational purposes only and are subject to change or withdrawal by CA at any time.

This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part,

without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may

not be used or disclosed by you except as may be permitted in a separate confidentiality agreement between you and

CA.

Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation,

you may print a reasonable number of copies of the Documentation for internal use by you and your employees in

connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy.

The right to print copies of the Documentation is limited to the period during which the applicable license for such

software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify

in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.

TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION "AS IS" WITHOUT

WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO THE END USER

OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION,

INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR

LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.

The use of any software product referenced in the Documentation is governed by the applicable license agreement and

is not modified in any way by the terms of this notice.

The manufacturer of this Documentation is CA.

Provided with "Restricted Rights." Use, duplication or disclosure by the United States Government is subject to the

restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section

252.227-7014(b)(3), as applicable, or their successors.

Copyright © 2010 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein

belong to their respective companies.

Contact CA Technologies

Contact Technical Support

For your convenience, CA Technologies provides one site where you can access

the information you need for your Home Office, Small Business, and Enterprise

CA Technologies products. At http://ca.com/support, you can access the

following:

■ Online and telephone contact information for technical assistance and

customer services

■ Information about user communities and forums

■ Product and documentation downloads

■ CA Support policies and guidelines

■ Other helpful resources appropriate for your product

Provide Feedback

If you have comments or questions about CA Technologies product

documentation, you can send a message to [email protected].

If you would like to provide feedback about CA Technologies product

documentation, complete our short customer survey, which is available on the

CA Support website at http://ca.com/docs.

http://www.ca.com/support

mailto:[email protected]

http://www.ca.com/docs

http://www.ca.com/docs

Contents 5

Contents

Chapter 1: About Studio 9

Studio Features and Benefits ................................................................... 9

Key Features and Benefits ................................................................. 10

How to Get Started with Studio ................................................................ 12

The Studio Process Overview .............................................................. 12

About Data Providers ..................................................................... 14

Important Studio Terms ....................................................................... 15

Chapter 2: Partitions 17

Partitions Overview ........................................................................... 17

The Benefits of Using Partitions ............................................................ 17

How Partitioning Works ....................................................................... 18

About Partition Models .................................................................... 19

Partitions and Object Views ................................................................ 20

Portlets and Partitioned Data Providers ..................................................... 20

How to Work with Partitions ................................................................... 21

How to Create and Use Partitions .............................................................. 22

Create Partition Models .................................................................... 22

Add a Partition to a Partition Model......................................................... 23

Add Many Partitions to a Partition Model (Quick Create) ..................................... 24

Add Members (Resources) to a Partition .................................................... 25

Apply a Partition Model to an Object ....................................................... 26

Chapter 3: Configuring CA Clarity PPM (PowerMods) 27

About Objects ................................................................................ 28

Process Overview: Working with Objects ....................................................... 29

About Data Providers ......................................................................... 30

Objects Data Provider ..................................................................... 31

System Types Data Provider ............................................................... 35

Create Objects ............................................................................... 36

Grant Access to Objects ....................................................................... 37

Object Attributes ............................................................................. 38

Attribute Data Types ...................................................................... 38

How to Add Attributes to Objects .......................................................... 40

Calculated Attributes ...................................................................... 68

Autonumber Object Attributes ............................................................. 79

6 Studio Developer's Guide

Modify Object Attributes ................................................................... 84

Delete Object Attributes ................................................................... 85

How to Audit Objects ......................................................................... 87

Delete Objects ............................................................................... 89

About Add-Ins ................................................................................ 90

Apply the Add-In ............................................................................. 90

Views ........................................................................................ 91

Add User-Defined Fields to Views .......................................................... 92

Create Subpages for the Properties View .................................................. 102

Publish Changes to List and Filter Views ................................................... 107

Restore Defaults for Object Views ......................................................... 110

Restore Defaults for Selected Views ....................................................... 110

Restore Defaults Based on Partitions ...................................................... 111

How to Display Multiple Subpages on a Tab ................................................... 114

Define and Manage a Custom Property View ............................................... 114

Display Custom Subpage Links on a Tab Using the Custom Property View ................... 118

Links for Pages and Subpages ................................................................ 120

Link from an Object Page to a Subpage ................................................... 121

Link from an Object Attribute to a Web Page ............................................... 121

Link to Properties Pages from External Applications ........................................ 123

Add Image Fields to List Column Views ........................................................ 124

Add Gantt Chart Fields to List Column Views ............................................... 124

Add Image Link Fields to List Column Views ............................................... 126

Add Progress Bar Fields to List Column Views .............................................. 127

Change Field Properties ...................................................................... 128

How to Change a Field's Appearance .......................................................... 130

Change Field Labels ...................................................................... 130

Display a Range of Values as a Color or Icon............................................... 131

Change the Appearance of Properties View Attributes ...................................... 132

Change the Appearance of List Column View Fields ......................................... 134

Change the Appearance of List Filter View Fields ........................................... 137

Display Fields as Bar or Column Graphs ................................................... 138

Menus, Sections, and Links ................................................................... 141

Add Menu Items or Links ................................................................. 141

Change Sections and Links ............................................................... 143

Move Sections and Links ................................................................. 144

Delete Sections or Links .................................................................. 144

Icons ....................................................................................... 145

Stock Icons ................................................................................. 147

Chapter 4: Portlets: Grids, Graphs, Pages, and Menus 151

Portlet Overview ............................................................................. 151

Contents 7

Types of Access Rights ....................................................................... 152

Stock Portlets ............................................................................... 154

About Personal Dashboards and Portlets ...................................................... 160

Dashboard Properties Settings ............................................................ 161

Dashboard Access Rights ................................................................. 161

Administrator Access to User Portlets ..................................................... 162

Personal Dashboarding Operations by User Type ........................................... 162

Data Providers for Personal Dashboards ................................................... 163

Interactive Portlets .......................................................................... 164

Create the Interactive Portlet ............................................................. 164

Create Object or Global Parameters ....................................................... 166

Graph Portlets ............................................................................... 167

Data Providers ........................................................................... 168

Graph Portlet Types ...................................................................... 169

Create Graph Portlets .................................................................... 170

Determine Graph Portlet Appearance ...................................................... 172

Determine Graph Portlet Data to Display .................................................. 178

Change Graph Portlets ................................................................... 179

Delete Graph Portlets .................................................................... 180

HTML Text Portlets .......................................................................... 180

Create HTML Portlets ..................................................................... 181

Change HTML Portlets .................................................................... 182

Delete HTML Portlets ..................................................................... 182

Grid Portlets................................................................................. 183

Access Rights and Grid Portlets ........................................................... 183

Grid Portlet Aggregation, Comparison, and Variance Options ................................ 183

Hierarchical Grid Portlets ................................................................. 184

Things to Consider When Creating Grid Portlets ............................................ 184

Create Grid Portlets ...................................................................... 185

Determine the Layout of Grid Portlets ..................................................... 187

Change Grid Portlets ..................................................................... 190

Delete Grid Portlets ...................................................................... 190

Filter Portlets ................................................................................ 191

Filter Precedence ........................................................................ 192

Scope of Filter Portlets ................................................................... 193

Filter Persistence ........................................................................ 193

How to Set Up Filter Portlets .............................................................. 194

Create Filter Portlets ..................................................................... 194

Field Data Types for Adding to Filter Portlets ............................................... 195

View the List of Portlet Pages for Filter Portlets ............................................ 207

Determine the Layout of Fields on Filter Portlets ........................................... 208

Portlet Pages: Deploying Content ............................................................. 209


Create Portlet Pages ..................................................................... 209

Add Filter Portlets to Portlet Pages ........................................................ 213

Delete Portlet Pages ..................................................................... 215

Publish Changes to Portlets................................................................... 215

Access to Portlets and Pages ................................................................. 215

Restrict Access to Portlets or Pages ....................................................... 216

User Configuration Restrictions of Portlets ................................................. 217

Configurable User Actions ................................................................ 219

Delete Filter Portlets ......................................................................... 223

Chapter 5: NSQL 225

About NSQL Queries ......................................................................... 225

The NSQL Syntax ........................................................................ 225

NSQL Constructs ......................................................................... 228

User-Defined Constructs ................................................................. 230

Advanced NSQL Constructs ............................................................... 235

About Queries ............................................................................... 237

Create Queries .......................................................................... 237

Change Queries .......................................................................... 239

Delete Queries ........................................................................... 239

About Lookups .............................................................................. 240

Browse-only Construct for Dynamic Query Lookups ........................................ 241

Hierarchical Queries ......................................................................... 242

Filtering in Hierarchical Queries ........................................................... 242

NSQL Troubleshooting and Tips ............................................................... 243

Index 245


Chapter 1: About Studio

This section contains the following topics:

Studio Features and Benefits (see page 9)

How to Get Started with Studio (see page 12)

Important Studio Terms (see page 15)

Studio Features and Benefits

Studio is the interface to the PowerMods™ framework that you can use to

configure CA Clarity PPM. Use Studio to tailor your CA Clarity PPM system and

deploy local configurations and personalized user interfaces. With Studio,

organizations and individuals can create a work environment that delivers

information in meaningful ways.

Studio‘s point-and-click configuration empowers you to create and deploy

portals, dashboards, menus, and business objects that adapt to your business

process—not the other way around. Users can personalize their dashboards by

choosing which portlets to show or hide and where to show them on a page.

Studio:

■ Delivers real-time information to the users who need it most.

■ Allows you to personalize individual user environments with user-defined

content and graphics.

■ Reduces training requirements and speeds new user adoption by offering

tailored menus, and pages and views that use familiar language and

processes.

■ Allows you to tailor portfolio, project, resource, and idea business objects

without specialized programming skills using PowerMods.

■ Provides partitions that facilitate local management with global governance

while supporting multiple local configurations in a single application

instance.

You can propagate the fields and objects you create to CA Clarity PPM interfaces

and the CA Clarity PPM XML Open Gateway (XOG). Unlike most configurations,

your CA Clarity PPM configurations automatically carry forward to future versions

of the product.



Key Features and Benefits

The following key features and benefits are available to you using Studio.

Features Benefits

User-defined portlets Enables organizations to easily collect, aggregate,

analyze and display important information by using a

combination of PowerMods and portlets. Through a

completely point-and-click user interface, CA Clarity

PPM administrators can create fields, deploy them in

forms on specific pages, and build portlets to

graphically communicate the information collected.

Point-and-click portlet

construction

Delivers over 40 stock and an unlimited number of

user-defined portlets that display graphs, tables, and

HTML content. These portlets reflect the user‘s access

rights and filter settings and allow them to access and

drill into information in a single, consolidated view.

Multiple display types Displays graphical information in grids or bar, bubble,

column, funnel, line, pie, and scatter graphs.

Drill-down graphs Allows administrators to define links that provide users

access to underlying data and specific instances of

objects.

Data filters Filter data on any number of predefined, configurable

parameters.

Precision Security™ Reduces administration costs by providing built-in

organizational breakdown structure (OBS) security.

Once access rights for viewing information are

assigned through a configurable, flexible hierarchy,

users see only the information for which they have

access. Portlets automatically generate graphs and

tables based on the privileges of the current user.

Partitions Supports distributed and diverse organizations by

allowing local configurations within a single global

instance of CA Clarity PPM. Each partition can be

configured with its own fields, forms, processes and

branding.

User-defined objects Add new business objects to CA Clarity PPM and then

configure them with fields, forms, processes, and

portlets.

Attachments Allows users to provide document and other types of

attachments for any standard or user-defined business

object.

Centralized field Simplifies administration by centralizing the



Features Benefits

control management of all user-defined fields within Studio.

User-defined fields are automatically deployed to the

user interface, to the process engine, to

OpenWorkbench, to Microsoft Project, and to the XOG

(XML Open Gateway).

User interface

configuration

Provides a consistent user interface across applications

by allowing organizations to configure CA Clarity PPM

to display colors, logos, menus and pages with a

specified corporate look and feel.

New dashboard page

development

Easily extends the capabilities of CA Clarity PPM by

creating new pages that organize and display

information in useful ways for the business, such as a

Project Management Office News page, an Executive

Dashboard, and a Program Issues Tracking work

space.

Menu manager Reduces training and support costs by organizing the

CA Clarity PPM menu navigation to match the

company‘s terms and processes.

View All During object creation, you can enable a feature to

allow all instances of this object and its subobjects on

one properties page.

Third-level object

hierarchy

Create a hierarchy of up to three levels of user-defined

objects that inherit properties from higher level

objects.

Large string attribute Create string objects of any length (subject to

limitations of your database).

Export to XML Export objects in XML format.

Add-Ins Apply add-ins to import a collection of content (pages,

portlets, queries, project templates, roles, etc.) as a

single entity.

Configurable action

items

Configure and add your own status attributes to action

items.

How to Get Started with Studio



To use Studio, you should have the following:

■ The Studio module installed and have a valid license for it.

■ Some knowledge of SQL to set up and manage the data you will use in

Studio.

■ Studio access rights (available only with a valid Studio license). Access to

Studio is controlled via standard access in the Administration Tool and can be

granted for the three components of Studio: menus, pages, and portlets.

Note: To get started with Studio, launch the CA Clarity PPM Administration Tool

and click the links from the Studio menu.

The Studio Process Overview

This following is a high-level overview of the process you will use to configure CA

Clarity PPM.

Step 1: (Optional) Create Partitions to Control What Users See and Do

With partitions, organizational units can implement and see CA Clarity PPM

(pages, processes, user interface themes) in different ways. Partitions allow you

to deploy and support different fields, forms, processes, methodologies, and

branding but also to control content access rights within your organization.

The System Partition is the default partition. If you do not create new partitions,

your objects are automatically assigned to the System Partition.



Partitions help you govern centrally and manage locally. Local organizational

units can manage their business independently of other organizational units, yet

still adhere to governance requirements.

CA Clarity PPM can look one way for one subsidiary or business unit and one way

for another.



Step 2: Configure the Interface with User-Defined Objects

Configure and extend business objects to do the following:

■ Create pages with a mix of standard and user-defined fields.

■ Specify validation rules or default values.

■ Create list views with filters and sorts.

■ Create hyperlinks between objects.

Step 3: Create Portlets, Pages, and Menu Items

Facilitate impromptu user reports by creating portlets that contain graphs,

tables, best practices, and documents—all of which are updated and available in

real-time without the need to execute and review reports. Once created, a

portlet‘s presentation is easily manipulated using point-and-click configuration

settings available to administrators and users.

With portlets, users can do the following:

■ Show information in bar, bubble, column, funnel, line, pie, or scatter graphs.

■ Use Gantt graph and progress bars to visually communicate schedules,

progress, and phase gate status for items such as project tasks, program

durations, and asset and application lifecycles.

■ Leverage out-of-the-box histograms to track resource utilization.

■ Build scorecards by segmenting continuous data into groups and applying

status icons such as red-yellow-green stoplights, approved/unapproved

checkmarks, and leading/steady/trailing performance indicators.

■ Create simple or complex filters to view just the information that is

important.

■ Provide real-time drill-down links from portlet content to business objects

such as portfolio investments, resources, projects, and ideas.

About Data Providers

Studio portlets access information from data providers (objects, queries, and

system types). If you choose to use queries to provide data, you will use NSQL to

create them. CA Clarity PPM‘s data model supports most of the business objects

you need. You can also create constructs that meet your unique business needs.

Important Studio Terms



The following terms are used throughout this book.

Term Definition

Access rights Access rights determine which CA Clarity PPM object

instances you can access and the actions you can take on

them, such as view, edit, or approve.

Attributes (Fields) Information that is associated with and may or may not

display on an object‘s pages.

Data provider The source of data used by Studio portlets. Data providers

can be objects, queries, and system types.

Dimension Related data elements in a query. For example

project-related data (project ID, name, start date, etc.) is

considered a single dimension. If a query contains project

and resource data, it contains two dimensions.

Lookup Drop-down lists or browse lists that filter portlet data.

Menu A navigational element of the user interface that provides

links to other pages in the application.

Metrics A value in a dataset, such as booked hours, capacity, or

number of tasks that can be measured.

NSQL An extension of the SQL language that is used to query data

in the CA Clarity PPM database.

Object A resource, document, user, access role, or system group.

These are particular elements or records that you can

attach or associate to an OBS unit. Some of the object

types included in CA Clarity PPM are portfolios, resources,

programs, projects, applications, assets, products, ideas,

other investments, companies, and users.

OBS Organizational Breakdown Structures; a hierarchical unit

structure used to view the framework of an organization

from both a visual and functional perspective for

aggregation, drill down, resource searching, and rights.

Partition Partitions are local configurations of CA Clarity PPM that

may have their own forms, fields, processes, branding, and

security rules.

Portlet A section of a page that is displayed in CA Clarity PPM.

Portlets can take the form of lists and graphs among other

types.

Query A set of conditions used to retrieve specific information

from a database.



Term Definition

Resource In CA Clarity PPM, a user who can be assigned to perform

work on a project is a resource. You can associate

resources with skills, primary role, resource pools and OBS.

Resource profiles have properties such as, resource name,

email address, employment type, manager, available hours

per day, target billable rate, and standard cost. A resource

does not have to be a user although every user is also a

resource.

System Partition This is the default partition that exists in each CA Clarity

PPM enterprise installation. Any partitions you create

become children to this partition.

User A CA Clarity PPM user who has access rights and

permissions to use CA Clarity PPM. A CA Clarity PPM user

can participate on a collaboration project and can also be a

resource.

Views An object‘s view determines how information displays on a

page.

Virtual column Columns whose data is not computed when the query is

created (i.e. the data is created in realtime).

Virtual field A field to which CA Clarity PPM can make calls but that does

not physically exist in CA Clarity PPM. It may be a

calculated field, or a field with temporary values generated

by CA Clarity PPM as needed. You cannot access a virtual

field because it does not physically exist.


Chapter 2: Partitions


Partitions Overview (see page 17)

How Partitioning Works (see page 18)

How to Work with Partitions (see page 21)

How to Create and Use Partitions (see page 22)

Partitions Overview

If you create new partitions, you should become familiar with the basic concepts

of partitions. If you create even one partition, you will see partition options as

you work objects and portlets. You can simply accept the default System

Partition and all groups and users will have access to your work.

If you do not create new partitions, all the objects you create are automatically

assigned to the System Partition.

The Benefits of Using Partitions

With partitions, you can create local configurations of CA Clarity PPM that have

their own forms, fields, processes, branding, and security rules.

For example, a corporation can consolidate all regional resource, budget, and

program data into a single, global view. A corporation can design and deploy

corporate processes, and provide a clear set of parameters to local organizations

for corporate-wide processes. At the local level—which can be

geographically-based, organizationally-based or a mixture of both—information

can be disseminated to meet local requirements.

You can govern globally by defining fields at the top of your organizational

hierarchy and then make them required for every object instance throughout CA

Clarity PPM.

Manage locally by deploying fields directly to child (descendant) partitions so

that only child partitions must supply values for a field.

How Partitioning Works



A default System Partition exists in each CA Clarity PPM enterprise installation.

Any partitions you create become children to the System Partition. You can also

create partitions within partitions.

You can set up partitions by department, geography, industry, division, by legal

structures or any other method that makes sense for your organization. For

example, the first level of partitions in a partition model may be geographical

while the second level and subsequent levels may be divisional partitions.

See the following example where United States and European partitions have

been created to display information that is relevant for each country‘s

operations. CA Clarity PPM pages in each of these partitions may appear

differently to reflect the language and operational differences for each location.

Within the United States and European operations, each has a marketing

organization that has its own partition to reflect the specific needs of those

organizations. The company also has an IT division that uses the default System

Partition to see the total company view.

You can partition the following:

■ Object user-defined attributes (fields)

■ Object views (Properties, List Column, and List Filter)

■ Object links

■ Lookup values

■ Portlet and process data providers (NSQL queries cannot be partitioned)

■ Programs (a list of projects)

Note: Reports and Jobs cannot be partitioned, but you can control access to

them using access rights.

When you create an attribute (field) you can choose to make it available for any

ancestor and/or descendant partition, or you can choose to only make it

available to the partition for which it was created. This association is called the

―Partition Association Mode‖. An attribute, however, can only be associated with

one partition at a time.



You can change the partition assignment or partition mode of an attribute at any

time. You should carefully consider the impact your changes may have on items

that reference those attributes. For example, a grid portlet that uses a

user-defined date attribute for Gantt chart columns may no longer be able to

render it because the required attribute is no longer available. A process instance

may fail because it can no longer evaluate or set a certain attribute.

About Partition Models

Partition models organize partitions into a hierarchical model. When you create

partitions, you will use this hierarchical model to assign user-defined attributes

at any level and make them available (or required) at lower level partitions. This

is how you drive governance from the highest level in an organization to lower

levels. It also makes partition administration easier by allowing lower-level

objects to automatically inherit partitioned items.

Partition models are similar to Organizational Breakdown Structures (OBS)

except the following:

■ OBSs are often used to control security and drive reporting, while

■ Partition models control how objects are managed in CA Clarity PPM.

Partition models support resource memberships that are based upon groups

or OBS units and thus are a way of grouping resources.

You can set up multiple partition models, however:

■ A business object can only be assigned to one partition model at a time.

■ As a Studio user, you can be a member of more than one partition within a

partition model. However, when you create new objects, you will be asked to

select the partitions to use. For example, you may be a member of the

United States and European partitions, but you will have to choose which one

to use when you create a project.

■ CA Clarity PPM users can only be members of one partition and thus do not

need to select a partition. Users that are not member of any partition will see

the System Partition (default) views.



Partitions and Object Views

Object views determine how information displays in CA Clarity PPM. There are

three types of views:

■ Properties views, which display and allow users to enter information about

an object,

■ List Column views, which display instances of an object in rows and columns,

and

■ List Filter views, which help users search for information.

You do not need to define object views for each partition in a partition model. If

a partition has no view, it inherits the view from the nearest ancestor partition.

If no ancestor partitions have views defined, the partition uses System Partition

views.

CA recommends that you first define partitioned views at the top of the partition

model. For example, if you are using a geographical partition model with ―World‖

at the top and ―United States‖ and ―Europe‖ as descendants, you should define

the World views first (see illustration below.)

If you set up object views for your partition and want to overwrite partitioned

views for descendant partitions, you can restore the default view for an ancestor

partition.

Portlets and Partitioned Data Providers

CA Clarity PPM portlets and processes retrieve their data from data providers

which can be NSQL queries, objects, or system types. Data providers, objects,

portlets and processes can be associated with a partition.

To create a portlet that uses a partitioned data provider, you will create

partition-specific fields for the object and then build a portlet for the object in the

partition.

You can partition static lookup values to associate them with a specific partition.

Users of a partitioned lookup see different values depending on the partition to

which an object instance belongs.

How to Work with Partitions


Partitioned lookups allow you to govern globally by enforcing the use of standard

options throughout an entire branch of a partition model. You can manage locally

by adding lookup values to meet the unique requirements of a business unit‘s

partition(s).

You can add partitioned values to stock CA Clarity PPM static lookups or to

user-defined static lookups. If an object instance is not partitioned, the lookup

shows only values for the System Partition. You can assign a lookup to a partition

when you create it or you can change an existing lookup and assign it to a

partition.

How to Work with Partitions

The following list provides an overview of the partitioning process:

1. Plan your partitioning implementation on paper so that you can carefully

consider the impact to users.

Note: Once you create partition models, you cannot delete them, you can

only deactivate them. Please plan your partition scheme carefully.

2. Set up a partition model.

3. Select an existing object to use or create a new object.

4. Add fields to the object, assign them to a partition, and select a partition

association mode.

5. Configure the views for each partition.

6. (Optional) Add partition-specific object links.

7. (Optional) Create partitioned lookup values.

8. (Optional) Create portlets based on partitioned objects.

9. (Optional) Create processes.

Note: You do not need to restart CA Clarity PPM to enable partitioning — all

partitioning configuration changes are immediately available. You can also

transfer partition models and other items created in connection with

partitioning from CA Clarity PPM using the XML Open Gateway (XOG).

How to Create and Use Partitions



The basic guidelines for working with partition models are as follows:

■ Once you set up a partition you cannot move it, not even within the same

level.

■ You cannot delete partition models—you can only deactivate them.

■ You can set up more than one partition model within CA Clarity PPM.

■ An object can only be assigned to one partition model.

Note: To work with partition models, you will need Studio - Access, Partition -

Administrator and preferably System Partition - Administrator access rights.

Create Partition Models

To create a partition model

1. Select Partition Models from the CA Clarity Studio menu.

The Partition Models page appears.

2. Click New.

3. Complete the following fields:

Partition Model Name

Enter the partition model name.

ID

Enter a unique ID for the partition model.

Note: Use only alphanumeric and underscore (_) characters. Also avoid

SQL reserved words such as SELECT or STRING. Once you save the new

field, you cannot change the ID.

Description

Enter a brief description of the partition model.

4. Click Submit.



Add a Partition to a Partition Model

Note: Before you perform this procedure, make sure you have already created a

partition model.

To add a partition to a partition model

1. Click Partition Models from the CA Clarity Studio menu.


2. Click the name of the partition model to which you want to add a partition.

3. Click the Partitions tab.

4. Click New.

5. At Partition Name, enter a name for the partition.

6. At Partition ID, enter a unique ID for this partition.

Note: Use only alphanumeric and underscore (_) characters. Also avoid SQL

reserved words such as SELECT or STRING. Once you save the new field, you

cannot change the ID.

7. At Description, enter a brief description of the partition.

8. If you are not adding the partition to the System Partition, at Parent Partition

click the Browse icon, select a (parent) partition, then click Add.

9. Click Submit.

10. (Optional) Repeat step 4 through step 10 add more partitions.

Note: You can authorize resources (users) or groups to be members of this

partition.



Add Many Partitions to a Partition Model (Quick Create)

Use Quick Create to create up to five partitions at once.


partition model.

To add many partitions to a partition model

1. Click Partition Models from the CA Clarity Studio menu.


2. Click the name of the partition model you want to use.


4. Click Quick Create.

5. At Partition Name, enter a name for the partition.

6. At Partition ID, enter a unique ID for this partition.

Note: Use only alphanumeric and underscore (_) characters. Also avoid SQL

reserved words such as SELECT or STRING. Once you save the new field, you

cannot change the ID.

7. At Description, enter a brief description of the partition.

8. If you are adding the partition to something other than the System Partition,

at Parent Partition click Browse and select that (parent) partition, then click

Add.

Note: You will not be able to select a parent partition if you haven‘t saved

the parent partition yet.

9. Click Submit.


partition.



Add Members (Resources) to a Partition


partition model.

To add a member to a partition

1. If you just created the partition and have the Partition Properties page

displaying, go to add an individual user (resource). If not, open the

Administration Tool, and then select Partition Models from the CA Clarity

Studio menu.


2. Click the name of the partition model to which you want to add members.


4. If you do not see the partition you want, click the + icon at the left of the

ancestor partition to see child partitions.

5. In the row that contains the partition you want to use, click the Properties

icon.

6. To add an individual user (resource):

a. Click Resources.

b. Click Add.

c. Select the resource you want to add or at User Name enter the

resource‘s name, and then click Filter.

d. Check the box next to the resource name, and then click Add.

e. Repeat this step to add more resources to the partition.

7. Click Exit.


partition.



Apply a Partition Model to an Object

If you want to apply a partition model to a user-defined object, first create that

object.

Note: To perform the procedures in this section you must have Administration -

Studio access rights. See the CA Clarity PPM Administration Guide for details.

You do not have to be a member of a partition to perform this task.

To apply a partition model to an object

1. Click Objects from the CA Clarity Studio menu.

The Objects page appears.

2. Click the name of the object to which you want to apply a partition model.

The Object Definition: Properties page appears.

3. At Partition Model, click the Browse icon, select a partition, and then click

Add.

4. Click Save and Exit.


Chapter 3: Configuring CA Clarity PPM

(PowerMods)


About Objects (see page 28)

Process Overview: Working with Objects (see page 29)

About Data Providers (see page 30)

Create Objects (see page 36)

Grant Access to Objects (see page 37)

Object Attributes (see page 38)

How to Audit Objects (see page 87)

Delete Objects (see page 89)

About Add-Ins (see page 90)

Apply the Add-In (see page 90)

Views (see page 91)

How to Display Multiple Subpages on a Tab (see page 114)

Links for Pages and Subpages (see page 120)

Add Image Fields to List Column Views (see page 124)

Change Field Properties (see page 128)

How to Change a Field's Appearance (see page 130)

Menus, Sections, and Links (see page 141)

Icons (see page 145)

Stock Icons (see page 147)

About Objects


About Objects

Objects are the heart of the PowerMods functionality. Objects define the

attributes (fields), subpages (links), page layout, and views that make up your

configured version of CA Clarity PPM pages.

Several stock objects are available for you to use. For example, you can use the

Audit stock object to create pages that manage audit trail information. You can

use the Audit object as is or you can create a subobject of the object that has

only some of the characteristics of the Audit object. In this situation, this object

would be the master object and your new object would be a subobject.

You can also create a hierarchy of up to three levels of objects and then allow

child objects to inherit properties and access rights from parent objects.

If you are using partitions and you add a master object to a partition model, any

subobjects you create are automatically assigned to that same partition model.

When you change the master object, those changes are automatically made

available to the subobject. After you select an object to use, you will then create

an instance of the object that you will actually use in your application.

Note: As the creator of an object, you automatically have access rights that

allow you to view and change the object. For other users to view and change the

new object, you will need to grant them access rights to it.

Process Overview: Working with Objects


Process Overview: Working with Objects

As you work with objects:

■ Decide if you will use an existing object, or create a new one.

■ Decide if you want to enable the Copy feature to allow objects to be copied.

If you select the Copy Enabled check box when you create an object, a user

has the ability to copy the attributes of one instance of the object when

creating a new instance. The Copy From button appears for the user in CA

Clarity PPM only if you select the Copy Enabled check box.

■ Decide if you want to enable the Export feature to allow the object to be

exported in XML format.

■ Decide if you want to enable the View All feature that allows the object and

all of its subobjects to display on the View All Page Properties page.

■ Define attributes (fields) that display on the object's pages.

■ You can also create portlets that are like mini-reports which display

information as graphs, grids, or HTML pages.

■ Create links from the object to other pages.

■ Define a view that determines how information appears with the object.

■ Change how fields appear. For example you can change a field's color or

label. You can also use icons to represent data, link to other pages, or

downloadable documents. You can also display bar or Gantt charts in a List

Column Views.




Data providers, the source of grid and graph portlet data, are special data

constructs that can be accessed directly with portlets or through queries.

Data provider types are Queries, Objects, and System.

Queries

CA Clarity PPM provides a query language called NSQL, that is similar to SQL,

that you can use to create queries. If you are not familiar with SQL, you can

still create portlets using the built-in data providers that come with CA

Clarity PPM.

Objects

The stock CA Clarity PPM objects—and any objects you create—contain fields

that you can use to access database information.

System

System types are data providers for the restricted portlets. You can use

these data providers in addition to stock CA Clarity PPM objects.

System Type Description

Booking Status List Used with the Team object to list data about

requests for project resources or roles.

Investments This provides combined data for investment types

(Projects, Assets, Applications, Products, and Other

Investment).

Key Tasks This is a subset of the Task object and contains data

about key tasks.

Organizer Tasks This provides data about the tasks a resource is

assigned to.

Portfolios This contains portfolio data.

Programs This contains data about programs and the projects

which belong to a program.

Project Team Members This contains data about resources assigned to

projects.

Project Team Selection This contains data about resources assigned to

projects.

Resource's Projects List This lists data about projects that a resource is

assigned to.



Objects Data Provider

The stock objects and any objects you create contain attributes (fields) that you

can configure and use to access CA Clarity PPM information. For any object, only

the attributes that are listed on the Object Definition: Attributes page display on

its pages.

Note: Object functionality is not available for timesheets, financial transactions,

budgets, and forecasts.

Action Item

Action items are the units of work, or tasks, that you assign to members of

a project, or to yourself. Action items allow you to track the progress of

investments, and ensure that the investment is complete and on time. CA

Clarity PPM supports the following action items: personal, project, and

process. All action items can be viewed from the Action Item area of the

Organizer.

Applications

See Other Investment object.

Asset

See Other Investment object.

Assignment

Assignments describe how a staff member will work on a task including the

start and finish time and dates, the actual and remaining work, and status.

Baseline

The baseline object contains a subset of project objects' fields and is a

snapshot of a project over time.

Benefit Plan Detail

This object describes benefit plan information used to enter proposed

returns on an investment.

Benefit Plan

This object contains benefit plan information used for the Benefit Plan list

page.

Change Requests

This object describes the criteria by which change requests are evaluated

and approved. This is a subobject of the Project object.

Constraint

This object stores project management task start and finish 'hints' to

scheduling. This is a subobject of the Task object.



Contract

This object contains information about project contracts.

Cost Plan Detail

This object details the cost plan information used to create cost projection

scenarios and budget revisions for an investment.

Cost Plan

This object contains the attributes used on the Cost Plan and Budget list

pages

Department

The object represents a place in a company's organizational chart. This

object is used primarily as a point of responsibility for staff and budgeting.

Dependency

This object stores project management dependencies between tasks.

Financial Properties

This object stores financial properties information displayed on the Financial

subpage for NPIOs.

Financials

This object stores the attributes for the Simple Budget page.

Fiscal Time Period

This object stores the fiscal time periods used in financial plans and

chargebacks.

GL Account

This object represents the general ledger account. A GL account is used

when charging departments costs delivered work, and for crediting

departments for the cost of resources.

Investment Parents

This object contains the attributes used on the Parents subtab under the

Hierarchy tab.

GL Allocation

This object represents the general ledger account. A GL account is used

when charging departments costs delivered work, and for crediting

departments for the cost of resources.

GL Allocation Detail

This object is used to capture the percentage of cost debited to a specified GL

account-department combination. This is a subobject of the GL Allocation

object.



Ideas

Ideas are the initial stage of creating new opportunities for investment such

as projects, assets, applications, programs, and products. Ideas lay the

foundation for a specific type of investment by serving as a container for

pertinent information. You can use CA Clarity PPM to track and convert ideas

into investment opportunities.

Incident

This object describes contact information, problem description, effort,

resolution, and resolver information for incidents (such as those reported to

a help desk).

Investment

This is an abstract object that contains the base attributes for all CA Clarity

PPM investments.

Investment Rollup

This object stores attributes used in the financial rollup and effort rollup for a

project. This information is displayed in subtabs under the Hierarchy tab that

displays for a project.

Invoice

This object stores the invoice attributes used for chargebacks.

Issues

This is a risk that has been realized. This object enables risk property

management to help increase the likelihood of project success.

Other Investment

Applications, projects, assets, products, programs, and other investments

comprise the ―inventory‖ of a portfolio. Until an organization identifies,

catalogues, and adequately describes the complete domain of investments

within their portfolio, portfolio management is effectively impossible. Each

type has a common set of attributes such as budgeted cost, ROI, Risk, and

NPV.

Other Work

This object stores attributes used within the Other Work investment.

Portfolio

This object represents a portfolio of investments in CA Clarity PPM. It

supports the portfolio management process where decisions about

investments to continue, discontinue, postpone, or start are evaluated.



Product

A project is a related set of tasks performed to achieve a specific objective.

This object describes who is responsible for managing and working on a

project, when it needs to be done, and how much it will cost. Projects are key

investments within a portfolio.

Project Financial Properties

This object stores project properties information that appears on the

Financial subpage for projects.

Project

A project is a related set of tasks performed to achieve a specific objective.

This object describes who is responsible for managing and working on a

project, when it needs to be done, and how much it will cost. Projects are key

investments within a portfolio.

Requisition

The object describes information about requisitions such as the date it was

created, by whom, priority, status, description, and the project with which it

is associated.

This is a subobject of the Project object.

Requisition Resource

This object stores staffing requisition resource information. This is a

subobject of the Requisition object.

Resource Credit

This object is used to capture a set of attributes that uniquely defines a GL

account- department combination when setting chargeback credit rules.

Resource Credit Detail

This object is used to capture the percentage of cost credited to a specified

GL account-department combination. This is a subobject of the Resource

Credit object.

Risk

This object describes the measurement of a project's likelihood of meeting

expectations (finishing on time, within the budget, and with the expected

quality level), determined by a measurement in the project's methodology.

The Risk Indicator reflects the highest risk of component projects. This is a

subobject of the Project object.

Service

This object stores the attributes used by a service investment.



Subscription

The object represents the relationship between a consumer department and

a investment or service. This is a subobject of the Department object.

Task

This object describes activities that span a specified period of time. Tasks are

part of the WBS and feed the Project Plans. Time can be tracked to a task.


Team

This describes the resource types that can be added to a team. There are

four types of labor resources that make up a team:

■ Staff, a member of the project (resource or role) who is assigned tasks.

■ Participant, a person who can access project to look at documents,

discussions, calendars, and properties, but are not assigned tasks.

■ Project Groups, a grouping of participants that can be assembled for the

project.

■ Collaboration Manager, a project role that allows you to create project

groups and grant participants


System Types Data Provider

System types are data providers that are not based on a specific CA Clarity PPM

object. The following table describes each system type.

System Type Data Provider - Type Descriptions

Type Description

Baseline The baseline object contains a subset of project objects'

fields and is a snapshot of a project over time.

Booking Status List Used with the Team object to list data about requests for

project resources or roles.



Investment).


about key tasks.

Organizer Tasks This provides data about the tasks a resource is assigned

to.

Create Objects


Type Description




Project Team

Members

This contains data about resources assigned to projects.

Project Team

Selection

This contains data about resources assigned to projects.

Resource's Projects

List

This lists data about projects that a resource is assigned

to.

Create Objects

Use the Object Definition: Properties page to view your CA Clarity PPM object's

properties and to define master and subobject relationships.

Once your object is created, you can assign access rights to users, OBS units, or

groups to access the object.

To create a new object



2. Click New.

The Create Object Definition page appears.

3. Complete the following:

Object Name

Enter a name for the new object.

Object ID

Enter a unique ID for the new object.

Description

Enter a brief description for the new object.

4. At Master or Subobject, select the type of object you are creating. Choose

Master or Subobject.

5. (Optional, master objects only) At Partition Model, click the Browse icon

and select the partition model to which this object should be added, and then

click Add.

Grant Access to Objects


6. (Subobjects only) Click the Browse icon, select the master object of this

subobject, and then click Add.

7. Click Event Enabled to make CA Clarity PPM's process engine aware of

object instances that are created or updated.

8. Click Copy Enabled to allow copies to be made of this object's instances.

9. Click Export Enabled to allow this object's instances to be exported into

XML from an action on the properties page.

10. Click View All Enabled to allow this object's instances to have a view that

contains all properties, subobject lists, and personalizable page portlets on a

single page.

11. Click Save.

Grant Access to Objects

Use this procedure to grant access to an object for users, groups, or OBS units.

Organizational breakdown structures (OBS) controls access, department

hierarchies, and reporting. If at least one OBS exists for an object, users can

associate those OBS's to their object instance.

To grant access to objects

1. If you just created the object and have the Object Properties page displayed,

go to To grant rights to:. If not, open the Administration Tool, and click

Objects from the CA Clarity Studio menu.


2. Click the name of the object you want to use.

3. To grant rights to:

■ individuals, under Access to this Object, click Resource.

■ groups, under Access to this Object, click Group.

■ OBS Units, under Access to this Object, click OBS Unit.

4. Click Add.

5. Check the box next to the access right(s) you want to grant, and then click

Next.

6. Check the box next to each user you want to grant access to.

7. To add these users and quit, click Add.

8. To add more users click Add and Select More.

9. Click Exit when done.

10. To see which users are authorized to use the object, click Full View.

Object Attributes


Object Attributes

Attributes (fields) are information that is associated with, and may or may not

display on an object's pages. If you are using an existing object you can choose

which of the fields to display on one or more pages. If you create an object, or if

you want to add user-defined attributes to an existing object, the topics in this

section show you how to create them.

Attribute Data Types

There are several procedures for creating attributes (fields). The procedure you

use will depend upon the attribute's data type. See a description of available

data types in the following table and the page on which the procedure for

creating that type of attribute is located.

CA Clarity PPM supports 11 attribute data types and each one has unique

information that determines how the attribute is used and displays.

Note: Virtual attributes are not listed in the table because they do not represent

actual data in the database. URL (link attributes) also do not appear because

they are simply links to other pages.

Data Type Description

String A text field that contains up to 2000 characters.

Large String This is similar to a string field, but the number of characters

is limited only by your database. This type does not support

filtering or sorting.

Number A field that contains numbers that can be used in

calculations.

Formula A field that is a weighted average of two or more number,

formula, money, or lookup-number fields. A

lookup-number field is a lookup that returns a numeric

value rather than a string value.

Money A field that contains currency.

Boolean A field that indicates one of two exclusive states:

■ ―on‖ or ―off‖

■ ―true‖ or ―false‖

■ ―yes‖ or ―no‖

■ ―0‖ or ―1‖

■ ―approved‖ or ―not approved.

Object Attributes


Data Type Description

Date A field that contains a date.

Lookup A field in which the user can select from predefined choices.

The choices can be static values entered by an

administrator or dynamic values returned from querying

the database. The following selection types are available:

■ Static Lists, that consist of a set of static values entered

by an administrator.

■ Static Dependent Lists, which are like static lists in that

the administrator sets up all the possible values, but

the values are arranged hierarchically like an OBS.

Sample uses include:

■ A ―Stage‖ field for an investment, but you need

different stages for different types of investments, such

as ―Research‖ and ―Develop‖ for a new product but

―Proposal‖ and ―Deploy‖ for a new asset.

■ A ―Model‖ field for a ―Car‖ object, but you need to offer

―SL1‖ and ―SL2‖ if the Make is a Saturn whereas you

need to offer ―Metro‖ and ―Tracker‖ if the Make is a

Geo.

■ Dynamic Queries, these lookups provide the most

up-to-date values possible and are best suited when

you want to offer a selection from a list of objects such

as resources, projects, issues, and so forth, as opposed

to a selection from a list of statuses or fixed options.

Multi-valued

lookup

A lookup field in which more than one value can be set. On

the object's properties page, it displays as multi-select

browse. In a filter it can display as a drop-down list, select

box, single-select or multi-select browse.

Attachment A field that contains a document attachment (such as a

Word document).

Time-varying A field in which a user can enter different values depending

on the time period being displayed. The user can enter a

start date and an end date for the value entered. The value

entered in the field can be one of the following data units

(measured per hour or per second): number, percentage,

or money.

Object Attributes


How to Add Attributes to Objects

CA Clarity PPM comes with stock attributes that you can use. These are listed on

the Object Definition: Attributes page in Studio. If you use a stock attribute, you

will not be able to change the attribute's general information (i.e. name, ID,

description, data type, lookup), but you can change how the attribute appears.

When you create user-defined attributes:

■ Make sure your attributes meet the needs of your users. Once you create an

attribute, you cannot remove it from the object. You can only deactivate the

attribute so that it does not display.

■ Create only the attributes you need. You can add many user-defined

attributes to an object; however, the number of attributes affects the

amount of time it takes to display pages, so do not create more attributes

than you need.

When you add an attribute to an object, the attribute is added to all existing

instances of that object. As new instances of the object are created, they will also

contain the new attribute.

You can also create lookup attributes that display as drop-down or browse lists

from which users can select one or more choices. Lookups can be single or

multi-valued. Multi-valued lookup attributes are frequently used in filters.

If you want to provide a link that users can click to download documents, you can

create an attachment attribute. These attributes display as clickable links in list

views and as editable text attributes with open and delete icons in property

views. When the user clicks the open icon, a document that is associated with the

attribute is downloaded or displayed for the user.

You can create attributes that provide links to web pages or virtual attributes

that are not based upon items in the database, but are derived from other data

attributes. Examples of virtual attributes are progress bars, Gantt charts, or

attributes that display the calculated results for other attributes.

Object Attributes


Add String Fields to Objects

Use this procedure to add a string (text) field. You can also use this procedure to

create large string fields whose size are limited only by the constraints of your

database. You should also consider the following limitations when using the large

string field data type:

■ Large string fields do not display in List Filter Views.

■ You cannot sort large string fields.

■ You cannot audit large string fields.

Use the Object Attribute page to add string fields to objects.

To add a string field to an object



2. Click the name of the object to which you want to add the field.


3. Click Attributes from the content menu.

The Object Definition: Attributes page appears.

4. Click New.

The Object Attribute page appears.


Attribute Name

Defines the name of the new field.

Attribute ID

Defines the unique ID for the field.




6. (Optional if you have created partitions) To associate this field with a

particular partition, complete the following fields:

Partition

Defines the partition with which this field is associated.

Partition Association Mode

Defines the partition that this field should be associated with.

Object Attributes


Options:

■ Partition, ancestors and descendents. Associates the field with this

partition and its parents and child partitions.

■ Partition and ancestors. Associates the field only with this partition

and its parents, grandparents, and so on up the chain to the System

Partition.

■ Partition and descendents. Associates the field only with this

partition and its children, grandchildren down the chain.

■ Partition only. Associates the field only with this partition.

Description

Defines the brief description of the field.

Data Type

Defines the type of data field you want to add.

Options:

■ String. Creates a field up to 2000 characters.

■ Large String. Creates a field up to an unlimited number of

characters.

Note: Once you save the field, you cannot change the data type.

Default Value

Defines the value that you want to appear as the default value for the

field.

Maximum Size

Defines the field's maximum size (up to 2000 characters).

Populate Null Values with the Default

Specifies whether you want to automatically populate existing objects

with the default value.

Default: Cleared

Value Required

Specifies whether you want to require that this field be non-blank, either

through an administrator-entered default or through end-user entry.

Default: Cleared

Object Attributes


Presence Required

Specifies whether you want to require that this field appear on the edit

properties page on at least one subpage.

Default: Cleared

Note: If the subpage that contains the field is not visible to some users

(due to display conditions or subpage security), then the field will not be

visible to the user.

Read-Only

Specifies whether you want to prevent users from changing the value of

this field.

Default: Cleared

Note: A read-only field must have a Default Value.

7. Click Submit.

Add Number Fields to Objects

Use this procedure to add a number data type attribute to an object.

To add a number field to an object







4. Click New.


5. Complete the following fields.

Attribute Name

Enter the name of the new field.

Attribute ID

Enter a unique ID for the field.




Object Attributes



particular partition, at:

Partition

Select the partition with which this lookup should be associated.


Defines the partition association mode.

Values:

■ Partition, ancestors and descendents, to associate the field with this


■ Partition and ancestors. To associate the field only with this partition


Partition.

■ Partition and descendents. To associate the field only with this

partition and its children, grandchildren, and so on down the chain.

■ Partition only. To associate the field only with this partition.


Description

Defines the brief description for this number field.

Data Type

Choose Number.


Validation Range

Enter the range of values that are acceptable for this field. Enter the

lowest number in the first box and the highest number in the second box.

Decimal Places

Enter the number of decimal places that should appear with this field.

Note: Enter ―0‖ to make the field an integer.

8. To display the number as a percent, click Show as Percent.

Do not select this check box if you want to display the number with a percent

sign.

9. If you want the field to appear with a default value, enter that value at

Default Value.

10. To automatically populate existing objects with the Default Value, check

Populate Null Values with the Default.

Object Attributes


11. To require that this field be non-blank, either through an

administrator-entered default or through end-user entry, check Value

Required.

12. To require that this field appear on the Edit Properties view on at least one

subpage, check Presence Required.

13. To prevent users from changing this value, check Read-Only.

Note: A read-only field must have a Default Value assigned in if you want

the field to appear with a default value, enter that value at.

14. (Optional) To display the field in color:

a. At Type, choose Color.

Note: Once you begin defining a display mapping, you cannot switch

display mapping types. To do so, first clear out your existing mapping

and save. You can then choose Icon or Color in the Type drop-down list.

b. At Color, select a color for the field.

c. At Description, enter a brief description of what the color represents.

d. At From, enter a number for the beginning of the range to be

represented by the color.

e. At To, enter a number for the end of the range to be represented by the

color.

f. Repeat the steps above to define any other ranges of numbers that

should be color-coded.

Note: Use color display mappings to associate a value or number range with

a description and a color. These colors can be used in many places

throughout CA Clarity PPM, such as in stoplight icons, filters, progress bars,

Gantt charts, and graph backgrounds.

15. (Optional) To display the field as an icon, at Type choose Icon and do the

following:

a. Click the Browse icon, select the icon you want to represent this range of

numbers, and then click Add.

b. At Description, enter a brief statement of what the icon represents.

c. At From, enter a number to for the beginning of the range to be

represented by the icon.

d. At To, enter a number to for the end of the range to be represented by

the icon.

Object Attributes


e. Repeat the steps above to define any other ranges of numbers that

should be represented by an icon.

Note: When you define ranges that are adjacent to one another, make sure

the ranges do not overlap. For example, the following ranges are correctly

defined to avoid number overlap: ―0-100‖, ―101-200‖, ―201-300‖. You can

define up to ten ranges in a mapping plus an optional Default Bucket for all

values that do not fall into defined ranges.

16. Click Submit.

Object Attributes


Add Formula Fields to Objects

Use the following procedure to add a formula field to an object. Formula fields

compute the weighted average of two or more fields in the same object.

To add a formula field



2. Click the name of the object to which you want to add a formula field.



4. Click New.


5. Edit the following fields:

Attribute Name


Attribute ID

Enter a unique ID that identifies the field.

Note: Use only alphanumeric and the underscore (_) characters. Do not use

SQL reserve words (such as SELECT or STRING). You cannot change the

Attribute ID after you save the field.



Partition

select the partition that this lookup should be associated with.


Select:

■ Partition, ancestors and descendents, to associate the field with

this partition and its parents and child partitions.

■ Partition and ancestors, to associate the field only with this

partition and its parents.

■ Partition and descendents, to associate the field only with this

partition and its children.

■ Partition only, to associate the field only with this partition.

Description

Enter a brief description of the field.

Object Attributes


Data Type

Choose Formula.

Note: Once you save this field, you cannot change the data type.

Decimal Places

Enter the number of decimal places for data to be returned by the field.

Note: Enter ―0‖ to make this an integer field.

7. (Optional) To display the field in color, complete the following fields:

a. Type, choose Color.

b. Color, select a color for the field.

Note: The first item you assign a color is the Default Bucket that

contains default values.

c. Description, enter a brief description of what the color represents.

d. From, enter a number to for the beginning of the range to be


e. To, enter a number to for the end of the range to be represented by the

color.

8. Repeat Step 7 to define any other ranges of numbers that should be

color-coded.

9. (Optional) To display the field as an icon, at Type choose Icon, then:




c. At From, enter a number for the beginning of the range to be


d. At To, enter a number for the end of the range to be represented by the

icon.

10. Repeat Step 9 to define any other ranges of numbers that should be

represented by an icon.

11. At Formula, click [Build Weighted Average Formula] to add a weighted

average formula.

The Build Weighted Average page appears.

a. In the Attribute column, select the name of the field you want to give

special consideration in the weighted average calculation.

Object Attributes


b. At Weighting, enter a number.

The Attribute value is multiplied by the number you entered at Weighting

to compute the weighted average for that row. Weighted values from all

rows are added and their average is computed. The entries you make in

the Weighting column cause CA Clarity PPM to consider the attribute to

be more important than other attributes when calculating the weighted

average. If you do not make any entries in the Weighting column, an

ordinary arithmetic average is computed instead.

For example:

weighted ave = [(Risk * 4) + (Customer Satisfaction * 2) + (Alignment)

* 1] /

c. To weight additional attributes, click New Row and repeat the steps

above.

d. To see if the weighted average formula works as expected, click

Recalculate. The page displays the formula results in the Test section.

12. Click Submit.

Object Attributes


Add Money Fields to Objects

Use this procedure to add a money field. CA Clarity PPM associates money fields

with a currency code so that you can convert the value to another currency if

necessary.

To add a money field






4. Click the name of the attribute to which you want to add the money field.


5. At Attribute Name, enter the name of the new field.

6. At Attribute ID, enter a unique ID that identifies the field.

Note: Use only alphanumeric characters and the underscore (_) character.

Also avoid SQL reserved words (such as SELECT or STRING). You cannot

change the ID once you save the new field.


particular partition:

a. At Partition, select the partition that this lookup should be associated

with.

b. At Partition Association Mode, select:




partition and its parents, grandparents, and so on up the chain to the

System Partition.




8. At Description, enter a brief statement about the field.

9. At Data Type, choose Money.


10. To provide a currency code for the field, do one of the following:

■ Select Attribute has its own currency code field.

Object Attributes


■ At Default Currency Code, choose the default currency code from the

drop down.

■ If the currency code is held in an existing field of the same object, select

Reference another attribute of this object. Then at Which Field, choose

the field that contains the currency code from the drop down.

11. At Validation Range, enter the lowest amount allowed for the field in the first

box, and the highest amount allowed in the second box.

12. If you want the field to appear with a default value, at Default Value enter

that value.

13. To automatically populate existing objects with the default value, click

Populate Null Values with the default.

14. To prevent users from entering values in the field, click Value Required.

15. To prevent users from removing this field from a view, click Presence

Required.

16. To prevent users from changing the field, click Read-Only.

Note: A read-only field must have a default value assigned.

17. (Optional) To display the field in color:




d. At From, enter a number to for the beginning of the range to be


e. At To, enter a number to for the end of the range to be represented by

the color.

f. Repeat the steps above to define any other ranges of numbers that


18. (Optional) To display the field as an icon, at Type choose Icon.




c. At From, enter a number for the beginning of the range to be


d. At To, enter a number for the end of the range to be represented by the

icon.

e. Repeat the steps above to define any other ranges of numbers that


19. Click Submit.

Object Attributes


Add Boolean Fields to Objects

Use Boolean fields to indicate one of two exclusive conditions.

To add a Boolean field to an object

1. Select Objects from the CA Clarity Studio menu.






4. Click New.



Attribute Name


Attribute ID

Defines the unique ID that identifies the field.

Note: Use only alphanumeric and the underscore (_) characters. Do not

use SQL reserve words (such as SELECT or STRING). You cannot change

the Attribute ID after you save the field.



Partition




Options:





Partition.




Object Attributes


Description


Object Attributes


Data Type

Defines the type of data field you want to add. Choose Boolean.


Default

Specifies whether the field's default value is true (selected) or false

(cleared).

Default: Cleared


Specifies whether to automatically populate existing objects with the

default value.

Default: Cleared

Presence Required

Specifies whether to require that this field appear on the Edit Properties

view of at least one subpage.

Default: Cleared




Read-Only


this field.

Default: Cleared

7. In the Display Mapping section of the page, (Optional) to display the field in

color, complete the following fields. Repeat this step to define any other

ranges of numbers that should be color-coded.

Type

Choose Color.

At Color

Select a color for the field.

At Description

Enter a brief description of what the color represents.

8. In the Display Mapping section of the page, (Optional) to display the field as

an icon, in the Type field, choose Icon. Repeat this step to define any other

ranges of numbers that should be represented by an icon.

a. Click the Browse icon, select the icon you want to represent this the true

or false state, and then click Add.

Object Attributes


b. Enter a brief statement of what the icon represents in the Description

field.

9. Click Submit.

Object Attributes


Add Date Fields to Objects

Use this procedure to add a date field.

To add a date field






4. Click New.



a. Attribute Name, enter the name of the new field.

b. Attribute ID, enter a unique ID for the field.

Note: This code must contain only alphanumeric characters and the

underscore (_) character, and it must also not be a SQL reserved word.

Once you have submitted or saved a field, the ID cannot be changed.


particular partition, at:

a. Partition, select the partition that this lookup should be associated with.

b. Partition Association Mode, select:





System Partition.




7. At Description, enter a brief description of the field.

8. At Data Type, choose Date.


9. Indicate the earliest date to include. At Validation From, choose:

■ Rolling Date, and select the macro to use such as Yesterday, Start of

Current Year, etc.

Object Attributes


■ At Specific Date, and select a date (e.g. 10/6/04) and time, or click the

Date icon and select one from the calendar.

■ At Time, and select the hour and/or minutes.

10. Indicate the latest date to include. At Validation To, select:

■ At Rolling Date, and select the macro to use such as Yesterday, Start of

Current Year, etc.



■ At Time, select the hour and/or minutes.

11. Indicate the default date. At Default Date, select:

■ At Rolling Date, and select the macro to use such as "Yesterday", "Start

of Current Year", etc.



■ At Time, and select the hour and/or minutes for the default date.

12. To automatically populate existing objects with the Default Date (that you

specified in Indicate the default date), check Populate Null Values with the

Default.

13. To require that users enter a value in the field, check Value Required.

14. To prevent users from removing the field in their Edit Properties view, check

Presence Required.

15. To prevent users from changing this field, check Read-Only.

Note: A read-only date field must have a default date.

16. Click Submit.

Object Attributes


Add Lookup Fields to Objects

Lookup fields display a drop-down or browse list from which users can select

items. Lookup fields are frequently used in filters. Use the following procedure to

add a lookup field based upon a single item.

Note: The lookup you add must already exist before you can add it to an object.

To add a lookup field







4. Click New.


Attribute Name


Attribute ID

Defines the unique ID for the field.






Partition

Defines the partition with which this lookup is associated.


Defines the partition association mode.

Values:





Partition.



Object Attributes



Description


Data Type

Choose lookup.


Lookup

Defines the lookup you want to use, and then click Save.

Default

Defines the value that you want to appear as the default value for the

field.


Specifies whether you want to automatically populate existing objects

with the default value.

Default: Cleared

Value Required

Specifies whether you want to require that this field be non-blank, either

through an administrator-entered default or through end-user entry.

Default: Cleared

Presence Required

Specifies whether you want to require that this field appear on the edit

properties page on at least one subpage.

Default: Cleared




Read-Only


this field.

Default: Cleared

Note: A read-only field must have a Default Value.

6. (Optional) If you selected static lookup, you can set up a display mapping

that lets you associate a value or number range with a description and a

color. These colors can be used in many places throughout CA Clarity PPM,

such as in stoplight icons, filters, progress bars, Gantt charts, and graph

backgrounds. To set up a display mapping:


Object Attributes




d. Repeat the steps above to define any other ranges of numbers that


e. At Value, select the lookup value to be represented by the color. You can

define colors for up to ten values in a mapping plus an optional Default

Bucket for all values that do not have an assigned color.

f. Repeat the steps above to define any other color-value combinations.

7. (Optional) To display the field as an icon, at Type choose Icon.

a. Click the Browse icon, select the icon you want to represent this the true

or false state, and then click Add.


c. Repeat the steps above to define any other ranges of numbers that


8. Click Submit.

Object Attributes


Add Multi-valued Lookup Fields to Objects

Multi-valued lookup fields display a drop-down or browse list from which users

can choose one or more items. On a properties page, it displays as a multi-select

browse field. In a filter it can display as a drop-down list, select box, single-select

or multi-select browse field.

Multi-valued lookup fields:

■ Cannot have default values.

■ Cannot be required or read-only fields.

■ Cannot have display mappings.

■ Are not supported by the XML Open Gateway (XOG).

Note: The lookup you add must already exist before you can add it to an object.

To add a multi-valued lookup field






4. Click New.



6. At Attribute ID, enter a unique ID for the field.


underscore (_) character. and it must also not be a SQL reserved word. Once

you save a field, you cannot change the ID.




with.






System Partition.

Object Attributes






9. At Data Type, choose Multi Valued Lookup.

Note: Once you save the field, the data type cannot be changed.

10. At Lookup, click the Browse icon, and select the lookup you want to use, then

click Save.

11. Click Save.

Object Attributes


Add Attachment Fields to Objects

Attachment fields can display links to up to ten documents. Users can use CA

Clarity PPM's search utility to find content in their document attachments, just

like any other document that has been checked into the Knowledge Store or

Document Manager.

To add a attachment field to an object

1. Select Objects from the Studio menu.





4. Click New.



6. At Attribute ID, enter a unique ID for the field.


underscore (_) character. and it must also not be a SQL reserved word. Once

you save a field, you cannot change the ID.




with.






System Partition.





9. At Data Type, choose Attachment.

Note: Once you save a field, you cannot change the data type.

Object Attributes


10. Do one of the following in the Attachment Style field:

■ To attach just one document, select Single Document.

■ To attach up to 10 attachments, select Multiple Documents, then enter

the maximum number of attachments allowed in the Maximum Number

of Attachments field.

11. To require that users provide an attachment, check Value Required.

12. To require that this field always appears in the user's Edit Properties view

and cannot be removed, check Presence Required.

13. Click Submit.

Object Attributes


Add Time-varying Fields to Objects

Time-varying fields allow users to enter different values for specific periods of

time. For example, a time-varying field can allow a user to enter the number of

hours worked on a project between a start and end date. Alternately, the field

can be set up to allow a user to enter the percentage of hours allotted to a project

that were worked between a start and end date, or the dollars spent on a project

for a specified time.

To add a time-varying field

1. Click Objects from the ye Clarity Studio menu.





4. Click New.



■ Attribute Name. Enter the name of the new field.

■ Attribute ID. Enter a unique ID for the field.






Partition

Select the partition that this lookup should be associated with.


Select:





System Partition.




Object Attributes



Description


Data Type

Select Time-varying. Once you save the field, you cannot change the

data type.

■ Time-varying Data Units. Select the appropriate data unit from

the drop-down. This selection determines what the value entered in

the field represents: a number value, a monetary value, or a

percentage.

■ Time-varying Unit Conversion. Select Seconds or Hours to

determine whether the time-varying data units are per hour or per

second.

■ Time-Varying Date Constraints. Start and finish dates selected

here provide a default date range for the field. A user can enter dates

in CA Clarity PPM that override the default dates. If no selection is

made, the default values are the widest available range. Defining a

date constraint limits the range of data received for the field and

improves processing performance.

8. If you selected Money as the time-varying data unit, to provide a currency

code for the field, do one of the following:

■ Check the box next to Attribute has its Own Currency Code Field. Then at

Default Currency Code, select the default currency code.

■ If the currency code is held in an existing field of the same object, check

Reference Another Attribute of this Object. Then at Which Field, select

the field that contains the currency code.

9. Click Save.

Object Attributes


Create Parameterized Lookup Attribute to Objects

Use this procedure to create a lookup attribute that allows mapping between

NSQL query parameters and the appropriate object attributes. This procedure

assumes that the NSQL query to be mapped already exists.

Note: See the Administration Guide for more information.

To create a parameterized lookup attribute



2. Click the name of the object for which you want to create an attribute.

3. The Object Definition: Properties page appears.



5. Click New.



Attribute Name


Attribute ID


Description

Enter a description of the field.

Data Type

Select Lookup. when you select Lookup, the remaining fields on the page

change.

7. Click the Browse icon next to the Lookup field and search for, select, and add

the lookup associated with the NSQL query you want to map.

8. Click Save.

The Lookup Parameter Mappings section displays at the bottom of the page.

The parameters listed in the section are from the NSQL code for the lookup

associated with the new attribute.

9. For each lookup parameter listed in the section, select an object attribute ID.

10. Click Submit.

Object Attributes


Calculated Attributes

A calculated attribute is a attribute whose value is based on a calculation using

the values of other attributes. For example, you might create a attribute called

"Remaining Budget" whose value is derived from the following formula:

Remaining Cost = Planned Cost - Actual Cost

In this case, a attribute's value (Remaining Budget) depends on the value of two

other attributes (Planned Cost and Actual Cost).

The value of a calculated attribute is not stored in the database; it is determined

at runtime by extracting the value from an equation set up for the attribute.

Because the value is not stored in the database, you cannot sort, use a power

filter, or manually update calculated attributes.

CA Clarity PPM provides a number of functions for calculation of an attribute's

value. The functions can be compounded to produce a complex calculation if that

is required for the attribute. For example, you might take the absolute value of

the difference in the equation given in the previous example:

Remaining Cost = Absolute (Planned Cost - Actual Cost)

Note that a calculated attribute can include other calculated attributes. CA

Clarity PPMdetermines the precedence of any calculated attributes included in an

expression at run-time.

The following attribute types cannot be used with calculated attributes:

■ Formula

■ Time-varying

■ Attachment

■ Long String

■ Multi-Value Lookups

■ Virtual

The result data type showing the results of the calculation can be one of the

following data types, depending on the function:

■ Number. This data type is used for a calculated attribute that requires a

number value such as a sum or an average of several numbers.

■ String. This data type is used for a calculated attribute that requires the

concatenation of two or more values, for example, the value of the attribute

"created_by" and the constant "2007." An example of the value produced by

the concatenation is "ssmith 2007."

■ Date. This data type is used to calculate dates using basic arithmetic or to

provide the current date.

Object Attributes


Note: You can receive a null result if the value of a parameter (field source)

included in an expression is null when the expression is evaluated for an

instance. A null result also occurs when the expression cannot be resolved. For

example, division by zero produces a null result.

Calculated Attribute Functions

The following table shows the functions that allow you to create a calculated

attribute.

Function Attribute Parameters Result Data

Type

Return Value

Absolute Value Absolute(number) Number Absolute value of the

number.

Add Add(number1, number2)

Add(number1, <constant>)

(ex: Add(A, 10))

Number Adds the value of

number1 to the value

of number2 and

returns the result of

the operation.

Average Average(number1, number2 …) Number Returns the average

of all of the

parameters passed

in.

Concatenate Concat(string1, string2 … )

Concat(string1, <constant> …)

String Concatenated string.

Date Add DateAdd(date attribute, unit, number)

■ Date attribute: This value can be an

attribute name or a sub-expression

only. It cannot be a constant.

■ Unit: Day, Hour, Minute, or Second.

This value is case-sensitive.

■ Number: Number of units to add to

the date.

(ex: DateAdd(approvedtime, ‖Day‖,4).

This expression returns a date value that

equals approvedtime + 4 days.)

Date Date value after the

number of units is

added.

Date Difference DateDiff(date attribute1, date attribute 2,

result unit)

■ Date attribute1: The date you are

subtracting from. This value can only

be an attribute name or a

sub-expression.

Number Returns the number

value as specified in

the result unit, the

difference of date

attribute1 minus

date attribute2.

Object Attributes



Type

Return Value

■ Date attribute2: The date you are

subtracting. This value can only be an

attribute name or a sub-expression.

■ Result unit: Day, Hour, Minute, or

Second. This value is case sensitive.

(ex: DateDiff(startdate, enddate,‖Day‖).

This expression returns a value indicating

the number of days between startdate

and enddate.)

Divide Divide(number1, number2)

Divide(number1, <constant>)

(ex: Divide (A,50))

Number Result from attr1

(number) divided by

attr2 (divisor).

Maximum Max(number1, number2 …) Number Largest value in the

set of values, so if:

A=10, B=20, C=30

Max(A, B, C) will

return 30.

Minimum Min(number1, number2 ... ) Number Smallest value in the

set of values, so if:

A=10, B=20, C=30

Min(A, B, C) will

return 10.

Multiply Multiply(number1, number2)

Multiply(number1, <constant> )

(ex: Multiply (A,50))

Number Product from the two

parameters.

Now Now() Date Returns the current

date and time.

Object Attributes



Type

Return Value

Percentage Percentage(number1, number2)

(ex: Percentage (A,B))

Percentage(number1, <constant>)

(ex: Percentage (A,50))

Number Result after the

percentage is taken.

(ex: If A=1000, A *

60%= 600, the

return value will be

600).

Power Power(number, power) Number Result of the number

raised to a power

specified.

Round Round(number, <number of digits>) Number Value after rounding

the number to a

specific number of

digits.

Square Root Sqrt(number) Number Square root of

number.

Subtract Subtract(number1, number2)

Subtract(number1, <constant>)

(ex: Subtract(A, 10))

Number Subtracts the value

of number1 from the

value of number2

and returns the

result of the

operation.

Sum Sum(number1, number2, ...) Number Sum from the list of

attributes.

A=10, B=20, C=30

Sum(A, B, C) will

return 60.

Object Attributes



Type

Return Value

Truncate Trunc(number, <number of digits>) Number Value after removing

the decimal or

fraction part of the

number.

How to View Calculated Attributes

You must include the calculated attribute in the layout of the object's Properties

view so that it can be viewed in CA Clarity PPM.

Object Attributes


Add Calculated Attributes

The following procedure explains how to create a calculated attribute.

To add a calculated attribute



2. Click the name of the object for which you want to create a calculated

attribute.




4. Click New.



Attribute Name

Enter a name for the attribute. The name you enter appears in the

instance of the object when the attribute is configured properly for

layout.

Attribute ID

Enter a unique ID for the attribute.

Data Type

Select Calculated from the drop-down list.

Result Data Type

Select Number, String, or Date to indicate the data type for the result of

the calculation.

6. Click Submit.

The attribute is created and appears in the list of attributes for the object.

Object Attributes


Build Calculations onto Object Attributes

To build the calculation expression, do one of the following:

■ Generate the expression in Studio by completing information about the

arguments and clicking Generate.

A generated expression for the sum of three numbers (num1, num2, and

num2) would appear in the Expression text box in the following format:

Sum(num1, num2, num3)

■ Manually enter the expression in the designated text box.

You can use the following unary operators: +, -, *, and / when the result

data type is Number. For example, the sum of three numbers can be entered

manually in the Expression text box as (num1+num2+num3). The use of the

unary operators can replace the Add, Sum, Multiply, Divide, and Subtract

functions.

To build the calculation



2. Select the object containing the attribute to which you want to build the

calculation.




4. Click the name of the new calculated attribute from the object‘s list of

attributes.


5. Click the Build Calculated Attribute link located in the Calculation field.

The Calculated Attribute page appears.

6. Select the appropriate function from the Function drop-down list.

7. Select the number of arguments in the Argument Number field. If the

function selected has a specific number of arguments, the field is read only.

If you can vary the number of arguments in the function, you can make a

selection from the drop-down list.

8. Create the arguments for the function's expression by selecting one of the

following options for each argument listed:

■ Constant. This is a value that remains the same for all calculations.

Enter the value in the field.

Object Attributes


■ Attribute Name (ID). Select an attribute from the drop-down list to

have to attribute's value included in the calculation. The list shows the

available object attribute names for the data type selected (number,

string, or date).

■ Sub-expression. Select this option to have an expression embedded

within the expression you are building for the calculation. You can accept

the default name in the text box or enter a different name for the

sub-expression.

9. Click Generate to generate the function's expression in the Expression text

box.

10. If you selected Sub-expression as one of the options, do the following:

a. In the Generate Expression for field, select the name of the

sub-expression.

b. In the Function field, select the function that defines the purpose of the

sub-expression.

c. Select and define the arguments for the sub-expression.

d. Click Generate to include the defined arguments for the sub-expression

in the whole expression.

11. When you are satisfied that all sub-expressions are defined for the whole

expression, click Validate to ensure that the expression's syntax is correct

and make any adjustments necessary.

12. Click Submit.

Object Attributes


By Example: Building Calculations onto Object Attributes

The following example shows the creation of an expression for the absolute value

of the difference between an investment's planned cost and actual cost. The

calculation can be expressed by the following equation:

Remaining Cost = Absolute(Planned Cost - Actual Cost)

The following figure shows the link for the tool that assists you in building an

expression for a calculated attribute.

When you click the Build Calculated Attribute link, the following dialog box

appears.

In the example, the absolute value of the difference between two numbers is the

desired result. When you select the "Absolute" function, the appropriate fields for

defining the function's argument appear. The following figure shows the fields for

defining the argument.

Object Attributes


The Absolute function has only one argument. The Sub-expression option is

selected to represent the expression for the difference between the numbers.

When you click Generate, the expression appears in the Expression text box.

When you include a sub-expression in a generated expression, the Generate

Expression for field appears at the top of the dialog box. To define the

sub-expression, you must select its name in the Generate Expression for field

and you must select the function for the sub-expression (Subtract in this

example) in the Function field.

Select the arguments for the Subtract function (Planned Cost and Actual Cost)

from the available list of attribute names for the object using the drop down list.

Object Attributes


When you click Generate, the entire expression with the sub-expression defined

appears in the Expression text box. The following figure shows the full

expression for the calculated attribute.

Test the Calculated Attribute

To test a calculated attribute, create an instance of the object for the calculated

attribute in CA Clarity PPM. Before you can see the calculated attribute in CA

Clarity PPM, you must add it to the object's Properties view and select the layout

for the attribute.

Object Attributes


Autonumber Object Attributes

You can use the auto-numbering feature to automatically name and number

object attributes that have a data type of string. For example, you can

auto-number the string attribute "Project ID." This ensures that when you create

a new project, the Project ID field is automatically populated with a new project

ID. You can also name and number attributes for sub-objects and the children of

sub-objects.

Each auto-numbered attribute of an object must have its own specific

auto-numbering scheme defined.

You can use auto-numbering with or without partitions. If you do not use a

partition, the System Partition is the default. If you use partitions, you can define

a different auto-numbering scheme for attributes in each partition.

How Autonumbering Works with Partitions

When an object is associated with a partition model, you can create different

auto-numbering schemes in each partition. This allows you to create

auto-numbering schemes for attributes associated with different aspects of your

business. For example, if you create a partition model that has partitions called

Sales, Marketing, and Engineering, an auto-numbering scheme can be set up

that assigns a unique number for attributes created in the partition. For

example, SAL-000001, MKT-000001, or ENG-000001. When a user creates an

object instance in CA Clarity PPM designated attributes are automatically

numbered using the auto-numbering scheme created for the appropriate

partition.

The following rules apply to using auto-numbering with partitions:

■ If an attribute is set to auto-numbered but there is no auto-numbering

scheme defined, the auto-numbering scheme of the closest ancestor

partition is applied when an object instance is created in the application.

■ If a deactivated partition has active descendant partitions that have no

auto-numbering scheme in place, the closest ancestor auto-numbering

scheme will be used when object instances are created in the descendant

partitions.

■ If an attribute belongs to a sub-object that has multiple master objects

(potentially in different partition models) and the attribute is created in the

context of a specific master object, the auto-numbering schemes will only be

applied when an instance of the sub-object is created under an instance of

the specific master object.

Object Attributes


Create Auto-Numbering Schemes on Objects

To create auto-numbering schemes for object attributes, you must have the

Object Administration or the Attribute Create access right.

To set up an auto-numbering scheme, you define the segments that make up the

number separately. For example, the scheme to create a project number such as

―PRJ00001‖ consists of two segments:

■ One for the three-character prefix ―PRJ‖, and

■ Another segment for the five digit number ―000001‖

You can create an auto-numbering scheme for a string data type object attribute

that consists of one or more segments of:

■ Text

■ Alpha-numeric counters (a combination of letters and numbers)

■ Numbers

■ Creation date

■ A reference to an attribute in a parent object

Important! If you use auto-numbering with two or more object types, make

sure that generated numbers for different object types cannot be the same. CA

Clarity PPM does not ensure that numbers are unique for different types of

objects. You can avoid duplications by using an alphanumeric numbering scheme

so that object types have a unique prefix such as "ASSET" for asset or "PRJ" for

project followed by a numeric counter.

Once created, each time a resource creates a new instance of the object, the

object ID will automatically populate using the auto-numbering scheme you

created.

To create an auto-numbering scheme



2. Click the name of the object for which you want to create an auto-numbering

scheme.




4. Click the name of the string data type attribute for which you want to create

an auto-numbering scheme.


Object Attributes


5. Click Auto-numbering in the content menu.

The Object Definition: Attribute Auto-numbering page appears.

6. In the Schemes section, click New.

The Auto-numbering Scheme page appears.

7. In the Scheme Name field, enter up to 80 characters for the scheme name.

For example, ―PRJ‖ or ―INV‖.

8. Click Save.

9. In the Segments section, click New.

10. At Type of Segment, select one of the following options:

■ Text. Creates a segment that contains only letters.

■ Numeric Counter. Creates a segment that contains only numbers.

■ Alpha-Numeric Counter. Creates a segment that contains letters and

numbers.

■ Instance Creation Date. Creates a segment that is a time stamp for

the instance being auto-numbered. The date format is: YYYYMMDD.

■ Parent Object Attribute Reference. (Sub-object attributes only)

Creates a segment that has the value of a unique attribute of the parent

object. This segment is a constant that cannot be incremented.

As you create the segments for the auto-numbering scheme, the scheme's

structure is shown in the General Information section in the Next Number

field.

11. If you are creating a text segment, in the Text Value field enter the

characters to use for this segment of the scheme. For example ―PRJ‖.

12. If you are creating a numeric or alpha-numeric counter segment, do the

following:

a. In the Counter Starting Number field enter the first number to use in the

numeric sequence.

b. In the Counter Length field, select the number of digits to use for the

segment.

c. Select the Auto-extended check box to extend the counter length when

the limit of the counter length is reached.

Object Attributes


13. If you are creating a parent object attribute reference segment, do the

following:

a. In the Referenced Attribute field, click Browse and select the attribute in

the parent object. The value of the attribute will be included in the

numbering segment.

For example, if the referenced attribute is "Name" and the referenced

object is "Project," when an instance of the specific sub-object attribute

(for example, a new task) is created in the application, the name of the

Project (up to 8 characters) is part of the numbering scheme. For

example, NewNet00000001

b. In the Segment Max Length field, select the length that you want this

segment to be. Note that the replacement value (the referenced

attribute) will be truncated if it is longer than the length selected.

14. Click Submit to create the segment.

15. Create as many segments as necessary.

16. In the Schemes section, select the partition the numbering scheme for the

attribute applies to. If the attribute's object is not associated with a partition,

only the System Partition is available.

17. To activate this scheme, select the Auto-numbered check box in the General

section.

Note: When auto-numbering is activated, users will not be able to change

object IDs because CA Clarity PPM will create them.

18. Click Save.

Object Attributes


Modify Auto-Numbering Schemes

This procedure explains how to modify an existing auto-numbering scheme for

an object attribute.

To modify an auto-numbering scheme



2. In the list of objects, click the object to open its Properties page.



4. Click the attribute whose auto-numbering scheme you want to modify.


5. In the content menu on the left, click Auto-numbering.


6. In the Partition field, select the partition for which the change to the

numbering scheme for the attribute applies.

If the attribute's object is not associated with a partition, only the System

Partition is available.

7. In the Schemes section, click Edit.

The Auto-numbering Scheme page appears.

8. To reorder the segments in the scheme, do the following:

a. Click Reorder.

b. Highlight segments individually and use the arrows to move them to the

correct position.

c. Click Submit when you are done.

As you make changes, the auto-numbering scheme's structure is shown in

the General Information section in the Next Number field.

9. Make changes to the segments as needed by clicking the segment name in

the Type of Segment column.

10. Click Save.

Object Attributes


Deactivating an Attribute's Auto-Numbering Scheme

This procedure explains how to deactivate an auto-numbering scheme for an

object attribute.

To deactivate an auto-numbering scheme



2. Click the name of the object.




4. Click the attribute whose auto-numbering scheme you want to deactivate.


5. In the content menu on the left, click Auto-numbering.


6. Clear the Auto-numbered check box.

7. Click Save.

Modify Object Attributes

Use this procedure to modify user-defined object attributes.

To modify an object attribute



2. Click the name of the object you want to modify.




4. Select the name of the attribute you want to modify from the list.


5. Modify the attribute, and submit your changes.

Object Attributes


Delete Object Attributes

Use this procedure to delete user-defined object attributes. You cannot delete

stock attributes. When you delete an attribute, the attribute is removed from the

object's views and the database. The following changes also occur:

■ Any attributes derived from the deleted attribute are deleted.

■ A record of the deletion is stored in the Audit Trail log.

■ Queries that use the database table column created for the attribute are

identified so that they can be removed manually.

■ Calculated and formula attributes that use the attribute prompt a warning

message.

Some attribute information is not deleted. If you use the attribute in reports or

reference the attribute in custom database code, these uses are not deleted.

Some uses of the attribute in NSQL queries may not be deleted.

If an attribute is being used anywhere in the view by a user, you cannot delete

the attribute. You must take one of the following actions before you can delete:

■ Contact any users who are using the attribute to have them remove the

personalization. When you try to delete an attribute that is being used, you

receive an error and a list of users who are currently using the attribute.

To have users delete a personalized attribute, have them navigate to the list

page of the object and select Configure from the Actions drop-down menu.

In the page that appears, the user must click General in the content menu,

then click Restore Defaults.

■ Publish the view. This action automatically removes any end-user

personalization. After you publish, you can delete the attribute.

Important! As a precaution, remove any use of the attribute in a query or in

calculations for attributes before you delete. Deleting an attribute used by a

query or included in a calculation can produce unintended results. Once the

deletion occurs, the only way to retrieve the data is through a database backup

restoration.

To delete an object attribute



2. Click the name of the object you want to modify.




Object Attributes


4. In the list of attributes, check the box next to the attribute you want to delete

and click Delete.

The Confirm Object Attribute Delete page appears.

5. Review the list of associated items and make sure none have dependencies

(queries or other attributes that use the attribute to be deleted).

6. Complete one of the following:

■ If you find dependencies, click No to exit the page, then remove the

dependencies and repeat the procedure to delete the attribute.

■ If no dependencies are listed, click Yes to delete the attribute.

How to Audit Objects



You can configure CA Clarity PPM to audit and preserve a record of operations

performed on many CA Clarity PPM objects. When an object is configured for

auditing, instances of the object display an Audit tab when viewed in CA Clarity

PPM.

Note: See the Common Features and Personal Options User Guide for more

information.

The Audit Trail features include:

■ Tracking insert, delete, and change operations

You can select the operations and the attributes that you want audited. For

example, you might track changes for a specific risk called "High Defect

Count" that you create and add to a project.

■ Tracking operations for subobjects with the master object

You can configure auditing operations for a subobject like a task. Users can

see the subobject's auditing information from the Audit tab of the subobject

or the master object.

Instance security is enforced on the object's Audit tab. This means that the

user must have the right to view the subobject, or it will not be visible on the

master object's Audit tab.

■ Tracking time varying attributes

Budgeting and resource planning use time varying attributes. You can

configure these attributes to track the history of changes.

■ Global Audit Trail view

Administrators can see a complete log of all insert, delete, and change

records across all objects.


■ Audit Trail maintenance

You can purge unneeded audit records by running the Purge Audit Trail job.

When you configure an object for auditing, you can specify the number of

days records are kept before being deleted. If you do not indicate the

number of days, object records are kept indefinitely.




To set up an audit trail for an object



2. Click the name of the object you want to set up for auditing.


3. Click Audit Trail from the content menu.

The Object Definition: Audit Trail Attributes page appears.

4. In the Audit Attribute section, highlight the attributes you want to audit for

changes and click the right arrow to place them in the Audited Attributes list.

5. In the Object Audit section, do the following:

■ Highlight the attributes you want audited for insertions and click the

right arrow to place them in the Logged Attributes for Insert Operation

list.

■ Highlight the attributes you want audited for deletions and click the right

arrow to place them in the Logged Attributes for Delete Operation list.

6. In the Purge Audit Trail section, enter a number to indicate how many days

a record for this object is to be kept before being purged when the Purge

Audit Trail job is run. Leave the field blank to keep records indefinitely, and

click Save.

The object is set up for audit trail.

Delete Objects


Delete Objects

Use this procedure to delete user-defined objects. You can delete any object that

you create. To delete an object created by another user, you must have the

appropriate access rights to the object. CA Clarity PPM stock objects cannot be

deleted.

When you delete an object, the following information is deleted from the

database:

■ Object views

■ Object database tables

■ Object page sets

■ Portlets using the object (through an object data provider)

Some object information is not deleted. If you use the object in reports or

reference the object in custom database code, these uses are not deleted. Some

uses of the object in NSQL queries may not be deleted. Although audit trail

records for the object are deleted, a record of the deletion itself is stored in the

Audit Trail log.

Queries that use the database table created for the object are identified so that

they can be removed manually.

Important! As a precaution, remove any use of the object in a query or a portlet

before you delete. Deleting an object used to provide information to other parts

of CA Clarity PPM can produce unintended results. Once the deletion occurs, the

only way to retrieve the data is through a database backup restoration.

To delete an object



2. In the list of objects, check the box next to the object you want to delete and

click Delete.

The Confirm Object Delete page appears.

3. Review the list of associated items and make sure none have dependencies

(portlets or queries).

4. Complete one of the following:

■ If you find dependencies, click No to exit the page, then remove the

dependencies and repeat the procedure to delete the object.

■ If no dependencies are listed, click Yes to delete the object.

About Add-Ins


About Add-Ins

Add-ins are a collection of content, such as portlets, pages, access groups,

processes, reports, and jobs that you can import as a single entity into CA Clarity

PPM. To get started with CA Clarity PPM you can install, apply, and use the

collection of content that comes with add-ins.

Apply the Add-In

If you already have the add-in installed and you are upgrading to a current

add-in version, you must choose which new or modified items you want to apply

to the add-in and apply them.

The Add-In Details page in Studio lists all of the items—portlets, pages, queries,

lookups, tabs, and reports—that are included with the add-in. You can use this

page to apply these items.

The following columns display on the Add-In Details page:

Status

Indicates if the add-in item is applied or not in CA Clarity PPM.

Values:

■ Not Installed. New items that are new to this add-in version or that you

did not install from a previous version.

■ Update Ready. Modified items that were applied to CA Clarity PPM and a

change to the item is included in the current version.

■ Installed. Items that are installed.

Type

Indicates the item type.

Values: Object, Lookup, Tab, Query, Portlet, Page, Custom View, Group,

Menu, Project, Process, Role, and Report/Job

ID

Displays the add-in item's code, which usually becomes the ID of the applied

add-in item.

By default, when you upgrade to the current add-in version, only the items that

are new or modified are selected. However, you can select or clear the items that

you want to apply.

Important! Before applying modified items, make sure that you have not

configured any existing item. If you have, you may not want to apply these

items. Applying modified items to existing items overwrites their configurations.

Views


To apply add-in items

1. Log in to CA Clarity PPM, and open the Administration Tool.

The Administration Home page appears.

2. Select Add-Ins from the CA Clarity Studio menu.

The Add-Ins page appears.

3. Click the name of the add-in from which you want to apply items.

The Add-In Details page appears.

4. Review each selected item and accept only the changes that you want. Only

those items selected update. You can select or clear the items that you want

to apply.

5. Click Apply.

Note: If a selected item has dependencies on other items, these

dependencies also update.

A list of updated items displays in the Confirm Add-In Update or Install page.

6. Do one of the following:

■ Click Yes to update or install the items.

Note: If a user has previously changed an item listed on the Confirm

Add-In Update or Install page, then you will need to publish the item

before users will see the change.

Note: See the Studio Developer's Guide for more information on how to

publish configured items, such as portlets, pages, and views.

■ Click No to cancel the process.

Views

An object's view determines how information displays on a page. There are three

types of views:

List Filter View

This view is a section that appears at the top of a list column view and allows

users to search for information.

List Column View

This view displays information about object instances in rows and columns.

Properties View

This view displays and allows users to enter information about an object.

Views


Add User-Defined Fields to Views

You can add user-defined fields to property, list filter, and list column views.

Add Fields to an Object's Properties View

To add a field to an object's Properties view



2. Click the object's name.


3. Click Views from the content menu.

The Object Definition: Views page appears.

4. Locate the properties view that you want to work with and click [Layout:

Edit] from the Setup column in that row.

The Property Layout page appears.

5. In the Property Layout hierarchy, select the section to which you want to add

the field, and click the Properties and Layout icon next to the item.

The Section Properties page appears.

6. In the Available list, click the name of the field you want to add to the page.

7. Click the Add Field (right arrow) button to move the field to the desired

column.

8. Click Submit.

Add Fields to an Object's List Filter View

List Filter views display on CA Clarity PPM list pages to help users filter the list. A

list filter view can appear in a collapsed state where only the filter field displays,

or in an expanded state so that users can see many filter options.

Use the List Filter Layout page to add fields to an object‘s list filter view.

When you set up list filter views you can choose to display a Build Power Filter

link that users can click to build and save complex queries.

Power Filters Example

A user enters two or more terms into a regular filter box (for example ―John

Adam‖). It is assumed that this is an AND operation and ―John Adam‖ is returned

in the results. The user decides to use a power filter and selects a variety of

operators including OR and select which fields to search in. With the power filter,

―John‖ or ―Adam‖ is returned in the results, but not both.

Views


The following image shows a sample page displaying the Applications object with

an expanded list filter view (in the filtering section above) and a list column view

(in the section below).

To add a field to an object's list filter view



2. Click the object category whose List Filter view you want to add a field.

Note: The categories that display depend upon how you CA Clarity PPM

administrator configured CA Clarity PPM.



4. Next to the List Filter category, click Layout.

The List Filter Layout page appears.

5. In the Available list, select the field to add and click the right arrow (Add

Field) button to move the field to the desired column.

6. Repeat until the fields you want to display are listed in the correct column.

7. Complete the following fields in the Settings section:

Section Title

Determines the name of the filter section's title bar.

Default Filter State

Determines how the filter displays initially. Select Collapsed to display

only one filter field or select Expanded to display multiple filter options

for the user.

Allow Power Filter

Determines whether the Build Power Filter link is available to the user to

build power filters. Select the box to display the link to the user.

Views


8. Click Submit.

The Applications page filter section now shows the effects of the options you

have selected.

9. Click Publish to replace personalized changes that users have made to this

view.

Note: This replaces any modifications that users have made to their

personal views.

Add Fields to an Object's List Column View

Use the following procedure to add fields to List Column views. You can also add

virtual fields that don't represent data in the database, but are derived from

other data fields. You can use these virtual fields to display aggregations,

comparisons, and variances. You can create many aggregation rows for a grid.

Use the Configure: List Column Layout page to add fields to an object‘s list

column view.

See following a sample page that displays an object with an collapsed list filter

view (hidden from view) and a list column view displaying a list of applications.

To add a field to an object's list column view



2. Click the object in which you want to display the field.

The Object Definition: Properties page appears



4. Next to the List Column view you want to add a field, click Layout.

The Configure: List Column Layout page appears.

5. In the Available Columns list, select the field you want to add.

Views


6. Click the right-arrow to move the field to the Selected Columns list.

7. Click Submit.

8. Next to List Column view, click Options, then set any of the following options:

Secondary Value Display

Select one of the options to show the secondary (alternative) value when

the user moves the cursor over the field. To show the secondary when

the value is null, select the "Show Secondary Null Values" check box.

Filter

Select an option to indicate whether filter results are shown

automatically or shown only after a filter operation is performed.

Rows per Page

From the drop-down list, select the number of rows to display for this

view.

Highlight Row by Attribute

When the value entered here is not zero, the row is highlighted.

Display Currency Code in Column

This check box controls the display of currency codes (for example, USD)

in investment grids. If multiple currencies are used, this option is

selected by default and the check box cannot be cleared.

If you clear the check box when a single currency is used, the currency

code displays in a legend below the grid.

Allow Configuration

When you select this option, users can see the Configure option in the

Actions field drop-down list.

Allow Label Configuration

This option works in conjunction with the Allow Configuration option. If

you select the Allow Configuration option and you clear the Allow Label

Configuration option, field labels become unavailable for configuration

while other items can still be configured.

Attribute Value Protection

Select an option to protect or display attribute values in the list. You can

protect attributes using display conditions and secured subpages or

secured subpages only, or you can display all attribute values.

9. Submit your changes.

Views


Add Aggregation Rows for Number Fields

Use this procedure if you have number or money fields, and you want to show

aggregations for these rows. Use the Aggregation Row Properties page to add

aggregation rows for number fields.

If you add more than one aggregation row, you can change the order in which

they appear in the view. The view‘s aggregation rows display on the Configure:

List Aggregation page.

To add aggregation rows for number fields

1. Select Objects from the Studio menu.


2. Click the object to which you want to add an aggregation row.




4. Next to the List Column view containing number fields for which you want to

add an aggregation row, click Aggregation.

The Configure: List Aggregation page appears.

5. Do the following for each aggregation row you want to add:

a. Click Add.

The Aggregation Row Properties page appears.

b. Complete the following fields:

■ Label, enter a name for the aggregation row.

■ Select the Show check box to enable the row.

■ At Attribute, select the field you want to use.

■ At Function, select the aggregation function you want to use to

calculate values in the row:

Views


– Aggregation Function. Select the aggregation function to use;

choose from Sum, Average, Count, Maximum, Minimum, Standard

Deviation, or Variance

– Threshold Aggregation Function. Select the aggregation

function to use; choose Sum, Average, Count, Maximum, Minimum,

Standard Deviation, or Variance.

– Comparison Column. Select the column to compare with this one.

– Comparison Column Aggregation Function. Select the

aggregation function to use; choose Sum, Average, Count,

Maximum, Minimum, Standard Deviation, or Variance.

– Display. Select the manner in which to display the data; choose

Number, Column Graph, or Bar Graph, and then click Save.

c. Click Submit.


Views


Change the Order of Aggregation Rows

Use this procedure if you have added more than one aggregation row to a view

and want to change the order in which they appear. The view‘s aggregation rows

display on the Configure: List Aggregation page.

To change the order of aggregation rows



2. Click the object to which you want to add an aggregation row.




4. Next to the List Column view containing number fields for which you want to

add an aggregation row, click Aggregation.


5. Click Reorder.

The Reorder Aggregation Rows page appears.

6. Select the row you want to move, and click the up or down arrows to move

it up or down the list.

7. Click Submit.


view.

This replaces any modifications that users have made to their personal

views.

Set up Multiple Time-varying Fields in List Column Views

You can display multiple time-varying fields in the same list column view. The

data for the fields displays as stacked on the page, with the information for each

time-varying field appearing in the same virtual column. The data that displays

can be in units of money, numbers, or percentages.

An object instance (Phone Replacement Project) in the list view shows two

time-varying values stacked in the same column: Cost of Units Completed

(money) and Number of Units Completed (number).

If you export data to Microsoft Excel, each time-varying value that is stacked in

a CA Clarity PPM virtual column will be allotted an Excel column of its own. For

example, if you have time slices A, B, C, and D with 3 time-varying attributes

configured in a virtual list view column, an export will produce 12 Excel columns:

A1, A2, A3, B1, B2, B3, C1, C2, C3, D1, D2, and D3.

Views


How to Set Up Multiple Time-varying Values

To set up multiple time-varying values in the same column in an object's list

view, you must complete the following basic steps:

1. Create the time-varying attributes you want to include in the list view if they

do not exist already.

2. Configure the list view for the object by doing the following:

a. Creating a time-scaled virtual column. A time-scaled virtual column can

be used to show multiple time periods in the same cell in the column.

b. Adding the time-varying attributes to the column.

c. Adding the time-scaled virtual column to the object's List Column view

layout.

3. Configure the properties view for the object to show the time-varying

attribute fields and to allow the CA Clarity PPM user to edit the fields and

change values.

4. Set up a time slice request for each time-varying attribute. See the CA

Clarity PPM Administration Guide for complete information on time slice

requests.

5. Run the Time Slicing job. This job can be set up to run on a schedule that

suits your business needs. See the CA Clarity PPM Administration Guide for

complete information on the Time Slicing job.

6. View the time-varying attributes displayed in the time-scaled virtual column

in CA Clarity PPM. To view the time-varying fields, create an instance of the

object and include values for the time-varying attributes in the Properties

page. Results for the values can be seen in the virtual column on the List

page.

Note that the user can edit the fields by entering values for different time

periods.

Configure the List Column View for Multiple Time-varying Fields

This procedure explains how to set up an object's list column view to show

multiple time-varying attributes in the same virtual column.

To configure the list column view



2. Click the name of the object in the list that appears.


3. Click Views.


Views


4. Create the virtual column by doing the following:

a. Click Fields in the object's list view.

The Configure: List Column Fields page appears.

b. Click New.

The Create Virtual List Column page appears.

c. Select Time Scaled Value and click Submit.

d. In the General section, do the following:

■ In the Available list box, select the attributes you want to list in the

column and use the arrow buttons to move the attributes to the

Selected list box.

■ Enter a name for the virtual column in the Column Label field.

■ Select the Allow Editing check box to allow users to make changes to

the fields in the column.

■ Select the Show Legend Column check box to display each attribute

name in the column beside its values.

■ Select the Show Column Label check box to display the column name

at the top of the column.

e. In the Time Scale section, enter the number of time periods that are to

display in the column.

f. Set any other options on the page that apply.

g. Click Submit.

5. Include the column in the object's List view by doing the following:

a. Click Layout in the object's List view.


b. In the Column Layout section, select the name of the column in the

Available Columns list box and move it to the Selected Columns list box

using the arrow buttons.

c. Set any other options on the page that apply.

d. Click Submit.


view.


personal views.

Views


Use Fields to Sort a List Column View

You can add up to four fields that sort a List Column view. The fields may be

user-defined, stock, or both.

To sort a list column view using a user-defined field



2. Click the name of the object you want to sort.


3. Click Views.


4. Next to List Column view click Layout.


5. Indicate the primary sort column in the Column Sorting section's First Field

row, select the field.

6. To sort the column in descending order, click Descending.

7. To indicate additional sort columns, repeat Step 5 and Step 6 in the second,

third, and fourth field columns respectively.

8. Click Save.


view.


personal views.

Views


Create Subpages for the Properties View

You can add a subpage to the properties view of an object. A subpage behaves

like a page when it is displayed, but it allows you to group specific information

that can be defined by the user or displayed for the user.

For example, you can create a subpage for scheduling or financial data. Some

stock objects have subpages included for this type of information.

To see a subpage, you click a link in the content menu that appears on the left of

the parent page.

Views


Add a Subpage

To add a subpage to an object's property view










5. Click Create Subpages.

The Create Subpages page appears.


Subpage Name

Identifies the name that will appear in the content menu as a link to the

subpage.

Subpage ID

Identifies the subpage using a unique alphanumeric identifier.

7. Click Submit.

The Property Layout page appears with the new subpage listed.

Views


Define Subpage Properties

You can define the layout of the subpage sections and determine whether the

page is secured against unauthorized access. In addition, you can define the

conditions under which the page does or does not display for all users. You can

secure a subpage so that it displays only if a user has been granted access rights

to view or edit the subpage.

To define subpage properties










5. In the Layout section, use the arrow keys to place the sections in the order

you want them to appear on the subpage.

6. In the Properties section, complete the following fields:

Subpage Name

Identifies the subpage in the content menu. You can change the current

name by entering a new name.

Linkable

Indicates that the subpage can have a link on other pages in the

application. Select the check box to allow the subpage to be linked.

Default: Cleared

Secure

Indicates whether the subpage has access rights associated with it.

When this check box is selected, access rights (view and edit) are

generated for the subpage. A user must be granted the access rights

view and edit information on the subpage.

Default: Cleared

7. (Optional) In the Display Conditions section, click [Define display

conditions].

The Display Condition Builder page appears. Use this page to define a set of

conditions that determine when the subpage appears..

8. Click Submit.

Views


About the Display Condition Builder

The following table shows the operands that allow you to create a display

condition. You can use the Display Condition Builder to generate the expression

or you can type the expression in the Expression text box.

Operand Function Example

== equals asset.created_by == "marybell"

! not !(asset.created_by == "marybell")

!= not equals asset.created_by != "marybell"

> greater than asset.planned_cst_total > 25000

>= greater than or

equal

asset.planned_cst_total >= 25000

< less than asset.planned_ben_total < 100000

<= less than or equal asset.total_ownership_cost <=

asset.forecast_cst_total

|| or asset.total_ownership_cost > 5000 ||

asset.planned_ben_total > 5000

&& and asset.is_active == 1 &&

asset.planned_cst_total > 50000

like like like( asset.created_by, "marybell" )

notLike not like notLike( asset.created_by, "marybell" )

Use the following rules to manually enter an expression:

■ Place text values in double quotes.

■ The syntax for the object to attribute relationship is object.attribute. For

example, in the expression asset.created_by=="marybell", the object to

attribute relationship is shown in the first half of the expression.

■ The expressions are case sensitive when evaluated. Enter values in the

appropriate case to ensure you get the correct true or false display value.

■ The Negate Expression button makes the entire expression that displays in

the Expression text box negative by enclosing the expression in parentheses

and placing and exclamation symbol before the parentheses. For example,

!(asset.created_by == "marybell").

Views


■ The Add Parentheses button encloses the entire expression in parentheses.

Use parentheses to specify precedence. For example, in the following

expression, asset.created_by != "marybell" || (asset.is_active == 1 &&

asset.planned_cst_total > 50000), the portion of the expression enclosed in

parentheses will be evaluated first. The result of the evaluation will then be

compared with asset.created_by != "marybell".

■ The Evaluate button evaluates the expression in the Expression text box.

Use this button if you enter text manually or modify text you have created

using the Display Condition Builder.

■ The And/Or field is used to create compound expressions in the Expression

text box. After the first expression is entered, this field becomes active so

that you can choose the operand (And or Or) for the second expression.

There are some operations in the Display Condition Builder that you can use for

any object for which you are defining display conditions.

Operation Syntax

Check resource's global

rights

checkGlobalRight(<global right code>,<value to

check>,<operator>)

Check resource's group checkGroup( <group code>, <value to check>,

<operator> )

Check resource's OBS

unit

checkOBSUnit( <OBS path>, <OBS Internal ID>,

<OBS level>, <value to check>, <operator> )

Check resource's partition checkOBSUnit( <OBS path>, <OBS Internal ID>,

<OBS level>, <value to check>, <operator> )

If an attribute is linked to a lookup, you can use the following syntax on the right

side of the equation.

Lookup Type Syntax

Numeric lookup( <lookup code>, <internal lookup value id>

)

String lookup( "<lookup code>", "<lookup value code>" )

Views


Add Sections to Subpages

To add a section to a subpage










5. Click the name of the subpage you want to add a section to, and click Create

Sections.

The Create Sections page appears.

6. Enter the section name or names you want in the individual text boxes, and

click Submit. The maximum number of sections that you can add at a time is

five.


7. Do the following, and then click Submit:

■ To add fields to the section, click the Section icon that appears in the

Section's row.

■ In the Available list, click the name of the field you want to add to the

page.

■ Use the arrow keys to move the field to the appropriate column, then use

the up and down arrow keys to place the field in the proper order in the

list of fields.

Your changes are saved.

Publish Changes to List and Filter Views

You can overwrite list and filter views for CA Clarity PPM users who have

personalized views by publishing new views. A user who has not personalized a

view sees changes in CA Clarity PPM immediately when you make and save

changes to the view in Studio. A user who has personalized the view does not see

changes to the new view until you publish the changes.

Views


If you are using partitions, the new published view affects only the partition you

select.

During a CA Clarity PPM upgrade or when installing add-ins, personalized user

views are not upgraded. Accordingly, if a view is configured or if the view‘s object

is partitioned, the system will not upgrade that view. To keep users current, you

may want to publish any new views provided by a CA Clarity PPM upgrade or

from an add-in.

Note: If upgrade or new system changes to a view's attributes are required for

CA Clarity PPM to operate properly, the changes are merged with the user's

configured view during an upgrade. The merge of required changes with the

user's configured view does not overwrite the user view and does not cause the

view to be marked as upgraded.

The Views page in Studio provides information that lets you make appropriate

decisions about publishing new views. Use this page to determine which views

were not upgraded automatically and may require manual upgrading and to

publish changes.

The Views page shows a list of system views and their current status in CA Clarity

PPM. Custom views are not listed. Use the Views page to manage all system

views across all objects and their partitions.

Use the following columns on this page to assess whether you need to publish a

view to users:

View::Code

Identifies the view name. "View" is the nonspecific part of the name and

many views can exist in different partitions or the same partition that have

this portion of the name. "Code" is a name attached in CA Clarity PPM that

identifies the view more specifically. Using the view::code name, object,

category, and partition, each view can be fully identified.

Object

Identifies the object on which the view is created.

Category

Specifies the category type for this view.

Values: filter, list, and property

Type

(Properties views) Displays the view type.

Values:

■ Creating. The purpose of this view is for creating an instance or an

object.

■ Editing. The purpose of this view is for editing an instance or an object.

Views


Partition

Displays the partition to which the view pertains.

Default: System

Personalized

Specifies whether at least one user has configured the view in CA Clarity

PPM. Publishing a new view or restoring the view default clears this check

mark.

Modified

Specifies whether changes have been made to the view by the CA Clarity

PPM administrator since its original installation or since the last time defaults

were restored.

Upgraded

Specifies whether an upgrade has occurred for the view since its original

installation. A check mark indicates the view was upgraded because it was

not configured.

Last Restored

Displays the date that view defaults were last restored.

Last Version

Indicates the last release version in which changes have been made to the

out-of-the-box view. The version number in this read-only field is updated

only when changes for a view occur in a release.

Note: Only the System partition has its views updated when an upgrade

occurs. If views from other partitions are in the list, the Last Version field for

these views will not show a value.

To publish changes to views

1. Select Views from the CA Clarity Studio menu.

The Views page appears.

2. Select the views that you want to publish to users, and click Publish.

The Restore View Confirmation page appears.

3. Click Yes.

Views


Restore Defaults for Object Views

This procedure explains how to restore the out-of-the-box CA Clarity PPM

defaults for an object's views. Restoring the defaults for an object's views

overwrites all user and CA Clarity PPM administrator configurations of properties

views, list views, and filter views to the original view properties. If you are using

partitions, the defaults are restored only in the selected partition.

Restoring defaults for an object's view also clears the check mark from the

Modified column and updates the Last Restored column with the current dateon

the Views page.

To restore the defaults for an object's views



2. Click the name of the object whose views are to be restored to default

values.


3. Click Views.


4. Click Restore Defaults.

Restore Defaults for Selected Views

You can restore CA Clarity PPM's out-of-the-box defaults for multiple views,

including property views, list views, and filter views. When you restore defaults,

any changes made by users or CA Clarity PPM administrators to the view are

overwritten, and the CA Clarity PPM view defaults are restored.

You must repeat this step for every view that was not upgraded. After restoring

defaults, add the new attributes to the views.

To restore the defaults for a selected view



2. Select the views to which you want to restore default values, and click

Restore Defaults.

The Restore View Confirmation page appears.

3. Click Yes.

Views


Restore Defaults Based on Partitions

When you restore defaults for a property, filter, or list view, in a particular

partition model, the attribute settings cascade from the ancestor partitions to

the descendent partitions based on the following rules:

If restoring defaults for a view at the system partition:

■ All views are overwritten with the out-of the-box system attribute settings.

■ The attribute settings cascade from the system partition to the first

descendent partition that has a configured view.

■ If no descendent view is configured, attribute settings cascade to the lowest

descendent node in the partition model.

If restoring defaults for a view at a descendent partition:

■ Views are overwritten based on the first ancestor partition that has a

configured view. If no ancestor partition has a configured view, attributes

settings are applied based on the system partition.

■ The attribute settings cascade from the descendent partition (at which

"restore default" was applied) to the first sub-descendent partition that has

a configured view.

■ If no view is configured at a sub-descendent partition, attribute settings

cascade to the lowest descendent node in the partition model.

Views


Best Practice: Restore defaults for your views from the top-down in your

partition model.

The following diagram shows how out-of-the-box attribute settings are applied

from the system partition level down to the descendent levels in a partition

model:

Views


The following diagram shows how out-of-the-box attribute settings are applied

from a descendent partition level down to the sub-descendent levels in a

partition model:

How to Display Multiple Subpages on a Tab



You can create and use a custom property view to display multiple subpages on

a custom portlet page tab. The custom property view can be used for custom

objects only, not stock CA Clarity PPM objects. You can display the subpage links

on the tab using one of the following options:

■ A content menu with links that display on the left side of the tab.

■ Subtab links that appear at the top of the tab. A subtab can also have a

content menu with links to additional subpages.

The process for displaying multiple subpages on multiple tabs using custom

property views includes the following basic steps:

1. Create a custom property view.

The custom property view defines a set of subpages and the content that

appears on each subpage.

2. Define the display of custom subpage links that appear on a custom portlet

page tab by selecting the appropriate custom property view.

Define and Manage a Custom Property View

A custom property view can only be created on the System partition. Once

created, the property view applies to all child partitions. Only the Layout:Edit

option under Setup in the Views definition is available for a custom property

view. The following sections explain how to create and manage custom property

views.



Create a Custom Property View

A custom property view can only be created for a custom object.

To create a custom property view

1. Open the custom object from the CA Clarity Studio menu by clicking Objects

and selecting the custom object from the list page that appears.


2. Click Views in the content menu on the left.

3. Click New.

4. Enter the name of the new property view and a unique ID.

5. Click Save.

The new property view is added to the Object Definition:Views list page.

Add Subpages to a Custom Property View

You can add five sub-pages at a time to a custom property view. The number of

sub-pages you can add to a property view is unlimited.

To add subpages to a custom property view

1. On the Object Definition: Views list page, locate the custom property view

and click [Layout:Edit] in the Setup column.


2. Click Create Subpages.

3. Enter a name and ID for each subpage you want to create and click Submit.

The Property Layout page appears showing the new subpages.

4. Populate the subpages with sections and attributes, and set up display

conditions, if needed.



Move Subpages Between Property Views

If you have multiple property views, you may need to move subpages from one

property view to another. This allows you to quickly change which view data is

displayed for a tab. Note that you can move subpages between stock and custom

property views.

To move subpages between property views

1. Locate the custom property view on the Object Definition: Views list page

and click [Layout: Edit].


2. Select the check box next to the subpages you want to move to another

property view, and click Move.

The Move Subpages page appears.

3. Select the option next to the property view you want to move the subpages

to, and click Move.

The Property Layout page reappears showing the subpage list without the

moved subpages.

4. Click Back.

The Object Definition: Views list page appears.

5. Click [Layout: Edit] in the row of the property set (view) you moved the

subpages to.

The moved subpages are listed in the Property Layout page.



Delete Subpages from Custom Property Views

If a subpage is associated with a subobject, it cannot be deleted from a property

view. In this case, you can move the subpage to another property view.

To delete a subpage from a property view





3. Locate the custom property view on the Object Definition: Views list page

and click [Layout: Edit].

The Property Layout page appears showing the subpages for the view.

4. Select the check box next to the subpage or subpages you want to delete and

click Delete.

A confirmation page appears asking if you want to delete the selected

subpages.

5. Click Yes.

Delete Custom Property Views

The following rules apply to deleting a custom property view:

■ Subpages linked to a subobject associated with the custom property view

must be moved to another property view before the custom property view

can be deleted. Note that subpages linked to a subobject cannot be deleted.

■ You cannot delete a custom property view if it is associated with a custom

tab or a portlet page subtab. You must remove all associations before a

check box appears that allows you to select the view for deletion.

■ You can only delete a custom property view from the System partition.

■ When you delete a custom property view from the System partition, the view

is also deleted from child partitions.

To delete a custom property view





3. Select the custom property view you want to delete and click Delete.



Restore Defaults for a Custom Property View

You can restore the defaults for a custom property view just as you can for other

views. Restoring the defaults reinstates the original view properties for all users.

Any personalized user changes to the view will be overwritten with the defaults.

Note: The Restore Defaults button does not display if the custom property view

is associated with a portlet page tab or a subtab.

Display Custom Subpage Links on a Tab Using the Custom Property View

You can display links for subpages on a tab in one of the following ways:

■ In a content menu on the left side of the tab

■ In a set of subtabs below the name of the tab

■ In a combination of content menus and subtabs which also contain content

menus

Prerequisite

To display custom subpages on a tab, the page that the tabs are associated with

must have a Type value that is equal to the custom object on which the custom

view and subpages were created. The Type value is assigned when a page is

created. If the Type value for the page you are adding subpages to is not equal

to the object on which you created the custom views, create a new page and

make the Type value equal to the custom object.

Display Subpage Links in a Tab's Content Menu

To display custom subpage links in a tab's content menu

1. In the CA Clarity Studio menu, click Portlet Pages.

The Pages page appears with a list of pages.

2. Click the name of the page you want to add a new tab to.

The Page: Properties page appears.

3. Click Tabs in the content menu.

The Page: Tabs page appears with a list of tabs that appear on the page.

4. Click New.

The Tab: Properties page appears.


Tab Name

Indicates the name that will appear on the tab in the user interface.



Tab ID

Indicates an internal identifier for the tab. Enter a unique alphanumeric

string.

Content Source

Indicates the origin of the content for the data on the tab. Select a

source from the drop-down menu.

6. In the Layout field, select Properties.

The View field appears directly below the Layout field.

7. In the View field, select the custom view with subpages you want to appear

on the content menu of the tab.

Note: For information purposes, the individual subpages are listed out for

each view with the subpages in parentheses. The subpage you select is the

default that displays for the view when you click the tab.


9. View the changes in the application.

Display Subpage Links as Subtabs on a Tab

To display subpage links as subtabs

1. In the CA Clarity Studio menu, click Portlet Pages.

The Pages page appears with a list of pages.

2. Click the name of the page you want to add a new tab to.


3. Click Tabs in the content menu.

The Page: Tabs page appears with a list of tabs that appear on the page.

4. Click New.

The Tab: Properties page appears.


Tab Name

Indicates the name that will appear on the tab in the user interface.

Tab ID

Indicates an internal identifier for the tab. Enter a unique alphanumeric

string.

Content Source

Indicates the origin of the content for the data on the tab. Select a

source from the drop-down menu.

Links for Pages and Subpages


6. In the Layout field, select Subtab.

The View field appears directly below the Layout field.

7. In the View field, select the custom view with subpages you want to appear

on the content menu of the tab.

Note: For information purposes, the individual subpages are listed out for

each view with the subpages in parentheses. The subpage you select is the

default that displays for the view when you click the tab.

8. Select Save and Continue.

The Tab: Subtabs page appears. Use this page to define subtabs.

9. Click New.

A new row appears where you can define additional subtabs.

10. Complete the following actions:

a. Enter a name in the Subtab field and a unique identifier in the Action

Code field.

b. Select a property set (view) from the Property Set drop-down list.

The property view you select appears in the content menu on the subtab.

If you do not want subpages to appear in the subtab content menu,

select General.

c. Click Save.

11. Click Exit.

12. View the changes in the application.


You can link to many object pages, such as Property, Overview, Process Flow

Layout, Budget/Forecast, Staff/Task Properties, Advanced Resource Search,

XDM forms, and documents.

You can create the following types of links to and from object pages:

■ Designate a page as a subpage so that you can create a link from an object's

pages to its subpages.

■ Add fields to object attributes that link (URL) to web pages.

■ Use a consistent URL format to link to the properties page of an object

instance record (stock or custom) from an external application.



Link from an Object Page to a Subpage

Use this procedure to designate a page in CA Clarity PPM as a subpage so that

you can provide a link to it.

To add a new link to an object



2. Click the name of the object to which you want to add the link.

3. Click Linking from the content menu.

The Object Definition: Linking page appears.

4. Click New.

The Link Settings page appears.


Link Name

Enter a name for the link.

Link ID

Enter a unique ID.

Description

Enter a description of the link.

Action

Select the page to display when the user clicks this link.

6. Depending upon the action you chose above, you will be asked to select

values for fields that the subpage has in common with this object. Both

objects must have these values in common for linking to work.

7. Click Submit.

Link from an Object Attribute to a Web Page

A link field provides a link to a URL (Web page) outside of CA Clarity PPM.

To add a link field



2. Click the name of the object to which you want to add the link.





4. Click New.



Attribute Name


Attribute ID



underscore (_) character and it must also not be a SQL reserved word.

Once you save a field, you cannot change the ID.

Description


Data Type

Choose URL.

Note: Once you save a field, you cannot change the data type.

Default Value

Enter the value you that you want to appear as a default value for the

field.

Maximum Length

Enter the field's maximum length. The maximum size of a string field is

1000 characters. Do one of the following:

■ To automatically populate existing objects with the Default Value,

check Populate Null Values with the Default.

■ To require that users enter a value into this field, check Value

Required.

■ To require that this field always appears in the user's Edit Properties

view and cannot be removed, check Presence Required.

■ To prevent users from changing the value of this field, check

Read-Only.

Note: A read-only field must have a Default Value assigned.

6. Click Save.



Link to Properties Pages from External Applications

You can link to the properties page of an object instance record (stock or custom)

in CA Clarity PPM from external applications using a consistent URL format. You

can use any unique attribute value to identify the object instance and view its

properties page. The action is consistent for all objects (stock, custom, or sub

object).

The following is an example of the URL format that you can use to reference the

stock object, project:

http://someclarity.somebiz.com/niku/app?action=odf.customObjectInstance&odf_c

ode=project&unique_code=myamazingproject

The relevant URL parameters are described below:

odf_code=project

Defines the stock object definition ID as defined in the administration

pages. In the above example, project is the code for the Project stock

object.

unique_code=myamazingproject

Determines how the object instance is retrieved. The parameter name

unique_code identifies the name of the unique attribute on the object which

in turn identifies the object instance that you want to reference. The

parameter name you use here depends solely on the object that you want to

reference as identified by the odf_code parameter described earlier. In the

above example, the object is Project, and unique_code is used to identify a

project instance with the unique_code value of myamazingproject.

The following is an example of the URL format that you can now use to reference

a custom object, BPM Department:

http://someclarity.somebiz.com/niku/app?action=odf.customObjectInstance&odf_c

ode=custom_workflow&release=1.0.1A

The relevant parameters in the above URL are described below:

odf_code=custom_workflow

Defines the custom object definition ID as defined in the Studio object

administration pages. In the above example, custom_workflow is the code for

the Custom Workflow custom object.

release=1.0.1A

Defines a custom string attribute Release on a custom object Custom Workflow

with object code custom_workflow where the release is 1.0.1A.

Note: URLs with properly escaped parameter values will work as valid URLs. For

example, if you use the attribute ―name‖ with the value ―My Green Items‖, the

URL is constructed as ‗...name=My%20Green%20Items‘.

Add Image Fields to List Column Views



You can use image fields to display information as Gantt charts, icons, image

links, or progress bars on List Column views.

Example

On the Projects list page, users can click the name of the project (link) to open

the project. Users can also view the general project Gantt from this page.

Add Gantt Chart Fields to List Column Views

Gantt charts show duration and progress over time. New virtual fields are

automatically displayed in the far right column of the list. You can move the

virtual field to a different position in the List Column layout.

To add a Gantt chart field to a list column view



2. Click the object name to which you want to add the chart.


3. Click Views.


4. In the List Column View row, click Fields.

5. Click New.

6. Select Gantt.

7. Click Submit.

8. In the Time Scales section:

a. At Column Label, enter a label for the top of the list column.

b. At Start Date, enter the start date in one of three ways:

■ Select Specific Date, then enter a date into the box, or click the

Calendar icon and choose a date.

■ Select Rolling Date, then select the period to include.

c. At Time Scale, select the time values to show across the top of the chart

(e.g. Day, Week, Month, etc.).

d. At Number of Time Periods, enter the number of time periods to be

displayed in the chart.



e. (Optional) At Time Period Offset, enter the number of time periods if you

want to shift the beginning of the Gantt bar relative to the Start Date.

Note: Use this option only if you also enter a Start Date.

f. At Show Group Header Row, enter the Year, Quarter, Month, or Week (if

you want to display a timescale above the Gantt bar).

g. At Column Width, enter the percentage of the view's width that should

be allocated to the Gantt chart column.

9. Define the primary bar of the Gantt chart:

a. At Item Name Attribute, select the attribute for the primary bar.

b. At Start Date Attribute, select the date field to use for the beginning of

the bar.

c. At Finish Date Attribute, select the date field to use for the end of the

bar.

d. At Milestone Attribute, select the field to use for milestones.

Note: If this field contains a non-zero value, the Gantt chart displays a

diamond.

e. At Progress Through Date Attribute, select a date field to use to indicate

when work is complete.

Note: If you choose a Progress Through Date Attribute, it overrides the

Progress Percent Attribute.

f. At Progress Percent Attribute, specify the percentage of the bar's length

that the progress line shall be.

g. At Color Attribute, select the bar's color.

h. At Show Mouseover, select the values that will appear when the user

moves a cursor over the bar. Choose from Item Name, Start Date, Finish

Date, Progress Through Date, and Progress Percent.

10. (Optional) To display a second bar below the primary bar (for comparison

purposes), check the Show Secondary Bar box and repeat Step 9 above in

the secondary bar section.

11. Click Save.



Add Image Link Fields to List Column Views

You can add an image link that when clicked links the user to another page. For

example, in a Project List Column view, when a user clicks the Document

Manager icon, the page for the project's document manager functions appear.

When you add image link fields to a list column view, CA Clarity PPM

automatically displays the new virtual field in the far right column of the list. You

can move the virtual field to a different position in the List Column layout.

To add an image link field to a list column view



2. Click the object name to which you want to add the field.



4. In the list column view's row, click Fields.


5. Click New.

The Create Virtual List Column page appears.

6. For the Display Type, select Image, and click Submit.

7. Click Submit.

The List Column Field page appears.


Column Label

Enter a label to display at the top of the list column.

Show Column Label

Make sure this option is selected.

Image

Select an image to display.

Link

Select the page to display when the user clicks the image.

Open as Pop-up

Select this option to have the page appear in a pop-up window.

9. Click Submit.



Add Progress Bar Fields to List Column Views

Use the following procedure to add a progress bar field to a list column view.

Progress bars show progress over time. Use the Progress Bar Column Settings

page to add progress bar fields to list column views.

CA Clarity PPM automatically displays the new virtual field in the far right column

of the list. You can move the virtual field to a different position in the List Column

layout.

To add a progress bar field



2. Click the object name to which you want to add the progress bar.




4. In the list column view's row, click Fields.


5. Click New.

The Create Virtual List Column page appears

6. Click Progress Bar and then click Submit.

The Progress Bar Column Settings page appears.


Column Label

Enter a label to display at the top of the list column.

Show Column Label

Click display the column label.

Current Stage Name

Select an attribute for each stage in the Progress Bar (this displays at

below the column label).

Current Stage Number

Select an attribute for the current stage.

Number of Stages

Select the attribute that defines the total number of stages in the bar.

Change Field Properties


Color Attribute

select the attribute that determines the color of each stage.

Show Label

Click display the name of the current stage in the Progress Bar.

Column Width

Enter a number that indicates the percentage of the list's width is

allocated to the Progress Bar column.

8. Click Submit.


You can change a user-defined field's properties; for stock CA Clarity PPM objects

and fields, you can only change the display mappings.

To change user-defined field properties



2. Click the name of the object that contains the field that you want to change.




4. Click the name of the attribute that you want to change from the list.


5. Change any of the following items:

Properties You Can

Change

Comments

Date range validation Applies only to new records.

Decimal Places You can only increase the value of this attribute.

Default Value The default value to display.

Description A description of the field.

Formula fields These fields retain existing calculated values and

change only when you edit the Formula field and

save it.

Links Links that when clicked, display other CA Clarity



Properties You Can

Change

Comments

PPM pages.

Lookup field default value You can't change the Lookup or change the lookup

type to Multi-valued. You can, however, change

the default value used when the Lookup is

updated.

Maximum Length You can only increase the value of this attribute.

Name The name of the field.

Numeric Range Validation Applies only to new records.

Presence Required Defines whether the field must appear.

Risk Only the formula can be changed.

Show as Percent If you change this property, only new values are

shown as a percent.

Unique You can change a field from unique to

non-unique, but not vice versa.

Value Required status You can change a field from required to

non-required, but not vice versa.

6. Click Submit.

Your changes are saved and the Object Definition: Attributes page appears.

7. To see your changes, click the field's name again.

8. Click Exit.

How to Change a Field's Appearance



This section describes the appearance changes you can make to fields. You can:

■ Change an object's Display Mapping

You can have various data represented by different colors or icons. These

colors are defined in each field's (attribute) definition page and indicates the

color to display for each range of data. For example you can indicate that the

numbers one through five display in red while values between 6 and 10

display in green.

■ Use icons to represent ranges of values

This technique is commonly used on List Column views. Studio provides a set

of icons that you can choose to display such as a yellow checkmark,

discussion bubbles, attachment icons, and envelope and lock icons.

■ Change field labels, hints, tooltips, default values, and if entry is

required

You cannot change the field's attributes or the data type, but depending

upon the field's data type, you can sometimes change the Display Type. You

can place a hint above or below a field.

■ Display data as bar or column graphs

If you are using number, formula, or money fields in a List Column view, you

can display the data as bar or column graphs. Column graphs are like bar

graphs, except that they are oriented up-and-down instead of left-to-right.

You can add a stacked bar to bar graphs that start at the right end of the

primary bar. You might do this, for example, in the Primary Column to show

cost to date and in the Secondary Column for cost remaining.

Note: Any changes you make to the field appearance affect only that particular

view. You can set different appearance options for the same field in different

views.

Change Field Labels

The label that is displayed for a field or column does not have to be the actual

field name. You can change the label of a stock or user-defined field. The same

field can also appear with a different label in different views.

Use the Object Definition: Property Fields page to modify a view's field label.

To change the field label





2. Click the object whose field label you want to change.

The Object Definition: Properties page appears by default.



4. Find the property view that you want to change, then click Fields next to that

view.

The Object Definition: Property Fields page appears.

5. In the Property Label row, find the field whose label you want to change and

enter a new name.

6. Click Submit.

Display a Range of Values as a Color or Icon

You can use icons and color in a list column to indicate a range of values. This

allows you to visually flag specific information so that a list can be scanned

quickly.

This feature allows you to:

■ Choose where the image is placed, either before or after the content

■ Map the image to any attribute available from the data provider, not just the

attribute being rendered in the field

■ Set up an unlimited number of images for a list column

You cannot use this feature in virtual columns that contain Gantt charts,

progress bars, time sliced values, or virtual images.

Note: You can only map a display image for those attributes whose data type is

"Number."

To display a range of values as a color or icon



2. Click the object whose field you want to change.

The Object Definition: Properties page appears by default.



4. Click the attribute for which you want to display an image.




5. In the Display Mappings section, to represent the range of values as:

■ a color, at Type choose Color. Then select a color from the drop-down list

to represent the information.

■ an icon, at Type choose Icon. Then click the Browse icon and select the

icon to use to represent the range of values.

6. Complete the following fields in the section:

Description

Enter a description for the range of values.

From

Enter the beginning value for the range.

To

Enter the ending value for the range.

7. If you are creating more than one image for an attribute (for example, a

green icon, yellow icon, and red icon for different statuses), repeat Complete

the following fields in the section: as many times as necessary.

8. Click Submit.

Change the Appearance of Properties View Attributes

To change the appearance of a properties view attributes



2. Click the code name of the properties view whose field you want to change.


3. In the Properties category row, click Fields.

The Object Definition: Property Fields page appears.

4. Click the Properties icon next to the field you want to change.

The Property Field page appears.

5. Change any of the following options (the options that appear depend on the

field's data and display type):

Attribute

Read-only. Displays the name of the field.



Property Label

Defines the label for the field.

Note: To translate the label into another language, click the Translate

icon and enter text in another language. If you do not see the Translate

icon, try clicking Save.

Display Type

This field displays for date data type fields. Specifies how you want the

date to display.

Values: Date, Date and Time

Default: Date

Hint

Enter a message that helps the user use the field. The maximum length

of this field is 512 characters.

Hint Position

Indicates where the hint appears in context with the field.

Values: Above or Below

Default: Below

Tooltip

Enter a short message to display when the user moves a cursor over the

field.

Width

Enter the number of characters allowed for the text entry box.

Attribute Default

Enter the default value for this field.

Override Default

Enter a new default value for new records created through this view.

Attribute Default Date

Enter the default date for this field.

Override Default Date

Specifies the default date.

Values: Rolling Date and Specific Date

Value Required

Check this box to require that users enter a value.



Enter Once

Check this box to prevent users from changing this field's value after it

has been entered.

Hidden

Check this box to prevent the field from displaying on user views. Use

hidden fields to add data that is used in calculations but does not display

on the page. When you add hidden attributes to properties views, they

will not appear to the user. You must define a default for hidden

attributes.

Height

Enter the number of lines allowed for a text area box.

6. Click Submit.

Change the Appearance of List Column View Fields

Before you can see the changes that you make to list column view fields, you

must add it to the List Column layout.

To change the appearance of a list column view field



2. Click the object whose field appearance you want to change.



4. In the List Column category row, click Fields.


5. Click the Properties icon in the row that contains the field whose appearance

you want to change.




Allow Editing

Enables edit mode and allow users to change the field's data.



Alignment

Defines the alignment.

Values:

■ Left, to align the field with the left side of the column,

■ Center, to center align the field in the column, or

■ Right, to align the field with the right side of the column.

Allow Word Wrapping in Column

Check this box to allow field text to wrap when the text is wider than the

column.

Allow Word Wrapping in Column Header

Check this box to allow header text to wrap when the column header is

wider than the column.

Column Label

Enter the name you want to appear for the column.

Column Width

Enter the column size (in pixels).

Decimal Places

Enter the number of decimal places to display for this field.

Display Elements

Defines the display elements.

Values:

■ Image, to display the field as an image.

■ Value, to display the field as a value.

■ Range Description, a descriptive label to represent the range of

values.

Note: You can choose to display such columns of information as a value

(e.g., 6.4), as a image (such as a green/re/yellow stoplight), as a range

description (e.g. super, fair, awful), or a combination of these options.



Display Type

Choose:

■ Number to display the field as a number

■ Percent to display the field as a value with a percent sign (for

example, .34% or 34%)

■ Calculated Percent to display the field as a calculated value (100 x

field value) with a percent sign (for example, 34% or 3400%)

■ Column Graph to display the field as a column graph

■ Bar Graph to display the field as a bar graph.

Disable Link Attribute

Select an attribute to indicate whether the value in the Link field appears

in a list or grid as text only or as a hyperlink.

If the value of the attribute selected equals zero, the text in the

corresponding Link field appears as text only. If the value selected in the

field is not zero or if a value is not selected, the value selected in the Link

field appears as a hyperlink.

This field applies only when the Link field has a value selected.

Link

Select a page to display when users click this link. To have the page

display in a pop-up window, check the Open as Pop-up box.

Secondary Value

Select a secondary field's value to display when the user moves a cursor

over the field.

Show Column Label

Check this box to display the column label.

7. Click Submit.

8. Click the Indicator Images icon next to the field whose appearance you want

to change by adding an image.

The List Column Field: Indicator Images page appears.

9. In the Available Images list box, select the image or images you want to

appear in the field and click the Move Image arrow below the list box.

10. Click the Move Image arrows at the bottom of the page to position the image

or images either before or after field content.

11. If you have multiple images, use the up and down arrows to set the order

that the images appear in the field.




Change the Appearance of List Filter View Fields

Before you can see the changes that you make to the appearance of a list filter

view field, you must add it to the List Filter layout.

To change the appearance of a field in a list filter view






4. In the List Filter category row, click Fields.

The Object Definition: List Filter Fields page appears.

5. Click the Properties icon in the row that contains the field whose appearance

you want to change.

The List Filter Field page appears.


field's data and display type). You can choose to display such columns of

information as just the value (e.g., 6.4), as an image (such as a

green/red/yellow stoplight), as a range description (e.g. super, fair, awful),

or a combination of these options.

Filter Label

Enter a new label.

Display Type

Select Date or Date Range.

Display Elements

Defines the display elements.

Values:

■ Image, to display the field as an image.

■ Value, to display the field as a value.

■ Range Description, to enter a descriptive label for the range values.



Filter Default

Defines the filter default. Do one of the following:

■ To choose a period to include, select that date from the Rolling Date

drop-down list,

■ Enter a date into the Specific box, or

■ Click the Calendar icon and select a date.

Note: If you choose Date Range as the Display Type, the page redraws

to show Filter Default From and Filter Default To options so that you can

set defaults for both ends of the date range.

Required in Filter

Check this box to ensure that the field cannot be removed from the List

Filter layout.

Hidden in Filter

Check this box to make the field appear in the List Filter view, but

invisible to users. Use hidden fields to include data for calculations that

are not displayed.

Read-Only in Filter

Check this box to prevent users from changing the value of this field in a

List Filter view.

Note: If you select this option, the field must have the Filter Default

value set.

Hint

Enter a message to help users use the field.

Limits: 512 characters

Tooltip

Enter a short message to display when the user moves the cursor over

the field.

7. Click Submit.

Display Fields as Bar or Column Graphs

To display a field as a bar or column graph









4. On a list column view type row, click Fields.

The Configure: List Column Views page appears.

5. Click the Properties icon in the row that contains the field you want to

change.




Column Label

Enter the name you want to appear for the column.

Show Column Label

Check this box to display the column label.

Allow Word Wrapping in Column Header

Check this box to allow header text to wrap when the column header is

wider than the column.


Display Type

Select:

■ Column Graph, to display the field as a column graph, or

■ Bar Graph, to display the field as a bar graph.

Secondary Value

Select the attribute whose value displays when the user moves a cursor

over the primary bar.

Alignment

Select:

■ Left, to align the field with the left side of the column,

■ Center, to center align the field in the column, or

■ Right, to align the field with the right side of the column.



Thickness

Choose from the following options:

■ Autofit to fit the graph to the column width.

■ Narrow to display a narrow graph.

■ Medium to display a medium-width graph.

■ Wide to display a wide graph.

Maximum Length

Enter the length of the bar (in pixels).

Length Scaling

Choose from the following options:

■ Relative to Same Column. Use this to make the bar length

proportional to other bars in the same column. This option is most

useful when displaying horizontal bars. For example, the Budget

Cost bar in a row with a value of $500,000 would show as twice the

height of the Budget Cost bar on a row with a value of $250,000.

■ Relative to Same Row. Use this to make the bar proportional to all

other bars in the same row. This option is most useful when

displaying vertical bars. For example, the Budget Cost bar with a

value of $500,000 would display as twice the height of the Budget

Benefit bar with a value of $250,000.

■ Relative to Entire Table. Use this to make the bar proportional to

all bars of the same type (vertical or horizontal) in the entire table.

For example, in a grid with the Budget Cost column as a vertical bar

and a row with a Budget Cost value of $500,000 would display as

twice the height as the Budget Cost value of $250,000 in another

row.

■ No Scaling. Use this to draw all bars to the maximum length. This

can be used to create progress bars.

For example, you could have an ETC column with actuals as the

threshold value. The part below the threshold shows how much work

is already done; the part above shows how much work remains to be

done. By looking at a column of these bar graphs you can quickly see

how close each task is to being complete relative to the others.

Color

Select a color for the primary bar.

Threshold Line Attribute

Select an attribute (field) in the same object that holds the threshold

value.

Note: In bar graphs, a vertical line marks the threshold value.

Menus, Sections, and Links


Over-threshold Color

Select a color to represent values greater than the threshold value.

Note: Any portion of the primary bar that extends past the threshold is

drawn in the over-threshold color. Any portion of the secondary bar that

extends past the threshold is drawn in a darker shade of the same color.

Link

Select a page to display when the user clicks the primary bar. If you want

the page to open in a pop-up window, check the Open as Pop-up box.

8. (Optional) To create a stacked bar, complete the following fields:

a. Stacked Attribute, select the attribute to be represented as a stacked

bar.

b. Color, select a color for the stacked bar.

c. Secondary Value, select a value to display when the user moves a

cursor over the secondary bar.

9. At Link, select a page to display when the user clicks the secondary bar.

10. Click Submit.


After you create pages of content, use the following procedures to add menus

and links in the Administration Tool or CA Clarity PPM main menu. You can also

do the following:

■ Rearrange sections and links

■ Move links between sections

■ Rename links and sections

Add Menu Items or Links

Use this procedure to add menu items and links that display pages to the

Administration Tool main menu or the CA Clarity PPM main menu. Main menus

display on the left side of all CA Clarity PPM pages.

To add sections or links to the Administration Tool or to the CA Clarity

PPM main menu

1. Select Menu Manager from the CA Clarity Studio menu.

The Menu Manager page appears.



2. To add a link to the:

■ Administration Tool, click Administration Tool Menu.

■ CA Clarity PPM application that users see, click Application Menu.

The Menu Hierarchy page appears and displays all sections and links. A

check mark appears in the Active column next to menu items that are

currently activated. System pages are always active.

3. Check the box next to the menu that you want to add a section or link to and

then click Add.

4. Do one of the following, and click Submit:

■ To create a link, click Link.

■ To create a section, click Section.

5. If you are adding a link, complete the following fields:

Link Name

Defines the link's name.

Description

Defines the link's description.

Page Name

Click the Browse icon and select the page to display when the link is

clicked.

Parent Menu Item

Select the menu in which this link will appear.

6. If you are adding a section:

Section Name

Enter a name.

Section ID

Enter unique section ID.

Description

Enter a description

7. Click Submit.

The Menu Hierarchy page re-appears and includes the items you added.



Change Sections and Links

Use this procedure to change the sections and links that display in the

Administration Tool main menu or the CA Clarity PPM main menu. Main menus


To change sections or links in the Administration Tool or CA Clarity PPM

main menu



2. To change an item in:

■ The Administration Tool, click Administration Tool Menu.

■ CA Clarity PPM, click Application Menu.

The Menu Hierarchy page appears and displays all sections and links.

3. Check the box next to the item you want to change.

4. You can do the following:

■ Change a link, click Link.

■ Change a section, click Section.

5. Click Submit.

6. Change any of the following fields:

Description

Enter a description. (Links only)

Link Name

Enter a name.

Page Name

Click the Browse icon and select the page to display when the link is

clicked.

Parent Menu Item

Select the section in which this menu item will appear. (Sections only)

Section Name

Enter a name.

Section ID

Enter unique section ID.

7. Click Submit.



Move Sections and Links

Use this procedure to move the sections and links that display in the

Administration Tool main menu or CA Clarity PPM main menu. Main menus


To move sections or links to the Administration Tool or CA Clarity PPM

main menu



2. To change an item in:

■ The Administration Tool, click Administration Tool Menu.

■ CA Clarity PPM, click Application Menu.

The Menu Hierarchy page appears and displays all sections and links.

A check mark appears in the Active column next to the item that is currently

activated. System pages are always active.

3. Click Reorder.

4. At Menu Items, select a section or link and then click the up and down arrow

buttons to move it to another position.

5. Click Submit.

Delete Sections or Links

Use this procedure to delete links or sections. You can only delete sections and

links that you created. Sections and links that are provided by CA Clarity PPM

cannot be deleted. If you delete a section or link that a user is currently viewing,

the user is unaffected. The next time the user displays the page, however the

section or links will not appear.

To delete a section or link from the Administration Tool or CA Clarity

PPM main menu



2. Select the section or link to delete.

3. Click Remove, then click Yes.

Icons


Icons

The following list shows the icons in CA Clarity PPM. You can use these to create

image links:

The detailed resource information icon

The grey diamond icon.

The grid with check mark icon.

The grid with plus icon.

The guideline icon.

The hierarchy icon.

The lock icon.

The OBS Investments icon.

The person with list icon.

The project icon.

The resource allocation icon.

The resource finder icon.

The resources icon.

Icons


The right arrow with indent icon.

The roles icon.

The scenario investments icon.

The staff icon.

The subproject icon.

Stock Icons


Stock Icons

The following list shows the stock icons. You can use these to create image links

The Attachment icon.

The blue down arrow icon.

The blue right arrow icon.

The blue right-facing triangle icon.

The blue up arrow icon.

The calendar icon.

The detailed resource information icon.

The discussions icon.

The document manager icon.

The envelope icon.

The exclamation icon.

The green book icon.

The green check mark icon.

Stock Icons


The green up arrow icon.

The green down arrow icon.

The green flag icon.

The green right arrow icon.

The grey down arrow icon.

The grey right arrow icon.

The grey right facing triangle icon.

The grey up arrow icon.

The list icon.

The process icon.

The properties icon.

The red check mark icon

The red down arrow icon.

The red flag icon.

The red right arrow icon.

Stock Icons


The red striped box icon.

The red up arrow icon.

The red x icon.


Chapter 4: Portlets: Grids, Graphs,

Pages, and Menus


Portlet Overview (see page 151)

Types of Access Rights (see page 152)

Stock Portlets (see page 154)

About Personal Dashboards and Portlets (see page 160)

Interactive Portlets (see page 164)

Graph Portlets (see page 167)

HTML Text Portlets (see page 180)

Grid Portlets (see page 183)

Filter Portlets (see page 191)

Portlet Pages: Deploying Content (see page 209)

Publish Changes to Portlets (see page 215)

Access to Portlets and Pages (see page 215)

Delete Filter Portlets (see page 223)

Portlet Overview

Portlets are snapshots into CA Clarity PPM data and can consist of grids, graphs,

or snippets of HTML. You select data to display in the portlet. While portlets do

not replace CA Clarity PPM reports, they can be considered as mini-reports.

You can create and publish portals across the enterprise. Each portal page is

comprised of a set of portlets—small windows of information presented as

graphs, tables, or web page snippets—that appear automatically on the desktops

of CA Clarity PPM users with the appropriate access privileges. Users can further

personalize their portal pages by deciding which portlets to show or hide and

where to show them on the page.

Portlets obtain information and business intelligence from CA Clarity PPM, from

other databases within the enterprise, and from external sources available in

HTML, such as business news and network status information. Users can

populate portlets with graphs, tables, workflows, best practices, documents, and

forms-all updated and available in real-time without the need to run reports.

The following portlet types are available:

Graph portlets (see page 167)

Provide graphic views into CA Clarity PPM data, such as pie and line charts.

Types of Access Rights


Grid portlets (see page 183)

Are lists or tables of data that can be filtered on-the-fly.

HTML portlets (see page 180)

Formatted in HTML, these portlets grab web page content and plug it into a

CA Clarity PPM page. Data can be extracted from other internal or external

web sites.

Filter portlets (see page 191)

Coordinate filtering operations between portlets on a page.

Interactive portlets (see page 164)

Displays visually-rich, real-time CA Clarity PPM information using imported

Xcelsius visualizations.


The following table describes the types of access rights you can assign:

Page Definition Editor

Change content and page layout (requires Studio Access access rights).

Page Definition Viewer

View only page content and layout (requires Studio Access access rights).

View Page

View a link to the page on the main menu and then view the page.

Portlet Definition Editor

Change the code and options for a portlet (requires Studio Access access

rights).

Portlet Definition Viewer

View only the portlet code and options (requires Studio Access access

rights).

View Portlet instance

View the portlet and add the portlet to a personal or global page.

Menu Definition Editor - All

Edit and view the definitions of all menus in the Administration Tool.

Menu Definition Viewer - All

View menu definitions in the Administration Tool.



Portlet Definition Editor

Edit and view the portlet definition (requires Studio Access access rights).

Portlet Definition Editor - All

Edit all portlet page definitions in the Administration Tool (requires Studio

Access access rights).

Portlet Definition Viewer

View the portlet definition (requires Studio Access access rights).

Portlet View

View a portlet.

Portlet Creator - Automatic

Edit a portlet (this is automatically granted to a portlet creator).

Portlet Page View

View a general portlet page in CA Clarity PPM. Users do not need this access

right to view instances of portlet pages (such as portfolio pages).

Portlet Page Creator - Automatic

Edit a portlet page (this access right is automatically granted to the creator

of a portlet page).

Portlet Page Viewer - All

View all configured portlet pages. This access right is dependent on portlet

pages being linked to a menu before they can be displayed. If the portlet

page is linked to the Administration menu, then the Administration - Access

access right must also be granted.

Portlet Page Definition Editor

Edit, view, and delete a portlet page definition (requires Studio Access

access rights).

Portlet Page Definition Viewer

View the portlet page definition in the Administration Tool (requires Studio

Access access rights).

Portlet Page Definition Viewer - All

View the all portlet page definitions in the Administration Tool (requires

Studio Access access rights).

Portlet Viewer - All

View all portlets and add them to portlet pages.

Stock Portlets


Object Administration

Access Object Definition pages (requires the Studio module license).

No instance-level access rights exist for queries or for the Menu Manager. You

can grant access rights to specific resources, groups, and OBS units over specific

portlets and pages. If the portlet and page objects are attached to an OBS, you

can assign each portlet and page to an OBS unit, therefore you can give specific

resources, groups, or OBS units access to pages and portlets in specific OBS

units.

In addition to the global access rights, you can grant access rights to individual

pages and portlets on a per instance basis, thereby permitting users to modify

just those portlets or pages for which they have explicit edit access rights.

Stock Portlets

See following a list of stock portlets that you can use. These portlets are

restricted and therefore can‘t be changed. You can however create new portlets.

See the rest of this section for instructions on creating new portlets.

Balance

Balance

ID: Balance

Category: Business Intelligence

Type: Portfolio

Benefits by Goal

Benefits by Goal

ID: Benefits by Goal


Type: Portfolio

Budgeted Costs

Budgeted Costs

ID: Budgeted Costs


Type: Portfolio

Stock Portlets


Change Requests

Assigned change requests

ID: Change Requests

Category: Project

Type: General

Cost of Investments

Cost of Investments

ID: Cost of Investments


Type: General

Cost/Benefit

Cost/Benefit

ID: Cost/Benefit


Type: Portfolio

Earned Value History

Earned Value History.

ID: EVHistory

Category: Project

Type: Project

Financials

Financials

ID: Financials


Type: Portfolio

Gantt

Gantt

ID: Gantt


Type: Portfolio

Stock Portlets


General

General information for a project

ID: project.General

Category: Project

Type: Project

Ideas

Idea portlet

ID: pma.ideaPortlet


Type: General

Incident Cost for Investments

Incident cost for investments

ID: Incident Cost for Investments


Type: General

Incidents Assigned to My Team

Incidents assigned to my team

ID: Team Incidents


Type: General

Investment Health

Investment health

ID: Investment Health

Category: BusinessIntelligence

Type: General

Investments

Investments

ID: Investments


Type: Portfolio

Stock Portlets


Issues

Assigned issues

ID: Issues

Category: Project

Type: General

Labor Resource Effort

Labor resource effort for a project.

ID: project.Effort

Category: Project

Type: Project

Life cycle Funnel

Life-cycle funnel

ID: Life-cycle Funnel

Category: Business intelligence

Type: Portfolio

Links

Links defined for a project

ID: project.Links

Category: Project

Type: Project

My Projects

Favorite projects

ID: projmgr.homeHotList

Category: Project

Type: General

Notifications

Summary count of notifications by category

ID: personal.notificationsNuggest

Category: Collaboration

Type: General

Stock Portlets


Realization

Realization for a project

ID: project.RLZ

Category: Project

Type: Project

Return on Investment

Return on investment for a project

ID: project.ROI

Category: Project

Type: Project

Risk Exposure by Category

Risk exposure by category

ID: Risk Exposure by Category

Category: Project

Type: General

Risk Trends

Risk Trends

ID: Risk Trends

Category: Project

Type: General

Risk/Reward Quadrants

Risk reward quadrants

ID: Risk/Reward Quadrants


Type: Portfolio

Risks

Assigned risks

ID: Risks

Category: Project

Type: General

Stock Portlets


ROI/Alignment Zones

ROI/Alignment Zones

ID: ROI/Alignment Zones


Type: Portfolio

Subprojects

Subprojects for a project

ID: project.Subprojects

Category: Project

Type: Project

Team Utilization

Displays the team-based utilization for the current project. Provides a

detailed picture of total usage vs. allocation.

ID: projmgr.teamUtilization

Category: Project

Type: Grid

Timesheets to Approve

Timesheets awaiting your approval

ID: projmgr.timesheetAdmin

Category: Resource

Type: General

Unfilled Allocations

Unfilled Allocations

ID: projmgr.unfilledAllocations

Category: Resource

Type: General

Weekly Detail

Weekly detail

ID: projmgr.weeklyDetail

Category: Resource

Type: General

About Personal Dashboards and Portlets



A dashboard is a portlet page created by an end user in CA Clarity PPM. A

dashboard has the capabilities of other portlet pages with the following

additional capabilities:

■ An end user can share a dashboard with other end users.

■ A dashboard has more options on how content is exported to Excel or

PowerPoint. The options include:

– Fit to page, which exports all portlets on a tab to a single page

– One portlet per slide or sheet, which exports each portlet to its own page

Note: An end user can export all of the content of some CA Clarity PPM

portlet pages (for example, the Overview portlet page). The export includes

any custom tabs added by the end user. The export is limited to pages of

type Page with Tabs or Page Without Tabs. The option will always be Fit to

page where all portlets for a tab are exported to one page.

Data Providers for User Portlets

When a user creates a portlet to be used in a dashboard, the user must select a

data provider. Query data providers can be used to provide information to user

portlets for dashboards.You can prohibit the use of a query data provider by

clearing the Available for User Portlets check box on the query's properties page.

When a user selects a data provider for a user portlet, the attributes for each

data provider are shown to help the user select the correct data provider. You

can modify the attribute names to provide more user friendly names to help

users make the correct data provider selection.

To re-label query attributes for the user portlet data provider selection

1. Click Queries in the CA Clarity Studio menu.

The list page appears.

2. Select the query.

The query's properties page appears.

3. Click Attributes in the content menu.

The list of attributes for the query appears.

4. Click the name of the attribute you want to re-label.

The Query Attribute page appears.

5. Click the Translate icon next to the Attribute Name field.

The Translate page appears.

6. Enter the name you want to appear for users in the data provider's attribute

list.



7. Click Submit.

Dashboard Properties Settings

A dashboard has the following specific properties settings:

■ The portlet page type must be either Page with Tabs or Page Without Tabs.

■ The dashboard layout can only be one of the following: Two column (50-50

percent), two column (66-34 percent), three column (25-50-25 percent), or

three column (33-33-33 percent).

■ The portlet page template is always equal to Application Page Template.

Dashboard Access Rights

The following table shows the access rights required for Personal Dashboarding.

Access Right What it does in the

application

Scope

Dashboard - Navigate Shows the Dashboard

Navigation link for a user.

Global

Portlet - Navigate Shows the Portlet

Navigation link for a user.

Global

Dashboard - Create Lets a user create a

dashboard.

Global

Portlet - Create Lets a user create a

portlet.

Global

Portlet Definition Editor Lets a user edit a portlet. Global/OBS/Instance

Portlet - View Lets a user view a portlet. Global/OBS/Instance

Page Definition Editor Gives a user manager

access to a dashboard.

Global/OBS/Instance

Page - View Lets a user view a

dashboard.

Global/OBS/Instance



Administrator Access to User Portlets

An administrator has different access to user portlets based on where access is

attempted:

– In Studio, an administrator can view all user portlets, make changes to

the portlets, and publish the changes.

– In the application, the administrator can view only those portlets the

administrator has created or portlets that have been shared.

Personal Dashboarding Operations by User Type

The following table shows which dashboard functions can be performed by

different types of users.

Dashboard Function Studio

Administratorr

Dashboard

Manager

Dashboard

Viewer

Share Yes Yes No

Edit properties Yes Yes No

Publish Yes Yes No

Personalize No Yes Yes

Export No Yes Yes



Data Providers for Personal Dashboards

Data Providers for User Portlets

When a user creates a portlet to be used in a dashboard, the user must select a

data provider. Query data providers can be used to provide information to user

portlets for dashboards.You can prohibit the use of a query data provider by

clearing the Available for User Portlets check box on the query's properties page.

When a user selects a data provider for a user portlet, the attributes for each

data provider are shown to help the user select the correct data provider. You

can modify the attribute names to provide more user friendly names to help

users make the correct data provider selection.

To re-label query attributes for the user portlet data provider selection

1. Click Queries in the CA Clarity Studio menu.

The list page appears.

2. Select the query.

The query's properties page appears.

3. Click Attributes in the content menu.

The list of attributes for the query appears.

4. Click the name of the attribute you want to re-label.

The Query Attribute page appears.

5. Click the Translate icon next to the Attribute Name field.

The Translate page appears.

6. Enter the name you want to appear for users in the data provider's attribute

list.

7. Click Submit.

Interactive Portlets



Interactive portlets display visually rich CA Clarity PPM information in real time.

Interactive portlets are created in CA Clarity PPM and contain Xcelsius

visualizations. These visualization are exported as vector-based graphic Adobe

Flash (.SWF) files and imported into CA Clarity PPM. Interactive portlets use

global and object parameters with Flash variables to establish secured data

transfers and to create context-aware visualizations.

Use interactive portlets to:

■ Perform a what-if analysis

■ Set up alerts

■ Drill down to go to more detailed information

■ Mouseover areas to view more information

Once you have created Xcelsius visualizations and imported them into CA Clarity

PPM interactive portlets, you can associate them with objects, such as Project or

Resource. You can also make Xcelsius visualizations available on object pages.

Users can personalize their pages and add interactive portlets anywhere in CA

Clarity PPM, such as their Overview page, as they can with other portlet types.

Note: See the Common Features and Personal Options User Guide for more

information.

Create the Interactive Portlet

Use the following procedure to create an interactive portlet and import the

Xcelsius visualization.

Before you start, create the Xcelsius visualization and export it to the Flash

(.SWF) format.

Note: See the CA Clarity-Xcelsius Implementation Guide for more information.

To create an interactive portlet

1. Click Portlets from the CA Clarity Studio menu.

The Portlets page appears.

2. Click New Portlet and select Interactive Portlet from the drop-down.

The Interactive Portlet: General page appears.




Portlet Name

Defines the name of the portlet. This name appears on the title bar of the

portlet and in the list of available portlets.

Portlet ID

Defines a unique alphanumeric identifier for the portlet.

Content Source

Specifies where the data that appears in the portlet originates.

Category

Specifies the general area on which the portlet reports data.

Description

Defines the purpose of the portlet and provides any relevant

information.

Active

Indicates the portlet is active and are visible to users. You can edit

inactive portlets and activate them later.

Default: Selected

Instance Type

Specifies the type of page the portlet can be placed on. If you select

General, the portlet can be added to any CA Clarity PPM page. If you

select an Object, the portlet can only be added to CA Clarity PPM pages

associated with that Object.

Visualization File (.swf)

Specifies the .SWF file used for the interactive portlet content.

Click the Browse icon to select the .SWF file. Do not enter or copy the file

path.

4. Save.

The Xcelsius visualization is imported into the interactive portlet.



Create Object or Global Parameters

Interactive portlet object or global parameters define the data that is exchanged

between CA Clarity PPM and the Xcelsius visualization. Your CA Clarity PPM

administrator defines the Flash variables in Xcelsius while designing the

visualization. The Flash variables allow the visualization to accept information

from CA Clarity PPM. You use the Flash variable name when you create the

interactive portlet.

Your CA Clarity PPM administrator must first create the Xcelsius visualization and

the required Flash variables before you can create object or global parameters.

Important! You can delete object and global parameters from the parameters

list page. Use care. Deleting global and object parameters can cause data

instability in the Xcelsius visualization.

To create an object or global parameter

1. Open the interactive portlet.

The Interactive Portlet: General page appears.

2. Click Parameters in the content menu.

The Interactive Portlet Parameters List page appears.

3. Click New and select either Object Parameter or Global Parameter from the

drop down.

The properties page appears for the selected parameter type.


Global Parameter

(Global Parameter only) Displays the selected global parameter.

Required: Yes

Object

(Object Parameter only) Displays the name of the object to which this

object parameter is associated.

Field

(Object Parameter only) Specifies the field name. The values displayed

are associated with the selected object.

Required: Yes

Graph Portlets


Flash Variable Name

Defines the name for the flash variable. This name must be the same as

the Flash Variable Name associated with the visualization.

For Global Parameter, BusinessObjects Session ID, displays the required

value: CELogonToken

Required: Yes

Description

Defines the description for the parameter.

Limits: 240 characters

Required: No

5. Click Submit.

Graph Portlets

You can use graph portlets to display query data in an easy-to-view graphical

format. Before you create a graph, see the topics in this section for a detailed

description of the various types of graph portlets and display options you can

select when creating graphs.

You might use various graph types to display the following types of information:

■ Pie charts that show the number of projects with low, medium or high risk

■ Pie charts that show revenue by project or OBS unit

■ Scatter graphs that show NPV or ROI per project

■ Bubble graphs that show NPV, ROI, and cost per project

■ Line graphs that show resource capacity over time

Graph Portlets


Data Providers

Data providers, the source of grid and graph portlet data, are special data

constructs that can be accessed directly with portlets or through queries.

Data provider types are Queries, Objects, and System.

Queries

CA Clarity PPM provides a query language called NSQL, that is similar to SQL,

that you can use to create queries. If you are not familiar with SQL, you can

still create portlets using the built-in data providers that come with CA

Clarity PPM.

Objects

The stock CA Clarity PPM objects—and any objects you create—contain fields

that you can use to access database information.

System

System types are data providers for the restricted portlets. You can use

these data providers in addition to stock CA Clarity PPM objects.

System Type Description

Booking Status List Used with the Team object to list data about

requests for project resources or roles.



Investment).


about key tasks.

Organizer Tasks This provides data about the tasks to which a

resource is assigned.




Project Team Members This contains data about resources assigned to

projects.

Project Team Selection This contains data about resources assigned to

projects.

Resource's Projects List This lists data about projects to which a resource is

assigned.

Graph Portlets


Graph Portlet Types

There are several graph portlet types that you can create in CA Clarity PPM. Use

the graph type that best suits the metrics in your query data. The graph type you

select should not have fewer metrics than the minimum number of metrics in

your query data.

Graphs are best for displaying data that contains several dimensions and

metrics.

■ Dimensions are related data elements. For example, project-related data

(Project ID, name, start date, etc.) is a dimension of data. If a query data

also contains resource data, then the data contains two dimensions.

■ Metrics are query values that can be measured. For example, "Actual Hours"

is a metric.

Graph Type

One-dimensional Multi-dimensional

Description Min.

Metrics

Max.

Metrics

Min.

Metrics

Max.

Metrics

Bar Displays each dimension of the

data in a horizontal bar.

1 Unlimited 1 1

Bubble Displays metrics on the

horizontal and vertical axes.

Also provides data points on the

radius to control data point size

that is based on a third metric.

3 3 3 3

Column Displays each dimension of the

data in a vertical bar.

1 Unlimited 1 1

Funnel Displays the data‘s dimension

objects in proportional ―slices‖,

like a pie chart, except the

greatest values appear in the

largest area of the funnel.

1 1 Not

Available

Not

Available

Line Displays data points that are

connected by lines along the

axes.

1 Unlimited 1 1

Pie Displays the data‘s dimension

objects in proportional ―slices‖.

1 1 Not

Available

Not

Available

Scatter Displays metrics across the

x-axis and y-axis.

2 2 2 2

Graph Portlets


Create Graph Portlets

Use this procedure to create a graph portlet. Before you perform this procedure:

■ Make sure that you have created a query that will provide data for the

portlet.

■ Decide which type of graph you want to create based upon the metrics and

dimensions in your query data.

To create a graph portlet

1. Select Portlets from the CA Clarity Studio menu.


2. Click New Portlet and select Graph Portlet from the drop-down menu that

appears..

The Graph Portlet: General page appears.


Portlet Name



Portlet ID


Content Source


Category


Description


information.

Base Size

Specifies the base size for the portlet. The values are Small, Medium,

and Large. If you plan to create a single graph portlet on a personalizable

page, you might select Large. If the portlet is to share a page with other

portlets, you might select Small.

Active



Default: Selected

Graph Portlets


Instance Type





Data Provider

Indicates the data construct that provides information to the portlet.

Click the Browse icon to select a data provder.

4. Click Next.

The Graph Portlet: Graph Type page appears.

5. At Graph Type, choose a graph type, and click Next.

The Graph Portlet: Finish page appears.

6. If your query contains multiple metrics, at Metric select a metric to display on

the X-axis and click Next.

7. Click Finish and Open.


8. Click Save.

9. Select Source Data from the content menu.

The Graph Portlet: Source Data page appears.

10. From the Available Metrics column, select the data you want to include in the

graph, then use the left and right arrow buttons to move the item into the

graph columns.

11. Click Save.

What’s Next?

Now that you have a new graph portlet, you should also perform the following

procedures:

■ Determining Graph Portlet Appearance

■ Determining Graph Portlet Data to Display

■ Changing Graph Portlets

Graph Portlets


Determine Graph Portlet Appearance

Now that you have created a graph, you can select from various display options

that determine how information displays on the graph (such as legends, titles,

and markers).

You can also choose to display guide lines that represent a fixed value or lines

that are relative to some other value. You can use this feature for example to

create guide lines or to display a mean value (see example next page).

In the following procedure you will be asked to specify various display options

(and only those that pertain to the graph type you have chosen will appear).

To determine graph appearance



2. Click the name of the graph portlet you want to determine graph

appearance.


3. Select Options from the content menu.

The Graph Portlet: Options page appears.

4. Indicate the type of options you are setting. Choose:

■ Entire Graph, to set options for the entire graph.

■ X Axis, to set options only for the x-axis.

■ Y Axis, to set options only for the y-axis.

■ Secondary X Axis, to set options only for a secondary x-axis.

■ Guide, to specify guide lines (skip to To specify guide lines:).

5. Depending on the type of graph you selected, enter values for the following

display options, then click Save.

Note: The options are entered in alphabetic order rather than the order they

appear on the page.

Allow Configuration

Indicates a user can make changes to the appearance of a portlet. Select

the check box to allow configuration.


Indicates a user can make changes to a portlet's labels. Select the check

box to allow configuration.

Graph Portlets


Angle of First Slice

Defines the position of the first dividing line. Use with Pie and Funnel

graphs.

Axis Label

Displays the metric name along the X, Y, or both axes. Use this option

with:

■ Bar. X, Y axis.

■ Column. X, Y axis.

■ Line. X, Y axis.

■ Bubble and Scatter. X axis.

Crosses Opposite Axis At

Defines the intersection point of the axis. Use this option with:

■ Bar. Y axis.

■ Column. X axis.

■ Line. X axis.

■ Bubble and Scatter. X axis.

Category Labels

Specifies for the X axis of column and line graphs and the Y axis of bar

graphs the labels that appear along the category axis. For example, if a

column graph shows five months of data with three metrics (shown as

red, green and blue bars), the months are the categories and this field

determines the label that appears on each one.

Datapoint Labels

Specifies the data name to be applied next to the value on the graph.

Use this option with all data types.

Decimal Places

Defines the number of decimal places to display for numbers. Use this

option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.

■ Bubble and Scatter. X, Y axis.

Graph Portlets


Display Units

Specifies how values are rounded up. Select a value for rounding from

the drop-down list. Use this option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.


Filter

Indicates how the results appear initially. Select an option that indicates

if you want immediate results or results provided after you set the filter.

Link

Specifies a page link that appears as a secondary value that the user can

select. Select a page from the drop-down list.

Logarithmic

Indicates that the data points are to be plotted and shown on the axis

major grid lines as a logarithmic scale, that is, as a power of 10 rather

than a regular linear scale.

Major Tick Marks

Specifies if major tick marks appear on the axis. Major tick marks are

used to identify major intervals on a graph. For example, the numbers 5,

10, 15, and so on may be highlighted with major tick marks.

■ Bar. X axis.




Major Unit Increment

Defines the interval of major ticks on the axis. Use this option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.


Graph Portlets


Maximum Value

Defines the greatest value to display on the axis. Use this option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.


Minor Tick Marks

Specifies if minor tick marks appear on the axis. Use this option with:

■ Bar. Y axis.




Minor Unit Increment

Defines the interval of minor tick marks on the axis. Use this option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.


Mouseover Labels

Specifies the data values to show when a user moves the cursor over a

graph value. Uses with all graph types.

Other Category Threshold

Defines the data point at which all records for a specified value are

grouped into a category called Other. Use this option if too many items

appear on the graph. Use this option with:

■ Bar

■ Column

■ Line

■ Pie and Funnel

Reverse

Specifies that the axis goes from maximum value to minimum value. The

standard is for an axis to go from minimum to maximum value.

Graph Portlets


Show Axis

Indicates whether the Axis line displays. Use this option with:

■ Bar. X, Y axis.


■ Line. X, Y, axis.


Show Legend

Indicates a legend is to be displayed for the graph. Use with all graph

types. Select the check box to display a legend.

Show Line Markers

Indicates that data points on the graph; otherwise, only a line displays.

Available for line graphs. Select the check box to show line markers.

Show Lines

Indicates that lines are to connect the data points. Available for line

graphs. Select the check box to show lines.

Show Major Grid Lines

Indicates whether major grid lines display on the graph. Use this option

with:

■ Bar. X, Y axis.




Show Minor Grid Lines

Indicates whether minor grid lines display on the graph. Use this option

with:

■ Bar. X, Y axis.




Graph Portlets


Show Separator

Specifies that a comma is to separate values greater than 999 (for

example, 1,000). Use this option with:

■ Bar. X axis.

■ Column. Y axis.

■ Line. Y axis.


Show Tick Labels

Indicates whether tick labels display on the graph. Use this option with:

■ Bar. X, Y axis.




Show Title

Indicates that the portlet name is to display. Available for all graph

types. Select the check box to show the portlet name.

Sort Column

Indicates a column is to be the default sort item. This option is available

for column graphs.

Sub-type

Indicates the metrics are to display as separate bars rather than a single

merged bar. Select the sub-type that is desired. This option is available

for bar and column graphs.

Tick Label Angle

Sets the angle of a label used with tick marks. Use this option with:

■ Bar. X, Y axis.




6. (Optional) If you are configuring a line graph, select Guides in the Options

field and click New, then complete the following fields and click Submit.

Axis

Specifies the axis for which guides are being set.

Label

Defines the name for the axis. Enter the name you want to appear.

Graph Portlets


Show Label

Determines whether the name of the axis displays. Select the check box

to display the name.

Type

Identifies the source of the information that displays on the guide. Select

the appropriate option. If you are selecting a type for an X axis, you can

only select an attribute. If you are selecting a type for a Y axis, select

either the fixed value or the percentage and fill in the amount.

Color

Specifies the color for the guide.

Determine Graph Portlet Data to Display

When there is a lot of data available, graphs can be very complex. Filters help

users view only information that is important to them.

As you create a graph, you can select only the data items you want from all

available data provided by your query. You can also specify if filter options

appear on the portlet or on a separate page. Displaying filters on a separate page

is ideal when the filter will not change often. The filter options are still available

but are hidden. To access the filters, a CA Clarity PPM user can simply click the

Properties icon.

To determine which data to display



2. Click the name of the graph portlet you want to change.

3. Click Layout.

4. To add a field, select it from the Available column, then click the right arrow

(Add Field) button to move it to the Left or Right Column list.

5. To move fields between columns or to change their order within a list, select

a field and then use the arrows to move it.

6. At Default Filter State, select Expanded to automatically display the filter

page, or Collapsed to display only the filter field.

7. Select Allow Power Filter to provide advanced search features.

Note: By default, users can perform wildcard searches. With Power Filters,

you can provide multiple fields that users can enter or select attributes to aid

in searching.

8. Click Save.

Graph Portlets


9. To determine which data displays on the graph, under Graph Filter Section,

click Fields. Then:

a. At Display, select the fields you want to display. Choose All, Selected (to

display those you selected in the To add a field, select it from the

Available column, then click the right arrow (, or Available (to display all

data provided by the query).

b. To change information about a field, click the Properties icon next to the

field, enter the new information, then click Save.


Change Graph Portlets

Use this procedure to change an existing graph portlet. If you change a portlet

that a user is currently viewing, the user will be unaffected. The next time the

user displays the page, however, they will see your changes.

To change a graph portlet



2. Click the name of the graph portlet you want to change.

3. To change the graph type:

a. Click Graph Type from the content menu.

The Graph Portlet: Graph Type page appears.

b. Select a new graph type from the Graph Type drop-down.

c. Click Save.

4. To change the data metric used for the graph portlet:

a. Click Source Data from the content menu.

The Graph Portlet: Source Data page appears.

b. Select metrics for the new graph type.

The method of selection for the graphic varies depending on which graph

type was selected.

5. Click Save.

HTML Text Portlets


Delete Graph Portlets

Use this procedure to delete a graph portlet. When you delete a graph that a user

is currently viewing, the user is unaffected. The next time the user displays the

page, however the graph portlet will not appear.

To delete a graph portlet



2. Select the box next to the graph you want to delete.

3. Click Delete, then Yes to confirm.

HTML Text Portlets

You can use HTML portlets to display HTML data. Before you create a portlet

page, see the topics in this section for a detailed description of the various types

of portlet pages and display options you can select when creating portlet pages.

As you create portlet pages, first determine if the page will contain tabs. Then

determine if you will allow users to change the pages or to add their own tabs

and content. Once a page is personalized by a user, it will not be affected by any

future administrative changes, except the addition of any required portlets.

You can use Studio to do the following:

■ Create pages with various page layouts

■ Define personalized home pages

■ Add new tabs to the CA Clarity PPM Organizer and Overview pages

■ Create a business intelligence page

■ Display news from a company Intranet site

■ Display corporate phone information

■ Display portions of external web sites

■ Display recorded messages

HTML Text Portlets


Create HTML Portlets

Use the following procedure to create a new HTML portlet.

To create a new HTML portlet



2. Click New.

The Create Portlet page appears.

3. Click HTML, then click Submit.


Portlet Name



Portlet ID


Content Source


Category


Description


information.

Active



Default: Selected

Instance Type





HTML Code

Defines the HTML that you want to display in the portlet.

5. Click Save and Continue.

HTML Text Portlets


Change HTML Portlets

Use the following procedure to change an HTML portlet.

To change an HTML portlet



2. Click the name of the HTML portlet you want to change.


Portlet Name



Category


Description


information.

Active



Default: Selected

HTML Code

Defines the HTML that you want to display in the portlet.


Delete HTML Portlets

Use the following procedure to delete an HTML portlet.

Note: When you delete a portlet that a user is currently viewing, the user is

unaffected. The next time the user tries to display the page, it will not appear.

To delete an HTML portlet



2. Check the box next to the HTML portlet you want to delete.


Grid Portlets


Grid Portlets

Use grid portlets to display query data in rows and columns. Before you create a

grid, see the detailed description of the various types of grids and display options

you can select for grids.

Grid portlets are most suitable when your query data contains only one or two

dimensions, which are related data elements in a query. For example,

project-related data (Project ID, name, start date, etc.) is considered a single

dimension. Queries that contain project and resource data are considered to be

two-dimensional. Graphs are better suited for query data that contains several

dimensions or metrics (query values that can be measured).

You might use grids to display:

■ Lists of resources or transactions

■ Capacity and assignment demand for resources over time

■ The number of overdue action items per resource per OBS unit

Access Rights and Grid Portlets

If the data you use on a grid portlet comes from a secured subpage, the access

restrictions of the subpage are also enforced in the grid portlet. That means that

if a user does not have the rights to access the content of the subpage, the data

from the subpage will not appear on the grid and the cells for that data will be

empty. If the data on the subpage is secure, however, and you used it on an

unsecured grid, the contents appear in the grid.

Grid Portlet Aggregation, Comparison, and Variance Options

You can create virtual columns with data that is derived from the query data.

Virtual columns can be:

■ Aggregations, which operate on a large set (column) of data and typically

return a single value (such as SUM, AVG, MIN, MAX, and COUNT). You can

have multiple rows of aggregated data.

■ Comparisons, which compare two or more query data fields.

■ Variances, which display the difference between the aggregation and

comparison columns or rows.

Grid Portlets


Depending upon the type of data involved, you can choose from the following

aggregation or comparison functions:

■ Sum

■ Average

■ Count

■ Minimum

■ Maximum

■ Variance

■ Standard deviation

Note: When the query data is a date, only the COUNT, MIN, and MAX functions

are available. String fields cannot be aggregated.

If the data in your query has at least two dimensions, you can create another

virtual column that compares and aggregates the two fields. Depending upon the

data, you can then choose to display the results as a number or a bar or column

graph.

Hierarchical Grid Portlets

A hierarchical grid portlet can be used to show the structure of data that has

more than one level. A parent row can have multiple child rows, and the data

that shows in the parent row can be an aggregate of the child data.

Things to Consider When Creating Grid Portlets

When creating grids, consider the following:

■ If your grid contains virtual columns, the source data for those columns must

be defined in the query that supplies data to the grid. In the following

example the values used to create a total row of data (budget, actual, and

allocated) must be provided by the query.

■ The y-axis (rows) of the grid can contain only one dimension of data.

■ If your query data contains two dimensions, either dimension be displayed in

the rows. The second dimension is displayed on the x-axis (columns).

Queries that contain three or more dimensions display one dimension in the

rows and all other dimensions in the columns.

■ Metrics always display in columns.

■ Metrics display in the first or last header row of columns when the query data

contains two or more dimensions. If the query contains three or more

dimensions, the dimensions are placed in order along the x-axis (see

example next page).

Grid Portlets


Create Grid Portlets

Use this procedure to create a grid portlet. Before you perform this procedure:

■ Make sure that you have created a query that will provide data for the

portlet.

■ Review the tips for creating grids.

To create a grid portlet



2. Click New and select Grid Portlet from the drop-down menu that appears.

The Grid Portlet: General page appears.


Portlet Name



Portlet ID


Content Source


Category


Description


information.

Active



Default: Selected

Grid Portlets


Instance Type





Data Provider

Indicates the data construct that provides information to the portlet.

Click the Browse icon to select a data provder.

4. Click Next.

5. On the Grid Portlet: Finish page, click Finish and Open.

What’s Next?

After you have created a new grid portlet, you should also perform the following

procedures:

■ Determining the Layout of Grid Portlets

■ Restricting Access to Portlets and Pages

■ Using Portlet Pages: Deploying Content

Grid Portlets


Determine the Layout of Grid Portlets

Use the following procedure to determine the column sort order of data that

appears in your grid portlet. You can specify how columns will be sorted, filter

options, and define any virtual columns or rows that are derived from your query

data appear on the grid.

To determine the layout of grid portlets



2. Click the name of the grid portlet you want to change.


3. Click Layout under the List Column Section content menu item.

The Grid Portlet: List Column Layout page appears.

4. Do the following, and click Save:

■ From the Available Columns list, select a column to include in the grid,

then click the right arrow (Add Field) button to add it to the Selected

Columns list. Use the up and down arrows to place the columns in the

desired order. Repeat this step for each item you add to the grid.

■ To determine how columns are sorted on the grid:

a. Select the order in which columns should be sorted.

b. Click Ascending or Descending to determine how data is sorted

within each column.

Your changes are saved.

5. To determine which fields appear on the grid click Fields from the List

Column Section content menu item.

The Grid Portlet: List Column Fields page appears.

6. From the Show drop down, select the attributes to display on this page.

7. From the Display drop down, select the values you want to add to the grid.

Grid Portlets


8. To determine grid display options click Options and complete the following

fields:

Secondary Value Display

Indicates the way that secondary values display in a grid cell. Select

Mouseover only to have no secondary value display.

Select Mouseover and redline to display a secondary value when a user

places the pointer over a cell in a grid. This helps you compare values.

For example, if you have a column called Cost and another column called

Baseline Cost, you might want to display both values in one cell. To show

both, you can choose Baseline Cost as the secondary value. The Cost

value displays as usual; however, when a user moves the pointer over a

cell in the grid, the Baseline Cost also displays.

Select Show Null Secondary Values to show the secondary value even

when there is no number value to show.

Filter

Indicates how the results appear initially. Select an option that indicates

if you want immediate results or results provided after you set the filter.

Rows per Page

Specifies the number of rows per page to display.

Highlight Row by Attribute

Specifies the attribute whose row is highlighted when the attribute's

value is not zero.

For example, if you want to see all investments in your portfolio that are

approved, enable highlighting for the Approved attribute. Then, when an

investment is approved, it is highlighted on the grid.

Display Currency Code in Column

For money attributes, the currency code is shown in the column. This

applies only when a single currency is being used. Select the check box

to display the currency code.

Allow Configuration

Indicates a user can make changes to the appearance of a portlet. Select

the check box to allow configuration.


Indicates a user can make changes to a portlet's labels. Select the check

box to allow configuration.

Attribute Value Protection

Specifies how attribute values will be protected in a grid portlet.

9. Click Save.

Grid Portlets


10. In the List Filter section, click Layout and complete the following actions:

a. At Available, select the query fields you want to make available to CA

Clarity PPM users who use this portlet. Click Add Field to move them to

the Selected Columns lists.

b. At Section Title, enter the text you want to appear at the top of this

section.

c. At Default Filter State, select Expanded or Collapsed.

d. Click Allow Power Filter to provide advanced search features.

e. Click Save.

11. In the List Filter Section, click Aggregation and set the following options then

click Save:

■ To show one or more aggregation row that group several data items,

click Show Aggregation Row. Then, in the Aggregation Rules section,

select the field to aggregate and an aggregation function to use for

displaying data in the row.

■ To show a comparison row that compares values, click Show Comparison

Row. Then in the Comparison Rules section, select the comparison

column and comparison aggregation function. Click the link in the

Display column to specify how the comparison data will display.

■ To show the difference between the aggregation and comparison rows,

click Show Variance Row.

12. To determine the properties to display in the filter field, under List Filter

Section, click Fields. Then:

a. At Display, select the fields you want to display:

■ Choose All,

■ Selected (to display those you selected), or

■ Available (to display all possible fields).

b. To change information about a field, click the Properties icon next to the

field, enter the new information, then click Save.

c. Click Save and Exit.

Grid Portlets


Change Grid Portlets

Use this procedure to change a grid portlet.

To delete a grid portlet



2. To filter the portlet list, in the Portlet Filter section enter one or more

attributes about the grid you want to change and click Filter.

3. Click the name of the grid portlet you want to change.


■ Portlet name

■ Category (optional)

■ Description

■ Active status (optional)

■ OBS Selections

5. (Optional) Change the appearance of the grid portlet

Note: Click Save on each page to save your changes.

6. (Optional) Change the access restrictions for the gird portlet.

7. Deploy the grid.

Delete Grid Portlets

Use this procedure to delete a grid portlet. When you delete a grid that a user is

currently viewing, the user is unaffected. The next time the user displays the

page, however the grid portlet will not appear.

To delete a grid portlet



2. Check the box next to the grid you want to delete.


Filter Portlets


Filter Portlets

Filter portlets coordinate filtering operations across portlets in CA Clarity PPM. A

filter portlet contains defined placeholder filter fields that are mapped to

attributes in grid and graph portlets. When you configure and publish a filter

portlet on a page with grid or graph portlets, CA Clarity PPM users can filter the

page content across portlets using the portlet's fields.

When a user clicks the filter portlet's Filter button, the following occurs:

■ All portlets configured to work with the filter portlet are filtered using the

filter portlet values.

■ Filter portlet values appear in the filters of portlets on the page. The portlet

attribute must be mapped to the filter portlet field for the value to display.

A filter portlet can contain fields that do not display in all portlets. In this

case, the affected portlets still filter on the filter portlet‘s values, even if the

values are not displayed.

Filter Portlets


You can configure a filter portlet to appear on a page in the following ways:

■ Standalone filter section for a tabbed or non-tabbed page

■ Toolbar section in a tabbed or non-tabbed page

Filter Precedence

The following table shows how filter precedence works when multiple filters are

mapped to a filter portlet.

Filter from this

portlet

Result

Filter portlet The filter portlet has precedence and determines the

filter values for all portlet attributes mapped to filter

portlet fields. The user sees the following behavior:

■ Show All selected at the filter portlet level initiates

a Show All behavior for all portlets mapped to the

filter portlet. Any portlet attribute that is not

mapped does not have its value overridden.

■ Data that displays in an individual portlet is reset,

and the result set that appears is determined by

the filter criteria of the filter portlet combined with

the portlet‘s filter criteria of unmapped portlet

attributes.

■ Portlets that have no mapped attributes are not

affected by the filter portlet.

Grid or graph portlet The portlet filter has precedence. The user sees the

following behavior:

■ If a user clicks Show All on the portlet filter, all the

filter records for the portlet appear. Portlet filter

values always override the filter values of

previously submitted filter portlet requests.

Filter Portlets


Scope of Filter Portlets

You can configure a filter portlet to share filter values for the following levels in

the CA Clarity PPM application:

Page level

Filter values are not shared across pages.

Application level

Filter values are shared across pages. For a filter portlet to be application

level, the same filter portlet must be added to each page.

Important! Scope for filter portlets is based on the use of the same filter portlet

across pages. Different filter portlets cannot be configured to share and persist

filter request values. The scope across pages is determined by the selection of

the Persist option for the filter portlet to persist its filter request values and the

mapping of the filter portlet fields to the attributes of portlets on the pages.

Filter Persistence

The following rules determine which filter‘s values persist as filter criteria:

■ If the scope of a filter portlet is page level, the filter portlet field values

persist only within that page.

■ If the scope is application level, the filter portlet used last has its field values

persisted across pages.

■ If multiple filter portlets are present on a page, the fields of the most recently

used filter portlet are persisted. This is true for both page-level and

application-level cases.

Filter Portlets


How to Set Up Filter Portlets

Before you create a filter portlet to use on a page, identify the following:

■ All portlets that are to appear on the page

■ Attributes on each of the portlets that you want to map to the filter portlet

fields

For a filter portlet to work, its fields must be mapped to the appropriate

attributes in the portlets that provide content on the page.

The following steps show how to configure a filter portlet for a page:

1. Create the filter portlet (see page 194).

2. Add fields to the filter portlet (see page 195).

3. Determine the field layout on the filter portlet (see page 208).

4. Select an existing portlet page or create a portlet page and add content (see

page 209).

5. Add the filter portlet to the portlet page (see page 213) and map the filter

portlet fields to the attributes of the portlets on the page.

Create Filter Portlets

Use this procedure to create a filter portlet that can be used to filter the content

of all portlets that appear on a page.

To create a filter portlet



2. Click New.

3. Select Filter and click Submit.

The Filter Portlet: General page appears.

4. In the General section of the page, enter the following information:

Portlet Name



Portlet ID


Content Source


Filter Portlets


Category


Description


information.

Active



Default: Selected

Instance Type





5. Click Submit.

Field Data Types for Adding to Filter Portlets

You can add fields of the following data types to a filter portlet:

■ String

■ Number

■ Money

■ Boolean

■ Date

■ Lookup

■ Multivalued Lookup

■ URL

Add String Fields to Filter Portlets

Use the following procedure to add a string field to a filter portlet.

To add a string field to a filter portlet



2. Click the name of the filter portlet you want to change.


Filter Portlets


3. Click Fields from the content menu.

The Filter Portlet: Fields page appears.

4. Click Add.

The Filter Portlet: Field Properties page appears.


Field Name

Defines the field name you want to appear in the filter portlet.

Field ID

Defines a unique alphanumeric identifier for the field.

Description

Defines the purpose of the field and provides any relevant information.

Data Type

Specifies the data type for the field.

Select String.

Display Type

Specifies how the field is to be used by to the user. Possible values

include: Browse, Text Entry, Numeric Range, Pull-Down, Date, or Date

Range.

Filter Default

Specifies the value that appears in the filter field as the default value. If

the filter portlet associated with this field is published to a dashboard as

the filter default, this value will be applied to the portlet attributes

mapped to this field.

Width

Defines the width of the field. If you leave the field blank, the field

receives the default, which is 30 pixels. The default for date fields is 20

pixels.

Required in Filter

Specifies that a value is required in the field when a filter request is

executed. If you select this check box, you must enter a value in the

Filter Default field.

Hidden in Filter

Specifies that the field does not display in the filter at runtime, but the

default value of the field is included when a filter request is executed.

Select the check box to hide the field in the filter. If you select this field,

you must provide a value in the Default Filter field.

Filter Portlets


Read-Only in Filter

Specifies that the field displays with a default value that cannot be edited

by a user. Select the check box to make the field read only in the filter.

If you select this field, you must provide a value in the Default Filter field.

Hint

Provides a short message that helps a user use the field.

Tooltip

Provides a short message that displays when the user moves a cursor

over the field.

6. Click Submit.

Add Number Fields to Filter Portlets

Use the following procedure to add a number field to a filter portlet.

To add a number field to a filter portlet







4. Click Add.



Field Name


Field ID


Description


Data Type


Select Number.

Filter Portlets


Display Type



Range.

Select Text Entry if a number is to be typed into the field or Numeric

Range for a range of numbers.

Show as Percent

Indicates if the value entered in the field should be shown as a percent.

Select the check box to show the value as a percentage.

Filter Default





Width



pixels.

Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

6. Click Submit.

Filter Portlets


Add Money Fields to Filter Portlets

Use the following procedure to add a money field to a filter portlet.

To add a money field to a filter portlet







4. Click Add.



Field Name


Field ID


Description


Data Type


Select Money.

Display Type



Range.

Filter Default





Width



pixels.

Filter Portlets


Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

6. Click Submit.

Add Boolean Fields to Filter Portlets

Use the following procedure to add a Boolean field to a filter portlet.

To add a Boolean field to filter portlet







4. Click Add.



Field Name


Filter Portlets


Field ID


Description


Data Type


Select Boolean.

Display Type



Range.

Filter Default





Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

6. Click Submit.

Filter Portlets


Add Date Fields to Filter Portlets

Use the following procedure to add a date field to a filter portlet.

To add a date field to a filter portlet







4. Click Add.



Field Name


Field ID


Description


Data Type


Select Date.

Display Type



Range.

Select Date or Date Range.

Filter Default





Filter Portlets


Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

6. Click Submit.

Add Lookup or Multi-valued Lookup Fields to Filter Portlets

Use the following procedures to add a lookup or multi-valued lookup field to a

filter portlet. Lookup fields display a drop-down or browse list from which users

can select items.

To add a lookup or multi-valued lookup field to a filter portlet







4. Click Add.



Field Name


Filter Portlets


Field ID


Description


Data Type


Select Lookup or Multivalued Lookup.

Display Type



Range.

Select Pull-Down or Browse.

Lookup

Specifies a list of lookup values that appears in the field for the user to

choose from. The user views the list according to the display type

selected. Click the Browse icon to select the lookup list.

6. Click Save.

The fields on the page change to reflect the lookup you select and its data

source (static or dynamic). Some of the fields listed in this section may not

show on your page.

Lookup Style

Indicates how many items a user can select for the field when the lookup

is executed.

Entry

(Static dependent lookup lists only). Defines the starting point for the

data a user sees listed in the lookup field. Select a level in the Level field

or click the Browse icon and select a parent lookup value.

Exit

(Static dependent lookup lists only). Defines the end point of the data a

user sees listed in the lookup field.

Filter Default





Filter Portlets


Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

7. If you selected a parameterized lookup in the Lookup field, complete the

mappings in the Lookup Parameter Mappings section. This section is visible

only for parameterized lookups.


8. Click Submit.

Filter Portlets


Add URL Fields to Filter Portlets

Use the following procedure to add a URL field to a filter portlet. Use URL fields as

a place to put a Uniform Resource Locator, such as a reference to a professional

Internet homepage, an FTP archive where you maintain papers, or to a club or

group's homepage of which you are a member.

To add a URL field



2. Click the name of the filter portlet you want to change, click Fields, and click

Add.


3. Enter information in the following fields:

Field Name


Field ID


Description


Data Type


Select URL.

Display Type



Range.

Filter Default





Width



pixels.

Filter Portlets


Required in Filter




Hidden in Filter





Read-Only in Filter




Hint


Tooltip


over the field.

4. Click Submit.

View the List of Portlet Pages for Filter Portlets

Use this procedure to view the list of portlet pages that contain a specific filter

portlet.

To view the portlet pages for a filter portlet



2. Click the name of the filter portlet whose pages you want to view.


3. Click Portlet Pages from the content menu.

The Filter Portlet: Portlet Pages page appears listing the pages that include

the filter portlet.

Filter Portlets


Determine the Layout of Fields on Filter Portlets

Use this procedure after you have created the filter portlet and its fields to

determine the placement of the fields within the filter portlet when it is rendered

on a portlet page.

The displayed list order of fields is how the fields appear in the Section view on a

portlet page. If the Toolbar view is selected for the filter portlet, the fields display

in a different order. The left column is equivalent to the top row and the right

column is equivalent to the bottom row on the portlet. The left and right columns

represent where the fields display on the portlet page.

To determine the layout fields on a filter portlet




The Portlet: General page appears.

3. Click Layout from the content menu.

The Filter Portlet: Layout page appears.

4. Move the fields to the appropriate list box by highlighting the fields and

clicking the appropriate Move Field buttons.

The field is moved.

5. Change the order of the fields in the list boxes by highlighting a field and

clicking the up and down arrows to move it in the list.

The field is moved within the list.


Render As

Select how you want the filter portlet to appear on the published page.

Values: Toolbar or Section

Note: If you select toolbar, then the default filter state is fixed as

expanded.

Default Filter State

Select how you want the filter portlet to appear on the published page.

Values: Collapsed or Expanded

7. Click Save.

Portlet Pages: Deploying Content



You can distribute new pages to all or selected CA Clarity PPM users by creating

global pages in the Administration Tool. The pages you create in the

Administration Tool can be used to distribute content via menu manager on the

left side of the page.

Portlet pages are HTML pages that contain graph, grid, or HTML portlets. Once

you have created a graph, grid, or HTML portlet, use the information in this

section to create or reuse HTML pages, and manage tabs on those pages so that

users can use your portlets.

Use Studio to do the following:

■ Create pages with various page layouts

■ Define the Home page on a per-instance basis

■ Add new tabs to the Organizer and Overview pages

■ Create a Business Intelligence page

First determine if the new page will contain tabs and if users can change the new

page or add their own tabs. Tabbed pages can provide a useful method to group

several related pages under a menu item. You can control whether these pages

can be personalized. CA Clarity PPM users can add portlets and create additional

tabs. Once a user personalizes a page, those changes will not be effected by

changes made in Studio (except the addition of required portlets).

Note: To make sure that all users see the same page and any future changes,

disable the Personalizable option.

Create Portlet Pages

To create new portlet pages

1. Select Portlet Pages from the CA Clarity Studio menu.

The Pages page appears.

2. Click New.

The Create Page page appears.


Page Name

Enter the name of the page.

Page ID

Enter a unique identifier for the page.



Content Source

Select a data source.

Type

Select a page template (to create a page with tabs, select a template

that contains tabs).

Description

Describe the page.

Template

Defines the template.

Values:

■ Application Page Template. The template for CA Clarity PPM user

pages.

■ Admin Page Template. The template for Administration Tool pages.

■ Popup Page Template. The template for popups.


Personalizable

Specifies whether users are allowed to personalize the page.

Layout

Specifies the option that has the number of columns and column sizes

that you want as the default for the portlet page.



6. Complete the following field:

Linkable

(Optional) Specifies whether users are allowed to create links to the

page.

Select this check box.


The Page: Link Parameters page appears.



8. Do the following:

a. Click New to create a link.

b. Complete the following fields:

■ Parameter Name. Enter a name for the link. This is the name you

and others will select when creating links to this page from an object

or portlet.

■ Parameter ID. Enter a unique ID for the link.

c. Click Submit.

d. Click Continue.

The Page: Content page appears.

9. To add content to the page, do the following:

a. Click Add.

b. Select the boxes next to the portlet content you want to add to the page

and click Add.


The Page: Filter page appears.

To add a filter to the page, do the following:

a. Click Add.

b. Select the boxes next to the content filter you want to add to the page

and click Add.


The Page: Layout page appears.

a. Complete the following field:

Layout

Specifies the column configuration.

Values:

■ Three Column 25-50-25. In this display, the Left column uses

25% of the available page space, the Center column uses 50% of the

available space, and the Right column, 25%.

■ Three Column 33-33-33. The three columns share the available

page space equally.

■ Two Column 50-50. The Left and Right columns share space

equally; the Center column is eliminated.

■ Two Column 66-34. The Left column uses 66% of the available

page space, while the Right column uses 34%.



■ Row Layout. In this display, portlets on each row on a portlet page

can be allotted either 33% of the width of the page (three portlets in

the row), 50% (two portlets), or 100% (a single portlet). This is

unlike other Layout options which apply the column selection to the

entire page.

b. Select the content from the left column, then click Move Content to move

the content to the center or right columns.

c. Position the content in the correct order in the columns by using the up

and down arrows beside each column.

Note: If Row Layout is selected, each row on the page can have different

column widths. As portlets are moved between the columns,

percentages of 33%, 50% or 100% are allotted to the portlets,

depending on the number of items included in a single row in the layout

columns.

The following figure shows rows on a portlet page with a Layout option of

Row Layout. The first row defined for the portlet page contains three

portlets and each portlet is allotted 33 percent of the width of the page.

The second row of the portlet page contains two portlets and each is

allotted 50 percent of the width of the page. The remaining rows contain

a single portlet and 100 percent of the page width is allocated in these

instances.

d. Click Save and Continue.

12. Control access to this portlet.

13. Add this page to a menu.



Add Filter Portlets to Portlet Pages

Use this procedure to add a filter portlet to a page that already has portlets for

content added. The procedure explains how to add the filter portlet to a page and

map the filter portlet fields to the attributes of other portlets that appear on the

page.

To add a filter portlet to a page

1. Click Portlet Pages from the CA Clarity Studio menu.


2. Click the name of the page you want to change.

If you are adding the filter portlet to a page, click Tabs in the content menu

and click the name of the tab in the list to display the Tab: Properties page.

3. Click Page Filters in the content menu.

4. Click Add.

5. Check the box next to the filter portlet you want to add to the page and click

Add.

You can add multiple filter portlets to a page.

The Page: Filter page appears showing the filter portlet name in the list.

6. Make the following adjustments.

■ (Optional) If you are adding the filter portlet to pages and you want the

values in the filter to persist when you move from one page to another,

select the Persist check box. Filter values will persist only across pages

that use the same filter portlet.

■ (Optional) Select the Default option for the desired page filter default.

The first filter published to the page is the page filter default unless a

selection indicates otherwise.



7. Click the icon next to the filter portlet name.

The Page: Filter Content Mappings page appears. This page shows the filter

portlet fields listed under each portlet on the page and allows you to map

corresponding portlet fields.

8. In the Mapping Field drop-down, for each entry, select the portlet attribute

that you want to map to the filter portlet field. The values that appear in the

drop-down are filtered based on the data type of the filter portlet field being

mapped.

■ If you are mapping lookup attributes, the filter portlet field and the

portlet attribute must have the same lookup ID.

■ If a filter portlet field is not mapped to at least one portlet attribute on

the page, the field does not display in the filter portlet.

■ If a filter portlet does not have at least one field mapped, the filter portlet

does not display on the page.

9. Select the Hide If Empty check box to hide the portlet if a value is not entered

in the corresponding filter portlet field during a filter request.

If you check the box for multiple attributes in a portlet, a blank

corresponding filter portlet field for any of the attributes will cause the

portlet not to appear.

10. Click Submit.

Publish Changes to Portlets


Delete Portlet Pages

Use this procedure to delete portlet pages. When you delete portlet pages that a

user is currently viewing, the user is unaffected. The next time the user displays

the page, however the portlets page will not appear.

To delete a portlet page

1. Select Portlet Pages from the CA Clarity Studio menu.


2. Check the box next to the portlet page you want to delete.

3. Click Delete, then click Yes.

Publish Changes to Portlets

You can update portlets for CA Clarity PPM users by publishing the portlet. When

you publish changes to a portlet, the new portlet overwrites the existing portlet,

including any changes that a user has created by personalizing the portlet or any

changes that a CA Clarity PPM administrator has created and previously

published. If you are using partitions, the new published portlet affects only the

partition you have selected.

During a CA Clarity PPM upgrade or when installing add-ins, personalized user

portlets are not upgraded. To keep users current, you may want to publish any

new portlets provided by a CA Clarity PPM upgrade or from an add-in. Use the

Portlet: General page to publish changes. To access this page, select Portlets

from the CA Clarity Studio menu, and open the portlet that has changed.

To publish changes to portlets



2. Click the name of the portlet you want to publish.

The Portlet: General page appears.

3. Click Publish.

Access to Portlets and Pages

You can restrict access to portlets and pages for individual users, groups, or OBS

units. When you restrict access to pages, users won‘t see links to the pages if

they do not have the appropriate access rights. For portlets, you can assign

restrictions that prevent users from adding portlets to their personal pages. If a

user has access to a page, they can view all the portlets on the page.



Restrict Access to Portlets or Pages

To restrict access to portlets

1. From CA Clarity Studio menu, select:

■ Portlets to restrict access to a portlet, or

■ Portlet Pages to restrict access to a portlet page.

2. Click the name of the desired portlet or portlet page.

3. At Access to this Page, click the type of user you want to grant access rights

to. Choose from:

■ Resource (a user)

■ Group (a group of users)

■ OBS Unit (an OBS unit)

4. Click Add.

5. Select the rights you want to enable. Choose from the following:

Portlet - View

Allows users to view a portlet in CA Clarity PPM.

Group

Allows users to change and view the definition of a portlet (if the user has

been granted the Studio Access right.

Page - View

Portlet Pages only. Allows users to view the page in CA Clarity PPM.

Page Definition Editor

Portlet Pages only. Allows users to edit, view, and delete the page

definition (requires that the user have Studio Access rights).

Page Definition Viewer

Portlet Pages only. Allows users to view the page definition (requires that

the user have Studio Access rights).

6. Click Next and see a list of resources, group or OBS units appear.

Note: Click the + icon to expand an OBS unit to see child OBS units.

7. Check the box next to each user for whom you want to grant the access

rights you selected in Select the rights you want to enable. Choose from:.

8. (OBS units only) For each OBS unit, select one of the following OBS

association modes:

■ Unit and ancestors, grants rights to the OBS unit and all of its parent

OBS units.



■ Unit and descendants, grants rights to the OBS unit and all of its child

OBS units.

■ Unit, descendants, and ancestors, grants rights to the OBS unit and all of

its parent and child OBS units.

■ Unit only, grants rights to the OBS unit only, not to any parent or child.

9. Click Add.

User Configuration Restrictions of Portlets

When you create a portlet, users have the ability to configure the portlet by

default. You can restrict the ability to configure an individual portlet grid, graph,

or filter view using the following options:

Allow Configuration

When this option is turned off for a portlet, users cannot see the Configure

option in the portlet‘s Actions field drop-down list.

When turned on, this option allows users to:

■ Configure column layout

■ Configure column names and display properties

■ Configure display options

■ Add aggregation rows


This option works in conjunction with the Allow Configuration option. If the

Allow Configuration option is selected and the Allow Label Configuration

option is cleared, field labels become unavailable for configuration while

other items can still be configured. Specifically, this option determines

whether the following items can be edited:

■ List column fields

■ List column field labels

■ List filter fields

■ List filter field properties (filter label field only)

■ Graph options (metrics section for 1D bar, column, and line graphs)

■ Graph filter fields

■ Graph filter field properties (filter label field only)



Restrict User Configuration

To restrict user configuration rights



2. Click the name of the desired portlet to open it.

3. Click Options in the content menu on the left.

The Options page for the portlet appears.

4. Clear one or both of the following options:

■ Allow Configuration

■ Allow Label Configuration

5. Click Save.

Set a System View for a Portlet

You can set up and maintain a portlet that has the same view for all users by

setting the Allow Configuration option and publishing the portlet changes.

To set a system view for a portlet page



2. Click the name of the desired portlet to open it.

3. Click Options in the content menu on the left.

The Options page for the portlet appears.

4. Clear the Allow Configuration option.

5. Click Save.

6. Click General in the content menu.

7. Click Publish.



Configurable User Actions

A configurable user action is an ease-of-use feature that saves a user time and

effort by reducing the number of mouse clicks required to add or delete a new

instance of an object. You can add New or Delete configurable user actions to a

new grid portlet.

When you create an object, the New and Delete actions are created

automatically for the object and can be set up to operate with a grid portlet. In

CA Clarity PPM, buttons for the actions are available to the user on the portlet.

For example, if you create a new grid portlet using the user-defined object

Compliance with an NSQL query as the data provider, you can add the New

button to the portlet in Studio. When a user clicks the New button in the grid

portlet in CA Clarity PPM, the Create Compliance property page appears.

Note: Custom user actions are not available. Only New or Delete can be selected

for user actions.

Radio buttons or check boxes are automatically provided as selectors in the first

column of the grid portlet if they are required for multiple or single row selections

for the user action.

Access to the user action buttons is controlled by global access rights and

instance rights. The buttons are visible only to users who have global create or

edit rights.

If a user has global create or edit rights but does not have instance rights, the

buttons display but do not complete the requested action. The user receives an

error message indicating that the action cannot be completed without the proper

rights for the instance. For example, a grid portlet with configurable user action

buttons might show four instances of an object listed. If a user has global create

or edit access rights, the Delete button appears on the grid portlet. The user can

select any of the instances and click Delete, but only those instances to which the

user has instance access rights are deleted. Any selected instances that the user

does not have rights to are not deleted. In this case, the user receives an error

message.



How to Add Configurable User Actions

The following steps explain the process for adding configurable user actions to a

grid portlet. A user-defined object, an NSQL query, and a grid portlet must be

associated in a specific way so that the action buttons appear and can be

configured on the portlet. Each step below is required to set up user action

buttons.

To add configurable user actions to a grid portlet, you must:

1. Create an object (see page 36).

2. Create an NSQL query (see page 220) for the object.

3. Create a grid portlet (see page 185) that uses the NSQL query as a data

provider.

4. Select configurable user actions for the grid portlet (see page 222).

5. Test the configurable user actions in CA Clarity PPM (see page 222).

Create an NSQL Query for User Actions

To create the NSQL query, you need the following information:

■ An alias name for the object that can be included in the query and used as an

internal ID for the object‘s database table. The alias name can be any value

that you choose. For example, COMPL_ID could be the alias for an object

named Compliance.

■ The database table name and the column names for the attributes "ID" and

"Name," which are created when the object is created. To find the column

names, see the list of attributes for the object. The list contains the database

table and column for each attribute.

To create an NSQL query

1. Click Queries from the CA Clarity Studio menu.

The Queries page appears.

2. Click New.

The Query Properties: General page appears.

3. Complete the following information:

Query Name

Enter a name for the query.

Query ID

Enter a unique ID for the query.

Content Source

Select the content source for the query from the drop-down list.




The Query Properties: NSQL page appears.

5. In the NSQL text box, enter the following text and supply the appropriate

values where indicated by brackets:

SELECT @SELECT:DIM:USER_DEF:IMPLIED:RESOURCE:I.ID:<alias

name>@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:RESOURCE:I.

<database table name for attribute "id">:ID@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:RESOURCE:I.

<database table name for attribute "name">:NAME@

FROM <database table name> I

WHERE @FILTER@


The Query Properties: Attributes page appears. The listing of attributes for

the query contains the alias name, the ID attribute, and the Name attribute.

7. Click Continue.

The Query Properties: Configurable Actions page appears.

8. In the Action Source section, click the Browse icon and select the name of the

data provider object for the query. The data provider must be a user-defined

object.

9. In the Primary Key (Id:Type) section, select the alias name.

Entering the alias name here allows identification of the instance in the

portlet view in CA Clarity PPM so that the appropriate configurable action can

be applied.




Select Configurable User Actions for Grid Portlets

This procedure explains how to add configurable user actions to a grid portlet.

Before you begin, create a grid portlet and select the NSQL query created for the

portlet in the Data Provider field.

To select configurable user actions for grid portlets

1. Select Portlets from the CA Clarity Studio menu, then click the portlet name.


2. Click Layout from the content menu.

The Grid Portlet: List Column Layout page appears.

3. In the Column Layout section, do the following:

a. Move "id" and "name" to the Selected Columns list box.

b. Move any additional fields that you want to display in the portlet to the

Selected Columns list box.

c. If the alias name appears in the Selected Column list box, move it to the

Available Columns list box.

4. In the Action Layout section, select the actions you want available in the

portlet and move them to the Selection Actions for Button Bar list box. Use

the up and down arrows to put the actions into the proper order for display.


Test Configurable User Actions in CA Clarity PPM

To test the user actions in CA Clarity PPM, add the grid portlet to a page, then

open the page in CA Clarity PPM. To quickly test the grid portlet and its

configurable user actions in CA Clarity PPM, you can add the grid portlet to your

Overview page.

See the CA Clarity PPM Common Features and Personal Options guide for more

details on the Overview page.

Delete Filter Portlets


Delete Filter Portlets

When you delete a filter portlet, it is removed from any portlet pages where it is

published. If a filter portlet is the default filter for the page, deleting the filter has

the following effect on remaining filters:

■ If other filter portlets are present on the page, the default filter values are

inherited by the one published to the page at the earliest date.

■ If no other filter portlets exist on the page, the page no longer has a page

filter default and the system defaults of grid or graph portlets present are

used when the page is initially rendered.

To delete a filter portlet



2. Check the box beside the name of the filter portlet you want to delete.

3. Click Delete.

Chapter 5: NSQL 225

Chapter 5: NSQL

Before you can create a portlet to extract and display data in CA Clarity PPM, you

need to write a query that defines the data. The topics in this section discuss the

CA Clarity PPM data model and its primary database tables, and how to build

NSQL queries and lookups to extract data.


About NSQL Queries (see page 225)

About Queries (see page 237)

About Lookups (see page 240)

Hierarchical Queries (see page 242)

NSQL Troubleshooting and Tips (see page 243)

About NSQL Queries

NSQL queries are read-only operations; they do not change data, they only

retrieve it. Only SELECT statements that specify which rows and columns to fetch

from one or more tables are permitted. NSQL statements fail with an error

message if a statement does not start with SELECT. This means that UPDATE,

INSERT, and DELETE operations cannot be performed in NSQL. NSQL should not

used for reporting or for stored procedures. Anything in the database can be

used to call stored procedures.

When you define an NSQL query, you will identify the query segments and then

designate them as metric values, dimensions, dimension properties, or

parameters. All these terms, as well as the overall query definition process, are

described in this section.

With NSQL, you can access data in the CA Clarity PPM database and create

queries in Studio and use them to create new portlets. Since queries are not

directly associated with a single portlet, the same query can be used to produce

multiple portlets.

The NSQL Syntax

The main NSQL keywords are the same as standard SQL keywords and are

described in this section.

SELECT

The SELECT statement retrieves column data from tables. NSQL statements fail

with an error message when a query statement does not start with SELECT.

About NSQL Queries


FROM

The FROM clause is a standard SQL statement. It identifies the required tables

and includes tables that contain the fields in the SELECT statement lists as well

as any additional required tables.

Select @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@,

@Select:DIM_PROP:IMPLIED:PRJ:P.Name:ProjectName@

FROM SRM_PROJECTS P

-------------------------------------------------------------

Select @Select:DIM:USER_DEF:IMPLIED:PRJ:SRM_PROJECTS.ID:ProjectID@,

@Select:DIM_PROP:IMPLIED:PRJ:SRM_Projects.Start:ProjectStart@,

@Select:DIM:USER_DEF:IMPLIED:RES:R.Unique_Name:ResourceID@,

@Select:DIM_PROP:IMPLIED:RES:R.Full_Name:ResourceName@

FROM SRM_PROJECTS, SRM_RESOURCES, PRTEAM

About NSQL Queries

Chapter 5: NSQL 227

WHERE

The WHERE statement filters data returned by a query to be used on portlets.

NSQL follows the same syntax with one exception, each WHERE statement must

contain a @FILTER@ parameter.

Select @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@,

@Select:DIM_PROP:IMPLIED:PRJ:P.Name:ProjectName@

FROM SRM_PROJECTS P

WHERE @FILTER@ AND P.Is_Active=1

-------------------------------------------------------------------------

Select @ Select:DIM:USER_DEF:IMPLIED:PRJ:SRM_PROJECTS.ID:ProjectID@,

@Select:DIM_PROP:IMPLIED:PRJ:SRM_Projects.Start:ProjectStart@,

@ Select:DIM:USER_DEF:IMPLIED:RES:R.Unique_Name:ResourceID@,

@Select:DIM_PROP:IMPLIED:RES:R.Full_Name:ResourceName@

FROM SRM_PROJECTS, SRM_RESOURCES, PRTEAM

WHERE

@FILTER@

AND SRM_PROJECTS.ID=PRTeam.prProjectID

AND SRM_RESOURCES.ID=PRTeam.prResourceID

XPATH (XML Parameter) Constuct

There is syntax construct that can be used in the WHERE clause that will allow a

portlet to retrieve a name-value pair from the XML page URL where a

user-defined portlet is placed. The construct is:

@where:param:xml:string:/data/id/@value@

The syntax construct is called an XPATH or XML Parameter construct. This

construct can only be used on a specific portlet instance type, not the General

portlet instance type. This construct expects the internal ID value to come from

the URL that is displaying the page that contains the portlet. Therefore, the

portlet must be created as a specific portlet instance type, such as the Project

object portlet instance type to be placed on one of the pages from the project

object. If you create and place a General portlet on a general page, there will not

be a specific internal ID value in the URL that displays the page containing the

portlet.

Note: The construct must be entered in lowercased letters

Example

The following example shows how an NSQL query would use the XPATH

construct. The example assumes a portlet is placed on the Project Dashboard. In

the example, "id" is the name of the parameter that appears in the Project

Dashboard that must be used for this particular query to filter the data.

About NSQL Queries


SELECT @SELECT:DIM:USER_DEF:IMPLIED:PROJECT:P.ID:PID@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:PROJECT:P.UNIQUE_NAME:PNAME@,

@SELECT:METRIC:USER_DEF:IMPLIED:COUNT(*):TEAM_COUNT:AGG@

FROM SRM_PROJECTS P,

PRTEAM T

WHERE P.ID = @where:param:xml:string:/data/id/@value@

AND P.ID = T.PRPROJECTID

AND @FILTER@

GROUP BY P.ID, P.UNIQUE_NAME

HAVING @HAVING_FILTER@

When using this construct, be sure that you understand the name-value pair that

you want to retrieve from the URL on the page where the portlet is placed. If you

do not specify the correct named parameter, the portlet will not generate the

expected result set.

GROUP BY and HAVING

The GROUP BY clause is typically used to combine database records with

identical values in a specified field into a single record, usually for the purposes

of calculating some sort of aggregate function. For example, to summarize all

hours for each role on each project, group data by project and then by role.

HAVING is typically used only when GROUP BY is used and when the purpose is

to filter data based on the fields that are being grouped. In NSQL, HAVING is

required whenever a metric is used. The syntax for the HAVING statement is

@HAVING_FILTER@.

SELECT @SELECT:DIM:USER_DEF:IMPLIED:PROJECT:P.PROJECT_CODE:ProjID@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:PROJECT:P.PROJECT_NAME:ProjName@,

@select:metric:user_def:implied:P.ACTUAL_HOURS:Actuals:agg@

FROM NBI_PROJECT_CURRENT_FACTS P

WHERE @FILTER@

HAVING @HAVING_FILTER

-------------------------------------------------------------------------

SELECT @SELECT:DIM:USER_DEF:IMPLIED:PROJECT:C.MANAGER_LAST_NAME:MANAGER@,

@SELECT:METRIC:USER_DEF:IMPLIED:SUM(C.ACT_HOURS):Actuals:AGG@,

FROM NBI_PROJECT_CURRENT_FACTS C

WHERE C.MANAGER_LAST_NAME is not null AND @FILTER@

GROUP BY C.MANAGER_LAST_NAME


NSQL Constructs

The constructs described in this section expand to become elements of an NSQL

query based on the Datamart and CA Clarity PPM operational model.

About NSQL Queries

Chapter 5: NSQL 229

OBS Dimensions

The following constructs simplify the OBS structure in NSQL:

■ @SELECT:DIM:DATA_MART:OBS:PROJECT or RESOURCE[:<name>]@

The PROJECT or RESOURCE element specifies if the OBS dimensions are

Project or Resource OBS assignments. This element is mandatory. This

statement expands to one or more columns to be used in the SELECT list of

the query, some of which comprise the OBS dimension and, potentially,

some which are properties of the OBS dimension.

■ @FROM:DIM:DATA_MART:OBS[:<name>]@

This expands to include one or more OBS tables needed in the query. These

tables have aliases that start with the string ―OBS_‖, therefore other aliases

in the query must not start with this string.

■ @WHERE:DIM:DATA_MART:OBS:F[:<name>]@

This expands to include criteria to be used in the WHERE clause of the query.

The element preceding ―F‖ is optional, supplied by the application

administrator, and is the table name or alias of the fact table used in the

query. The NSQL engine can produce the correct string for joining with the

OBS information in the fact table.

■ @GROUP_BY:DIM:DATA_MART:OBS[:<name>]@

This expands to the same values of the @SELECT…@ sibling but without any

column aliases. This way it can be used in the GROUP BY clause of the query.

Security Joins

Some CA Clarity PPM entities enforce instance-level security for certain objects.

To slice queries based on the security information of the user that executes the

query, NSQL provides the following construct:

@WHERE:SECURITY:<entity type>:<entity id>]@

Where:

■ <entity type> is one of the following:

■ PROJECT

■ RESOURCE

■ <entity id> is the query expression that represents the primary key of the

entity. For example:

■ SRM_PROJECTS.ID

For example:

@WHERE:SECURITY:PROJECT:SRM.PROJECTS.ID@

About NSQL Queries


User-Defined Constructs

All parts of the SELECT clause must use special NSQL syntax and be specified

with an NSQL @SELECT@ construct.

Data Types

The following data types are supported in NSQL, are valid only as part of the

Dimension, Properties, and Metrics columns, and cannot be used as parameters:

■ IMPLIED indicates there is no need to further qualify a data type — whatever

the database contains is used. This data type is allowed only in @SELECT…@

constructs since this is the only location from which the NSQL engine can

retrieve information about the data type.

■ MONEY (<currency column>) specifies that the value is a monetary amount

and that the currency is specified by the column alias in parenthesis. The

currency must also be part of the SELECT statement.

■ STRING specifies a basic string that cannot be manipulated.

■ INTEGER

■ FLOAT

■ DATE

About NSQL Queries

Chapter 5: NSQL 231

Dimensions

A dimension is a grouping of similar data elements from one or more tables. For

example, ―Project‖ may be one dimension and ―OBS‖ or ―Tasks‖ could be other

dimensions.

Dimensions are defined in the SELECT statement using specific syntax. First you

define a key value for the dimension, then you can define the other data

elements in the dimension.

For example:

Defining the Dimension Column

Each dimension must contain a definition for the dimension column. Typically,

this is the table‘s primary key, though that may not always be the case. Use the

following syntax to define a dimension column:

SELECT @SELECT:DIM:USER_DEF:IMPLIED:<Dimension>:<Table.Field>:<label>@

When defining dimensions:

■ Each statement must begin and end with the ―@‖ character.

■ Use IMPLIED if the data type does not need to be further quantified (than

what can be derived from the database).

■ <Dimension> is a user-defined name such as RES.

■ <Table.Field> is the table or alias name — a field provided by CA Clarity PPM.

■ <label> is a user-defined name or the field that appears in the query.

■ The dimension should be comprised of unique values. If not, portlets based

on the query will not work as expected.

For example:

Select @Select:DIM:USER_DEF:IMPLIED:Project:SRM_PROJECTS.ID:ProjectID@

Select @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@

Select @Select:DIM:USER_DEF:IMPLIED:MyDim:SRM_Projects.Name:ProjectName@

Select @Select:DIM:USER_DEF:IMPLIED:PRJ:SRM_PROJECTS.ID:ProjectID@

@Select:DIM:USER_DEF:IMPLIED:RES:R.Unique_Name:ResourceID@

The following statement defines the resource dimension as the full name of the

resource:

SELECT @SELECT:DIM:USER_DEF:IMPLIED:RESOURCE:R.FULL_NAME:RSRC@

The following construct defines the resource dimension as the primary key of the

resource table (SRM_RESOURCES). It is important that the dimension is

comprised of unique values. If not, portlets based on the query will not work as

expected.

About NSQL Queries


■ R.ID is the actual column expression.

■ RSRC_RD is the alias the column receives.

The actual SQL for this NSQL expression is as follows:

SELECT R.ID RSRC_ID,

Defining the Dimension Properties Column

Once the dimension is defined, all other fields are referred to as dimension

properties. The syntax you use to define the dimension column is the same as

the one you will use to define the dimension properties column(s) with one

exception: instead of using ―DIM‖ after the select statement, you will use

―DIM_PROP‖.

SELECT @SELECT:DIM:USER_DEF:IMPLIED:<Dimension>:<Table.Field>:<label>@

@SELECT:DIM_PROP:USER_DEF:IMPLIED:<Dimension>:<Table.Field>:<label>@

When defining the Dimension Properties column:

■ Each statement begins and ends with the ―@‖ character.



■ <Dimension> must be the same Dimension name as for the Dimension

column

■ <Table.Field> is the Table or Alias name and field from CA Clarity PPM.

■ <label> is the user-defined name or the field that appears in the query.

SELECT @SELECT:DIM_PROP:USER_DEF:IMPLIED:<Dimension>:<Table.Field>:<label>@

Using the sample dimension statement from above, we add the names of the

resource and the Manager dimension properties, resulting in the following

example:

SELECT

@SELECT:DIM:USER_DEF:IMPLIED:RESOURCE:R.ID:RSRC_ID@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:RESOURCE:R.FULL_NAME:RSRC@,

@SELECT:DIM_PROP:USER_DEF:IMPLIED:RESOURCE:MR.FULL_NAME:MANAGER@

In the statement above, the unique name of the dimension is the same for the

three columns. This tells the NSQL engine that the three columns belong

together.

About NSQL Queries

Chapter 5: NSQL 233

The Metrics Column

A metric column is similar to a dimension property in that it belongs in the

SELECT section of the query, but metric column values can be totaled on a grid

or displayed as value(s) on the graph. Use the following syntax to define a metric

column:

@SELECT:METRIC:USER_DEF:IMPLIED:<Table.Field>:<label>:agg@

When defining metric columns:

■ Each statement must begin and end with the ―@‖ character.

■ The keyword <METRIC> must be present (do not use the dimension name

since metrics cross dimensions).



■ <Table.Field> is the table or alias name — a field provided by CA Clarity PPM.

■ <label> is a user-defined name or the field that appears in the query.

■ Use agg to allow the metric to be totaled when used in a grid.

For example:

@Select:METRIC:USER_DEF:IMPLIED:NBI_PROJECT_CURRENT_FACTS.ACTUAL_HOURS:hrs:agg@

@Select:METRIC:USER_DEF:IMPLIED:PRASSIGNMENT.PRACTSUM/3600:Actuals:agg@,

@Select:METRIC:USER_DEF:IMPLIED:PRASSIGNMENT.PRESTSUM/3600:ETC:agg@

@Select:METRIC:USER_DEF:IMPLIED:Count(*):Project_Count:agg@

Specifying a metrics column (or columns) is very similar to specifying a

dimension. For example, to add the Project Count (the number of projects this

resource has created) metric to the example above:

@SELECT:METRIC:USER_DEF:IMPLIED:COUNT(*):PROJECT_COUNT[:AGG]@

The last segment of the metric SELECT syntax is optional and determines if the

column expression uses an aggregation function such as COUNT, AVG, SUM, or

is a plain column expression. This is required for Metric Column filters.

If the expression uses an aggregate function, the filter is part of the HAVING

clause of the query. Otherwise, it becomes part of the WHERE clause. Adding this

to the example presented above produces the following query:

SELECT R.ID RSRC_ID,

R.FULL_NAME RSRC,

MR.FULL_NAME MANAGER,

COUNT(*) PROJECT_COUNT

About NSQL Queries


Parameters

Parameters are substitution variables that you use in a query to pass values.

Parameters only appear in the SELECT list and in the WHERE clause. There are

two kinds of parameters.

■ User-supplied parameters, which are used as filters in portlets and are either

based on the query or are fixed when the portlet is created. User-supplied

parameters are specified using the following syntax:

@SELECT:PARAM:USER_DEF:DATA_TYPE:PARAM_NAME[:ALIAS]@

or,

@WHERE:PARAM:USER_DEF:DATA_TYPE:PARAM_NAME@

Where:

DATA_TYPE is the data type for the parameter, and

PARAM_NAME is the unique identifier for the parameter.

■ Built-in parameters, which automatically take their values at run-time based

on the current user settings or system context. Built-in parameters are

specified using the following syntax:

@SELECT:PARAM:PARAM_IDENTIFIER[:ALIAS]@

or,

@WHERE:PARAM:PARAM_IDENTIFIER@

Where:

PARAM_IDENTIFIER is one of the following:

■ USER_ID

■ USER_NAME

■ LANGUAGE

■ LOCALE

Example

i.xdm_priority = prio.id and prio.language_code = @where:param:language@

and i.act_status = s.id and s.language_code = @where:param:language@

and i.xdm_impact = imp.id and imp.language_code = @where:param:language@

and i.xdm_issue_type = isstype.id and isstype.language_code =

@where:param:language

About NSQL Queries

Chapter 5: NSQL 235

Advanced NSQL Constructs

NSQL provides several special constructs to make building reports easier.

Constructs are available for the following types of data:

■ OBS

■ Calendar Time

■ Fiscal Time

■ Security

OBS

Use the OBS construct with Datamart tables to limit to an OBS unit level. In the

SELECT statement, you will specify if this is a Project or a Resource OBS. In the

WHERE statement, you will specify the Datamart table.

The syntax for OBS construct is:

@SELECT:DIM:DATA_MART:OBS:<Entity>@,

@FROM:DIM:DATA_MART:OBS@

@WHERE:DIM:DATA_MART:OBS:<Datamart Table>@

@GROUP_BY:DIM:DATA_MART:OBS@

<Entity> must be set to either PROJECT or RESOURCE

<Datamart Table> must be one of the datamart tables

Example

SELECT @SELECT:DIM:DATA_MART:OBS:PROJECT@,

@SELECT:DIM:USER_DEF:IMPLIED:PROJECT:P.PROJECT_CODE:ProjID@,

@select:metric:user_def:implied:Sum(P.ACTUAL_HOURS):Actuals:agg@,

@select:metric:user_def:IMPLIED:Sum(P.ETC_Hours):ETC:agg@

FROM NBI_PROJECT_CURRENT_FACTS P, @FROM:DIM:DATA_MART:OBS@

WHERE @FILTER@ AND @WHERE:DIM:DATA_MART:OBS:P@

GROUP BY @GROUP_BY:DIM:DATA_MART:OBS@, P.Project_Code


About NSQL Queries


Calendar Time

Use the CALENDAR TIME construct with the following Datamart time tables to

show hours or costs across a time scale:

■ NBI_PM_PT_FACTS

■ NBI_PM_PROJECT_TIME_SUMMARY

■ NBI_RT_FACTS

■ NBI_RESOURCE_TIME_SUMMARY

The syntax for CALENDAR TIME construct is:

@SELECT:DIM:DATA_MART:CALENDAR_TIME@

@FROM:DIM:DATA_MART:CALENDAR_TIME@

@WHERE:DIM:DATA_MART:CALENDAR_TIME: <Datamart TIME Table>@

@GROUP_BY:DIM:DATA_MART:CALENDAR_TIME@

Fiscal Time

Use the FISCAL TIME construct when dealing with fiscal periods:

@SELECT:DIM:DATA_MART:FISCAL_TIME[:<name>]@

@FROM:DIM:DATA_MART:FISCAL_TIME[:<name>]@

@WHERE:DIM:DATA_MART:FISCAL_TIME:F[:<name>]@

@GROUP_BY:DIM:DATA_MART:FISCAL_TIME[:<name>]@

Security

Projects or resources appear only in a grid or graph when a user has sufficient

access rights. Use SECURITY in the WHERE clause to verify the user‘s access

rights.

The syntax for Security construct is:

@WHERE:SECURITY:<entity type>:<entity id>@

When defining a Security construct:

■ Each statement begins and ends with the ―@‖ character.

■ WHERE, must appear in the WHERE section of the NSQL.

■ <entity type> is either PROJECT or RESOURCE.

■ <entity id> is the project or resource ID (for example, SRM_PROJECTS.ID or

NBI_PROJECT_CURRENT_FACTS.Project_ID).

About Queries

Chapter 5: NSQL 237

About Queries

Before you can create a portlet in CA Clarity PPM, you need to write a query to

extract the data.

Create Queries

This section shows you how to create a simple query. Studio provides a variety of

query templates to help you get started. Query templates are available for the

following types of data:

■ Collaboration

■ Project

■ Productivity

■ Resource

■ Business Intelligence

■ Framework

Each of the query templates specifies typical data elements for that type of

query. Once your query is created, you can use it to populate data in a portlet.

Important! If an NSQL query‘s SELECT statement includes too many columns

or aggregate functions at runtime, a system error occurs. The total amount of

actual data for sorting (plus the aggregates) cannot be greater than the current

database block size.

Use the Query Properties: General page to create new queries.

To create a new query

1. Select Queries from the CA Clarity Studio menu.


2. Click New.



Query Name

Enter a name for the query.

About Queries


Available for User Portlets

Specifies that users can use the query as a data provider for user portlets

that will be used in personal dashboards.

Query ID

Enter a unique ID.

Content Source

Select a data source.

Category

Select the type of query you are creating. The choices that appear

depend upon the categories set by your CA Clarity PPM administrator.

Description

Enter a description of the query.


5. Enter your NSQL into the query window.


7. Review the data to be included in the query and identify which of the columns

can be filtered, which are required, and which can be used as lookups. Click

Continue.

8. To define links to another table, click New and complete the following fields:

Name

Enter a name for the link.

Link ID

Enter a unique ID for the link.

Description

Enter a description.

Action

Select a link (or destination) for the link.

Note: Links are predefined.

9. Enter a unique ID in the next field and click Submit.

About Queries

Chapter 5: NSQL 239

Change Queries

If the query has not yet been associated with an object, you can use the following

procedure to change it.

To change a query



2. Click the name of the query that you want to change.


3. Select NSQL from the content menu.

The Query Properties: NSQL page appears.

4. Enter your changes.

5. Click Save.

Delete Queries

You can delete queries that are not yet associated with a portlet.

To delete a query



2. Check the box next to the query that you want to delete.

3. Click Delete, then click Yes.

About Lookups


About Lookups

You can use NSQL to create lookups that dynamically filter portlet data. Rather

than have a full-text field as a filter, you can create lookups as drop-down lists

and browse lists to filter portlet data. There are three types of lookups:

■ Static List, that consist of a standard set of choices. These are often used as

drop-downs or browse lists for reports, user-defined fields, and user-defined

XDM forms.

■ Static Dependent Lists, that provide two or more choices. Use this type of

lookup to create a hierarchy of lookups and values. Items that appear on the

second and subsequent selection lists depend upon choices previously made

by the user.

For example, if the user selects ―USA‖ from a country browse list, then a

state list may appear from which the user can select an appropriate state. If

the user selects ―Canada‖ in the country browse list, a list of provinces

appears in the second selection list.

■ Dynamic Queries, which fetch data from the CA Clarity PPM database in

realtime to populate the drop-down or browse lists. These lookups provide

the most up-to-date values possible.

The following example shows a dynamic query that returns a list of resources

and filters out all resources with a null user_id value. The result set will contain

resources with a user account to sign in to the application.

SELECT @SELECT:r.user_id:user_id@,

@SELECT:r.unique_name:unique_name@,

@SELECT:r.first_name:first_name@,

@SELECT:r.last_name:last_name@,

@SELECT:r.full_name:full_name@

FROM srm_resources r

WHERE r.user_id IS NOT NULL

AND @FILTER@


About Lookups

Chapter 5: NSQL 241

Browse-only Construct for Dynamic Query Lookups

For dynamic query lookups, browsing works in a specific way. When a record is

displayed in the application, the value does not appear in the lookup field

because there is no match between the value stored on the record and the list

value in the lookup. The old values are retained within the database table for the

instance record. However, if a record with the old value is retrieved and is not

seen in the application's display, clicking the Save or Submit button removes the

old value from the record.

To retain inactivated values in the record and see them in the application, you

must change the lookup query definition. For this case, the definition must

include the specific NSQL construct @BROWSE-ONLY. When a user uses the

lookup on new records, active values are displayed. And, when an existing

record is shown with inactive values, the inactive value remains on the record.

The syntax for this construct is :

@BROWSE-ONLY: /* include SQL statement here to look at active results only */

:BROWSE-ONLY@

The following example shows the BROWSE-ONLY construct with a value included

that defines the results that will be displayed.

SELECT ......

FROM .....

WHERE @FILTER@

@BROWSE-ONLY:

AND IS_ACTIVE = 1

:BROWSE-ONLY@

Hierarchical Queries


Hierarchical Queries

A hierarchical query is used to display values in a hierarchical grid portlet. A

hierarchical query is written using the same NSQL syntax as a regular query, and

all NSQL constructs are available for a hierarchical query. The following items are

specific for hierarchical queries:

■ A dimension property with a code of "hg_has_children." The property can be

of any data type but is usually number or string. It must be a unique value

for all rows in the dimension (or it can be NULL). A value at runtime for this

property signifies that the row has children and the row in the grid will have

the [+] icon rendered. A NULL value means the row does not have children.

■ A parameter with a code of "hg_row_id." The parameter‘s data type must

match that of hg_has_children. This parameter means "the current row."

When a user clicks on the expand icon in the grid, the id of the expanded row

is passed into the query as this parameter. The value passed in is the same

value that was previously returned as hg_has_children. The following rules

must be followed when using this parameter:

■ When hg_row_id is null, you return only the top-level rows in the

hierarchy.

■ When hg_row_id has a value, you return only the "child" rows for that

row—immediate children only, no grandchildren, great grandchildren,

and so on.

Filtering in Hierarchical Queries

Filter values are passed into the hierarchical queries as they are for regular

queries. The standard CA Clarity PPM hierarchical grids return all ancestor rows

when a leaf row matches the filter criteria. For example, consider this simple

hierarchy:

North America

Canada

Ontario

Toronto

If you filter on name="Toronto," the query returns "North America," "Canada,"

"Ontario," and "Toronto," one level at a time. This allows you to expand through

the hierarchy to find the row(s) matching the filter criteria and still see the data

in a hierarchical format. Although it is not required, you can structure a query to

provide similar functionality.

NSQL Troubleshooting and Tips

Chapter 5: NSQL 243

NSQL Troubleshooting and Tips

The following errors can occur when you are working with NSQL:

■ This query produced duplicate dimensional data. The results shown here

may be invalid or incomplete.

The unique key in the Dimension property cannot contain duplicate values.

Make sure that the tables joins are correct.

■ Error when trying to execute the query.

Possible causes:

■ A field listed In the SELECT or WHERE clause does not specify the table

name. Because the field name appears in multiple tables, the table name

must precede the field name.

■ A comma after the last table listed in the FROM clause.

■ Incorrect table name.

Use the following tips to ensure NSQL successful queries:

■ When you create queries for use with pie charts and funnel charts, make

sure that the metric does not contain negative values by filtering all values

greater than zero.

■ NSQL adds SQL constructs to the end of the statement for automated

filtering and other statements. This can create problems when you use

UNION in NSQL. As a workaround, use the @SELECT@ in the outer select of

an inline view that encapsulates the UNION statement.

Index 245

Index

A

access • 37

access, restricting • 217

activating objects, event enabling • 36

add-ins

applying • 90

described • 90

admin page template • 210

application page template • 210

attributes

about the object attribute • 79

deleting • 85

description • 68

parameters • 67

audit trail • 87

auto-numbering

creating schemes • 80

deactivating • 84

modifying schemes • 83

using with partitions • 79

B

boolean fields • 52

C

calculated attributes

building the calculation • 74

creating • 72

example • 76

functions • 69

testing • 78

colors

displaying boolean fields as icons • 52

displaying formula fields in • 47

displaying money fields in • 50

displaying number fields in • 43

configurable user actions

basic steps for adding • 221

description • 220

NSQL query for • 221

selecting for grid portlet • 223

core tables

npt.filterPortletProperties • 195

currency codes • 50

D

dashboards, user • 160

data providers • 167

data types

adding attributes to • 40

supported in CA Clarity PPM • 40

date fields

adding to objects • 56

displaying • 56

display mappings • 128

displaying • 178

F

field data types • 38

attachments • 38

boolean • 38

dates • 38

dynamic queries • 38

formulas • 38

large strings • 38

lookups • 38

money • 38

multi-valued lookups • 38

numbers • 38

static dependent lists • 38

strings • 38

time-varying • 38

field values

displaying as color or icon • 131

highlighting range of • 131

fields

changing appearance • 128

changing labels • 130

changing properties • 128

for column or bar graphs • 138

representing number fields • 43

filter portlets

adding • 224

adding Boolean fields • 201

adding date fields • 203

adding lookup fields • 204

adding money fields • 200

adding number fields • 198

adding string fields • 196


adding URL fields • 207

basic setup steps • 195

creating • 195

deleting • 224

descriptions • 192

layout • 209

persistence • 194

precedence • 193

scope • 194

viewing • 208

fiscal time • 236

formula fields, adding • 47

G

Gantt fields, adding • 124

graph portlets

appearance • 167, 172, 180

changing • 180

creating • 170

data display • 167, 178, 180

deleting • 167, 180

dimensions • 169

graph types • 169

graphs

bar • 169

bubble • 169

column • 169

funnel • 169

line • 169

metrics • 169

pie • 169

grid portlets

access rights • 184

changing • 184, 191

comparison • 184

considerations • 184, 185, 186

creating • 186


layout • 184, 188, 191

mouseover text • 188

using • 184

variance • 184

guidelines • 172

H

hierarchies (Studio) • 29

HTML portlets

about • 181


creating • 181


I

icons

displaying boolean fields as • 52

displaying formula fields as • 47

displaying money fields as • 50

image fields • 124

individuals, access to • 37

interactive portlet parameters

creating • 166

interactive portlets

about • 164

associating with objects • 166

creating • 164

L

legends, graph portlets • 172

links • 121

list column • 91

list column views

adding fields • 94

adding image fields • 124

adding to • 126

highlighting in • 94

modifying • 134

multiple-time varying • 98

setting up in • 94

sorting in • 91, 99

list filter views

modifying • 137

setting up in • 92

lookups

about • 240

displaying fields • 58

partitioned • 20

static list • 38

M

markers, adding legends • 172

master objects, designating • 36

menus

changing • 141

creating links • 141

money fields, displaying • 50

mouseover • 124

multi-valued lookup fields, displaying • 61

Index 247

N

NSQL

calendar time • 235, 236

constructs • 228, 229, 230

data types • 230

DATE • 230

defining the metrics column • 229, 233

dimensions • 229, 231

fiscal time • 236

FLOAT statement • 230

FROM statement • 226

GROUP BY command • 228

HAVING command • 228

IMPLIED • 230

INTEGER • 230

MONEY • 230

OBS construct • 235

OBS dimensions • 228, 229

parameters • 234

queries • 225

SELECT command • 225

SQL • 225

STRING • 230

syntax • 225

troubleshooting • 243

WHERE statement • 227

number fields, adding • 43

O

objects

adding fields to • 40

applying partition models to • 26

child • 29

copy enabling • 36

creating new • 36

deleting • 89

described • 29

granting access to • 37

process overview • 29

resetting views • 110

P

partition models

about • 19

adding partitions to • 24

adding to • 23

creating • 22

partitioned data providers • 20

partitions

adding to partitions • 25

basic guidelines • 22

creating and using • 22

hierarchies • 19

hierarchies and partitions • 29

how they work • 18

parent • 23, 24

partitioned data providers • 20

relationship to object views • 20

using • 17

pop-up page template • 210

portlet pages

adding to • 214

creating • 210

deleting • 216

portlets

deploying content • 191, 210, 223

graphs • 167

hierarchical grid • 185

portlet pages • 217

publishing • 216

restricting access • 191, 216

restricting portlet configuration • 218

types • 151

portlets and pages, accessing • 216

portlets, user • 160

power filters • 92

PowerMods, configuration • 29

progress bar fields • 127

properties views

about • 91

adding to object views • 92

fields • 132

Q

queries


deleting • 239

described • 237

S

scatter graphs • 169

secondary values • 94

sections

adding • 141

changing • 143

deleting • 144

moving • 144


selecting UI theme • 23

static lookups

partitions • 20

user-defined • 20

stock icons • 147

stock objects

baseline • 35

string fields

adding large • 41

adding to objects • 41

Studio • 15

subobjects • 36

subpages

about • 121

about the Display Condition Builder • 105

adding • 102

System Partition • 18

system types

booking status list • 35

investments • 35

key tasks • 35

organizer tasks • 35

portfolios • 35

U

user dashboard • 160

user portlet • 160

user-defined fields

creating • 40

maximum allowed number • 40

user-defined objects • 29

V

views

described • 91

list filter • 91

publishing • 107

virtual fields • 94

W

weighted average • 47

word wrapping

bar graphs • 138

column graphs • 138

enabling • 138

caclarityppm studio developerguide enu

Documents

ca clarity

minor tick

major tick

organizational

sql reserve

lowest descendent

facing triangle

custom property