Sie sind auf Seite 1von 279

CA Clarity PPM

Studio Developer's Guide


v13.0.00

This documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the Documentation) is for your informational purposes only and is 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 disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) 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 or otherwise make available 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 or otherwise make available 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 YOU 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 such license agreement 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 2011 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Contact CA Technologies
Contact CA 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

Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. 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.

Contents
Chapter 1: Studio Introduction 13
About Studio .............................................................................................................................................................. 13 Key Studio Terms........................................................................................................................................................ 15 Prerequisite for Working in Studio ............................................................................................................................. 17

Chapter 2: Objects

19

About Objects............................................................................................................................................................. 19 Display an Object's Properties ................................................................................................................................... 21 Create an Object ........................................................................................................................................................ 21 Grant Access to an Object's Definition ....................................................................................................................... 22 Audit an Object .......................................................................................................................................................... 23 Delete an Object......................................................................................................................................................... 24

Chapter 3: Attributes

27

About Attributes......................................................................................................................................................... 27 Attribute Data Types .................................................................................................................................................. 28 Display an Object's Attributes .................................................................................................................................... 30 How to Create an Attribute ........................................................................................................................................ 30 Create an Attachment Attribute ......................................................................................................................... 31 Create a Boolean Attribute ................................................................................................................................. 32 Create a Calculated Attribute.............................................................................................................................. 35 Create a Date Attribute ....................................................................................................................................... 45 Create a Formula Attribute ................................................................................................................................. 47 Create a Lookup Attribute................................................................................................................................... 49 Create a Money Attribute ................................................................................................................................... 51 Create a Multi-valued Lookup Attribute ............................................................................................................. 54 Create a Number Attribute ................................................................................................................................. 56 Create a Parameterized Lookup Attribute .......................................................................................................... 58 Create a String Attribute ..................................................................................................................................... 59 Create a Time-Varying Attribute ......................................................................................................................... 61 Create a URL Link Attribute ................................................................................................................................. 63 Display Mappings for Attributes ......................................................................................................................... 64 Auto-Numbered Attributes ........................................................................................................................................ 65 Auto-Numbering and Partitions .......................................................................................................................... 65 Create an Auto-Numbering Scheme ................................................................................................................... 66 Modify an Auto-Numbering Scheme .................................................................................................................. 69

Contents 5

Deactivate an Auto-Numbering Scheme............................................................................................................. 69 Modify Attribute Properties ....................................................................................................................................... 70 Delete an Object Attribute ......................................................................................................................................... 71

Chapter 4: Partitions

73

About Partitioning ...................................................................................................................................................... 73 Partition Models.................................................................................................................................................. 75 Partitions and Views ........................................................................................................................................... 75 Partitioned Data Providers and Portlets ............................................................................................................. 76 Partitions and Lookups ........................................................................................................................................ 76 Partitions and Access Rights ............................................................................................................................... 77 Basic Partition Guidelines........................................................................................................................................... 77 Overview of the Partition Model Process .................................................................................................................. 78 Create a Partition Model ............................................................................................................................................ 78 Add a Partition to a Partition Model .......................................................................................................................... 79 Add Multiple Partitions to a Partition Model (Quick Create) ..................................................................................... 79 Add Members (Resources) to a Partition ................................................................................................................... 80 Apply a Partition Model to an Object......................................................................................................................... 81

Chapter 5: Views

83

About Views ............................................................................................................................................................... 84 Configure the Properties View ................................................................................................................................... 85 Add an Attribute to an Object's Properties View ................................................................................................ 86 Add a Section to the Properties View ................................................................................................................. 87 Add a Subpage to the Properties View ............................................................................................................... 88 Modify a Properties View Attribute .................................................................................................................... 94 Configure the List Column View ................................................................................................................................. 96 Set Up Columns for the List View ........................................................................................................................ 96 Use Attributes to Sort a List Column View .......................................................................................................... 98 Images in the List Column View .......................................................................................................................... 99 Add Aggregation Rows to a List Column View .................................................................................................. 111 Change the Order of Aggregation Rows............................................................................................................ 112 Modify a List Column View Attribute ................................................................................................................ 112 Configure the List Filter View ................................................................................................................................... 116 Add an Attribute to an Object's List Filter View ................................................................................................ 116 Modify a List Filter View Attribute .................................................................................................................... 117 Edit an Attribute's Label for a Specific View............................................................................................................. 119 Publish Changes to List and Filter Views .................................................................................................................. 120 Restore Defaults for Object Views ........................................................................................................................... 122 Restore Defaults for Selected Views ........................................................................................................................ 123

6 Studio Developer's Guide

Chapter 6: Links

125

About Links ............................................................................................................................................................... 125 Link from an Object Page to a Subpage ................................................................................................................... 125 How to Link from CA Clarity PPM to a Web Page .................................................................................................... 126 Link to Properties Pages from External Applications ............................................................................................... 126

Chapter 7: Portlets

129

About Portlets .......................................................................................................................................................... 129 Relabel Attribute Names for User Portlet Data Providers ................................................................................ 130 User Portlets and Personal Dashboards ................................................................................................................... 131 About Personal Dashboards .............................................................................................................................. 131 Personal Dashboard Properties Settings ........................................................................................................... 131 Access Rights for Personal Dashboards ............................................................................................................ 132 Administrator Access to User Portlets .............................................................................................................. 132 Personal Dashboard Operations by User Type ................................................................................................. 133 Chart Portlet ............................................................................................................................................................. 133 Create a Chart Portlet ....................................................................................................................................... 134 Set up a Chart Filter .......................................................................................................................................... 137 Determine a Chart Portlet's Data and Layout ................................................................................................... 138 Determine a Chart Portlet's Appearance .......................................................................................................... 138 Modify a Chart Portlet ...................................................................................................................................... 144 Filter Portlet ............................................................................................................................................................. 144 Filter Precedence .............................................................................................................................................. 145 Scope of Filter Portlets ...................................................................................................................................... 145 Filter Persistence ............................................................................................................................................... 146 How to Set Up a Filter Portlet ........................................................................................................................... 146 Create a Filter Portlet ........................................................................................................................................ 146 Add a Field to a Filter Portlet ............................................................................................................................ 148 Complete Field Layout for a Filter Portlet ......................................................................................................... 150 Add a Filter Portlet to a Portlet Page ................................................................................................................ 150 View Portlet Pages that Contain a Specific Filter Portlet .................................................................................. 152 Grid Portlet ............................................................................................................................................................... 152 Secured Data and Grid Portlets ......................................................................................................................... 152 Grid Portlet Options .......................................................................................................................................... 153 Considerations for Grid Portlets ....................................................................................................................... 153 Create a Grid Portlet ......................................................................................................................................... 154 Set up a Grid Portlet's Layout ........................................................................................................................... 156 Set up Display Options for a Grid Portlet .......................................................................................................... 156 Display a Gantt Chart in a Grid Portlet .............................................................................................................. 158 Display a Progress Bar in a Grid Portlet ............................................................................................................ 160 Display a Bar or Column Chart in a Grid Portlet ................................................................................................ 162

Contents 7

Add Aggregation Rows to a Grid Portlet ........................................................................................................... 164 Display an Image Link in a Grid Portlet ............................................................................................................. 165 Set Up a List Filter for a Grid Portlet ................................................................................................................. 166 Modify a Grid Portlet ........................................................................................................................................ 167 Delete a Grid Portlet ......................................................................................................................................... 167 HTML Portlet ............................................................................................................................................................ 167 Create an HTML Portlet..................................................................................................................................... 168 Modify an HTML Portlet .................................................................................................................................... 169 Interactive Portlets ................................................................................................................................................... 170 Create the Interactive Portlet ........................................................................................................................... 171 Create Object or Global Parameters ................................................................................................................. 172 Publish Changes to a Portlet .................................................................................................................................... 174 Set User Configuration of Portlets ........................................................................................................................... 174 Restrict User Rights for a Specific Portlet or Portlet Page........................................................................................ 175 Set a System View for a Portlet ................................................................................................................................ 176

Chapter 8: Portlet Pages

179

About Portlet Pages ................................................................................................................................................. 179 How to Create a Non-Tabbed Portlet Page .............................................................................................................. 180 Create a Portlet Page ........................................................................................................................................ 180 Configure a Non-tabbed Portlet Page ............................................................................................................... 181 How to Create a Tabbed Portlet Page ...................................................................................................................... 182 Set Up Link Parameters for a Tabbed Portlet Page ........................................................................................... 183 Create a Tab ...................................................................................................................................................... 183 Configure a Tab ................................................................................................................................................. 184 Configure a Portlet Page Tab Set.............................................................................................................................. 186 Activate or Deactivate Tabs .............................................................................................................................. 186 Reorder Tabs ..................................................................................................................................................... 187 Select User Object Actions for a Tab Menu ...................................................................................................... 187 Rename a Portlet Page Tab ...................................................................................................................................... 188 How to Display Multiple Subpages on a Custom Portlet Page Tab .......................................................................... 188 Create a Custom Properties View ..................................................................................................................... 189 Add a Subpage to a Custom Properties View.................................................................................................... 189 Move a Subpage Between Properties Views .................................................................................................... 190 Delete a Subpage from a Custom Properties View ........................................................................................... 190 Delete a Custom Properties View ..................................................................................................................... 191 Restore Defaults for a Custom Properties View................................................................................................ 191 Display Custom Subpage Links on a Tab ........................................................................................................... 191

Chapter 9: Menu Manager

195

How to Work with CA Clarity PPM Menus ............................................................................................................... 195

8 Studio Developer's Guide

Add a Menu Section ................................................................................................................................................. 196 Add a Menu Page Link .............................................................................................................................................. 197 Add a Menu Action Link ........................................................................................................................................... 198 Edit a Menu Section or Link...................................................................................................................................... 198 Reorder a Menu Section or Link ............................................................................................................................... 199 Remove a Menu Section or Link ............................................................................................................................... 200

Chapter 10: Object Actions

201

About Object Actions ............................................................................................................................................... 201 Where You Can Place Object Actions ................................................................................................................ 202 Object Action Scope .......................................................................................................................................... 202 Object Actions Access Rights............................................................................................................................. 203 How to Create and Set Up an Object Action ............................................................................................................ 204 Create a Report Object Action .......................................................................................................................... 204 Create a Job Object Action ................................................................................................................................ 206 Create a Process Object Action ......................................................................................................................... 207 Create an Internal Link Object Action ............................................................................................................... 208 Create an External Link Object Action............................................................................................................... 209 Edit an Object Action................................................................................................................................................ 211 Delete or Deactivate an Object Action ..................................................................................................................... 211 Create an Actions Menu for Object Actions ............................................................................................................. 212 Determine the Order for Menus .............................................................................................................................. 213 Add an Object Action Link to the Home Menu ........................................................................................................ 213

Chapter 11: Time-Scaled Values

215

About Time-Scaled Values ........................................................................................................................................ 215 How to Set Up Calendar Time-Scaled Values ........................................................................................................... 216 Create a Virtual Column for a Time-Scaled Value ............................................................................................. 216 Add a Virtual Column ........................................................................................................................................ 219 Custom Fiscal Time-Scaled Values............................................................................................................................ 219 Controlling Fiscal Time-Scaled Values ............................................................................................................... 220 How to Create a Custom Fiscal Time-Scaled Value Field .................................................................................. 221 Test a New Time-Scaled Value ................................................................................................................................. 222 Display Multiple Time-Scaled Values in a List Column ............................................................................................. 223

Chapter 12: NSQL Queries

225

About NSQL Queries................................................................................................................................................. 225 NSQL Syntax ............................................................................................................................................................. 226 SELECT ............................................................................................................................................................... 226 FROM ................................................................................................................................................................ 226

Contents 9

WHERE .............................................................................................................................................................. 227 GROUP BY and HAVING..................................................................................................................................... 228 NSQL Constructs ....................................................................................................................................................... 228 Security Joins..................................................................................................................................................... 229 User-Defined Constructs .......................................................................................................................................... 229 Data Types......................................................................................................................................................... 229 Dimensions ........................................................................................................................................................ 230 Metrics Column ................................................................................................................................................. 232 Parameters ........................................................................................................................................................ 233 Advanced NSQL Constructs ...................................................................................................................................... 234 Security ............................................................................................................................................................. 234 Create a Query ......................................................................................................................................................... 234 About Lookups ......................................................................................................................................................... 236 BROWSE-ONLY Construct for Dynamic Query Lookups .................................................................................... 237 Hierarchical Queries ................................................................................................................................................. 238 Filtering in Hierarchical Queries ........................................................................................................................ 238 NSQL Troubleshooting and Tips ............................................................................................................................... 239

Chapter 13: UI Themes

241

About UI Themes ...................................................................................................................................................... 241 Stock UI Themes ....................................................................................................................................................... 241 Select a New UI Theme ............................................................................................................................................ 242 Select a UI Theme for a Partition ............................................................................................................................. 242 Custom UI Themes ................................................................................................................................................... 243 CSS Stylesheet ................................................................................................................................................... 244 Create a Custom UI Theme ............................................................................................................................... 245 Application Page Header Examples................................................................................................................... 246 Main Menu Examples........................................................................................................................................ 247 Workspace Examples ........................................................................................................................................ 248 Exporting and Importing UI Themes ........................................................................................................................ 249

Chapter 14: Add-ins

251

About Add-ins........................................................................................................................................................... 251 Updates to Add-Ins................................................................................................................................................... 251 Apply an Update for an Add-In to CA Clarity PPM ................................................................................................... 252

Appendix A: Access Rights

253

Basic Studio Access Rights ........................................................................................................................................ 253 Object Access Rights ................................................................................................................................................ 253 Portlet Access Rights ................................................................................................................................................ 254

10 Studio Developer's Guide

Portlet Pages Access Rights ...................................................................................................................................... 255 Partition Model Access Rights .................................................................................................................................. 256 Menu Manager Access Rights .................................................................................................................................. 256 Add-in Access Rights ................................................................................................................................................ 257

Appendix B: Stock Objects Appendix C: Stock Portlets

259 263

Stock Chart Portlets.................................................................................................................................................. 263 Stock Grid Portlets.................................................................................................................................................... 264 Stock Filter Portlets .................................................................................................................................................. 267 Restricted Stock Portlets .......................................................................................................................................... 267

Appendix D: Data Providers

271

About Data Providers ............................................................................................................................................... 271 System Type Data Providers ..................................................................................................................................... 271

Appendix E: Stock Object Actions

273

Contents 11

Chapter 1: Studio Introduction


This section contains the following topics: About Studio (see page 13) Key Studio Terms (see page 15) Prerequisite for Working in Studio (see page 17)

About Studio
Studio lets you tailor your CA Clarity PPM system and deploy local configurations and personalized user interfaces to users. It is a way to configure CA Clarity PPM so that it works for your exact business processes and information needs. You can propagate the attributes 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. The following table shows the features that are available to you using Studio. Features User-defined portlets Benefits Enables organizations to collect easily, 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 attributes, deploy them in forms on specific pages, and build portlets to communicate graphically the information collected. Delivers over 40 stocks and an unlimited number of user-defined portlets that display charts, tables, and HTML content. These portlets reflect the users access rights and filter settings to allow them to access and drill into information in a single, consolidated view. Displays graphical information in grids or bar, bubble, column, funnel, line, pie, and scatter charts. Allows administrators to define links that provide users access to underlying data and specific instances of objects. Filters data on any number of predefined, configurable parameters.

Point-and-click portlet construction

Multiple display types Drill-down charts Data filters

Chapter 1: Studio Introduction 13

About Studio

Features Precision Security

Benefits Reduces administration costs by providing built-in organizational breakdown structure (OBS) security. Once access rights for viewing information are assigned, users see only the information for which they have access. Portlets automatically generate charts and tables based on the access rights of the current user. 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 attributes, forms, processes, and branding. Lets you add new business objects to CA Clarity PPM and then configure them with attributes, forms, processes, and portlets. Lets users provide document and other types of attachments for any standard or user-defined business object. Simplifies administration by centralizing the management of all user-defined attributes within Studio. User-defined attributes are automatically deployed to the user interface, to the process engine, to OpenWorkbench, to Microsoft Project, and to the XOG (XML Open Gateway). 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. 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 workspace. Reduces training and support costs by organizing the CA Clarity PPM menu navigation to match the companys terms and processes. Lets you enable a feature to allow all instances of an object and its subobjects on one properties page. Using subobjects lets you create an object hierarchy with a maximum of three levels of user-defined objects that inherit properties from higher-level objects. Lets you create string objects of any length (subject to limitations of your database). Lets you export objects in XML format.

Partitions

User-defined objects

Attachments

Centralized attribute control

User interface configuration

New dashboard page development

Menu manager

View All Third-level object hierarchy Large string attribute Export to XML

14 Studio Developer's Guide

Key Studio Terms

Features Add-ins

Benefits Lets you apply add-ins to import a collection of content (pages, portlets, queries, project templates, roles, etc.) as a single entity. Lets you configure and add your own status attributes to action items and any notification sent by CA Clarity PPM.

Configurable notifications

Key Studio Terms


The following terms are used throughout this book. 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 object. The information 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, or system types. If you chose to use queries to provide data, you must use NSQL to create the queries. CA Clarity PPM's data model supports most of the business objects you need, but you can also create constructs to meet your unique business needs. 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 data set, 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.

Chapter 1: Studio Introduction 15

Key Studio Terms

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, products, other investments, companies, and users. Object Action An action for an object that can be performed by clicking a link in a menu. System object actions are provided out-of-the-box, but you can create custom object actions and place them on a menu where they are needed in the application. Examples of system object actions include New Project, Create Baseline, and Add Subproject. 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, attributes, 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 charts among other types. Portlet Page A CA Clarity PPM web page with content comprised of portlets or views. A portlet page can be configured to have a single tab or multiple tabs. Query A set of conditions used to retrieve specific information from a database. 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. 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 user can participate on a collaboration project and can also be a resource.

16 Studio Developer's Guide

Prerequisite for Working in Studio

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 (that is, the data is created in real time). Virtual attribute An attribute to which CA Clarity PPM can make calls but that does not physically exist in CA Clarity PPM. It can be a calculated attribute or an attribute with temporary values generated by CA Clarity PPM as needed. You cannot access a virtual attribute because it does not physically exist. Virtual columns are not stored in database tables.

Prerequisite for Working in Studio


Before you start working in Studio, verify that you have the appropriate Studio access rights. Knowledge of SQL is not required to work in Studio, but some knowledge of SQL is helpful in setting up and managing data.

Chapter 1: Studio Introduction 17

Chapter 2: Objects
This section contains the following topics: About Objects (see page 19) Display an Object's Properties (see page 21) Create an Object (see page 21) Grant Access to an Object's Definition (see page 22) Audit an Object (see page 23) Delete an Object (see page 24)

About Objects
Objects define the attributes (fields), subpages (links), page layout, and views that make up your configured version of CA Clarity PPM pages. CA Clarity PPM provides stock objects that 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 create a hierarchy with a maximum of three levels of objects and allow child objects to inherit properties and access rights from parent objects. The following illustration shows how master objects and subobjects are related.

A user with access rights to this object has the same rights to all of its subobjects.

Master Object

Parent of Subobject 1 and the grandparent of Subobject 2

Subobject 1

Child of the Master Object and parent of Subobject 2

Subobject 2

Child of Subobject 1 and grandchild of the Master Object

Chapter 2: Objects 19

About 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 must grant them access rights to it. The following illustration shows the relationship of partitions, objects, attributes, views, and subpages. A partition contains the object and the other components that make up the pages that a user sees.

20 Studio Developer's Guide

Display an Object's Properties

Display an Object's Properties


You can display an object to view its properties or to make edits. Follow these steps: 1. Open Administration, and from Studio, click Objects. The objects list page appears. 2. In the Object column, click the name of the object. The properties page appears.

Create an Object
Once an object is created, you can assign access rights to users, OBS units, or groups to access the object. When creating an object, do not use the following reserved words for the object name or object ID:

asset application company contract discussion glallocation idea incident incidentcategory investmentallocation investmenthierarchy invoice

invoiceitem invoicetransaction other product release releaseplan requirement requisition resourcecredit service subscription

Follow these steps: 1. Open Administration, and from Studio, click Objects. The list page appears. 2. Click New. The create page appears.

Chapter 2: Objects 21

Grant Access to an Object's Definition

3.

Complete the following fields: Object Name Defines the object name. Object ID Defines a unique alphanumeric identifier for the object. Description Defines the purpose of the item being created and provides any relevant information. Master or Subobject Specifies whether an object is a master object or a subobject. Values:

Master. Specifies the object is not the child of another object. Select the partition model of the master object in the Partition Model field. The default is the System partition model. Subobject. Specifies the object is the child of another object. Select the master object of the subobject in the Master Object field.

Event Enabled Specifies that the process engine is made aware of object instances that are created or updated. Copy Enabled Specifies that copies can be made of the object's instances. Export Enabled Specifies that object instances can be exported into XML. View All Enabled Specifies that the object's instances can have a view that contains all properties, subobject lists, and personalizable page portlets on a single page. 4. Save your changes.

Grant Access to an Object's Definition


Use this procedure to grant access to an object's definition. When you grant this access right, a user can open and edit the definition for the object. Organizational breakdown structures (OBS) control access, department hierarchies, and reporting. If at least one OBS exists for an object, users can associate those OBSs to their object instance.

22 Studio Developer's Guide

Audit an Object

Follow these steps: 1. With the object open, click Access to this Object and select one of the following options:

Resource. Lets you grant access to individual resources. Group. Lets you grant access to defined groups of resources. OBS Unit. Lets you grant access to defined OBS units containing resources.

2.

Click Add. A list of access rights appears.

3.

Select the check boxes next to the access rights you want to grant, and click Add and Continue. A list appears with a list of resources, groups, or OBS units.

4.

Select the check boxes next to each resource, group, or OBS unit you want to grant access to, and click Add.

Audit an Object
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 Trail tab when viewed in CA Clarity PPM. See the Administration Guide for more information. 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 named "High Defect Count" that you create and add to a project.

Tracking operations for sub-objects with the master object You can configure auditing operations for a sub-object like a task. Users can see the sub-object's auditing information from the Audit Trail tab of the sub-object or the master object. Instance security is enforced on the object's Audit Trail tab. This means that the user must have the right to view the sub-object, or it will not be visible on the master object's Audit Trail tab.

Tracking time varying attributes Budgeting and resource planning use time varying attributes. You can configure these attributes to track the history of changes.

Chapter 2: Objects 23

Delete an Object

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 available from the Reports and Jobs link under the Data Administration menu. 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.

Follow these steps: 1. 2. 3. With the object open, click Audit Trail. In the Attribute Audit section, select the attributes you want to audit for changes and move them to the Audited Attributes list. In the Object Audit section, do the following:

Select the attributes you want audited for insertions and move them to the Logged Attributes for Insert Operation list. Highlight the attributes you want audited for deletions and move them to the Logged Attributes for Delete Operation list.

4.

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.

5.

Save your changes.

Delete an Object
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)

24 Studio Developer's Guide

Delete an Object

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. Follow these steps: 1. Open Administration, and from Studio, click Objects. The list page appears. 2. Select the check box next to the object you want to delete, and click Delete. The confirmation page appears listing the dependent items for the object that will also be deleted. 3. 4. Review the list of associated items and verify none have dependencies (portlets or queries). Complete one of the following actions:

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.

Chapter 2: Objects 25

Chapter 3: Attributes
This section contains the following topics: About Attributes (see page 27) Attribute Data Types (see page 28) Display an Object's Attributes (see page 30) How to Create an Attribute (see page 30) Auto-Numbered Attributes (see page 65) Modify Attribute Properties (see page 70) Delete an Object Attribute (see page 71)

About Attributes
Attributes (or fields) are information associated with an object's views (pages). You can display or not display an attribute associated with an object's view. If you create an object and need to create attributes for it, or if you want to add custom attributes to an existing object, the topics in this section show you how. CA Clarity PPM comes with stock attributes that you can use. If you use a stock attribute, you cannot change the attribute's general information (that is, name, ID, description, data type, lookup), but you can change how the attribute appears. When you create custom attributes:

Verify that attributes meet the needs of users. Once you create an attribute, you cannot remove it from the object. You can only deactivate it so that it does not display. Create only the attributes needed. 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.

Important! While CA Clarity PPM supports up to 500 custom attributes per object, CA strongly advises against assigning more than 100 custom attributes to a single stock or custom object. High numbers of custom attributes for an object can cause performance issues and can cause subsequent upgrades to fail. If you need a large number of custom attributes, consider creating and using a subobject rather than assigning a large number of custom attributes to a single object. 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.

Chapter 3: Attributes 27

Attribute Data Types

You can 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.

Attribute Data Types


Several procedures for creating attributes exist. The procedure you use depends on the attribute's data type. CA Clarity PPM supports 11 attribute data types. Each data type has unique information that determines how the attribute is used and displays. The following table provides a description of the available attribute data types. Note: Virtual attributes are not listed in the table because they do not represent actual data in the database. URL (link attributes) do not appear because they are simply links to other pages. Data Type String Large String Description A text field that contains up to 2000 characters. This data type is similar to a string data type, but the number of characters is limited only by your database. This type does not support filtering or sorting. A field that contains numbers that can be used in calculations. 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. A field that contains currency.

Number Formula

Money

28 Studio Developer's Guide

Attribute Data Types

Data Type Boolean

Description 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"

Date Lookup

A field that contains a date. A field that contains predefined choices from which a user can select. 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, which consist of a set of static values entered by an administrator. Static Dependent Lists, which are like static lists where the administrator sets up all the possible values, but the values are arranged hierarchically like an OBS. 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. A stage field for a project, but you need different stages for different types of projects, such as Research and Develop for a new development project but Proposal and Deploy for a proposal. 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.

Sample uses include:

Multi-valued lookup A lookup field in which more than one value can be set. On the object's properties page, a lookup displays as multi-select browse. In a filter, a lookup can be displayed as a drop-down list, a select box, or a single-select or multi-select browse. Attachment A field that contains a document attachment (such as a Word document).

Chapter 3: Attributes 29

Display an Object's Attributes

Data Type Time-varying

Description 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.

Display an Object's Attributes


Follow these steps: 1. Open Administration, and from Studio, click Objects. The objects list page appears. 2. Click the name of the object. The properties page appears. 3. Click Attributes.

How to Create an Attribute


You can create the following attribute types for use in CA Clarity PPM: Attachment (see page 31) Boolean (see page 32) Calculated (see page 35) Date (see page 45) Formula (see page 47) Lookup (see page 49) Money (see page 51) Multi-valued lookup (see page 54) Number (see page 56) Parameterized lookup (see page 58)

30 Studio Developer's Guide

How to Create an Attribute

String (see page 59) Time-varying (see page 61) URL link (see page 63)

Create an Attachment Attribute


An attachment attribute can display links for a maximum of ten documents. Users can use the CA Clarity PPM search utility to find content in document attachments. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

Chapter 3: Attributes 31

How to Create an Attribute

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Attachment. Attachment Style Specifies whether single or multiple documents can be attached. If you select Multiple Documents, enter the number of attachments allowed. A maximum of 10 documents is allowed. Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view and cannot be removed.

6.

Save your changes.

Create a Boolean Attribute


Use a Boolean attribute to indicate one of two exclusive conditions. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears.

32 Studio Developer's Guide

How to Create an Attribute

3.

Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute.

4.

(Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Boolean. Default Specifies whether the attribute default value is true (selected) or false (cleared). Default: Cleared

Chapter 3: Attributes 33

How to Create an Attribute

Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Presence Required Specifies that the attribute always appears in the Edit Properties view of at least one subpage. Default: Cleared Note: If the subpage that contains the field is not visible to the user (due to display conditions or subpage security), the field is not visible to the user. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. (Optional) To display the attribute in color, complete the following steps in the Display Mapping Section. Repeat this step to define any other ranges of numbers that should be color-coded. a. b. c. 7. In the Type field, select Color. In the Color field, select a color. Enter a brief description of what the color represents in the Description field.

(Optional) To display the attribute as an icon, complete the following steps in the Display Mapping Section: Repeat this step to define any other ranges of numbers that should be represented by an icon. a. b. c. In the Type field, select Icon. In the Icon field, select the icon you want to represent the true or false state. Enter a brief statement of what the icon represents in the Description field.

8.

Save your changes.

34 Studio Developer's Guide

How to Create an Attribute

Create a Calculated Attribute


To create a calculated attribute, you must: 1. 2. Create and save the attribute (see page 39). Create an expression to calculate a value for the new attribute (see page 40).

The information in this section explains how to create the attribute and how to create the expression that provides the value for the attribute.

About Calculated Attributes


A calculated attribute is an attribute whose value is based on a calculation using the values of other attributes. For example, you might create an attribute named Remaining Budget whose value is derived from the following formula:
Remaining Cost = Planned Cost - Actual Cost

In this case, an 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)

A calculated attribute can include other calculated attributes. CA Clarity PPM determines 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

Chapter 3: Attributes 35

How to Create an Attribute

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 "2010." An example of the value produced by the concatenation is "ssmith 2010." Date. This data type is used to calculate dates using basic arithmetic or to provide the current date.

Note: You can receive a null result if the value of a parameter (attribute 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 Absolute Value Add Attribute Parameters Absolute(number) Add(number1, number2) Add(number1, <constant>) (ex: Add(A, 10)) Result Data Type Number Number Return Value Absolute value of the number. Adds the value of number1 to the value of number2 and returns the result of the operation. Returns the average of all of the parameters passed in. Concatenated string.

Average

Average(number1, number2 )

Number

Concatenate

Concat(string1, string2 ) Concat(string1, <constant> )

String

36 Studio Developer's Guide

How to Create an Attribute

Function Date Add

Attribute Parameters DateAdd(date attribute, unit, number)

Result Data Type Date

Return Value Date value after the number of units is added.

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 Difference DateDiff(date attribute1, date attribute 2, result unit)

Number

Date attribute1: The date you are subtracting from. This value can only be an attribute name or a sub-expression. 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.

Returns the number value as specified in the result unit, the difference of date attribute1 minus date attribute2.

(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)) Maximum Max(number1, number2 ) Number Number Result from attr1 (number) divided by attr2 (divisor). 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.

Chapter 3: Attributes 37

How to Create an Attribute

Function Multiply

Attribute Parameters Multiply(number1, number2) Multiply(number1, <constant> ) (ex: Multiply (A,50))

Result Data Type Number

Return Value Product from the two parameters. Returns the current date and time. Result after the percentage is taken. (ex: If A=1000, A * 60%= 600, the return value will be 600). Result of the number raised to a power specified. Value after rounding the number to a specific number of digits. Square root of number. Subtracts the value of number1 from the value of number2 and returns the result of the operation. Sum from the list of attributes. A=10, B=20, C=30 Sum(A, B, C) will return 60. Value after removing the decimal or fraction part of the number.

Now Percentage

Now() Percentage(number1, number2) (ex: Percentage (A,B)) Percentage(number1, <constant>) (ex: Percentage (A,50))

Date Number

Power

Power(number, power)

Number

Round

Round(number, <number of digits>)

Number

Square Root Subtract

Sqrt(number) Subtract(number1, number2) Subtract(number1, <constant>) (ex: Subtract(A, 10))

Number Number

Sum

Sum(number1, number2, ...)

Number

Truncate

Trunc(number, <number of digits>)

Number

38 Studio Developer's Guide

How to Create an Attribute

Create the Attribute


The following procedure explains how to create a calculated attribute. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Calculated. Result Data Type Specifies the data type for the result of the calculation. Select Number, String, or Date. Decimal Places Defines the number of decimal places for data to be returned by the attribute. Enter a zero (0) to make the attribute an integer. Presence Required Specifies that the attribute always appears in the Edit Properties view and cannot be removed. 4. Save your changes.

Chapter 3: Attributes 39

How to Create an Attribute

Build the Expression for a Calculated Attribute


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 num3) 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.

Follow these steps: 1. 2. 3. With the calculated attribute's property page displayed, click the Build Calculated Attribute link located in the Calculation field. Select the appropriate function in the Function field. 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. 4. 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. 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.

5. 6.

Click Generate to generate the function's expression in the Expression text box. If you selected Sub-expression as one of the options, do the following: a. b. c. In the Generate Expression for field, select the name of the sub-expression. In the Function field, select the function that defines the purpose of the sub-expression. Select and define the arguments for the sub-expression.

40 Studio Developer's Guide

How to Create an Attribute

d. 7.

Click Generate to include the defined arguments for the sub-expression in the whole expression.

When you are satisfied that all sub-expressions are defined for the whole expression, click Validate to verify that the expression's syntax is correct and make any necessary adjustments. Save your changes.

8.

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 illustration shows the link for the tool that assists you in building an expression for a calculated attribute.

Chapter 3: Attributes 41

How to Create an 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.

42 Studio Developer's Guide

How to Create an Attribute

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.

Chapter 3: Attributes 43

How to Create an Attribute

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.

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.

44 Studio Developer's Guide

How to Create an 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.

Create a Date Attribute


Use this procedure to add a date attribute. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

Chapter 3: Attributes 45

How to Create an Attribute

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Date. Validation From Specifies the earliest date to include in the date attribute. Select Rolling Date or Specific Date and select the specific values you want for your selection. If needed, specify the hour and minute. Validation To Specifies the latest date to include in the date attribute. Select Rolling Date or Specific Date and select the specific values you want for your selection. If needed, specify the hour and minute. Default Date Specifies the default date for the date attribute. Select Rolling Date or Specific Date and select the specific values you want for your selection. If needed, specify the hour and minute. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view of at least one subpage. Default: Cleared Note: If the subpage that contains the field is not visible to the user (due to display conditions or subpage security), the field is not visible to the user.

46 Studio Developer's Guide

How to Create an Attribute

Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. Save your changes.

Create a Formula Attribute


A formula attribute computes the weighted average of two or more attributes in the same object. Use the following procedure to add a formula attribute to an object. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

Chapter 3: Attributes 47

How to Create an Attribute

5.

Complete the following fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Formula. Decimal Places Defines the number of decimal places for data to be returned by the attribute. Enter a zero (0) to make the attribute an integer.

6.

(Optional) To display the field in color or as an icon, complete the following steps in the Display Mapping Section. a. b. c. d. e. In the Type field, select Color or Icon. Select the appropriate color or icon. Enter a brief description of what the color or icon represents in the Description field. Enter a number for the beginning of the range represented by the color or icon in the From field. Enter a number for the end of the range represented by the color or icon in the To field.

Repeat this step to define any other ranges of numbers that should be color-coded or represented by an icon. 7. 8. 9. Click Save. In the Formula field, click [Build Weighted Average Formula] to add a weighted average formula. Complete the following fields: Attribute Specifies the attribute you want to give consideration in the weighted average calculation.

48 Studio Developer's Guide

How to Create an Attribute

Weighting Specifies the value to be multiplied by the value of the attribute you selected to compute the weighted average for a row. Weighted values from all rows are added and their average is computed. The entries you make in the Weighting column cause the attribute to be more important that 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. Example: weighted ave=[(Risk * 4) + (Customer Satisfaction * 2) + (Alignment * 1)] /3 10. To weight additional attributes, click New Row. 11. To see if the weighted average formula works as expected, click Recalculate. The page displays the formula results in the Test section. 12. Save your changes.

Create a Lookup Attribute


Lookup attributes display a drop-down or browse list from which users can select items. Lookup attributes are frequently used in filters. Use the following procedure to add a lookup attribute based upon a single selection item. Note: The display type for static lookups is automatically set to the Drop-down option when the lookup has 20 or fewer selection values. If the Browse option is selected, it is overridden in this case. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute.

Chapter 3: Attributes 49

How to Create an Attribute

4.

(Optional if you have created partitions) To associate this attribute with a partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Lookup. Lookup Specifies the lookup that appears in the field with a list of items for the user to select from. Default Specifies the value you want to appear as the attribute's default value. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Value Required Specifies whether a value is required for the attribute. Default: Cleared.

50 Studio Developer's Guide

How to Create an Attribute

Presence Required Specifies that the attribute always appears in the Edit Properties view of at least one subpage. Default: Cleared Note: If the subpage that contains the field is not visible to the user (due to display conditions or subpage security), the field is not visible to the user. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. (Optional) If you selected a static lookup, you can set up a display mapping that lets you associate a value or number range with a description and a color or icon. These colors or icons can be used in many places throughout CA Clarity PPM, such as in stoplight icons, filters, progress bars, Gantt charts, and chart backgrounds. To set up a display mapping: a. b. c. d. In the Type field, select Color or Icon. Select the appropriate color or icon. Enter a brief description of what the color or icon represents in the Description field. Select the lookup value to be represented by the color or icon in the Value field. You can define a color or icon for up to ten values plus an optional Default Bucket for all values that do not have an assigned color or icon. Repeat this step to define any other ranges of numbers that should be color-coded or represented by an icon. 7. Save your changes.

Create a Money Attribute


Use this procedure to add a money attribute. CA Clarity PPM associates money attributes with a currency code so that you can convert the value to another currency if necessary. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears.

Chapter 3: Attributes 51

How to Create an Attribute

3.

Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute.

4.

(Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Money. Currency Code Location Specifies that the attribute has its own currency code field. Select the default currency code in the Default Currency Code field. Validation Range Defines the range of values allowed for the attribute. Enter the lowest value in the first box and the highest value in the second box.

52 Studio Developer's Guide

How to Create an Attribute

Default Value Specifies the value you want to appear as the attribute's default value. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view and cannot be removed. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. (Optional) To display the field in color or as an icon, complete the following steps in the Display Mapping Section: a. b. c. d. e. In the Type field, select Color or Icon. Select the appropriate color or icon. Enter a brief description of what the color or icon represents in the Description field. Enter a number for the beginning of the range represented by the color or icon in the From field. Enter a number for the end of the range represented by the color or icon in the To field.

Repeat this step to define any other ranges of numbers that should be color-coded or represented by an icon. 7. Save your changes.

Chapter 3: Attributes 53

How to Create an Attribute

Create a Multi-valued Lookup Attribute


Multi-valued lookup attributes display a drop-down or browse list from which users can select 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 attributes:

Cannot have default values. Cannot be required or read-only. Cannot have display mappings.

Note: The lookup you add must already exist before you can add it to an object. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute.

54 Studio Developer's Guide

How to Create an Attribute

Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren.

Partition only. Associates the attribute only with the selected partition. 5. Complete the following fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Multi Valued Lookup. Lookup Specifies the lookup that appears in the field with a list of items for the user to select from. Default Specifies the value you want to appear as the attribute's default value. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared

Chapter 3: Attributes 55

How to Create an Attribute

Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view and cannot be removed. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. Save your changes.

Create a Number Attribute


Use this procedure to add a number data type attribute to an object. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute.

56 Studio Developer's Guide

How to Create an Attribute

Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Validation Range Defines the range of values allowed for the attribute. Enter the lowest value in the first box and the highest value in the second box. Decimal Places Defines the number of decimal places for data to be returned by the attribute. Enter a zero (0) to make the attribute an integer. 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. Default Value Specifies the value you want to appear as the attribute's default value. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Value Required Specifies whether a value is required for the attribute. Default: Cleared.

Chapter 3: Attributes 57

How to Create an Attribute

Presence Required Specifies that the attribute always appears in the Edit Properties view of at least one subpage. Default: Cleared Note: If the subpage that contains the field is not visible to the user (due to display conditions or subpage security), the field is not visible to the user. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. (Optional) To display the field in color or as an icon, complete the following steps in the Display Mapping Section: a. b. c. d. e. In the Type field, select Color or Icon. Select the appropriate color or icon. Enter a brief description of what the color or icon represents in the Description field. Enter a number for the beginning of the range represented by the color or icon in the From field. Enter a number for the end of the range represented by the color or icon in the To field.

Repeat this step to define any other ranges of numbers that should be color-coded or represented by an icon. 7. Save your changes.

Create a Parameterized Lookup Attribute


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. See the Administration Guide for more information. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears.

58 Studio Developer's Guide

How to Create an Attribute

3.

Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Multi Valued Lookup. Lookup Specifies the lookup associated with the NSQL query you want to map.

4.

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.

5. 6.

For each lookup parameter listed in the section, select an object attribute ID. Save your changes.

Create a String Attribute


Use this procedure to add a string (text) attribute. You can also use this procedure to create large string fields whose sizes 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 attributes do not display in List Filter Views. You cannot sort large string attributes.

Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears.

Chapter 3: Attributes 59

How to Create an Attribute

3.

Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute.

4.

(Optional if you have created partitions) To associate this attribute with a partition, complete the following fields: Partition Specifies the partition to be associated with the attribute. Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Values for a string attribute:

String. Creates a field with a maximum of 2,000 characters. Large String. Creates a field with an unlimited number of characters.

Default Value Specifies the value you want to appear as the attribute's default value. Maximum Size Defines the maximum size of the attribute up to 2,000 characters. Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared

60 Studio Developer's Guide

How to Create an Attribute

Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view of at least one subpage. Default: Cleared Note: If the subpage that contains the field is not visible to the user (due to display conditions or subpage security), the field is not visible to the user. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 6. Save your changes.

Create a Time-Varying Attribute


Use only alphanumeric and underscore (_) characters when entering a unique ID for a time-varying attribute. Also avoid SQL reserved words such as SELECT or STRING. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. 4. (Optional if you have created partitions) To associate this attribute with a particular partition, complete the following fields: Partition Specifies the partition to be associated with the attribute.

Chapter 3: Attributes 61

How to Create an Attribute

Partition Association Mode Specifies how the attribute is to be associated with the partition. Values:

Partition, ancestors, and descendants. Associates the attribute with the selected partition and its parent and child partitions. Partition and ancestors. Associates the attribute only with the selected partition and its parents and grandparents. Partition and descendants. Associates the attribute only with the selected partition and its children and grandchildren. Partition only. Associates the attribute only with the selected partition.

5.

Complete the remaining fields: Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select Time-varying. Time-varying Data Units Specifies the unit time-scaled value represents such as a number value, a monetary value, or a percentage. A fiscal time-scaled value created with a time-varying data unit set to Money has its currency code set to the system currency. When you create an instance of this fiscal time-scaled value, the currency code is set to the home currency of the associated financial entity. Time-varying Unit Conversion Specifies whether the time-varying data units are per hour or per second. Time-varying Date Constraints Defines time constraints to limit the range of data received for the attribute and improve processing performance. You can enter dates in CA Clarity PPM that override these dates. If you select nothing, the default values are the widest available range.

62 Studio Developer's Guide

How to Create an Attribute

6.

If you selected Money as the time-varying data unit, to provide a currency code for the attribute, do one of the following:

Select the Attribute has its Own Currency Code Field check box. Then select the default currency code. If the currency code is held in an existing attribute of the same object, select the Reference Another Attribute of this Object check box. Then at Which Field, select the attribute that contains the currency code.

7.

Save your changes.

Create a URL Link Attribute


A link attribute provides a link to a URL (web page) outside of CA Clarity PPM. Follow these steps: 1. With the object open, click Attributes. The attributes list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Attribute Name Defines the name of the attribute. The name you enter appears in the instance of the object when the attribute is configured properly for layout. Attribute ID Defines a unique alphanumeric identifier for the attribute. Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Select URL. Default Value Specifies the URL you want to appear as the attribute's default value. Maximum Size Defines the maximum number of characters that can be used for the attribute. The maximum size for a string field is 1,000 characters.

Chapter 3: Attributes 63

How to Create an Attribute

Populate Null Values with the Default Specifies whether to automatically populate existing objects with the default value. Default: Cleared Value Required Specifies whether a value is required for the attribute. Default: Cleared. Presence Required Specifies that the attribute always appears in the Edit Properties view and cannot be removed. Read-Only Specifies whether a user can change the value in the field. A read-only attribute must have a default value. Default: Cleared 4. Save your changes.

Display Mappings for Attributes


You can create display mappings for the following attribute types: number, money, static lookup, and Boolean. You can use either an icon or a color to represent a value range for the attribute. Tips on Display Mapping

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. When you define a range, the range specification is as follows: Lower range boundary value <= Attribute value < Upper range boundary value That means the color or icon you select displays if the attribute value is greater than or equal to the lowest value in the range and less than the highest value in the range. If the attribute value is equal to the upper range boundary value, the icon or color does not display.

When you define ranges that are adjacent to one another, verify that 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.

64 Studio Developer's Guide

Auto-Numbered Attributes

Once you select a display-mapping type and 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 select a new display mapping type (Icon or Color) in the Type drop-down list.

Auto-Numbered 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 helps ensure 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.

Auto-Numbering and 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 named 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.

Chapter 3: Attributes 65

Auto-Numbered Attributes

Create an Auto-Numbering Scheme


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 Alphanumeric 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, verify that generated numbers for different object types are not the same. CA Clarity PPM does not verify 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 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. Follow these steps: 1. With the object for which you want to create an auto-numbering scheme open, click Attributes. The attributes list page appears. 2. Click the name of the string data type attribute for which you want to create an auto-numbering scheme. The properties page for the attribute appears. 3. 4. Click Auto-numbering. In the Scheme section, click [New]. The scheme create page appears.

66 Studio Developer's Guide

Auto-Numbered Attributes

5.

Complete the information in the following field. Scheme Name Defines the name of the auto-numbering scheme. Enter up to 80 characters for the name. For example, PRJ or INV.

6.

Click Save. The scheme is created and a section appears for adding segments. The numeric counter is a default segment.

7.

Click New to create segments for the autonumbering identifier. The segment properties page appears. 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.

8.

In the Type of Segment field, select the segment type you want to create. The following values are available for selection:

Text. Creates a segment that contains only letters. Numeric Counter. Creates a segment that contains only numbers. Alphanumeric 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.

The selection of the segment type causes additional fields to appear. 9. Complete the following fields as they apply to the segment type you selected. The fields listed include all fields that occur for all types of segment creation. The fields you see depend on the segment type you select. The list is alphabetical. Auto-extended Specifies the counted length is to be extended when the limit of the counter length is reached. Counter Length Specifies the number of digits to use for the segment. The maximum is 22 digits. Counter Starting Number Defines the starting number for a numeric or alphanumeric segment. Length Displays the length of the instance creation date format (YYYYMMDD).

Chapter 3: Attributes 67

Auto-Numbered Attributes

Referenced Attribute Specifies the attribute to be referenced in the parent object. The value of the referenced attribute is 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. Referenced Object Specifies the parent object from which the referenced attribute will be selected. By selecting a parent object, you set the attributes that appear for selection in the Referenced Attribute lookup. Segment Max Length Specifies the length you want the segment to be. The maximum length is 30 characters. The replacement value (the referenced attribute) is truncated if it is longer than the length selected. Value Defines the text value to be included in the segment. For example, PRJ. 10. Click Save and Continue to create the segment. 11. Create as many segments as necessary. 12. (Optional) Click Reorder to place the segments in the appropriate order. You can view the results of reordering the segments in the Next Number field. 13. 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. 14. To activate this scheme, select the Auto-numbered check box in the General section. Note: When auto-numbering is activated, users cannot enter object IDs because CA Clarity PPM creates them. 15. Save your changes.

68 Studio Developer's Guide

Auto-Numbered Attributes

Modify an Auto-Numbering Scheme


To modify auto-numbering schemes for object attributes, you must have the Object Administration or the Attribute Create access right. This procedure explains how to modify an existing auto-numbering scheme for an object attribute. Follow these steps: 1. With the object open, click Attributes. The attribute list page appears. 2. Click the attribute whose auto-numbering scheme you want to modify. The properties page appears. 3. 4. Click Auto-numbering. 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. 5. 6. In the Schemes section, click Edit. To reorder the segments in the scheme, do the following: a. b. c. Click Reorder. Highlight segments individually and use the arrows to move them to the correct position. Click Save and Continue 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. 7. 8. Make changes to the segments as needed by clicking the segment name in the Type of Segment column. Save your changes.

Deactivate an Auto-Numbering Scheme


This procedure explains how to deactivate an auto-numbering scheme for an object attribute. Follow these steps: 1. With the object open, click Attributes. The attribute list page appears.

Chapter 3: Attributes 69

Modify Attribute Properties

2.

Click the attribute whose auto-numbering scheme you want to deactivate. The properties page appears.

3. 4. 5.

Click Auto-numbering. Clear the Auto-numbered check box. Save your changes.

Modify Attribute Properties


You can change a user-defined attribute's properties; for stock CA Clarity PPM objects and attributes, you can only change the display mappings. Note: To change attribute properties, you will need the Administration - Studio access right. Follow these steps: 1. With the object open, click Attributes. The attribute list page appears. 2. Click the name of the attribute that you want to change from the list. The properties page appears. 3. Change any of the following items: Comments Applies only to new records. You can only increase the value of this attribute. The default value to display. A description of the attribute. These fields retain existing calculated values and change only when you edit the Formula field and save it. Links that when clicked, display other CA Clarity PPM pages. You cannot change the Lookup or change the lookup type to Multi-valued. You can, however, change the default value used when the Lookup is updated. You can only increase the value of this attribute. The name of the attribute.

Properties You Can Change Date range validation Decimal Places Default Value Description Formula fields

Links Lookup default value

Maximum Length Name

70 Studio Developer's Guide

Delete an Object Attribute

Properties You Can Change Numeric Range Validation Presence Required Risk Show as Percent Unique Value Required status 4. Click Save and Continue.

Comments Applies only to new records. Defines whether the attribute must appear. Only the formula can be changed. If you change this property, only new values are shown as a percent. You can change an attribute from unique to non-unique, but not vice versa. You can change an attribute from required to non-required, but not vice versa.

Your changes are saved and the attribute list page appears. 5. To see your changes, click the attribute's name again.

Delete an Object Attribute


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

Chapter 3: Attributes 71

Delete an Object Attribute

Follow these steps: 1. Click the Administration menu, and select Objects from the Studio menu. The objects page appears. 2. Click the name of the object you want to modify. The object properties page appears. 3. Click Attributes. The object attributes page appears. 4. In the list of attributes, select the check box next to the attribute you want to delete and click Delete. The confirm object attribute delete page appears. 5. 6. Review the list of associated items and verify none have dependencies (queries or other attributes that use the attribute to be deleted). 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.

72 Studio Developer's Guide

Chapter 4: Partitions
This section contains the following topics: About Partitioning (see page 73) Basic Partition Guidelines (see page 77) Overview of the Partition Model Process (see page 78) Create a Partition Model (see page 78) Add a Partition to a Partition Model (see page 79) Add Multiple Partitions to a Partition Model (Quick Create) (see page 79) Add Members (Resources) to a Partition (see page 80) Apply a Partition Model to an Object (see page 81)

About Partitioning
Partitioning lets you determine what a user sees. Not all users need to see every field or page that is available. By defining what can be seen in a partition and associating the partition with a user or group of users, you can simplify the user's experience in CA Clarity PPM. 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 partitions in a partition model may be geographical while the second-level and subsequent levels may be divisional partitions.

Chapter 4: Partitions 73

About Partitioning

See the following example where United States and European partitions have been created to display information that is relevant for each countrys 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.
System Partition

US Operations

European Operations

US Marketing

European Marketing

You can partition the following:


Object user-defined attributes (fields) Object views (Properties, List Column, and List Filter) Object links Lookup values User interface (UI) themes 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 make it available for any ancestor or descendant partition or both, or you can make it available to the partition for which it was created. This association is named 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.

74 Studio Developer's Guide

About Partitioning

Partition Models
Partition models organize partitions into a hierarchy. You can assign user-defined attributes at any model hierarchy level and make them available (or required) at lower-level partitions in the model. Making user-defined attributes available through a partition model is one way to drive governance from the highest level in an organization to lower levels. Allowing lower-level objects to automatically inherit partitioned items also makes partition administration easier to maintain. A partition model and an OBS share some similarities, they are different in the following ways:

OBS is often used to control security and drive reporting, while a partition model is used to control how objects are managed in CA Clarity PPM. A partition model supports resource memberships based on groups or OBS units. A partition model is considered a way to group resources.

Consider the following when setting up a partition:


You can set up multiple models, but 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 are asked to select the partitions to use. For example, you might be a member of the United States and European partitions, but you must select which one to use when you create a project. CA Clarity PPM users can be members of only one partition and thus do not need to select a partition. A user who is not a member of any partition sees the default System partition views.

Partitions and Views


Object views determine how information displays. CA Clarity PPM has three types of views: Properties Lets a user enter information for an object instance. List Column Displays the instances of an object in rows and columns. List Filter Lets a user search for information.

Chapter 4: Partitions 75

About Partitioning

If a partition has no view associated with it, the partition inherits the view from the nearest ancestor partition. If no ancestor partitions have views defined, the partition uses the System partition's views. Best Practice: Define partitioned views at the top of the partition model first. 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 the following illustration.
World

United States

Europe

Partitioned Data Providers and Portlets


CA Clarity PPM portlets and processes retrieve 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, create partition-specific attributes for the object and build a portlet for the object in the partition.

Partitions and Lookups


You can partition static lookup values. Users of a partitioned lookup see different values in the lookup, depending on the partition to which an object instance belongs. 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 units 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.

76 Studio Developer's Guide

Basic Partition Guidelines

Partitions and Access Rights


Access rights determine what a user can see and the functions the user can perform. The CA Clarity PPM administrator can grant access rights to users (resources), groups, OBS units, or globally to all users. Partitioning affects what objects are exposed to users. Therefore, partitioning and access rights work together. If a user has access rights to an instance of a partitioned object, that user can see partitioned views of that instance, even if the user is not a member of the partition to which the object instance belongs. Partitioning affects your ability to do the following:

Create partitioned attributes Change the layout and appearance of attributes for partitioned objects Assign an object instance to a partition Select a default partition Switch partition views See and personalize partitioned List Column and List Filter views Create or see partitioned values for lookups

Basic Partition Guidelines


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 hierarchy level. You cannot delete partition models. You must 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. To work with partition models you need the following access rights:

Administration - Studio Administration - Partition Models

Chapter 4: Partitions 77

Overview of the Partition Model Process

Overview of the Partition Model Process


The following steps provide an overview of the partitioning process. 1. Plan the 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 must deactivate unwanted models. Plan your partition scheme accordingly. 2. 3. 4. 5. 6. 7. 8. 9. Set up a partition model. Select an existing object to use or create a new object. Add attributes to the object, assign them to a partition, and select a partition association mode. Configure the views for each partition. (Optional) Add partition-specific object links. (Optional) Create partitioned lookup values. (Optional) Create portlets based on partitioned objects. (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).

Create a Partition Model


Follow these steps: 1. Open Administration, and from Studio, click Partition Models. The partitions list page appears. 2. 3. Click New. Complete the following fields: Partition Model Name Defines the name of the partition model. ID Defines a unique alphanumeric identifier for the partition model. Avoid SQL reserved words such as SELECT or STRING.

78 Studio Developer's Guide

Add a Partition to a Partition Model

Description Defines the purpose of the item being created and provides any relevant information. 4. Save your changes.

Add a Partition to a Partition Model


Before you perform this procedure, verify you have already created a partition model. Follow these steps: 1. 2. 3. With the partition model open, click Partitions. Click New. Complete the following fields: Partition Name Defines the name of the partition. Partition ID Defines a unique alphanumeric identifier for a partition. Description Defines the purpose of the item being created and provides any relevant information. Parent Partition Specifies the parent partition for the partition. 4. Save your changes.

Note: You can authorize resources (users) or groups to be members of a partition.

Add Multiple Partitions to a Partition Model (Quick Create)


Use Quick Create to create up to five partitions at once. Before you perform this procedure, verify you have already created a partition model. Follow these steps: 1. 2. With the partition model open, click Partitions. Click Quick Create.

Chapter 4: Partitions 79

Add Members (Resources) to a Partition

3.

Complete the following fields for each partition you want to add: Partition Name Defines the name of the partition. Partition ID Defines a unique alphanumeric identifier for a partition. Description Defines the purpose of the item being created and provides any relevant information. Parent Partition Specifies the parent partition for the partition. Note: You will not be able to select a parent partition if you havent saved the parent partition yet.

4.

Save your changes.

Note: You can authorize resources (users) or groups to be members of these partitions.

Add Members (Resources) to a Partition


Before you perform this procedure, verify you have created a partition model. Follow these steps: 1. 2. 3. With the partition model open, click Partitions. If you do not see the partition you want, click the + icon at the left of an ancestor partition to see child partitions. In the row that contains the partition you want to use, click the Properties icon. The properties page appears. 4. To add an individual user (resource) as a member of the partition: a. b. c. Open the Partition Members menu and click Resources. Click Add. Select the check box next to each resource name you want to make a partition member, and click Add. If you have more members to add than appear on a single selection page, use Add and Select More. 5. When all members have been added, click Return.

80 Studio Developer's Guide

Apply a Partition Model to an Object

Apply a Partition Model to an Object


If you want to apply a partition model to a user-defined object, you must first create that object. To perform the procedures in this section, you must have the Administration - Studio access right. See the Administration Guide for more information. You do not have to be a member of a partition to perform this task. Follow these steps: 1. Open Administration, and from Studio, click Objects. The objects list page appears. 2. Click the name of the object to which you want to apply a partition model. The properties page appears. 3. 4. Complete the Partition Model field by selecting a partition. Save your changes.

Chapter 4: Partitions 81

Chapter 5: Views
This section contains the following topics: About Views (see page 84) Configure the Properties View (see page 85) Configure the List Column View (see page 96) Configure the List Filter View (see page 116) Edit an Attribute's Label for a Specific View (see page 119) Publish Changes to List and Filter Views (see page 120) Restore Defaults for Object Views (see page 122) Restore Defaults for Selected Views (see page 123)

Chapter 5: Views 83

About Views

About Views
An object has three views that you can configure to determine how information displays on a page in CA Clarity PPM. Properties View This view displays and allows users to enter information about an object. The properties view controls what is seen when a user creates a new object instance or edits an existing instance.

List Column View This view displays information about object instances in rows and columns. 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.

84 Studio Developer's Guide

Configure the Properties View

The following illustration shows the list column view and the list filter view for the project object.

Configure the Properties View


The following sections describe how to configure the properties view that displays in the application when an end user creates a new instance of an object. To configure the properties view you can add:

Attributes (see page 86) Sections (see page 87) Subpages (see page 88)

Chapter 5: Views 85

Configure the Properties View

Add an Attribute to an Object's Properties View


You can define which attributes are visible on properties pages. You do this by adding and removing attributes on an object's properties page view. You can also define the order and location in which attributes display on the page. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. In the Category column, locate the properties view that you want to work with and click one of the following links from the Setup column in that row:

[Layout:Create]. This option lets you add attributes to the properties page a user uses to create an instance initially for the object. [Layout:Edit]. This option lets you add attributes to the properties page a user uses to make changes to the created instance of the object.

3.

In the property layout, select the section to which you want to add the attribute, and click the Properties and Layout icon next to the item. List boxes of available and selected attributes appear.

4.

In the Available list, select the attributes you want to add and use the arrow keys to move the attributes into the correct Selected list box. Save your changes.

5.

86 Studio Developer's Guide

Configure the Properties View

Add a Section to the Properties View


Sections let you group the attributes that appear on a properties page in meaningful ways. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. In the Category column, locate the properties view that you want to work with and click one of the following links from the Setup column in that row:

[Layout:Create]. This option lets you add attributes to the properties page a user uses to create an instance initially for the object. [Layout:Edit]. This option lets you add attributes to the properties page a user uses to make changes to the created instance of the object.

The properties layout page appears. 3. 4. Click Create Sections. Complete the following fields: Parent Displays the name of the parent page for the sections being created. Section Names Defines the names for sections that appear on the page for a view. Enter up to five section names at a time. 5. Save your changes.

Chapter 5: Views 87

Configure the Properties View

Add a Subpage to 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 tab menu.

To add a subpage to the properties view, you must: 1. 2. Create the subpage. Define the properties for the subpage, including display conditions.

The information in this section explains how to create a subpage and how to define the properties that determine how the subpage is used.

Create the Subpage


Follow these steps: 1. With the object open, click Views. The list of views appears.

88 Studio Developer's Guide

Configure the Properties View

2.

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.

3.

Click Create Subpages. The create page appears.

4.

Complete the following fields: Subpage Name Defines the name that appears as a link in a menu for the subpage to be selected. Subpage ID Defines a unique alphanumeric identifier for the subpage.

5.

Click Save and Return. The property layout page appears with the new subpage listed.

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. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. 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. 3. 4. Click the Properties and Layout icon of the subpage. In the Layout section, use the arrow keys to place the subpage sections in the order you want them to appear on the subpage.

Chapter 5: Views 89

Configure the Properties View

5.

In the Properties section, complete the following fields: Subpage Name Defines the name that appears as a link in a menu for the subpage to be selected. Linkable Specifies 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 Specifies whether a 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 to view and edit subpage information. Default: Cleared

6.

(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.

7.

Click Save and Return.

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 == ! != 90 Studio Developer's Guide Function equals not not equals Example asset.created_by == "marybell" !(asset.created_by == "marybell") asset.created_by != "marybell"

Configure the Properties View

Operand > >= < <= || && like notLike

Function greater than greater than or equal less than

Example asset.planned_cst_total > 25000 asset.planned_cst_total >= 25000 asset.planned_ben_total < 100000

less than or equal asset.total_ownership_cost <= asset.forecast_cst_total or and like not like asset.total_ownership_cost > 5000 || asset.planned_ben_total > 5000 asset.is_active == 1 && asset.planned_cst_total > 50000 like( asset.created_by, "marybell" ) 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 help 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").

Chapter 5: Views 91

Configure the Properties View

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 select 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 Check resource's global access rights Check resource's group Check resource's OBS unit Check resource's partition Syntax checkGlobalRight(<global right code>,<value to check>,<operator>) checkGroup( <group code>, <value to check>, <operator> ) checkOBSUnit( <OBS path>, <OBS Internal ID>, <OBS level>, <value to check>, <operator> ) 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 Numeric String Syntax lookup( <lookup code>, <internal lookup value id> ) lookup( "<lookup code>", "<lookup value code>" )

92 Studio Developer's Guide

Configure the Properties View

Add a Section to a Subpage


Follow these steps: 1. With the object open, click Views. The list of views appears. 2. 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. 3. 4. Click the name of the subpage you want to add a section to, and click Create Sections. Complete the following fields: Parent Displays the name of the parent page for the sections being created. Section Names Defines the names for sections that appear on the page for a view. Enter up to five section names at a time. 5. Click Save and Continue. The property layout page appears. 6. Do the following:

To add attributes to the section, click the Section icon that appears in the Section's row. In the Available list, click the name of the attribute you want to add to the page. Use the arrow keys to move the attribute to the appropriate column, then use the up and down arrow keys to place the attribute in the proper order in the list.

7.

Save your changes.

Chapter 5: Views 93

Configure the Properties View

Modify a Properties View Attribute


Follow these steps: 1. 2. Open the properties view. In the Properties category row, click Fields. The list of attributes for the view appears. 3. 4. Click the Properties icon next to the attribute you want to change. Change any of the following options (the options that appear depend on the attribute's data and display type): Attribute Read-only. Displays the name of the attribute. Property Label Defines the label for the attribute. 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 attributes and specifies how the date is to display. Values: Date, Date and Time Default: Date Hint Enter a message that helps the user. The maximum length for a hint is 512 characters. Hint Position Indicates where the hint appears in context with the attribute. Values: Above or Below Default: Below

94 Studio Developer's Guide

Configure the Properties View

Tooltip Enter a short message to display when the user moves a cursor over the attribute. Width Enter the number of characters allowed for the textbox. Attribute Default Enter the default value for the attribute. Override Default Enter a new default value for new records created through the view. Attribute Default Date Enter the default date for the attribute. Override Default Date Specifies the default date. Values:

Rolling Date. Specific Date.

Value Required Select this check box to require that users enter a value. Enter Once Select this check box to prevent users from changing the attribute's value after it has been entered. Hidden Select this check box to prevent the attribute from displaying on user views. Use hidden attributes 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.

Chapter 5: Views 95

Configure the List Column View

Height Enter the number of lines allowed for a text box. 5. Save your changes.

Configure the List Column View


The following sections describe how to configure the list column view that displays initially when an end user clicks a link in the Home menu. The list column view lists all of the instances of an object that have been created. To configure the list properties view you can:

Set up columns in the list view (see page 96) Sort the list using attributes (see page 98) Add images (see page 99) Add aggregation rows (see page 111)

Set Up Columns for the List View


Use the following procedure to add attributes to List Column views. You can also add virtual attributes that don't represent data in the database, but are derived from other data attributes. You can use these virtual attributes to display aggregations, comparisons, and variances. You can create many aggregation rows for a list. If you are adding a lookup attribute to the list column view, note the following:

Static dependent list lookups configured as multi-value lookups are not supported in list views. Autosuggest does not work with static dependent lists.

Follow these steps: 1. With the object open, click Views. The list of views appears.

96 Studio Developer's Guide

Configure the List Column View

2.

Next to the List Column view, click Layout. The layout page appears.

3. 4.

In the Available Columns list, select the attribute or attributes you want to add and move the attributes to the Selected Columns list. Click Save and Continue. The list of views appears.

5.

Next to List Column view, click Options, then set any of the following options: Secondary Value Display Indicates the way that secondary values display in a grid cell. Values:

Mouseover only. Specifies no secondary value display. Mouseover and redline. Specifies the display of a secondary value when a user places the pointer over a cell in a grid. This helps to compare values. For example, if you have a column named Cost and another column named Baseline Cost, you might want to display both values in one cell. To show both, you can select 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. Show Null Secondary Values. Specifies that the secondary value displays even when there is no number value to show.

Filter Indicates how the results appear initially. Values:


Automatically show results. Indicates you want immediate results. Do not show results until I filter. Indicates you want results provides after you filter.

Default: Automatically show results

Chapter 5: Views 97

Configure the List Column View

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. 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 Specifies a user can make changes to the appearance of a page or a portlet. Select the check box to allow configuration. Allow Label Configuration Specifies a user can make changes to a page or portlet label. This option works with the Allow Configuration option. If you select the Allow Configuration option and you clear the Allow Label Configuration option, labels become unavailable for configuration while other items can still be configured. Attribute Value Protection Indicates whether an attribute is protected or displayed. You can protect attributes using display conditions and secured subpages or secured subpages only, or you can display all attribute values. 6. Save your changes.

Use Attributes to Sort a List Column View


You can add up to four attributes that sort a List Column view. The attributes can be user-defined, stock, or both. Follow these steps: 1. With the object open, click Views. The list of views appears. 98 Studio Developer's Guide

Configure the List Column View

2.

Next to List Column view click Layout. The list column layout page appears.

3. 4. 5. 6.

Indicate the primary sort column in the Column Sorting section's First Field row, and select the attribute. To indicate the direction of the sort, select Ascending or Descending. To indicate additional sort columns, select attributes for the remaining fields in the Column Sorting section. Save your changes.

Images in the List Column View


This section describes the images you can use in the list column view. You can:

Change an object's display mapping You can have data ranges represented by different colors or icons. Each color defines an attribute in the definition page and indicates the color to display for each range of data. For example, you can configure an attribute so that the numbers 1-5 display in red, while the numbers 6-10 display in green.

Use icons to represent ranges of values Studio provides a standard set of icons that you can use to display for your own purposes. The icons include items such as colored checkmarks, a discussion bubble, an attachment icon, a lock icon and many others.

Display data as bar or column charts If you are using number, formula, or money attributes in a List Column view, you can display the data as bar or column charts. Column charts are like bar charts, except that they are oriented up-and-down instead of left-to-right. You can add a stacked bar to bar charts 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.

Chapter 5: Views 99

Configure the List Column View

Note: Any changes you make to the attribute's appearance affect only that particular view. You can set different appearance options for the same attribute in different views.

Display an Attribute as a Bar or Column Chart


Follow these steps: 1. With the object open, click Views. The list of views appears. 2. Locate the List Column view in the Category column, and on the same row click [Fields]. A list of fields for the list column view appears. 3. 4. Click the Properties icon in the row that contains the attribute you want to change. Change any of the following options (the options that appear depend on the attribute's data and display type): Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates whether the text in the column label can wrap within the column. Select the check box to allow wrapping. Display Type Specifies the type of chart. 5. 6. Click Save. Complete the following fields: Secondary Value Select the attribute whose value displays when the user moves a cursor over the primary bar. 100 Studio Developer's Guide

Configure the List Column View

Alignment Select:

Left, to align the attribute with the left side of the column Center, to center align the attribute in the column Right, to align the attribute with the right side of the column.

Thickness Select from the following options:


Autofit to fit the chart to the column width. Narrow to display a narrow chart. Medium to display a medium-width chart. Wide to display a wide chart.

Maximum Length Enter the length of the bar (in pixels). Length Scaling Specifies the length scaling. Values:

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.

Chapter 5: Views 101

Configure the List Column View

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, 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 charts you can quickly see how close each task is to being complete relative to the others.

Color Specifies the color for the primary bar. Threshold Line Attribute Select an attribute in the same object that holds the threshold value. Note: In bar charts, a vertical line marks the threshold value. 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 Specifies the page to display when the user clicks the primary bar. If you want the page to open in a pop-up window, select the Open as Pop-up check box.

102 Studio Developer's Guide

Configure the List Column View

7.

(Optional) To create a stacked bar, complete the following fields: Stacked Attribute Specifies the attribute to be represented as a stacked bar. Color Specifies the color for the stacked bar. Secondary Value Specifies the value to display when the user moves a cursor over the secondary bar. Link Specifies the page to display when the user clicks the secondary bar.

8.

Save your changes.

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:

Select where the image is placed, either before or after the content. Map the image to any attribute available from the data provider, not only 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.

Chapter 5: Views 103

Configure the List Column View

Note: You can only map a display image for those attributes whose data type is Number. Follow these steps: 1. With the object open, click Attributes. The attributes list appears. 2. Click the attribute for which you want to display an image. The properties page appears. 3. Complete the following steps in the Display Mapping Section: a. b. c. d. e. In the Type field, select Color or Icon. Select the appropriate color or icon. Enter a brief description of what the color or icon represents in the Description field. Enter a number for the beginning of the range represented by the color or icon in the From field. Enter a number for the end of the range represented by the color or icon in the To field.

Repeat this step to define any other ranges of numbers that should be color-coded or represented by an icon. 4. Save your changes.

Display a Gantt Chart in a List Column View


A Gantt chart shows duration and progress over time. New virtual attributes are displayed in the far right column of the list. You can move the virtual attribute to a different position in the List Column layout. Users can also personalize the list page to display a Gantt chart in a list column view. When you add a Gantt chart to a view, the Gantt chart only displays information. See the Personalizing CA Clarity User Guide for more information. Follow these steps:

104 Studio Developer's Guide

Configure the List Column View

1.

With the object open, click Views. The views page appears.

2.

Locate the List Column view in the Category column, and click Fields in the same row. The list column fields page appears.

3.

Click New. The create page appears.

4.

Select Gantt, and click Save and Continue. The settings page appears.

5.

Complete the following fields in the General section: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates if you want text in the column label to wrap. Default: Cleared

6.

Complete the following fields in the Time Scale section: Start Date Indicates the start date for the column spread. Values: Specific Date or Rolling Date Default: (Rolling Date) Start of Current Week Time Scale Specifies the time period by which data displays. Values: Year, Quarter, Month, Week, Day Default: Week

Chapter 5: Views 105

Configure the List Column View

Number of Time Periods Defines the number of time periods you want to see displayed. Default: 12 Time Period Offset Shifts the beginning of the Gantt bar relative to the Start Date. Enter a positive or negative number of time periods into the field. Enter a Start Date first. Show Group Header Row Indicates if the timescale displays above the Gantt bar. If you select this option, be sure that you also select a value. Values: Year, Quarter, Month, or Week Default: Cleared 7. Complete the following fields in the Primary Bar section: Item Name Attribute Specifies the type of information to display in the corresponding bar. Default: Task Required: Yes Start Date Attribute Defines the start date of the corresponding bar display. Required: Yes Finish Date Attribute Defines the finish date of the corresponding bar display. Default: Finish Required: Yes

106 Studio Developer's Guide

Configure the List Column View

Milestone Attribute Specifies the attribute to designate a milestone. You can only assign a milestone attribute for a task. Default: Milestone Required: Yes Progress Through Date Attribute Specifies the attribute to define when to stop drawing the black overlay line that indicates how much work is complete. If you select the Progress Through Date Attribute, it overrides the Progress Percent Attribute. Progress Percent Attribute Defines the percentage used to move the green progress line relative to the length of the taskbar to indicate the completed task work. If you select a value for this field, it overrides the Progress Through Date Attribute selection. Default: % Complete Label for Bar Specifies the label text to display above each taskbar. Additional Information Attribute Specifies the field used in the text note when you mouse over a taskbar. Example: To display the assigned resources for a task when the cursor is over a taskbar, select Assigned Resources from the field. Then, select the Additional Information checkbox in the Show Mouseover field.

Chapter 5: Views 107

Configure the List Column View

Show Mouseover Specifies the information you want to display in a text note when the mouse scrolls over an area of the Gantt chart. Values: Item Name, Start Date, Finish Date, Progress Through Date, Progress Percent, Additional Information Default: Item Name (Selected), Start Date (Selected), Finish Date (Selected), Progress Through Date (Cleared), Progress Percent (Selected), Additional Information (Cleared) 8. Indicate the dates to show in the primary bar by selecting the desired dates in the Available section and clicking the right arrow to add the dates to the Selected section. You may change the order of the dates in the list by clicking the up and down arrows in the Selected section. To display a second bar below the primary bar (for comparison purposes), select the Show Secondary Bar check box and repeat the previous primary bar steps for the secondary bar section.

9.

10. Save your changes.

Display an Image Link in a List Column View


You can add an image link that when clicked links the user to another page. When you add image links 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. Follow these steps: 1. With the object open, click Views. The views page appears. 2. Locate the List Column view in the Category column, and click Fields in the same row. The list column fields page appears.

108 Studio Developer's Guide

Configure the List Column View

3.

Click New. The create page appears.

4.

Select Image, and click Save and Continue. The list column field page appears.

5.

Complete the following fields: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Image Specifies the image to use in the grid column. Select an image from the drop-down list. Link Specifies a page link that appears as a secondary value that the user can select. Open as Pop-up Indicates whether the page appears as a pop-up. Select the check box to have the page appear as a pop-up.

6.

Save your changes.

Display a Progress Bar in a List Column View


Use the following procedure to add a progress bar field to a list column view. Progress bars show progress over time. 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.

Chapter 5: Views 109

Configure the List Column View

Follow these steps: 1. With the object open, click Views. The list of views page appears. 2. Locate the List Column view in the Category column, and click Fields in the same row. The list column fields page appears. 3. Click New. The create page appears 4. 5. Click Progress Bar, and click Save and Continue. Complete the following fields: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Current Stage Name Specifies the field value to use for each stage in the progress bar. The value displays below the column label. Current Stage Number Specifies the field value to use for the current stage in the progress bar. Number of Stages Specifies the field value that defines the total number of stages in the progress bar. Color Attribute Specifies the color.

110 Studio Developer's Guide

Configure the List Column View

Show Label Determines whether the name of the current stage is displayed in the progress bar. Select the check box to display the name. Column Width Defines the percentage of the list's width that is allocated to the progress bar column. 6. Save your changes.

Add Aggregation Rows to a List Column View


Use this procedure if you have number or money attributes, and you want to show aggregations for the rows in which they display. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. 3. Locate the List Column view in the Category column, and click [Aggregation] in the same row. Complete the following actions for each aggregation row you want to add: a. Click Add. The properties page appears. b. Complete the following fields: Label Defines the name for the aggregation row. Enter the name you want to appear. Show Determines whether the name of the aggregation row is displayed. Select the check box to display the name.

Chapter 5: Views 111

Configure the List Column View

Attribute Specifies the field value that is to be used for aggregation. Function Specifies the aggregation function used to calculate values for a selected field (cell) in the row. c. Save your changes.

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. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. 3. 4. 5. Locate the List Column view in the Category column, and click [Aggregation] in the same row. Click Reorder. Select the row you want to move, and click the up or down arrows to move it up or down the list. When aggregation rows are in the correct order, save your changes.

Modify a List Column View Attribute


Before you can see the changes that you make to list column view attributes, you must add it to the List Column layout. Follow these steps: 1. With the object open, click Views. The list of views appears.

112 Studio Developer's Guide

Configure the List Column View

2.

Locate the List Column view in the Category column, and click [Fields] in the same row. The list column fields appear.

3. 4.

Click the Properties icon for the field whose appearance you want to change. Change any of the following options (the options that appear depend on the field's data and display type): Allow Editing Specifies whether a user can edit fields. Select the check box to allow editing. Alignment Specifies the text alignment in grid cells. Allow Word Wrapping in Column Indicates whether the text in the column can wrap within the column. Select the check box to allow wrapping. Allow Word Wrapping in Column Header Indicates whether the text in the column label can wrap within the column. Select the check box to allow wrapping. Color Specifies the color for the graph. Column Label Defines the name that appears at the top of the list column. Column Width Defines the width of the column in pixels. Decimal Places Defines the number of decimal places for data to be returned by the attribute. Enter a zero (0) to make the attribute an integer.

Chapter 5: Views 113

Configure the List Column View

Display Elements Select from:


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 display such columns of information as a value (for example, 6.4), an image (such as a green/red/yellow stoplight), a range description (for example, super, fair, awful), or a combination of these options. Disable Link Attribute Specifies 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. Display Type Specifies how the attribute value is to display. Length Scaling Specifies what will be used as the basis for scaling if you want the graph scaled. Link Specifies a page link that appears as a secondary value that the user can select. Maximum Length Defines the maximum length that the graph can be as a column or bar in pixels.

114 Studio Developer's Guide

Configure the List Column View

Over-threshold Color Specifies the graph color used to indicate when the threshold has been exceeded. Secondary Value Specifies the secondary value that you want to display in the column when you mouse over. (Optional) Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Stacked Attribute Specifies the second field value to be displayed as a bar or column graph in a column. Thickness Specifies the thickness of the column. Values:

Autofit Narrow Medium

Wide Threshold Aggregation Function Specifies the mathematical function used to calculate a threshold for the graph. Threshold Line Attribute Specifies the field that is to be used to calculate a threshold for the graph. 5. 6. Click Save and Continue. Click the Indicator Images icon next to the attribute whose appearance you want to change by adding an image. The images list page appears.

Chapter 5: Views 115

Configure the List Filter View

7.

In the Available Images list box, select the image you want to appear in the attribute's field and move the image to the appropriate list box, depending on whether you want the image to appear before or after the content in the cell. Save your changes.

8.

Configure the List Filter View


List Filter views display on CA Clarity PPM list pages to help users filter the list. A list filter 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. When you set up list filter views, you can display a Build Power filter link that users can click to build and save complex queries. Example If a user enters two or more terms into a regular filter box (for example, John Adam), typically CA Clarity PPM assumes that this is an AND operation and provides John Adam in the results. With Power Filters, the user can select a variety of operators including OR and select which fields to search in. With Power Filters the user can also return results that have John or Adam and not necessarily both.

Add an Attribute to an Object's List Filter View


Follow these steps: 1. With the object open, click Views. The list of views appears. 2. Locate the List Filter view in the Category column, and on the same row click [Layout]. The layout page appears.

116 Studio Developer's Guide

Configure the List Filter View

3.

In the Available list, select the attribute or attributes you want to add to the list filter, then move the attributes to the appropriate columns. Complete the following fields in the Settings section: Section Title Defines the text that will appear at the top of the section for the filter. Default Filter State Specifies whether the filter's initial display is expanded or collapsed. Values: Collapsed or Expanded Allow Power Filter Specifies whether the filter will provide advanced search features. Select the check box to provide the advanced search features.

4.

5.

Save your changes.

Modify a List Filter View Attribute


Before you can see the changes that you make to the appearance of a list filter view attribute, you must add it to the List Filter layout. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. Locate the List Filter view in the Category column, and on the same row click [Fields]. The list of filter fields appears 3. Click the Properties icon next to the attribute whose appearance you want to change.

Chapter 5: Views 117

Configure the List Filter View

4.

Change any of the following options (the options that appear depend on the attribute's data and display type): Display Elements Select from:

Image, to display an image. Value, to display a value. Range Description, to enter a descriptive label for the range values.

Display Type Specifies how the attribute value is to display. Filter Default Specifies the value that appears in the filter field as the default value. Filter Label Defines the label that appears in the list filter for the attribute. 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. Hint Defines a short message that helps a user use the field. Limits: 512 characters 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.

118 Studio Developer's Guide

Edit an Attribute's Label for a Specific View

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. Tooltip Provides a short message that displays when the user moves a cursor over the 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. 5. Save your changes.

Edit an Attribute's Label for a Specific View


The label that is displayed for a field or column does not have to be the actual attribute name. You can change the label of a stock or user-defined attribute. The same attribute can also appear with a different label in different views. Follow these steps: 1. With the object open, click Views. The list of views appears. 2. Locate the view that you want to change in the Category column, and click [Fields} in the same row. A list of attributes for the view appears. 3. 4. In the list, locate the attribute whose label you want to change, and enter a new label. Save your changes.

Chapter 5: Views 119

Publish Changes to List and Filter Views

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 will see changes in CA Clarity PPM immediately when you make and save changes to the view in Studio. A user who has personalized the view will not see changes to the new view until you publish the changes. 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. 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 option in Studio provides information that lets you make appropriate decisions about publishing new views. Use the Views page to publish changes. To access this page, select Views from Studio. The Views page shows a list of system views and their current status in CA Clarity PPM. Custom views are not listed. 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.

120 Studio Developer's Guide

Publish Changes to List and Filter Views

Object Identifies the object on which the view is created. Category Identifies whether the view is a filter, list, or property view. Type Identifies whether the view is for the purpose of creating or editing an instance of an object. Only a property view has data in this column. Partition Identifies the partition to which the view pertains. Personalized Indicates with a checkmark that at least one user has configured the view in the user interface. Publishing a new view or restoring the view default removes the checkmark from this field. Modified Indicates with a checkmark that changes have been made by an administrator since the view was originally installed or the last time defaults were restored. Upgraded Indicates with a checkmark that an upgrade has occurred for the view since its original installation. Last Restored Indicates the last date that view defaults were restored. Restoring defaults overwrites all user and administrator modifications and clears the checkmark from the Modified column. Last Version Indicates the last release version in which changes were 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. Chapter 5: Views 121

Restore Defaults for Object Views

Follow these steps: 1. Click the Administration menu, and select Views from the Studio menu. The list page appears. 2. Select the views that you want to publish to users, and click Publish. The confirmation page appears. 3. Click Yes.

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 causes the properties view, list view, and filter view to be restored to the original view properties for all users. Any personalized user changes to the object's view are overwritten with the defaults. If you are using partitions, the defaults are restored only in the selected partition. Follow these steps: 1. Click the Administration menu, and select Objects from the Studio menu. The list page appears. 2. 3. Select the object whose views are to be restored to default values. Click Views. The views list page appears. 4. Click Restore Defaults to remove all changes (layout, labels, appearance of fields, and options) made at the administrator level or by users to views in the current partition.

122 Studio Developer's Guide

Restore Defaults for Selected Views

Restore Defaults for Selected Views


You can restore the 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. Follow these steps: 1. Open Administration, and from Studio, click Views. The views list page appears. 2. 3. Select the views to which you want to restore default values. Click Restore Defaults. The confirmation page appears. 4. Click Yes.

Chapter 5: Views 123

Chapter 6: Links
This section contains the following topics: About Links (see page 125) Link from an Object Page to a Subpage (see page 125) How to Link from CA Clarity PPM to a Web Page (see page 126) Link to Properties Pages from External Applications (see page 126)

About Links
You can create links to an object page that:

Display a subpage that belongs to the object page Link to a web page through a URL address Link to the properties page of an object instance record 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. Follow these steps: 1. Open Administration, and from Studio, click Objects. The object list page appears. 2. 3. Click the name of the object to which you want to add the link. Click Linking. The list of links appears. 4. Click New. The create page appears. 5. Complete the following fields: Link Name Defines the name of the page link. This is the label for the page link that displays in the menu.

Chapter 6: Links 125

How to Link from CA Clarity PPM to a Web Page

Link ID Defines a unique alphanumeric identifier for the link. Description Defines the purpose of the item being created and provides any relevant information. Action Specifies the page that appears when the link is clicked in the menu. Depending upon the action you select, you are asked to select values for attributes that the subpage has in common with the object. Both objects must have these values in common for linking to work. 6. Click Save and Return.

How to Link from CA Clarity PPM to a Web Page


The following process explains how to create a link to an external website and place it on an object's Properties view. 1. 2. Create a URL link attribute for the object (see page 63). Add the attribute to the object's Properties view (see page 86).

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

126 Studio Developer's Guide

Link to Properties Pages from External Applications

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.

Chapter 6: Links 127

Chapter 7: Portlets
This section contains the following topics: About Portlets (see page 129) User Portlets and Personal Dashboards (see page 131) Chart Portlet (see page 133) Filter Portlet (see page 144) Grid Portlet (see page 152) HTML Portlet (see page 167) Interactive Portlets (see page 170) Publish Changes to a Portlet (see page 174) Set User Configuration of Portlets (see page 174) Restrict User Rights for a Specific Portlet or Portlet Page (see page 175) Set a System View for a Portlet (see page 176)

About Portlets
Portlets and the portlet pages used to display them can be used provide information in real time for CA Clarity PPM users. While portlets do not replace reports, they can be considered mini-reports. Portlets Portlets are snapshots into CA Clarity PPM data and can consist of grids, charts, or snippets of HTML. You select data to display in the portlet. You can create and publish portlets across the enterprise. Each portlet page is comprised of a set of portlets, small windows of information presented as charts, 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 portlet pages by deciding which portlets to show or hide and where to show them on the page. Portlets can collect data and business intelligence from:

CA Clarity PPM Other databases within an enterprise External sources available in HTML, such as business news and network status information.

Chapter 7: Portlets 129

About Portlets

Users can populate portlets with charts, tables, workflows, best practices, documents, and forms-all updated and available in real time without the need to run reports. CA Clarity PPM supports the following portlet types: Chart portlets (see page 133) Provides graphic views into CA Clarity PPM data, such as pie and line charts. Filter portlets (see page 144) Coordinates filtering operations between portlets on a page. Grid portlets (see page 152) Provides lists or tables of data that can be filtered on-the-fly. HTML portlets (see page 167) Grabs web page content and plugs it into a CA Clarity PPM page in HTML format. Data can be extracted from other internal or external web sites. Interactive portlets (see page 170) Displays visually-rich, real-time CA Clarity PPM information using imported Xcelsius visualizations.

Relabel Attribute Names for User Portlet Data Providers


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. Follow these steps: 1. Open Administration, and from Studio, click Queries. The list page appears. 2. Select the query. The properties page appears. 3. Click Attributes. The list of attributes for the query appears. 4. Click the name of the attribute you want to relabel. The query attribute page appears.

130 Studio Developer's Guide

User Portlets and Personal Dashboards

5.

Click the Translate icon next to the Attribute Name field. The translation page appears.

6. 7.

Enter the name you want to appear for users in the data provider's attribute list. Save your changes.

User Portlets and Personal Dashboards


Users can create portlets in the CA Clarity PPM application using the same functionality that is found in Studio. The following sections provide the basic facts on how personal user dashboards and portlets work.

About Personal Dashboards (see page 131) Personal Dashboards Properties Settings (see page 131) Access Rights for Personal Dashboards (see page 132) Administrator Access to User Portlets (see page 132) Personal Dashboard Operations by User Type (see page 133)

About Personal Dashboards


A personal dashboard is a portlet page created by an end user in CA Clarity PPM. A personal 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. If both options are selected, One portlet per slide or sheet takes precedence.

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.

Personal Dashboard Properties Settings


A dashboard has specific properties settings. The properties settings include:

The portlet page type must be either Page with Tabs or Page Without Tabs.

Chapter 7: Portlets 131

User Portlets and Personal Dashboards

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.

Access Rights for Personal Dashboards


The following table shows the administrator access rights required for personal dashboards. Access Right Portlet Definition Editor Page Definition Editor What it does in the application Lets an administrator edit a portlet. Gives a user manager access to a dashboard. Scope Global/OBS/Instance Global/OBS/Instance

The following table shows the user access rights required for personal dashboards. Access Right Dashboard - Navigate Portlet - Navigate Dashboard - Create Portlet - Create Portlet - View Page - View What it does in the application Scope

Shows the Dashboards link Global for a user in the Home menu. Shows the Portlets link for a user in the Home menu. Lets a user create a dashboard. Lets a user create a portlet. Lets a user view a portlet. Global Global Global Global/OBS/Instance

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.

132 Studio Developer's Guide

Chart Portlet

In the application, the administrator can view only those portlets the administrator has created or portlets that have been shared.

Personal Dashboard Operations by User Type


The following table shows which dashboard functions can be performed by different types of users. Dashboard Function Share Edit properties Publish Personalize Export Studio Administrator Yes Yes Yes No No Dashboard Manager Yes Yes Yes Yes Yes Dashboard Viewer No No No Yes Yes

Chart Portlet
Studio allows you to generate a chart portlet dynamically, so that you can add it to your local configuration and personalized user interface. Each chart portlet appears in a three-dimensional and animation display. You can create a chart portlet to display information about business intelligence, collaborations, project, resource and personal information. You can add a chart to any page that can display a chart, including a custom dashboard or a portfolio management page. Use the chart type that best suits the way you want to visualize the metrics in query data. The chart type selected should not have fewer metrics than the minimum number of metrics in the query data. Charts 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, and so on) is a dimension of data. If a query data also contains resource data, then the data contains two dimensions. Metrics are measured query values. For example, Actual Hours is a metric. One-dimensional Three-dimensional Max. Metrics

Chart Type Description

Min. Metrics

Max. Metrics Min. Metrics

Chapter 7: Portlets 133

Chart Portlet

Chart Type Description Bar Bubble Displays each dimension of the data in a horizontal bar. Displays metrics on the horizontal and vertical axes. Also provides data points on the radius to control data point size based on a third metric. Displays each dimension of the data in a vertical bar.

One-dimensional Min. Metrics 1 3

Three-dimensional Max. Metrics Unlimited 3

Max. Metrics Min. Metrics Unlimited 3 1 3

Column Funnel

Unlimited 1

1 1

Unlimited 1

Displays the datas dimension 1 objects in proportional slices, like a pie chart, except the greatest values appear in the largest area of the funnel. Displays data points connected by lines along the axes. Displays data points connected by lines along the axes. Displays different colors to fill in the area below the line. Displays the datas dimension objects in proportional slices. Displays metrics across the x-axis and y-axis. 1 1

Line Area

Unlimited Unlimited

1 1

1 1

Pie Scatter

1 2

1 2

1 2

1 2

Create a Chart Portlet


This section describes how to create a chart portlet. Before you create a chart, complete the following actions:

Create an object or query data provider that includes the correct data for the chart. Decide the type of chart you want based on the metrics and dimensions in the query.

134 Studio Developer's Guide

Chart Portlet

Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlet list page appears. 2. Click New and select Chart Portlet from the menu. The create page appears. 3. Complete the following fields: 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. Required: Yes Portlet ID Defines a unique alphanumeric identifier for the portlet. Required: Yes Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Default: Business Intelligence Required: No Description Defines the purpose of the item being created and provides any relevant information. Base Size Specifies the base size for the portlet. Values: Extra Small, Small, Medium, and Large Example: If you plan to create a single chart portlet on a page that you can personalize, select Large as the base size. If the portlet is to share a page with other portlets, select Small as the base size. Default: Small

Chapter 7: Portlets 135

Chart Portlet

Active Specifies whether the portlet is active and users can see the portlet. 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 for this field, the portlet can be placed on any page. Values: Department, General, Location, Standard Rule, Portfolio, and Project Default: General Required: Yes Data Provider Indicates the data construct that provides information to the portlet. Required: Yes 4.
T

Click Next. Complete the following field: Chart Type Specifies the chart type. Values: Bar, Bubble, Column, Funnel, Line, Pie, Scatter Default: Bar

5.

6. 7.

Click Next. If you select Bubble, Funnel, Pie, or Scatter, complete the following information by selecting the metrics that you want to display. The metrics page is specific to the type of chart that you are creating. Example: If you are creating a bubble chart, then you select an X-axis, Y-axis and Bubble Radius. X Axis Specifies the metrics to display the X-axis for the chart. Y Axis Specifies the metrics to display the Y-axis for the chart. Bubble Radius Specifies the metrics to display the bubble radius for the chart.

8. 9.

Click Next. Click Finish and Open.

136 Studio Developer's Guide

Chart Portlet

Set up a Chart Filter


A chart can be complex if it contains a lot of data. Filters can help users view only the information that is important to them. For each type of chart, you can select the specific data that you want to display from the available data provided by a query. You can also specify if you want the filter options to appear on the portlet or on a separate page. You can display filters on a separate page if the filter will not change often. The filter options are still available, but hidden. Use the following process to set up a chart filter: 1. 2. Determine the chart layout (see page 137). Determine the chart fields (see page 138).

Determine the Chart Layout


Follow these steps: 1. 2. Open the chart portlet. Open the Chart Filter Section menu and click Layout. The layout page appears. 3. 4. Select the fields you want to appear in the filter in the Available column and move the fields to the appropriate column using the arrows. Complete the following fields: Section Title Defines the text that will appear at the top of the section for the filter. Default Filter State Specifies whether the filter's initial display is expanded or collapsed. Values: Collapsed or Expanded Allow Power Filter Specifies whether the filter will provide advanced search features. Select the check box to provide the advanced search features. 5. Save your changes.

Chapter 7: Portlets 137

Chart Portlet

Determine the Chart Fields


Follow these steps: 1. 2. Open the chart portlet. Open the Chart Filter Section menu and click Fields. The filter field list page appears. 3. From the Display menu, select the fields to display. You can select one of the following:

All. Displays all data provided by the query Selected. Displays the fields selected you selected in the Layout menu (above). Available. Display all available data provided by a query.

4.

Save your changes.

Determine a Chart Portlet's Data and Layout


This procedure explains how to determine which data displays on a chart. The procedure assumes that the basic chart has been created. Follow these steps: 1. 2. 3. 4. Open the chart portlet. Open the Chart Section menu and click Source Data. Select the metrics you want included in the chart. Save your changes.

Determine a Chart Portlet's Appearance


The following procedure explains how to determine the appearance of a chart. This procedure assumes the basic chart has been created and the data that the chart is to show has been chosen. Note: This procedure explains the basic procedure for all charts. All fields that might occur for any chart type are included but are marked by the type of chart to which the fields apply. Follow these steps: 1. 2. Open the chart portlet. Open the Chart Section menu and click Options. The options page appears.

138 Studio Developer's Guide

Chart Portlet

3.

In the Options field, specify the part of the chart for which you are setting options. You can select one of the following:

Entire Chart X-Axis Y-Axis

4.

Depending on the type of chart selected, complete the following display options and save your changes. Note: The options are entered in alphabetic order rather than the order they appear on the page. Allow Configuration Indicates that a user can make changes to the appearance of a portlet. Select the check box to allow configuration. Default: Selected Allow Label Configuration Indicates that a user can make changes to portlet labels. Select the check box to allow configuration. Default: Selected Angle of First Slice Defines the position of the first dividing line. Use with Pie and Funnel charts. Values: 0 to 360 degrees Default: 0 Axis Label Displays the metric name along the X-axis, Y-axis, or both axes. Use this option with:

Bar. X-axis, Y-axis. Column. X-axis, Y-axis. Line. X-axis, Y-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.

Chapter 7: Portlets 139

Chart Portlet

Crosses Opposite Axis At

Defines the intersection point of the axis. Use with bubble and scatter charts.

Datapoint Labels Specifies the data name to be applied next to the value on the chart. 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-axis, Y-axis.

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. Bubble and Scatter. X-axis, Y-axis.

Filter Indicates how the results appear initially. Values:


Automatically show results. Indicates you want immediate results. Do not show results until I filter. Indicates you want results provides after you filter.

Default: Automatically show results Link Specifies a page link that appears as a secondary value that the user can select.

140 Studio Developer's Guide

Chart Portlet

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. Bubble and Scatter. X-axis, Y-axis.

Maximum Value Defines the greatest value to display on the axis. Use this option with:

Bar. X-axis. Column. Y-axis. Line. Y-axis. Bubble and Scatter. X-axis, Y-axis.

Mouseover Labels Specifies the data values to show when a user moves the cursor over a chart value. Use with all chart types. Other Category Threshold Defines the data point at which all records for a specified value are grouped into a category named Other. Use this option if too many items appear on the chart. Use this option with the following chart types:

Bar Column Line Pie and Funnel

Show Axis Indicates whether the Axis line displays. Use this option with:

Bar. X-axis, Y-axis. Column. X-axis, Y-axis. Line. X-axis, Y-axis. Bubble and Scatter. X-axis, Y-axis.

Show Legend Specifies whether to display a legend for the chart. Use with bar, column, line, bubble, and scatter chart types. Default: Selected

Chapter 7: Portlets 141

Chart Portlet

Show Line Markers Indicates data points on the chart; otherwise, only a line displays. Available for line charts. Select the check box to show line markers. Default: Selected Show Lines Indicates that lines are to connect the data points. Available for line charts. Select the check box to show lines. Default: Selected Show Major Grid Lines Indicates whether major grid lines display on the chart. Use this option with:

Bar. X-axis, Y-axis. Column. X-axis, Y-axis. Line. X-axis, Y-axis. Bubble and Scatter. X-axis, Y-axis.

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. Bubble and Scatter. X-axis, Y-axis.

Show Tick Labels Indicates whether tick labels display on the chart. Use this option with:

Bar. X-axis, Y-axis.. Column. X-axis, Y-axis. Line. X-axis, Y-axis. Bubble and Scatter. X-axis, Y-axis.

Show Title Indicates that the portlet name is to display. Available for all chart 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 and line charts.

142 Studio Developer's Guide

Chart Portlet

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 charts. Tick Label Angle Sets the angle of a label used with tick marks. Use this option with:

Bar. X-axis. Column. X-axis. Line. X-axis. Bubble and Scatter. X-axis.

5.

(Optional) If you are configuring a line chart, select Guides in the Options field and click New, then complete the following fields and save your changes: Axis Specifies the axis for which guides are being set. Label Defines the name for the axis. Enter the name you want to appear. 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 percent value and enter the amount. Values: Fixed Value, Percent Value, or Attribute Default: Attribute Color Specifies the color for the guide. Default: Black

Chapter 7: Portlets 143

Filter Portlet

Modify a Chart Portlet


This procedure explains how to modify the type of an existing chart portlet. Modifying a portlet that is in use by another user does not immediately affect what the user views. However, the next time the user displays the page; your changes will be visible. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The list page appears. 2. 3. 4. 5. Click the name of the chart portlet you want to change. Open the Chart Section menu, and click Chart Type. Select a new chart type from the Chart Type drop-down list. Save your changes.

Filter Portlet
A filter portlet coordinates filtering operations across portlets in CA Clarity PPM. A filter portlet contains defined placeholder filter fields that are mapped to attributes in grid and chart portlets. When you configure and publish a filter portlet on a page with grid or chart 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 portlets values, even if the values are not displayed. 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

144 Studio Developer's Guide

Filter Portlet

Filter Precedence
The following table shows how filter precedence works when multiple filters are mapped to a filter portlet: Filter from this portlet Filter portlet Result 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 portlets filter criteria of unmapped portlet attributes. Portlets that have no mapped attributes are not affected by the filter portlet.

Grid or Chart 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.

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.

Chapter 7: Portlets 145

Filter Portlet

Filter Persistence
The following rules determine which filters 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.

How to Set Up a Filter Portlet


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. 2. 3. 4. 5. Create the filter portlet (see page 146). Add fields to the filter portlet. Determine the field layout on the filter portlet (see page 150). Select an existing portlet page or create a portlet page and add content (see page 180). Add the filter portlet to the portlet page (see page 150). This step includes mapping the filter portlet fields to the attributes of the portlets on the page.

Create a Filter Portlet


Use this procedure to create a filter portlet that can be used to filter the content of all portlets that appear on a page. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlets list page appears. 2. Click New, and select Filter Portlet.

146 Studio Developer's Guide

Filter Portlet

3.

Complete the following fields: 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. Required: Yes Portlet ID Defines a unique alphanumeric identifier for the portlet. Required: Yes Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Required: Yes Description Defines the purpose of the field and provides any relevant information. Active Indicates the portlet is active and is 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 for this field, the portlet can be placed on any page. Values: Department, General, Location, Standard Rule, Portfolio, and Project Default: General Required: Yes

4.

Save your changes.

Chapter 7: Portlets 147

Filter Portlet

Add a Field to a Filter Portlet


You can add a field with one of the following data types to a filter portlet:

Boolean Date Lookup or multi-valued lookup Money Number String URL

Follow these steps: 1. With the filter portlet open, click Fields. The fields list page appears. 2. Click Add. The create page appears. 3. Complete the following fields. The fields you are required to complete vary according to the data type selected. Not all fields listed appear for each data type. Field Name Defines the name that appears in the filter portlet. Field ID Defines a unique alphanumeric identifier for the field. Description Defines the purpose of the item being created and provides any relevant information. Data Type Specifies the data type for the field. Once you save, you cannot change the data type. Display Type Specifies how the field is to be used by to the user. Values: Browse, Text Entry, Numeric Range, Pull-Down, Date, or Date Range. 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.

148 Studio Developer's Guide

Filter Portlet

Filter Default Defines the value you want to appear in the filter field as the default value. If the filter portlet associated with this field is published to a page as the filter default, this value is applied to the portlet attributes mapped to this field. Lookup Specifies a list of lookup values that appears in the field for the user to select. The user views the list according to the display type selected. Lookup Style Indicates how many items a user can select for the field when the lookup is executed. 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. 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 Defines a short message that helps a user use the field. Limits: 512 characters Tooltip Provides a short message that displays when the user moves a cursor over the field. 4. Save your changes.

Chapter 7: Portlets 149

Filter Portlet

Complete Field Layout for a Filter Portlet


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. Follow these steps: 1. With the portlet open, click Layout. The layout page appears. 2. Move the fields to the appropriate list box (Left Column or Right Column) using the arrows. The order you place the fields in the list boxes is the order of appearance in the filter portlet. Complete the following fields: Render As Indicates how you want the filter portlet to appear on the published page or dashboard. Select Toolbar or Section. If you select Toolbar, the default filter state is fixed as Expanded. Default Filter State Specifies whether the filter's initial display is expanded or collapsed. Values: Collapsed or Expanded 4. Save your changes.

3.

Add a Filter Portlet to a Portlet Page


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. Follow these steps: 1. Open Administration, and from Studio, click Portlet Pages. The portlet pages list page appears.

150 Studio Developer's Guide

Filter Portlet

2.

Select the page you want to add the filter portlet to. If you are adding the filter portlet to a tab, click Tabs, then click the name of the tab in the list to display the tab's properties page.

3.

Click Page Filters. The page filters list page appears.

4. 5.

Click Add. Select the check box next to the filter portlet you want to add and click Add. You can add multiple filter portlets to a page. The page filters list 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 Filter Mappings icon next to the filter portlet name. The mapping page appears. This page shows the filter portlet fields listed under each portlet on the page and allows you to map to 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 select the check box for multiple attributes in a portlet, a blank corresponding filter portlet field for any of the attributes causes the portlet not to appear.

10. Save your changes.

Chapter 7: Portlets 151

Grid Portlet

View Portlet Pages that Contain a Specific Filter Portlet


Use this procedure to view the list of portlet pages that contain a specific filter portlet. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlet list page appears. 2. Select the filter portlet whose pages you want to view. The properties page appears. 3. Click Portlet Pages.

Grid Portlet
Use grid portlets to display query data in rows and columns. Before you create a grid, see the detailed description of the 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. Charts are better suited for query data that contains several dimensions or metrics (query values that can be measured). You might use a grid portlet 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

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.

Secured Data and Grid Portlets


If the data used in a grid portlet comes from a secured subpage, the access restrictions for the subpage are enforced in a grid portlet. That means a user who cannot view a subpage will also not be able to receive data from the subpage in a grid portlet.

152 Studio Developer's Guide

Grid Portlet

Grid Portlet Options


You can create virtual columns with data derived from query data. A virtual column can be one of the following: Aggregation Operates on a large set (column) of data and typically return a single value. You can have multiple rows of aggregated data. Comparison Compares two or more query data fields. Variance Displays the difference between the aggregation and comparison columns or rows. Depending upon the type of data involved, you can select 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 attributes 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 attributes. Depending upon the data, you can display the results as a number or a bar or column chart.

Considerations for 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. The y-axis (rows) of the grid can contain only one dimension of data. If your query data contains two dimensions, either dimension can 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.

Chapter 7: Portlets 153

Grid Portlet

Metrics always displayed 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. If you are adding a lookup attribute to a grid portlet, note the following:

Static dependent list lookups configured as multi-valued lookups are not supported in grid portlets. Autosuggest does not work with static dependent lists.

Create a Grid Portlet


Use this procedure to create a grid portlet. Grid portlets display lists for users. Before you perform this procedure:

Verify that you have created a query to provide data for the portlet. Review the considerations for creating grids.

To create a grid portlet 1. Click the Administration menu, and select Portlets from the Studio menu. The list of portlets appears. 2. Click New and select Grid Portlet. The create page appears. 3. Complete the following fields: 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. Required: Yes Portlet ID Defines a unique alphanumeric identifier for the portlet. Required: Yes Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes

154 Studio Developer's Guide

Grid Portlet

Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Required: Yes Description Defines the purpose of the item being created and provides any relevant information. Active Specifies whether the portlet is active and users can see the portlet. 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 for this field, the portlet can be placed on any page. Values: Department, General, Location, Standard Rule, Portfolio, and Project Default: General Required: Yes Data Provider Indicates the data construct that provides information to the portlet. Required: Yes Partition Specifies the partition associated with the portlet. 4. Click Next. The portlet finish page appears. 5. Click Finish and Open.

Chapter 7: Portlets 155

Grid Portlet

Set up a Grid Portlet's Layout


Use the following procedure to determine the order of data that appears in a 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. Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Layout. The layout page appears. 3. 4. 5. 6. 7. 8. 9. In the Available Columns list, select the attributes you want to add. Click the right-arrow to move the attributes to the Selected Columns list. Click Save. Indicate the primary sort column in the Column Sorting section's First Field row, and select the attribute. To indicate the direction of the sort, select Ascending or Descending. To indicate additional sort columns, select attributes for the remaining fields in the Column Sorting section. Save your changes.

Set up Display Options for a Grid Portlet


Use the following procedure to set up display options for a grid portlet. Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Options. The list options page appears. 3. Complete the following fields: Secondary Value Display Indicates the way that secondary values display in a grid cell. Values:

Mouseover only. Specifies no secondary value display.

156 Studio Developer's Guide

Grid Portlet

Mouseover and redline. Specifies the display of a secondary value when a user places the pointer over a cell in a grid. This helps to compare values. For example, if you have a column named Cost and another column named Baseline Cost, you might want to display both values in one cell. To show both, you can select 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. Show Null Secondary Values. Specifies that the secondary value displays even when there is no number value to show.

Filter Indicates how the results appear initially. Values:


Automatically show results. Indicates you want immediate results. Do not show results until I filter. Indicates you want results provides after you filter.

Default: Automatically show results 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. 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 Specifies a user can make changes to the appearance of a page or a portlet. Select the check box to allow configuration. Allow Label Configuration Specifies a user can make changes to a page or portlet label. This option works with the Allow Configuration option. If you select the Allow Configuration option and you clear the Allow Label Configuration option, labels become unavailable for configuration while other items can still be configured. Attribute Value Protection Indicates whether an attribute is protected or displayed. You can protect attributes using display conditions and secured subpages or secured subpages only, or you can display all attribute values. 4. Save your changes.

Chapter 7: Portlets 157

Grid Portlet

Display a Gantt Chart in a Grid Portlet


A Gantt chart shows duration and progress over time. New virtual attributes are displayed in the far right column of the list. You can move the virtual attribute to a different position in the List Column layout. See the Personalizing CA Clarity User Guide for more information. Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Fields. The list column fields page appears. 3. 4. Click New. Select Gantt, and click Save and Continue. The settings page appears. 5. Complete the following fields in the General section: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates if you want text in the column label to wrap. Default: Cleared
.

6.

Complete the following fields in the Time Scale section: Start Date Indicates the start date for the column spread. Values: Specific Date or Rolling Date Default: (Rolling Date) Start of Current Week Time Scale Specifies the time period by which data displays. Values: Year, Quarter, Month, Week, Day Default: Week

158 Studio Developer's Guide

Grid Portlet

Number of Time Periods Defines the number of time periods you want to see displayed. Default: 12 Time Period Offset Shifts the beginning of the Gantt bar relative to the Start Date. Enter a positive or negative number of time periods into the field. Enter a Start Date first. Show Group Header Row Indicates if the timescale displays above the Gantt bar. If you select this option, be sure that you also select a value. Values: Year, Quarter, Month, or Week Default: Cleared 7. Complete the following fields in the Primary Bar section: Item Name Attribute Specifies the type of information to display in the corresponding bar. Default: Task Required: Yes Start Date Attribute Defines the start date of the corresponding bar display. Required: Yes Finish Date Attribute Defines the finish date of the corresponding bar display. Default: Finish Required: Yes Milestone Attribute Specifies the attribute to designate a milestone. You can only assign a milestone attribute for a task. Default: Milestone Required: Yes Progress Through Date Attribute Specifies the attribute to define when to stop drawing the black overlay line that indicates how much work is complete. If you select the Progress Through Date Attribute, it overrides the Progress Percent Attribute.

Chapter 7: Portlets 159

Grid Portlet

Progress Percent Attribute Defines the percentage used to move the green progress line relative to the length of the taskbar to indicate the completed task work. If you select a value for this field, it overrides the Progress Through Date Attribute selection. Default: % Complete Label for Bar Specifies the label text to display above each taskbar. Additional Information Attribute Specifies the field used in the text note when you mouse over a taskbar. Example: To display the assigned resources for a task when the cursor is over a taskbar, select Assigned Resources from the field. Then, select the Additional Information checkbox in the Show Mouseover field. Show Mouseover Specifies the information you want to display in a text note when the mouse scrolls over an area of the Gantt chart. Values: Item Name, Start Date, Finish Date, Progress Through Date, Progress Percent, Additional Information Default: Item Name (Selected), Start Date (Selected), Finish Date (Selected), Progress Through Date (Cleared), Progress Percent (Selected), Additional Information (Cleared) 8. Indicate the dates to show in the primary bar by selecting the desired dates in the Available section and clicking the right arrow to add the dates to the Selected section. You may change the order of the dates in the list by clicking the up and down arrows in the Selected section. To display a second bar below the primary bar (for comparison purposes), select the Show Secondary Bar check box and repeat the previous primary bar steps for the secondary bar section.

9.

10. Save your changes.

Display a Progress Bar in a Grid Portlet


Use the following procedure to add a progress bar field to a grid portlet. Progress bars show progress over time. 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.

160 Studio Developer's Guide

Grid Portlet

Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Fields. The list column fields page appears. 3. 4. 5. Click New. Click Progress Bar, and click Save and Continue. Complete the following fields: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates whether the text in the column label can wrap within the column. Select the check box to allow wrapping. Current Stage Name Specifies the field value to use for each stage in the progress bar. The value displays below the column label. Current Stage Number Specifies the field value to use for the current stage in the progress bar. Number of Stages Specifies the field value that defines the total number of stages in the progress bar. Color Attribute Specifies the color. Show Label Determines whether the name of the current stage is displayed in the progress bar. Select the check box to display the name. Column Width Defines the percentage of the list's width that is allocated to the progress bar column. 6. Save your changes.

Chapter 7: Portlets 161

Grid Portlet

Display a Bar or Column Chart in a Grid Portlet


Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Fields. The list column fields page appears. 3. 4. Click the Properties icon in the row that contains the attribute you want to change. Change any of the following options (the options that appear depend on the attribute's data and display type): Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates whether the text in the column label can wrap within the column. Select the check box to allow wrapping. 5. 6. Select the type of chart in the Display Type field, and click Save. Complete the following fields: Secondary Value Select the attribute whose value displays when the user moves a cursor over the primary bar. Alignment Select:

Left, to align the attribute with the left side of the column Center, to center align the attribute in the column Right, to align the attribute with the right side of the column.

Thickness Select from the following options:


Autofit to fit the chart to the column width. Narrow to display a narrow chart. Medium to display a medium-width chart. Wide to display a wide chart.

162 Studio Developer's Guide

Grid Portlet

Maximum Length Enter the length of the bar (in pixels). Length Scaling Select 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 charts 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 in the same object that holds the threshold value. Note: In bar charts, a vertical line marks the threshold value. 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, select the Open as Pop-up check box.

Chapter 7: Portlets 163

Grid Portlet

7.

(Optional) To create a stacked bar, complete the following fields: Stacked Attribute Specifies the attribute to be represented as a stacked bar. Color Specifies a color for the stacked bar. Secondary Value Specifies a value to display when the user moves a cursor over the secondary bar. Link Specifies a page to display when the user clicks the secondary bar.

8.

Save your changes.

Add Aggregation Rows to a Grid Portlet


Use this procedure if you have number or money attributes, and you want to show aggregations for the rows in which they display. Follow these steps: 1. 2. 3. Open the portlet. Open the List Column Section menu, and click Aggregation. Complete the following actions for each aggregation row you want to add: a. Click Add. The properties page appears. b. Complete the following fields: Label Defines the name for the aggregation row. Enter the name you want to appear. Show Determines whether the name of the aggregation row is displayed. Select the check box to display the name. Attribute Specifies the field value that is to be used for aggregation. Function Specifies the aggregation function used to calculate values for a selected field (cell) in the row.

164 Studio Developer's Guide

Grid Portlet

c.

Save your changes. The aggregation row list appears.

4.

Complete the following actions as needed:


To show the difference between two rows, select the Variance check box. This check box is available only if two aggregation rows are selected as Show. To reorder the rows, click Reorder.

5.

Save your changes.

Display an Image Link in a Grid Portlet


You can add an image link that takes the user to another page when the link is clicked. When you add an image link to a grid portlet, 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. Follow these steps: 1. 2. Open the portlet. Open the List Column Section menu, and click Fields. The list column fields page appears. 3. 4. Click New. Select Image, and click Save and Continue. The list column field page appears. 5. Complete the following fields: Column Label Defines the name that appears at the top of the list column. Show Column Label Indicates whether the column label appears at the top of the column list. Select the check box to have the column label appear. Allow Word Wrapping in Column Header Indicates whether the text in the column label can wrap within the column. Select the check box to allow wrapping. Image Specifies the image to use in the grid column. Select an image from the drop-down list. Link Specifies a page link that appears as a secondary value that the user can select.

Chapter 7: Portlets 165

Grid Portlet

Open as Pop-up Indicates whether the page appears as a pop-up. Select the check box to have the page appear as a pop-up. Disable Link Attribute Specifies 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. 6. Save your changes.

Set Up a List Filter for a Grid Portlet


List filters display on CA Clarity PPM list pages to help users filter the list provided by a grid portlet. A list filter 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. When you set up a list filter, you can display a Build Power filter link that users can click to build and save complex queries. Follow these steps: 1. 2. Open the portlet. Open the List Filter Section menu, and click Layout. The layout page appears. 3. 4. In the Available list, select the attribute or attributes you want to add to the list filter, then move the attributes to the appropriate columns. Complete the following fields in the Settings section: Section Title Defines the text that will appear at the top of the section for the filter. Default Filter State Specifies whether the filter's initial display is expanded or collapsed. Values: Collapsed or Expanded Allow Power Filter Specifies whether the filter will provide advanced search features. Select the check box to provide the advanced search features. 5. Save your changes.

166 Studio Developer's Guide

HTML Portlet

Modify a Grid Portlet


Use this procedure to change a grid portlet. Follow these steps: 1. With the grid portlet open, change any of the following items:

Portlet name Category (optional) Description Active status (optional) OBS Selections

2.

(Optional) Change the appearance of the grid portlet Note: Click Save on each page to save your changes.

3. 4.

(Optional) Change the access restrictions for the grid portlet. Save your changes.

Delete a Grid Portlet


Use this procedure to delete a grid portlet. When you delete a grid that a user is viewing, what the user sees is not changed. However, the next time the user displays the page, the grid portlet does not appear. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlets list page appears. 2. 3. Select the check box next to the grid portlet you want to delete. Click Delete, then click Yes to confirm.

HTML Portlet
You can use an HTML portlet to display HTML data. You can use Studio to do the following:

Display news from a company Intranet site Display corporate telephone information Display portions of external web sites Display a recorded message

Chapter 7: Portlets 167

HTML Portlet

Create an HTML Portlet


Use the following procedure to create an HTML portlet. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The list of portlets appears. 2. 3. Click New and select HTML Portlet. Complete the following fields: 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. Required: Yes Portlet ID Defines a unique alphanumeric identifier for the portlet. Required: Yes Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Required: Yes Description Defines the purpose of the item being created and provides any relevant information. Active Specifies whether the portlet is active and users can see the portlet. You can edit inactive portlets and activate them later. Default: Selected

168 Studio Developer's Guide

HTML Portlet

Instance Type Specifies the type of page the portlet can be placed on. If you select General for this field, the portlet can be placed on any page. Values: Department, General, Location, Standard Rule, Portfolio, and Project Default: Department Required: Yes HTML Code Defines the HTML you want to display in the portlet. Required: Yes 4. Save your changes.

Modify an HTML Portlet


Use the following procedure to modify an HTML portlet. Follow these steps: 1. With the portlet open, change any of the following fields: 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. Required: Yes Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Required: Yes Description Defines the purpose of the item being created and provides any relevant information.

Chapter 7: Portlets 169

Interactive Portlets

Active Specifies whether the portlet is active and users can see the portlet. You can edit inactive portlets and activate them later. Default: Selected HTML Code Defines what displays in the portlet. Enter the HTML that you would like to display in the portlet. 2. Save your changes.

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 associated Flash variables to establish secured data transfers and to create context-aware visualizations. Use interactive portlets to:

Perform what-if analyses Set up alerts Drill down to go to more detailed information Mouseover areas to view more information

After the Xcelsius visualizations are imported into the interactive portlets, associate them with objects, such as the Project object or Resource object. You can 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. See the Personalizing CA Clarity User Guide for more information.

170 Studio Developer's Guide

Interactive Portlets

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. See the CA Clarity-Xcelsius Implementation Guide for more information. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlets page appears. 2. Click New and select Interactive Portlet from the menu that appears. The general page appears. 3. Complete the following fields: 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. Required: Yes Portlet ID Defines a unique alphanumeric identifier for the portlet. Required: Yes Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes Category Specifies the general area on which the portlet reports data. Values: Business Intelligence, Collaboration, Personal, Productivity, Project, and Resource Required: Yes Description Defines the purpose of the portlet and provides any relevant information.

Chapter 7: Portlets 171

Interactive Portlets

Active Specifies whether the portlet is active and users can see the portlet. 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 for this field, the portlet can be placed on any page. Values: Department, General, Location, Standard Rule, Portfolio, and Project Default: Department Required: Yes Dashboard File (.swf) Specifies the Flash (.SWF) file used as the data source for the interactive portlet. Add the file using the Upload SWF icon. Do not enter or copy the file path. Required: Yes 4. Save your changes. 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. Before you can create object or global parameters, your CA Clarity PPM administrator must first create the Xcelsius visualization and the required Flash variables and you must create the interactive portlet. 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. Follow these steps: 1. Open the interactive portlet. The general page appears. 2. Click Parameters. The parameters list page appears.

172 Studio Developer's Guide

Interactive Portlets

3.

Click New and select either Object Parameter or Global Parameter. The properties page appears.

4.

Complete the following fields: Global Parameter (Global Parameter only) Specifies the global parameter. Use this field to map the name you used to define the Flash variable in Xcelsius to this global parameter. Values: Business Objects Session ID, Business Objects Web Service URL, Clarity Session ID in SOAP Header, Clarity User Internal ID, Clarity User Name, Clarity Web Service URL, and Language Required: Yes Object (Object Parameter only) Displays the name of the object to which this object parameter is associated. Default: Department Required: Yes Field (Object Parameter only) Specifies the field name. Values: The values displayed are associated with the selected object. Required: Yes 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) If you choose Business Objects Session ID as the global parameter, the required value CELogonToken is the flash variable name, and this field is locked. Required: Yes Description Defines the description for the parameter. Limits: 240 characters Required: No

5.

Save your changes.

Chapter 7: Portlets 173

Publish Changes to a Portlet

Publish Changes to a Portlet


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. This means the following is overwritten:

Changes a user has created by personalizing the portlet Changes 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. Follow these steps: 1. Open Administration, and from Studio, click Portlets. The portlets list page appears. 2. Select the check box next to the name of the portlet you want to publish, and click Publish. The changes are published to the portlet.

Set User Configuration 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 icon in the portlets Options toolbar. When turned on, this option allows users to:

Configure column layout Configure column names and display properties Configure display options Add aggregation rows

174 Studio Developer's Guide

Restrict User Rights for a Specific Portlet or Portlet Page

Allow Label Configuration This option works 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)

Follow these steps: 1. With the portlet open, do one of the following:

For a grid portlet, open the List Column Section menu, and click Options. For a chart portlet, open the Chart Section menu, click Options.

The options page for the portlet appears. 2. Clear one or both of the following check boxes:

Allow Configuration Allow Label Configuration

3.

Save your changes.

Restrict User Rights for a Specific Portlet or Portlet Page


You can restrict access to portlets for individual users, groups, or OBS units. 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. Follow these steps: 1. 2. Open the portlet. Open the Access to this Portlet menu and click one of the following options:

Resource Group OBS Unit

Chapter 7: Portlets 175

Set a System View for a Portlet

3. 4.

Click Add. Select the rights you want to enable. Select from the following: Portlet - View Allows a user to view a portlet in the application. Portlet Definition Editor Allows a user to view and edit the definition of a portlet. This right is dependent on the Administration - Studio right.

5.

Click Add and Continue. A list of resources, groups, or OBS units appear. Note: Click the + icon to expand an OBS unit to see child OBS units.

6. 7.

Select the check box next to each resource, group, or OBS unit to be granted access rights. (OBS units only) For each OBS unit, select one of the following OBS association modes in the Default Association Mode field:

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.

8.

Click Add.

Set a System View for a Portlet


You can set up and maintain a grid or chart portlet that has the same view for all users by setting the Allow Configuration option and publishing the portlet changes. Follow these steps: 1. With the portlet open, do one of the following:

For a grid portlet, open the List Column Section menu, and click Options. For a chart portlet, open the Chart Section menu, and click Options.

The options page for the portlet appears. 2. 3. Clear the Allow Configuration check box. Click Save.

176 Studio Developer's Guide

Set a System View for a Portlet

4. 5.

Click General. Click Publish.

Chapter 7: Portlets 177

Chapter 8: Portlet Pages


This section contains the following topics: About Portlet Pages (see page 179) How to Create a Non-Tabbed Portlet Page (see page 180) How to Create a Tabbed Portlet Page (see page 182) Configure a Portlet Page Tab Set (see page 186) Rename a Portlet Page Tab (see page 188) How to Display Multiple Subpages on a Custom Portlet Page Tab (see page 188)

About Portlet Pages


You can distribute new pages to all or selected CA Clarity PPM users by creating global pages. The pages you create can be used to distribute content using the Home and Administration menus. Portlet pages are web pages that contain chart, grid, or HTML portlets. Create portlets, then use the information in this section to create or reuse HTML portlet pages, and manage tabs on the pages so that users can view and use the 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 Project Default Layout page Create a Business Intelligence page

Decide whether the new page contains tabs and how much control users have regarding the page. Tabbed pages can provide a useful way to group several related pages under a menu item. You can control whether a page can be personalized so that users can add portlets and create additional tabs. Once a user personalizes a page, those changes are not affected by changes made in Studio (except the addition of required portlets). Note: To verify that all users see the same page and any future changes, disable the Personalizable option.

Chapter 8: Portlet Pages 179

How to Create a Non-Tabbed Portlet Page

How to Create a Non-Tabbed Portlet Page


The following process explains how to set up a non-tabbed portlet page. 1. Create the portlet page (see page 180). Select the page type Page without Tabs when you create the portlet page. 2. 3. 4. Configure the portlet page (see page 181). Add the portlet page to the Home or Administration menu (see page 195). View the page in the application.

Create a Portlet Page


Before you create a portlet page you should know the following information:

User How a page is used determines the page template and the menu where the link to the page is placed. An end-user page is placed in the Home menu, and an administrator page is placed in the Administration menu.

Page type You can select a page type with or without tabs, or you can select from the existing default pages of stock master objects or custom objects.

Follow these steps: 1. Open Administration, and from Studio, click Portlet Pages. The portlet pages list page appears. 2. Click New. The create page appears. 3. Complete the following fields: Page Name Defines the name of the page. Page ID Defines a unique alphanumeric identifier for the page. Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes

180 Studio Developer's Guide

How to Create a Non-Tabbed Portlet Page

Type Specifies the type of page you want to create. Select Page with Tabs to create a tabbed page or Page without Tabs to create a single page. Master objects, custom objects, and classes have default portlet pages that you can select as the type of page you want to create. Description Defines the purpose of the item being created and provides any relevant information. Layout Specifies how portlets added to a page or a tab are placed. The number of columns indicates how many portlets can be placed on a row and indicates the percentage of the page given to each portlet on the row. The Row layout can have the one to three portlets in a row with equal space provided for each portlet. Personalizable Specifies if an end user can make personal changes to a page or a tab that only the end user can view. 4. Click Save and Continue. The OBS section appears. 5. If you are using OBS, complete the following fields: Department Specifies the OBS department associated with the portlet page. Location Specifies the OBS location associated with the portlet page. 6. Save your changes.

Configure a Non-tabbed Portlet Page


This procedure explains how to:

Add portlets to a portlet page Add a filter to a portlet page Design the layout of portlets Give a user or a group of users explicit rights to the page.

Follow these steps: 1. With the portlet page open, click Content.

Chapter 8: Portlet Pages 181

How to Create a Tabbed Portlet Page

2. 3.

Click Add. Select the portlet or portlets you want to add and click Add. The portlets are added to the content list.

4.

Click Save and Continue. The Page Filters tab activates, and the list of page filters appears.

5. 6.

Click Add. Select the appropriate filter for the page and click Add. The filter is added to the list of filters.

7.

Click Save and Continue. The Layout tab activates, and the layout page appears. Any content portlets and filter portlets you selected are listed in the layout columns.

8.

Place the portlets in the column you want by highlighting one or more and using the arrow keys to move the portlets from one column to another. Use the up and down arrows to change a portlet's position inside a column. You can change the column layout using the Column field.

9.

When the layout is complete, select Save and Continue to assign access rights to the page or click Save and Return to leave the portlet page.

How to Create a Tabbed Portlet Page


You can create a custom tabbed portlet page or you can add custom tabs to the default Project portlet page. The following process explains how to set up a portlet page. 1. Create the portlet page (see page 180). The portlet page type selected must be Page with Tabs. 2. (Optional) Set up link parameters for the portlet page (see page 183). If you want users to be able to link to the portlet page, you can assign a parameter that they see in a selection list for linking. 3. 4. 5. Create tabs (see page 183). Configure tabs (see page 184). Select user actions for tab menus (see page 187). Each tab has a menu that drops down below the tab name. You can select actions that display on the menus.

182 Studio Developer's Guide

How to Create a Tabbed Portlet Page

6. 7.

Add the portlet page to the Home or Administration menu (see page 195). View the page in the application.

Set Up Link Parameters for a Tabbed Portlet Page


Link parameters are selected by users who want to link to the portlet page from another page in the application. Follow these steps: 1. 2. 3. With the portlet page open, click Link Parameters. Click New. Complete the following fields: Parameter Name Defines a name for the link. This is the name that a user selects to create a link to this tab from an object or portlet. Parameter ID Defines a unique alphanumeric identifier for a link. 4. Save your changes.

Create a Tab
You can add a tab to the following page types:

A custom portlet page with the page type, Page with Tabs An object's default layout page, for example, the Project Default Layout page

Follow these steps: 1. 2. With the portlet page open, click Tabs. Click New. The tab list page appears. 3. Complete the following fields: Tab Name Defines the name of the tab. The name appears on the tab in CA Clarity PPM. Tab ID Defines a unique alphanumeric identifier for the tab.

Chapter 8: Portlet Pages 183

How to Create a Tabbed Portlet Page

Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes Description Defines the purpose of the item being created and provides any relevant information. Layout Specifies how portlets added to a page or a tab are placed. The number of columns indicates how many portlets can be placed on a row and indicates the percentage of the page given to each portlet on the row. The Row layout can have the one to three portlets in a row with equal space provided for each portlet. Personalizable Specifies if an end user can make personal changes to a page or a tab that only the end user can view. Linkable Specifies a tab can be linked to from another location in the application. 4. Save your changes.

Configure a Tab
This procedure explains how to:

Add a link parameter for a tab This option creates a parameter that appears in list for users to select if they want to create a link to the tab.

Add a portlet to a tab Add a filter to a tab Design the portlet layout for a tab

184 Studio Developer's Guide

How to Create a Tabbed Portlet Page

This procedure assumes that all portlets that are to be added to the tab already exist. Follow these steps: 1. With the portlet page open, click Tabs. The list of tabs appears. 2. Click a tab to configure. The properties page appears. 3. (Optional) Click Link Parameters. The tab must have the Linkable check box selected on the Properties tab before the Link Parameters option is available. 4. Complete the following fields: Parameter Name Defines a name for the link. This is the name that a user selects to create a link to this tab from an object or portlet. Parameter ID Defines a unique alphanumeric identifier for a link. 5. Click Save and Continue. The Content tab activates showing any portlets already added to a tab. 6. 7. Click Add. Select the portlets that you want to add by selecting the check box next to the portlet, and click Add. The portlets are listed in the content list for the tab. 8. Click Save and Continue. The Page Filters tab activates. 9. Click Add.

10. Select the appropriate page filter and click Add. The filter is added to the page filter list. 11. Click Save and Continue. The Layout tab activates. Any content portlets and filter portlets you selected are listed in the layout columns. 12. Place the portlets in the column you want by highlighting one or more and using the arrow keys to move the portlets from one column to another. Use the up and down arrows to change a portlet's position inside a column. You can change the number of columns using the Column field.

Chapter 8: Portlet Pages 185

Configure a Portlet Page Tab Set

13. When the layout is complete, select Save and Continue to assign access rights to the page or click Save and Return.

Configure a Portlet Page Tab Set


You can configure how a tab set for a portlet page appears to users. What you can configure in the tab set depends on the tabbed portlet page. The following table shows the tab set configuration actions and the tabbed portlet pages that allow the actions. Portlet page Custom tabbed portlet page What you can do to configure the tab set

Add or delete custom tabs (see page 183) Reorder Tabs (see page 187) Add or delete custom tabs (see page 183) Reorder Tabs (see page 187) Activate or deactivate tabs to control what displays (see page 186) Set a default tab to display initially (see page 186) Add or delete custom tabs (see page 183) Reorder Tabs (see page 187) Activate or deactivate tabs to control what displays (see page 186) Set a default tab to display initially (see page 186) Add object actions to the tab menu (see page 187)

Default portlet page (all objects)

Project Default Layout page Default portlet page

Activate or Deactivate Tabs


Deactivate a tab to leave it in the tab list but keep it from displaying to users. You can activate the tab if you want to include it in the application for users in the future. Follow these steps: 1. With the tabbed portlet page open, click Tabs. The list of tabs appears.

186 Studio Developer's Guide

Configure a Portlet Page Tab Set

2. 3. 4.

For each tab, select the Active check to display the tab or clear the check box to keep the tab from displaying. Select the Default option to indicate the tab that is to display initially when the portlet page opens. Save your changes.

Reorder Tabs
You can set the order in which tabs display in the application. Some default portlet pages have a set order for tabs and do not permit you to reorder those tabs. You can reorder tabs that you create. Follow these steps: 1. With the tabbed portlet page open, click Tabs. The list of tabs appears. 2. Click Reorder. The Tabs list box appears with the tabs in the current order. Any fixed tabs that you cannot reorder are listed above the Tabs list box. 3. 4. Highlight the tabs you want to move and use the arrow keys to move them into the correct order. Save your changes.

Select User Object Actions for a Tab Menu


You can select user object actions to appear on the drop-down menu that appears for each tab. Follow these steps: 1. With the tabbed portlet page open, click Configure Tabs. The list of tabs for the portlet page appears. 2. Click Actions for the tab you want to configure. A list of configure actions appears. 3. 4. In the Default column, select the object actions you want for the tab menu. Click Save.

Chapter 8: Portlet Pages 187

Rename a Portlet Page Tab

Rename a Portlet Page Tab


You can rename any stock or custom tab. Follow these steps: 1. Open Administration, and from Studio, click Portlet Pages. The list of portlet pages appears. 2. Open the portlet page. The properties page appears. 3. Click Tabs. The list of tabs for the page appears. 4. 5. 6. 7. Click the Translate icon next to the name of the tab you want to rename. Enter the new tab name in the appropriate language or languages, and click Save and Return. Click Properties. Click Publish to make the change visible to all users.

How to Display Multiple Subpages on a Custom Portlet Page Tab


You can create and use a custom properties view to display multiple subpages on a custom portlet page tab. The custom properties view can be used for custom objects only, not stock CA Clarity PPM objects. You can display subpage links on the tab as a menu option or a submenu option The process for displaying multiple subpages on multiple tabs using custom properties views includes the following basic steps: 1. Create a custom properties view (see page 189). The custom properties view defines a set of subpages and the content that appears on each subpage. 2. 3. Add subpages to the custom properties view (see page 189). Define the display of custom subpage links that appear on a custom portlet page tab (see page 191).

188 Studio Developer's Guide

How to Display Multiple Subpages on a Custom Portlet Page Tab

Create a Custom Properties View


A custom properties view can only be created for a custom object on the System partition. Once created, the properties view applies to all child partitions. Only the Layout:Edit option under Setup in the Views definition is available for a custom properties view. The following sections explain how to create and manage custom properties views. Note: Copy, View All, and Export to XML options are not available for custom properties pages. Follow these steps: 1. Open the custom object. The object properties page appears. 2. 3. 4. 5. Click Views. Click New. Enter the name of the new properties view and a unique ID. Click Save. The new properties view is added to the views list page.

Add a Subpage to a Custom Properties View


You can add five sub-pages at a time to a custom properties view. The number of sub-pages you can add to a properties view is unlimited. The custom properties view applies to custom objects only, not stock CA Clarity objects. Follow these steps: 1. With the custom object open, click Views. The views list page appears. 2. Locate the custom properties view and click [Layout:Edit] in the Setup column. The create page for subpages appears. 3. Enter a name and ID for each subpage you want to create and click Save and Return. The layout page appears showing the new subpages. 4. Populate the subpages with sections and attributes, and set up display conditions, if needed.

Chapter 8: Portlet Pages 189

How to Display Multiple Subpages on a Custom Portlet Page Tab

Move a Subpage Between Properties Views


If you have multiple properties views, you may need to move subpages from one properties view to another. This allows you to quickly change which view data is displayed for a tab. You can move subpages between stock and custom properties views. Follow these steps: 1. With the custom object open, click Views. The views list page appears. 2. Locate the custom properties view and click [Layout:Edit] in the Setup column. The layout page appears. 3. Select the check box next to the subpages you want to move to another properties view, and click Move. The selection page appears. 4. Select the option next to the properties view you want to move the subpages to, and click Move. The layout page reappears showing the subpage list without the moved subpages. 5. Click Return. The views list page appears. 6. Click [Layout: Edit] in the row of the properties set (view) you moved the subpages to. The moved subpages are listed in the layout page of the new view.

Delete a Subpage from a Custom Properties View


If a subpage is associated with a subobject, it cannot be deleted from a properties view. In this case, you can move the subpage to another properties view. A custom properties view applies to custom objects only, not stock CA Clarity objects. Follow these steps: 1. With the custom object open, click Views. The views list page appears. 2. Locate the custom properties view and click [Layout:Edit] in the Setup column. The layout page appears.

190 Studio Developer's Guide

How to Display Multiple Subpages on a Custom Portlet Page Tab

3.

Select the check box next to the subpage or subpages you want to delete and click Delete. The confirmation page appears.

4.

Click Yes.

Delete a Custom Properties View


The following rules apply to deleting a custom properties view:

Subpages linked to a subobject associated with the custom properties view must be moved to another properties view before the custom properties view can be deleted. Subpages linked to a subobject cannot be deleted. You cannot delete a custom properties view if it is associated with a custom tab. 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 properties view from the System partition. When you delete a custom properties view from the System partition, the view is also deleted from child partitions.

Note: A custom properties view applies to custom objects only, not stock CA Clarity objects. Follow these steps: 1. With the custom object open, click Views. The views list page appears. 2. Select the check box for the custom properties view, and click Delete.

Restore Defaults for a Custom Properties View


You can restore the defaults for a custom properties view 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 properties view is associated with a portlet page tab.

Display Custom Subpage Links on a Tab


For a custom object, you can display links for subpages on a tab in the tab's menu or as a submenu option on the tab's menu.

Chapter 8: Portlet Pages 191

How to Display Multiple Subpages on a Custom Portlet Page Tab

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 Custom Subpage Links as Menu Options


This procedure explains how to display a link for a custom subpage in a tab's menu. This procedure assumes:

The subpage links are being added to a custom object's default portlet page. The custom object has had a custom property view added.

Follow these steps: 1. Open Administration, and from Studio, click Portlet Pages. The portlet pages list page appears. 2. Click the name of the default custom portlet page. The properties page appears. 3. Click Tabs. The list of tabs for the portlet page appears. 4. 5. Click New. Complete the following fields: Tab Name Defines the name of the tab. The name appears on the tab in CA Clarity PPM. Tab ID Defines a unique alphanumeric identifier for the tab. Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes 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.

192 Studio Developer's Guide

How to Display Multiple Subpages on a Custom Portlet Page 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. 9. Save your changes. View the changes in the application.

Display Subpage Links as Submenu Options


This procedure explains how to display a link for a custom subpage in a tab menu. This procedure assumes:

The subpage links are being added to a custom object's default portlet page. The custom object has had a custom property view added.

Follow these steps: 1. Click Portlet Pages from the Studio menu. The portlet page list appears. 2. Click the name of the default custom portlet page. The properties page appears. 3. Click Tabs. The list of tabs for the portlet page appears. 4. 5. Click New. Complete the following fields: Tab Name Defines the name of the tab. The name appears on the tab in CA Clarity PPM. Tab ID Defines a unique alphanumeric identifier for the tab. Content Source Specifies where the data that appears in a portlet or portlet page originates. Default: Customer Required: Yes 6. In the Layout field, select Subtabs. The View field appears directly below the Layout field.

Chapter 8: Portlet Pages 193

How to Display Multiple Subpages on a Custom Portlet Page Tab

7.

In the View field, select the custom view with subpages you want to appear on the tab menu. 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 Content tab activates. Use this page to define submenu options.

9.

Click New. A new row appears where you can define additional submenu options.

10. Complete the following actions for each submenu you want to add for the tab's menu: a. Enter a name in the Subtab field. The name you enter in the subtab field appears as the submenu name in the tab's menu. b. c. Enter a unique identifier in the Subtab field. Select a property set (view) in the View (Subpage) field. The property view you select appears in the submenu defined by the Subtab field. d. Click Save.

11. Click Return. 12. View the changes in the application.

194 Studio Developer's Guide

Chapter 9: Menu Manager


This section contains the following topics: How to Work with CA Clarity PPM Menus (see page 195) Add a Menu Section (see page 196) Add a Menu Page Link (see page 197) Add a Menu Action Link (see page 198) Edit a Menu Section or Link (see page 198) Reorder a Menu Section or Link (see page 199) Remove a Menu Section or Link (see page 200)

How to Work with CA Clarity PPM Menus


The navigation area displays on the left side of all CA Clarity PPM pages. You can manage the Administration and Home menus from Menu Manager in Studio. You can also manage the Favorites menu from the Configure Favorites link that appears in the Favorites menu. Use the menu hierarchy page to display all sections, page links, and action links, and to manage the Home and Administration menus. To open the menu hierarchy page 1. 2. Open Administration, and from Studio, click Menu Manager. Click the name of the menu you want to edit. The menu hierarchy page appears.

Chapter 9: Menu Manager 195

Add a Menu Section

The following illustration shows the menu hierarchy page for the Home menu.

See the CA Clarity Basics User Guide for more information. You can do the following to manage menus:

Add new sections (see page 196). Add new page links (see page 197). Add new action links (see page 198). Reorder a section, page link, or an action link (see page 199). Edit links and menu sections (see page 198). Remove a section, page link, or an action link (see page 200).

Add a Menu Section


Follow these steps: 1. Open Administration, and from Studio, click Menu Manager.

196 Studio Developer's Guide

Add a Menu Page Link

2.

Click the name of the menu you want to edit. The menu hierarchy appears.

3.

Click Add. The create page appears.

4.

Select Section and click Next. The menu item properties page appears.

5.

Complete the following fields: Section Name Defines the name for the section. Section ID Defines the unique identifier for the section. Description Defines the purpose for the section or page link.

6.

Click Save and Return.

Add a Menu Page Link


Follow these steps: 1. 2. Open Administration, and from Studio, click Menu Manager. Click the name of the menu you want to edit. The menu hierarchy appears. 3. Click Add. The create page appears. 4. Select Page Link and click Next. The menu item properties page appears. 5. Complete the following fields: Link Name Defines the name of the page link. This is the label for the page link that displays in the menu. Description Defines the purpose for the section or page link. Page Name Specifies the page to display when the link is clicked.

Chapter 9: Menu Manager 197

Add a Menu Action Link

Parent Menu Item Specifies the section in which this link will appear. 6. Click Save and Return.

Add a Menu Action Link


Use this procedure to add an object action that performs a task to one of the menus. Follow these steps: 1. 2. Open Administration, and from Studio, click Menu Manager. Click the name of the menu you want to edit. The menu hierarchy appears. 3. Click Add. The create page appears. 4. Select Action Link and click Next. The menu item properties page appears. 5. Complete the following fields: Link Name Defines the name of the link that performs an action. This is the label for the link that displays in the menu. Description Defines the purpose of the link. Action Name Specifies the action that occurs when the link is clicked in the menu. Parent Menu Item Specifies the section in which the link appears. 6. Click Save and Return.

Edit a Menu Section or Link


This procedure explains how to make changes to the menu sections, page links, and action links that appear in the Administration or Home menus. The fields that display on the menu item properties page depend on the type of menu item you open to edit.

198 Studio Developer's Guide

Reorder a Menu Section or Link

Follow these steps: 1. 2. Open Administration, and from Studio, click Menu Manager. Click the name of the menu you want to edit. The menu hierarchy appears. 3. Click the name of the menu item you want to edit. The menu item properties page appears. 4. Edit the following fields: Link Name Defines the name of the page link. This is the label for the page link that displays in the menu. Section Name Defines the name for the section. 5. Click Save and Return.

Reorder a Menu Section or Link


Use this procedure to reorder sections that display in menus. Follow these steps: 1. 2. Open Administration, and from Studio, click Menu Manager. Click the name of the menu you want to edit. The menu hierarchy appears. 3. 4. 5. Click Reorder. In the Menu Items list box, select a section and click the up or down arrows to move the section to a new position. Click Save and Return.

Note: If you don't see your changes reflected in the menu, click the Refresh button.

Chapter 9: Menu Manager 199

Remove a Menu Section or Link

Remove a Menu Section or Link


Use this procedure to remove a menu section, page link, or action link. You can only remove sections or links that you have created. You cannot remove CA Clarity PPM default sections or links. If you remove a section or link that is being viewed by a user, the user will not notice a difference. However, the next time the user displays the menu, the section or link that you removed will not display. Follow these steps: 1. From the menu hierarchy, select the check box next to the section or link you want to delete, and click Remove. The confirm menu item delete page appears. 2. Click Yes.

200 Studio Developer's Guide

Chapter 10: Object Actions


This section contains the following topics: About Object Actions (see page 201) How to Create and Set Up an Object Action (see page 204) Edit an Object Action (see page 211) Delete or Deactivate an Object Action (see page 211) Create an Actions Menu for Object Actions (see page 212) Determine the Order for Menus (see page 213) Add an Object Action Link to the Home Menu (see page 213)

About Object Actions


An object action is a shortcut link to another location in CA Clarity PPM or to a function like running a job or a report. It is a way to configure the user interface and streamline the workflow for users. You can create and place an object action in the Actions menu on a page where the user needs it, significantly reducing the number of clicks needed to complete a task. The following illustration shows an Actions menu with default object actions displayed for a project properties page.

Chapter 10: Object Actions 201

About Object Actions

The General menu is the default menu. This menu contains the appropriate system object actions for each page on which it displays. You can create additional menus and add object actions to make them easy for users to find. If no object actions are listed for a menu, the menu does not display. You can create object actions that:

Run a report Run a process Run a job View another page in CA Clarity PPM View an external Internet site

Note: When you place an object action in the Actions menu, you do not have to publish to make the object action visible to users. Object actions are automatically visible to users, even those who have personalized views. Some stock object actions are provided with CA Clarity PPM. For example, New Project and New Resource are stock object actions that are provided with CA Clarity PPM. You can use the stock object actions or create object actions that are specific to your business needs.

Where You Can Place Object Actions


An object action can be placed in the Actions menu on any page that corresponds to a view in the object definition. You cannot define an action menu at the sub-page level. The following page types do not support menus for object actions:

Pages that do not have a view Pages that have one or more portlets (for example, dashboards) Pages that combine a view and portlets

Object Action Scope


Global object actions can be performed in CA Clarity PPM without having to identify a specific object instance. New Project and New Resource are examples of stock object actions that are global. The default scope for a new object action is global. Global object actions created for an object are available to add to all tabs on the object's pages in CA Clarity PPM, and global object actions can be added to the Home menu.

202 Studio Developer's Guide

About Object Actions

Instance-specific object actions require a user to select an instance or reference an instance before the object action is launched. For example, if you create an object action named Delete Risk that is intended to delete specific risks, that action is instance-specific and would require the user to identify the risk to delete before running the action. Whether an action's scope is defined as global or instance-specific depends on the type of action. The following table shows the object action types and how they can be defined. Object Action Report Job Process Internal Link External Link Scope can be defined as Global or instance-specific Global or instance-specific Instance-specific only Instance-specific only Global or instance-specific

Object Actions Access Rights


No special access rights are required to use object actions. However, a user must have access rights for the individual functions that can be launched from the Actions menu. For example, if a user does not have the access right to run a report, the object action for the report does not appear in the user's menu. In the case of a list view, if a user does not have access rights on one of the selected instances, the action displays but an error is received if the user attempts to execute the action.

Chapter 10: Object Actions 203

How to Create and Set Up an Object Action

How to Create and Set Up an Object Action


The following process provides the basic steps for setting up an object action on a page. 1. Create one of the following object actions:

Report (see page 204) Job (see page 206) Process (see page 207) Internal Link (see page 208) External Link (see page 209)

2. 3.

Set up the menu on a page and add the object action (see page 212). (Optional) Add the object action to the Home menu (see page 198).

Create a Report Object Action


You can set up a report object action to run automatically when a user selects the object action from a menu. You provide report parameters when you create the object action by mapping the parameters to value attributes on the object instance. Prerequisites

A user must have access rights to the report definition to run a report. If the user does not have access rights to the report definition, the object action for the report does not display in the Action menu. The report parameters for a report cannot be mapped to value attributes outside the partition of an object's view. The report must be active.

Follow these steps: 1. 2. Open the object. Click Actions. The action list appears. 3. Click New. The create page appears. 4. Complete the following fields: Action Name Defines the name of the action that appears in the Actions menu for the user.

204 Studio Developer's Guide

How to Create and Set Up an Object Action

Action ID Defines a unique identifier for the object action. Description Defines the purpose of the object action. Type Specifies the type of object action. Select Report. Select Report Specifies the report to launch from the Actions menu. Scope Specifies whether an object action is global or limited to an object instance. Values:

Global. Allows the end user to run the action without having to select an object instance. This option also makes the object action available to be added to any view within any object and to the Home menu. Instance-specific. Allows the end user to select an object instance before running the action. An instance-specific object action can only be added to the views for the object under which the object action was created. Instance-specific object actions cannot be added to the Home menu.

5.

Complete the following fields in the Attribute Mapping section: Parameters Displays the parameter fields that display when you run an instance-specific object action from the application. The parameters vary depending on the object action. Default Values Displays the global default values entered for parameters of an instance-specific object action in the application. You can change the default values for the object action. Object Attribute Overrides Specifies the object attributes that can override the default values listed for instance-specific object actions. Within an Object Attribute Overrides field, you can map only to attributes of the same data type as the value in the Parameter field.

6.

Save your changes.

Chapter 10: Object Actions 205

How to Create and Set Up an Object Action

Create a Job Object Action


You can set up a job object action to run automatically when a user selects the option from a menu. You provide job parameters when you create the object action by mapping them to value attributes on the object instance. Prerequisites

A user must have access rights to the job definition to run a job. If the user does not have access rights to the job definition, the object action for the job does not display in the Action menu. The job parameters for a job cannot be mapped to value attributes outside the partition of an object's view. The job must be active.

Follow these steps: 1. 2. 3. Open the object. Click Actions. Click New. The create page appears. 4. Complete the following fields: Action Name Defines the name of the action that appears in the Actions menu for the user. Action ID Defines a unique identifier for the object action. Description Defines the purpose of the object action. Type Specifies the type of object action. Select Job Specifies the job to be launched from the Actions menu by the user. Alert users before running the job Specifies whether the user is alerted before the job runs. Select the check box to alert the user.

206 Studio Developer's Guide

How to Create and Set Up an Object Action

Scope Specifies whether an object action is global or limited to an object instance. Values:

Global. Allows the end user to run the action without having to select an object instance. This option also makes the object action available to be added to any view within any object and to the Home menu. Instance-specific. Allows the end user to select an object instance before running the action. An instance-specific object action can only be added to the views for the object under which the object action was created. Instance-specific object actions cannot be added to the Home menu.

5.

Complete the following fields in the Attribute Mapping section: Parameters Displays the parameter fields that display when you run an instance-specific object action from the application. The parameters vary depending on the object action. Default Values Displays the global default values entered for parameters of an instance-specific object action in the application. You can change the default values for the object action. Object Attribute Overrides Specifies the object attributes that can override the default values listed for instance-specific object actions. Within an Object Attribute Overrides field, you can map only to attributes of the same data type as the value in the Parameter field.

6.

Save your changes.

Create a Process Object Action


The processes available to be selected for creating a process object action are the current active on-demand processes and auto-start processes defined for an object, and any generic processes. Prerequisites

A user must have access rights to start a process. If the user does not have access rights to start a process, the object action for the process does not display in the Action menu. The parameters for a process cannot be mapped to value attributes outside the partition of an object's view. The process must be active.

Chapter 10: Object Actions 207

How to Create and Set Up an Object Action

Follow these steps: 1. 2. 3. Open the object. Click Actions. Click New. The create page appears. 4. Complete the following fields: Action Name Defines the name of the action that appears in the Actions menu for the user. Action ID Defines a unique identifier for the object action. Description Defines the purpose of the object action. Type Specifies the type of object action. Select Process Specifies the process to be launched from the Actions menu by the user. Alert users before running the process Specifies whether the user is alerted before the process runs. Select the check box to alert the user. 5. (Optional) Complete the field in the Define Primary Object section if you plan to run this object action outside the primary object's view. For example, if you plan to run an object action named Approve Risk (where Risk is the primary object) from the Project object view, you must map to an attribute that belongs to the Project object. 6. Save your changes.

Create an Internal Link Object Action


The Internal Link object action lets a user navigate to a specific page from a link within an object view. You can specify the page for the link. Prerequisites

A user must have access rights to view the page that the link refers to. If the user does not have access rights to the page, the object action for the link does not display in the Action menu. The link must already exist.

208 Studio Developer's Guide

How to Create and Set Up an Object Action

Follow these steps: 1. 2. 3. Open the object. Click Actions. Click New. The create page appears. 4. Complete the following fields: Action Name Defines the name of the action that appears in the Actions menu for the user. Action ID Defines a unique identifier for the object action. Description Defines the purpose of the object action. Type Specifies the type of object action. Select Link Specifies the page opened from the Actions menu by the user. Select the page for the link from the drop-down list. The list includes all links displayed on the Linking tab for the object. 5. Save your changes.

Create an External Link Object Action


The External Link object action lets a user navigate to an external URL outside of CA Clarity PPM from a link within an object view. Follow these steps: 1. 2. 3. Open the object. Click Actions. Click New. The create page appears. 4. Complete the following fields: Action Name Defines the name of the action that appears in the Actions menu for the user.

Chapter 10: Object Actions 209

How to Create and Set Up an Object Action

Action ID Defines a unique identifier for the object action. Description Defines the purpose of the object action. Type Specifies the type of object action. Scope Specifies whether an object action is global or limited to an object instance. Values:

Global. Allows the end user to run the action without having to select an object instance. This option also makes the object action available to be added to any view within any object and to the Home menu. Instance-specific. Allows the end user to select an object instance before running the action. An instance-specific object action can only be added to the views for the object under which the object action was created. Instance-specific object actions cannot be added to the Home menu.

Enter URL Defines the URL that is to appear on the Actions menu for the user to select. Enter the URL that is to appear. For example: http://support.ca.com/. 5. If you selected instance-specific for the scope, complete the Define URL Arguments section by completing the following fields: Number of Arguments Specifies the number of arguments (name+value pairs) to be included as parameters. Select a number to indicate the number of name+value pairs you want to include. The name+value pairs are appended to the end of the URL. The values are URL-encoded when they are appended to the URL. Argument # Indicates the name in the name+value pair used as a parameter for an external link object action. Enter a name. Argument # - Value Indicates the value in the name+value pair used as a parameter for an external link object action. Select one of the options to indicate whether the value is a constant or an instance-specific value, and provide the value. You must select an object attribute for the instance-specific value. The attributes listed in the drop-down list are associated with the object on which the object action is being created. 6. Save your changes.

210 Studio Developer's Guide

Edit an Object Action

Edit an Object Action


This procedure explains how to make changes to an object action to change its definition. For stock object actions, you can modify only the name and description. For user-defined object actions, you can modify all fields except the ID and action type. Follow these steps: 1. With the object open, click Actions. The action list appears. 2. Click the name of the action you want to edit. The details page for the object action appears. The Action ID cannot be edited after the object action is created and saved. 3. 4. Make your changes. Save your changes.

Delete or Deactivate an Object Action


When you delete an object action, it no longer appears in the menu, and the action is removed from the list of actions for the object. The object action itself is removed from the CA Clarity PPM database. When you deactivate an object action, it is hidden from end users. You cannot delete or deactivate actions provided with CA Clarity PPM; you can only manually remove them from a menu for a specific view. The actions available for deletion or deactivation have check boxes next to them. Follow these steps: 1. With the object open, click Actions. The action list appears. 2. Select the check box next to the action, and click Delete or Deactivate.

Chapter 10: Object Actions 211

Create an Actions Menu for Object Actions

Create an Actions Menu for Object Actions


A menu on the Actions menu is a way to group object actions. All active object actions and global actions defined within any object are available to be added to a menu in an object's list or properties view. The General menu is the default menu. You can add or remove object actions from the default menu, or you can create your own menus and position them where you want in the menu display. If you want a menu to appear on the list and the properties view, you must create a menu for each view. Note: The following stock object actions are not available for custom property pages on custom objects: Copy, View All, and Export to XML. Follow these steps: 1. 2. With the object open, click Views. Click Actions Menu in the Setup Column. The actions menu page appears. 3. Click New. The create page appears. 4. Complete the following fields: Menu Name Defines the menu name. Menu Code Defines a unique alphanumeric identifier for the menu. Description Defines the purpose of the menu. 5. Select the object actions you want to appear under the menu in the Available Actions list box and move them to the Selected Actions list box. Use the up and down arrow keys to place the actions into the correct order in the Selected Actions list box. 6. Save your changes.

212 Studio Developer's Guide

Determine the Order for Menus

Determine the Order for Menus


Menus are ordered individually on the Menu Definition tab. You can configure the order in which the menus appear from the Menu Layout tab. To determine the order for menus 1. With the object open, click the Views tab. The view list appears. 2. 3. 4. 5. Click Actions Menu in the Setup column of the appropriate view. Click Menu Layout. Highlight menus in the Menus list box and use the up and down arrows to move the menus into the order you want to display. Save your changes.

Add an Object Action Link to the Home Menu


Follow these steps: 1. 2. 3. 4. 5. Open Administration, and from Studio, click Menu Manager. Click Application Menu. Click Add. Select Action Link and click Next. Complete the following fields: Link Name Defines the name of the link that performs an action. This is the label for the link that displays in the menu. Description Defines the purpose of the link. Action Name Specifies the action that occurs when the link is clicked in the menu. Parent Menu Item Specifies the section in which the link appears. 6. Click Save and Return.

Chapter 10: Object Actions 213

Chapter 11: Time-Scaled Values


This section contains the following topics: About Time-Scaled Values (see page 215) How to Set Up Calendar Time-Scaled Values (see page 216) Custom Fiscal Time-Scaled Values (see page 219) Test a New Time-Scaled Value (see page 222) Display Multiple Time-Scaled Values in a List Column (see page 223)

About Time-Scaled Values


A time-scaled value field is one that you can set up on a list page or a grid portlet that shows a value for a specific period of time. A time-scaled value is based on a time-varying attribute for which a user enters values in CA Clarity PPM. You can create time-varying attributes of the following types:

Calendar. This time-varying attribute is tied to a resource calendar that represents work or availability. The calendar is a standard Gregorian calendar that contains time off, vacations, and holiday exceptions. The calendar and its exceptions determine the values of the time-varying attribute. Calendar time-scaled values can be included on list column views or grid portlets. Fiscal. This time-varying attribute is tied to a fiscal time period. It represents money, usually costs or benefits, as they change over time. The fiscal time-periods are associated with an instance of an entity. Fiscal time periods have no relationship to a standard calendar. A fiscal time-scaled value can appear only on the list view of a subobject.

The list page or portlet shows a virtual column in which value amounts can be broken out and displayed for specific time periods. The values that display in a time-scaled value field are calculated by a time-slice job that determines the value of each time period represented in the virtual column.

Chapter 11: Time-Scaled Values 215

How to Set Up Calendar Time-Scaled Values

How to Set Up Calendar Time-Scaled Values


The following steps explain how to set up a calendar time-scaled value field in a list column view or a grid portlet. 1. 2. Create the time-varying attribute that the time-scaled value will use (see page 61). Complete the following actions from the properties view:

Add the time-varying attribute to the properties view (see page 86). The time-varying attribute must appear in the properties view for the user to enter values for the attribute in CA Clarity PPM.

3.

Complete the following actions for the list column view for an object or for a grid portlet: a. b. Create a virtual column and add the time-varying attributes to the column (see page 216). Add the virtual column to the list column view (see page 219).

4.

Set up a time slice request for each time-varying attribute. See the Administration Guide for more information.

5.

Run the Time Slicing job. This job can be set up to run on a schedule that suits your business needs. See the Administration Guide for more information.

6.

Test the time-scaled value in CA Clarity PPM (see page 222).

Create a Virtual Column for a Time-Scaled Value


This procedure explains how to create a virtual column and add the time-scaled value fields to the column for both the list column view and for a grid portlet. If you are configuring the list view for a subobject, you see additional fields not available for a master object. The fields allow you to select an attribute from the master object whose value sets the start time or the time scale for the subobject. Follow these steps: 1. Complete one of the following actions:

For an object's list view, open the object, click Views, and click Fields in the object's list view. For a grid portlet, open the portlet, open the List Column Section menu, and click Fields.

2.

Click New.

216 Studio Developer's Guide

How to Set Up Calendar Time-Scaled Values

3. 4.

Select Time Scaled Value and click Save and Continue. In the General section, complete the following fields: Value Attributes Specifies the time-scaled values that are to display in the virtual column. 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. Column Label Defines the name of the virtual column in which the time-scaled value appears. Display Type Specifies how the time-scaled value is to display, as a number, a column, or a bar chart. Secondary Value Specifies the secondary value that you want to display in the virtual column. (Optional) Link Specifies the page that appears when the user clicks the link. Open as Pop-up Specifies whether the page opens as a pop-up. Select the check box to open the page as a pop-up. Allow Editing Specifies whether a user can edit fields. Select the check box to allow editing. Show Legend Column Indicates whether the field label appears next to the time-scaled value in the virtual column. Select the check box to display the field label. Show Column Label Indicates whether the column label displays at the top of the virtual column. Select the check box to display the column label.

Chapter 11: Time-Scaled Values 217

How to Set Up Calendar Time-Scaled Values

5.

In the Time Scale section, complete the following fields: Start Date Indicates the start date for time period for the virtual-scaled value. Values:

Specific Date. Click the Datepicker icon to select a date. Rolling Date. Click the down arrow to select a relative date. Other Date. This option appears only if you are selecting a start date for a time-scaled value for a subobject. This field allows you to select a field from the master object on which to base the start date. This option only appears when a subobject has time-scaled value attributes.

Time Scale Specifies the length of time the time-scaled value covers. Values:

Specific Time Scale. Indicates by naming a specific length of time what the period for the time-scaled value is. Click the down arrow to select a specific period of time. Other Time Scale. This option appears only if you are selecting a time scale for a time-scaled value for a subobject. The field lets you select a field from the master object on which to base the time scale.

Number of Time Periods Defines the number of time periods that will be reported in the virtual column. Time Period Offset Defines the number of time periods you want to offset what displays from the start date. For example, if you want to start the display two time periods from the indicated start date, enter 2. Show Group Row Header Specifies a timescale is to be displayed above the virtual column. Select the check box to display a timescale and select the period type you want from the drop-down list. 6. 7. In the Display Options sections, select the appropriate settings for displaying the time-scaled value in CA Clarity PPM. Save your changes.

218 Studio Developer's Guide

Custom Fiscal Time-Scaled Values

Add a Virtual Column


Follow these steps: 1. Complete one of the following actions:

For a list column view, open the object, then open the Views menu and click Layout. For a grid portlet, open the portlet, then open the List Column Section menu and click Layout.

The layout page appears. 2. 3. 4. 5. In the Column Layout section, use the arrow buttons to move the name of the virtual column to the Selected Columns list box. Set any other options on the page that apply. Click Save. Click Publish to replace personalized changes users have made to this view.

Custom Fiscal Time-Scaled Values


You can create custom fiscal timescale values that follow the fiscal calendar year using time-varying attributes. These values are tied to fiscal time-periods and represent data that changes over time. For example, you can track the cost of a project over time. The fiscal time-periods are associated with a financial entity and have no relationship to a standard calendar. Prerequisites The following prerequisites must be met to create a fiscal timescale value:

The object on which the time-varying attribute is to be added must be a subobject or the subobject of a subobject The master object must be associated with a department OBS that has a financial entity.

By Example: Custom Fiscal Time-varying Attribute This example illustrates using a custom fiscal time-varying attribute to enter additional financial information for a project cost plan.

Chapter 11: Time-Scaled Values 219

Custom Fiscal Time-Scaled Values

A financial manager at INR Financial creates a cost plan for the EVM System Development project for the year 2010. The total cost incurred by the Development group for this project for the first three months of the year is $ 60,000. The financial manager uses two custom fiscal time-varying attributes, Committed and Actual in the Cost Details column to enter a monthly break-down of the total cost in terms of:

The amount that was originally committed for development The amount that was actually spent on development

This additional financial information allows the finance manager to more closely monitor if actual costs run over committed costs.

Controlling Fiscal Time-Scaled Values


A custom fiscal time-scaled value is always created on a subobject. When the time-scaled value is created, additional attributes are automatically created and pre-populated on the master object (if they do not already exist). These attributes control the span of time-scaled values, and the attribute values must be modified with the correct information about the master object for fiscal time-scaled values to work properly. The attributes that get pre-populated on the master object include:

Entity Code. Determines the entity with which the fiscal time-varying attribute is associated. This value is automatically populated when an instance of the master object is associated to a Department OBS unit. Fiscal Period Type. Determines the time period type (Monthly, Quarterly, Annually) on which the fiscal time-varying attribute is based. Fiscal Period Start Date. Determines the absolute beginning of the time-scaled values beyond which you cannot scroll in the past. If you do not provide this date, the time-scaled values are not limited to scrolling in the past except to the extent that fiscal time periods do not exist. Fiscal Period End Date. Determines the absolute end of the time-scaled values beyond which you cannot scroll in the future. If you do not provide this date, the time-scaled values are not limited to scrolling in the future except to the extent that fiscal time periods do not exist.

The Cost Plan and Benefit Plan objects include the additional master object attributes as defaults. The values given to these attributes when a new instance is created preset the timescale for the fiscal time-scaled values that appear on the subobject. For objects other than the Cost Plan or Benefit Plan, the addition of a time-varying attribute to the object's subobject causes the additional required attributes to be added to the object. However, you must add the attributes to the object's properties view.

220 Studio Developer's Guide

Custom Fiscal Time-Scaled Values

Example of Fiscal Time-Scaled Values in the Subobject The master object Cost Plan has a subobject named Cost Plan Detail. A time-scaled value field is created and placed on the list column view of the subobject Cost Plan Detail. The master object attributes that are required for the time-scaled value to display already exist for Cost Plan on the properties view. When an instance of the Cost Plan object is created, the period type is given a value of quarterly and the period start date is defined as September 1, 2010. When the user opens the Cost Plan Detail for the new instance for the first-time, the timescale period shows a start date of September 1, 2010 and a quarterly time period.

How to Create a Custom Fiscal Time-Scaled Value Field


The Cost Plan and Benefit Plan objects include the following attributes out-of-the-box:

Fiscal Period Type Fiscal Period Start Date Fiscal Period End Date

For other objects, these attributes are added to the list of attributes for the object automatically when you create a fiscal time-varying attribute on one of its subobjects. The following describes how to set up a custom fiscal time-scaled value field for a subobject. This process assumes that the object and subobject have been created already.

Chapter 11: Time-Scaled Values 221

Test a New Time-Scaled Value

1.

Verify the master object of the subobject is associated with a Department OBS and a fiscal entity. See the Administration Guide for more information.

2.

Complete the following tasks for the subobject: a. Create the time-varying attribute for the subobject (see page 61). Use the same partition and partition association mode as the master object. b. c. d. Add the time-varying attribute to the subobject's properties view (see page 86). Create a virtual column for the time-scaled value and add the time-varying attributes to the column (see page 216). Add the virtual column to the subobject's list column view (see page 219).

3.

Complete the following task for the master object:

Add the following attributes to the master object's properties view (see page 86).

Fiscal Period Type Fiscal Period Start Date Fiscal Period End Date

This step is not required for the Cost Plan and Benefit Plan objects.

Test a New Time-Scaled Value


The following steps explain how to test a new time-scaled value field that has been added to an object's list column view: 1. Create an instance of the object to which the time-scaled value is associated. For example, if the time-scaled value is associated with the project object, create a new project in CA Clarity PPM. 2. Include values in the new instance for the time-scaled value field you want to test. For example, if the time-scaled value field is "Actual Cost", enter a value in the field. 3. View the results of the values entered for the field by displaying object's list page or the grid portlet's page and viewing the virtual column setup for the time-scaled value.

222 Studio Developer's Guide

Display Multiple Time-Scaled Values in a List Column

Display Multiple Time-Scaled Values in a List Column


You can display multiple time-scaled values in the same list column view. The data for the attributes displays as stacked on the page, with the information for each time-scaled value appearing in the same virtual column. The data that displays can be in units of money, numbers, or percentages. 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.

Chapter 11: Time-Scaled Values 223

Chapter 12: NSQL Queries


This section contains the following topics: About NSQL Queries (see page 225) NSQL Syntax (see page 226) NSQL Constructs (see page 228) User-Defined Constructs (see page 229) Advanced NSQL Constructs (see page 234) Create a Query (see page 234) About Lookups (see page 236) Hierarchical Queries (see page 238) NSQL Troubleshooting and Tips (see page 239)

About NSQL Queries


Before you can create a portlet to extract and display data in CA Clarity PPM, you must 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. NSQL facts:

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. CA does not recommend using NSQL for reporting or for stored procedures. Anything in the database can be used to call stored procedures.

When you define an NSQL query, you identify the query segments and designate them as metric values, dimensions, dimension properties, or parameters. All these terms, and the overall query definition process, are described in the following sections. With NSQL, you can access data in the CA Clarity PPM database and create queries in Studio and use them to create new portlets. Because queries are not directly associated with a single portlet, the same query can be used to produce data for multiple portlets.

Chapter 12: NSQL Queries 225

NSQL Syntax

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.

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 and any additional required tables.
Select FROM Select @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@, @Select:DIM_PROP:IMPLIED:PRJ:P.Name:ProjectName@ SRM_PROJECTS P @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 -------------------------------------------------------------

226 Studio Developer's Guide

NSQL Syntax

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 FROM WHERE Select @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@, @Select:DIM_PROP:IMPLIED:PRJ:P.Name:ProjectName@ SRM_PROJECTS P @FILTER@ AND P.Is_Active=1 @ 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 WHERE @FILTER@ AND SRM_PROJECTS.ID=PRTeam.prProjectID AND SRM_RESOURCES.ID=PRTeam.prResourceID SRM_PROJECTS, SRM_RESOURCES, PRTEAM

-------------------------------------------------------------------------

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 named 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.

Chapter 12: NSQL Queries 227

NSQL Constructs

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 WHERE HAVING SELECT FROM WHERE GROUP BY HAVING NBI_PROJECT_CURRENT_FACTS P @FILTER@ @HAVING_FILTER @SELECT:DIM:USER_DEF:IMPLIED:PROJECT:C.MANAGER_LAST_NAME:MANAGER@, @SELECT:METRIC:USER_DEF:IMPLIED:SUM(C.ACT_HOURS):Actuals:AGG@, NBI_PROJECT_CURRENT_FACTS C C.MANAGER_LAST_NAME is not null C.MANAGER_LAST_NAME @HAVING_FILTER@ AND @FILTER@

-------------------------------------------------------------------------

NSQL Constructs
The constructs described in this section expand to become elements of an NSQL query based on the CA Clarity PPM operational model.

228 Studio Developer's Guide

User-Defined Constructs

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@

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 because 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

Chapter 12: NSQL Queries 229

User-Defined Constructs

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 and then you can define the other data elements in the dimension.

Defining the Dimension Column


Each dimension must contain a definition for the dimension column. Typically, this is the tables 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 Select Select @Select:DIM:USER_DEF:IMPLIED:Project:SRM_PROJECTS.ID:ProjectID@ @Select:DIM:USER_DEF:IMPLIED:PRJ:P.ID:ProjectID@ @Select:DIM:USER_DEF:IMPLIED:MyDim:SRM_Projects.Name:ProjectName@ @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@

230 Studio Developer's Guide

User-Defined Constructs

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.

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 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. Use IMPLIED if the data type does not need to be further quantified (than what can be derived from the database). <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:DIM_PROP:USER_DEF:IMPLIED:<Dimension>:<Table.Field>:<label>@

SELECT

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 preceding statement, the unique name of the dimension is the same for the three columns. This tells the NSQL engine that the three columns belong together.

Chapter 12: NSQL Queries 231

User-Defined Constructs

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 chart. 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 because metrics cross dimensions. Use IMPLIED if the data type does not need to be further quantified (than what can be derived from the database). <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

232 Studio Developer's Guide

User-Defined Constructs

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 and and i.act_status = s.id and s.language_code = @where:param:language@ i.xdm_impact = imp.id and imp.language_code = @where:param:language@ i.xdm_issue_type = isstype.id and isstype.language_code =

@where:param:language

Chapter 12: NSQL Queries 233

Advanced NSQL Constructs

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

Security
Projects or resources appear only in a grid or chart when a user has sufficient access rights. Use SECURITY in the WHERE clause to verify the users 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).

Create a Query
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

234 Studio Developer's Guide

Create a Query

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. You cannot modify a query that is associated with an object, and you cannot delete a query that has an association with a portlet. Important! If an NSQL querys 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. Follow these steps: 1. Open Administration, and from Studio, click Queries. The queries list page appears. 2. 3. Click New. Complete the following fields: Query Name Defines the name of the query. Required: Yes Query ID Defines a unique alphanumeric identifier for the query. Content Source Specifies where the data for a query originates. Category Specifies the general area that a query reports data on. Description Defines the purpose of the item being created and provides any relevant information. 4. Click Save and Continue. The NSQL tab activates. 5. 6. Enter your NSQL statement in the query window. Click Save and Continue. The Attributes tab activates. 7. 8. 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. The Linking tab activates.

Chapter 12: NSQL Queries 235

About Lookups

9.

To define links to another table, click New and complete the following fields: Name Defines the name of the link. Link ID Defines a unique alphanumeric identifier for the link. Description Defines the purpose of the item being created and provides any relevant information. Action Specifies a destination for the link. When the link is selected, additional fields can appear to complete the link definition. Complete the fields as needed.

10. Save your changes. 11. Click Return.

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. This lookup consists of a standard set of choices. These lookups are often used as drop-down or browse lists for reports, user-defined fields, and user-defined XDM forms. Static Dependent List. This lookup provides 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. These lookups fetch data from the CA Clarity PPM database in real time to populate the drop-down or browse lists. These lookups provide the most up-to-date values possible.

236 Studio Developer's Guide

About Lookups

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 log in to CA Clarity PPM.
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@

See the Administration Guide for more information.

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 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@

Chapter 12: NSQL Queries 237

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 parameters 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 rowimmediate 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.

238 Studio Developer's Guide

NSQL Troubleshooting and Tips

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. Verify 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 @SELECT statement. A comma after the last table listed in the FROM clause. Incorrect table name.

Use the following tips to help ensure NSQL successful queries:


When you create queries for use with pie charts and funnel charts, verify 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.

Chapter 12: NSQL Queries 239

Chapter 13: UI Themes


This section contains the following topics: About UI Themes (see page 241) Stock UI Themes (see page 241) Select a New UI Theme (see page 242) Select a UI Theme for a Partition (see page 242) Custom UI Themes (see page 243) Exporting and Importing UI Themes (see page 249)

About UI Themes
UI themes determine the look and feel of CA Clarity PPM application pages. CA Clarity PPM ships with a default UI theme and alternate UI themes that you can select to change the color, log in information, branding, and other aspects of the user interface. You cannot delete the UI themes that ship with CA Clarity PPM. You can also create a custom UI theme that is specific to your business needs. A custom UI theme lets you go beyond the changes that are present in the alternate themes provided with CA Clarity PPM. You can customize the logo, the application name, tabs, buttons, icons, and other features.

Stock UI Themes
CA Clarity PPM offers the following standard UI themes that you can select to change the way the user interface looks:

Default Red Blue Black and White

To see what the alternate UI themes look like, select and try each one.

Chapter 13: UI Themes 241

Select a New UI Theme

Select a New UI Theme


When you select a new UI theme, you do not have to publish the changes. You see the change to the new theme immediately. Other users see the change on the next login. Follow these steps: 1. Open Administration, and from Studio, click UI Themes. The UI themes list appears. 2. Select the theme you want and click Save.

Select a UI Theme for a Partition


You can associate a distinctive theme, including color and logo, for users who are members of a partition. Partitions without a designated UI theme setting inherit the UI theme of its closest ancestor partition that does have a UI theme. A user who is not a member of any partition always sees the UI theme of the system partition. A user who belongs to multiple partitions with different UI themes can go to Account Settings and select a default partition to determine which UI theme is used. Follow these steps: 1. Open Administration, and from Studio, click Partition Models. The partition models list appears. 2. 3. 4. Click the name of the partition model you want to view. Click Partitions. Click the name of the partition to which you want to assign a UI theme. The properties page appears. 5. 6. In the UI Theme field, select the theme. Click Save and Return.

242 Studio Developer's Guide

Custom UI Themes

Custom UI Themes
If the stock UI themes do not meet your business needs, you can create a custom UI theme by copying and modifying the CSS text of one of the stock themes. The following illustration shows the basic areas in the application that can be customized:

Main header Main Menu bar and menus CA Clarity PPM page

Although you can modify virtually any item in the user interface, the following table shows the items that CA recommends for modification. User Interface Area Main page header Recommended modification items

Logo Company name Links Icons Font Color (application background)

Chapter 13: UI Themes 243

Custom UI Themes

User Interface Area Main menu bar and menus

Recommended modification items


Menu bar icons (Back, Recent Pages, Refresh, Home, Search) Menu icons (Next, Previous, Refresh) Font Color Font Color (workspace background, buttons, headers, tabs, portlets) Tab style Button style Portlet header

Workspace

CSS Stylesheet
The CSS standard used for the CA Clarity PPM stylesheet is CCS3. This standard uses the following format:
/* Comments */ class_name { individual style individual style }

Comments in the stylesheet help you to identify the area in the user interface you want to modify.

244 Studio Developer's Guide

Custom UI Themes

Create a Custom UI Theme


The best practice for creating a custom UI theme is to modify a stock UI theme that is closest to the look-and-feel you want. This method provides you with predefined UI features that you can tweak until you have the look you want. Important! You can edit styles in the CSS stylesheet, but do not remove them. Removing a style can cause the UI to render incorrectly. CA Clarity PPM always expects a theme to be applied, and the styles that are specified in the Default UI theme are required. Follow these steps: 1. In CA Clarity PPM, open Administration, and from Studio, select UI Themes. The UI themes list appears. 2. Click the name the UI theme that is closest to the look that you want. The properties page appears displaying the CSS stylesheet. 3. 4. Select and copy all of the text in the CSS text box, and click Return. Click New. The create page appears. 5. 6. 7. Paste the copied text into the CSS text box. Make the necessary modifications to the CSS stylesheet in the CSS text box. Complete the following fields: Name Defines the name of the UI theme. In lists, displays the name of the UI theme. ID Defines a unique identifier. Limits: 60 characters Required: Yes Active Specifies if the UI theme is active and can be selected and used in CA Clarity PPM. Default: Selected 8. 9. Click Save and Return. Display the new theme (see page 242).

Chapter 13: UI Themes 245

Custom UI Themes

Application Page Header Examples


The following examples show how you can modify the CSS text from a stock UI theme to alter items in the main page header. Example: Change the Name To change the product name, replace Clarity PPM with a new name in the statement.
/* The product name itself */ #ppm_header_product span:before, #ppm_header_product_small span:before { content: "Clarity PPM"; }

Example: Change the Main Page Background Color To change the background color of the main page, locate the following statement and define the color you want.
/* The main page background color */ .ppm_page_bg { background: #04152d; background: -webkit-gradient(radial,50% 10, 1, 50% 100, 600, from(#052E5F), to(#04152D )); background: -moz-radial-gradient(50% 10% 0deg,ellipse contain, #052E5F, #04152D); }

Example: Change the Logo Convert any images you plan to use to base64. Free tools are available on the Internet that let you convert an image into a base64 string. You can paste the base64 encoded string within the area in the CSS shown in the following example. The example shows only the beginning and ending lines of the base64 string.
/* The logo in the upper left hand corner of the page header */ #ppm_header_logo { background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAqCAYAAADxughHAAAKMEl EQVRo3s1Z93eT5xX+AFvykoe85C3b2tuSLMmSB95gbMwIJcwwbGagISRAFg0JK6xAmGGUk7TNaU8T aEvapOn4157eez/JFtYnR7I5PfnhHun79I773Pvc8b5S9NV2LElqFsj/e/4CUfLb2EHfbdA3haC3j kBvG4feTtIxAL3JNz+mRnt+UUrq7Ci1OWHocsHgJwm6UGp1yvvUuHzB5QCEFK/3kMJrUTh0Csru30 E59D2UA395WQ7/A8q2x9AljkDf3j8PmqTYZEc5KVu7M4CWyzGYHyTQdjeOtjtpQs/mLxNovhBF7Y4 AytxOFdDygahK6J3roGx9oCo6+5zkGZSZZ+pnusi75yqogy+wauI8itoTqIw70HwuKkqKwrdzEAZF YOtngihpJ4NU2ZYIxGiFvs6Nwv7j8xbXUj6b8Nj95LU3n6Du8maY70ZyA7BAGHzTxxGhn67ClicQA eFC4eA75IW/q1bOB0S6MJgjBObipqWD+W0v6vZ3objZAd0inlEy6FTVAV1shrzwV9UTi1k9XbKN2/ cD9CcuofHaKMx3 ...

246 Studio Developer's Guide

Custom UI Themes

fhOr5aQMVuT5ABoyhtVuuJGiM+n/zIVDK/1iMW5aLDLmXrdX08ChNRhzcuJRqxVVhZ/p2BsBcFCBl BlKPNAmdVKzLH2YP8O8eH5Y1e8R4bjinLYL2nh+B7fxjxB5MyjtdoGA7DflAdx17l57p4FyocXkka bMz+r6cFsFJqISBk4SrajN3KlmKOM7V6yBtsKQZiP9Av1uh9ul5czYrwJtVBv2zCijIw9ki5xQ33i UGhEgNKPJwSBZvGulUQtBZ7l/fjuGRDsAe8Z1Qrs+LMfV7LQfuw1dmTTEGmHevINGSaJ0inpvFual UsnH7VSslNGG/Grqry+MS6TDmmEr/jjMZW4UDlAGSFSxqppXB6hT78zO+L6x2SnotNNM7skvhhT/M eMo6szRmKPdVC1uR57O3QxXFJCmwgpmVNd0BSMAc3z2HD1EQCydTsFoC19Jz6z0R56cg5l69tydxt g/bv6XVg4efL33WLzaP3EqMeldqcQPq+Wi9Ks4LzvZQtY52Fz7+QFmW+DxMx2vJe43816f1xNGKfh AAAAABJRU5ErkJggg==); margin: 6px 0px 0px 15px; width: 50px; height: 42px; }

Main Menu Examples


Example: Change Color and Font The following statement controls the color and fonts used in the main menu bar.
/* The main omnibar/navigation bar below the header */ #ppm_omnibar { background-color: #7791AB; background: -moz-linear-gradient(#7791AB, #4C6786); background: -webkit-gradient(linear, center top, center bottom, from(#7791AB), to(#4C6786)); background: linear-gradient(#7791AB, #4C6786); -pie-background: linear-gradient(#7791AB, #4C6786); color: #001122; font-family: Helvetica Neue,Arial,sans-serif; font-weight: bold; }

Example: Change Main Menu Hover Styles


/* The omnibar button hover styles */ .ppm_omnibar_button:hover { border: 1px solid #566a7c; } /* The styles of the primary navigation menus when hovered */ .ppm_nav_menu_hover { background-color: #f5f8fa; color: #335588; }

Chapter 13: UI Themes 247

Custom UI Themes

Workspace Examples
Example: Change Workspace Background Color
/* Button styles */ .ppm_button { border-top: 1px solid #c4d1e1; border-bottom: 1px solid #889ab5; border-left: 1px solid #bccee4; border-right: 1px solid #889ab5; background: -webkit-gradient(linear, center top, center bottom, color-stop(0, #ebf4fc), color-stop(.5, #d9e9fc), color-stop(.52, #c6ddf6), color-stop(1,#c3d3eb)); background-image: -moz-linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); background: linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); -pie-background-image: linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); }

Example: Change Tab Style


/* Top-level tabs */ .ppm_tab { background-color: #B3C8DB; background: linear-gradient( #B3C8DB, #92A8BE ); background: -moz-linear-gradient(#B3C8DB, #92A8BE); background: -webkit-gradient(linear, 0% 100%, 0% 0%, from(#B3C8DB), to(#92A8BE)); filter: progid:DXImageTransform.Microsoft.Gradient( GradientType=0, startColorStr='#B3C8DB', endColorStr='#92A8BE' ); } /* Top-level selected tab */ .ppm_sel_tab { background-color: #E8EBF2; background: -moz-linear-gradient(#FFF, #e3e7ec); background: -webkit-gradient(linear, center top, center bottom, from(#FFF), to(#e3e7ec)); background: linear-gradient(#FFF, #e3e7ec); filter: progid:DXImageTransform.Microsoft.Gradient( GradientType=0, startColorStr='#FFFFFF', endColorStr='#e3e7ec' ); }

/* The top-level tab labels */ .ppm_tab > a, .ppm_sel_tab > a { }

Example: Change Button Style

248 Studio Developer's Guide

Exporting and Importing UI Themes

/* Button styles */ .ppm_button { border-top: 1px solid #c4d1e1; border-bottom: 1px solid #889ab5; border-left: 1px solid #bccee4; border-right: 1px solid #889ab5; background: -webkit-gradient(linear, center top, center bottom, color-stop(0, #ebf4fc), color-stop(.5, #d9e9fc), color-stop(.52, #c6ddf6), color-stop(1,#c3d3eb)); background-image: -moz-linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); background: linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); -pie-background-image: linear-gradient(center top, #ebf4fc 0%, #d9e9fc 50%, #c6ddf6 52%, #c3d3eb 100%); } /* Button styles when hovered */ .ppm_button:hover { background: -webkit-gradient(linear, center top, center bottom, color-stop(0, #f8fbff), color-stop(.5, #e4effb), color-stop(.52, #d1e4f8), color-stop(1,#c5d5eb)); background-image: -moz-linear-gradient(center top, #f8fbff 0%, #e4effb 50%, #d1e4f8 52%, #c5d5eb 100%); background: linear-gradient(center top, #f8fbff 0%, #e4effb 50%, #d1e4f8 52%, #c5d5eb 100%); -pie-background-image: linear-gradient(center top, #f8fbff 0%, #e4effb 50%, #d1e4f8 52%, #c5d5eb 100%); }

Exporting and Importing UI Themes


You can export or import a UI theme using the XML Open Gateway. This effort requires that you use the specific UI themes XML read and write files provided with the XML Open Gateway. To restore UI themes to the default settings, you can import the UI themes XML write file using the XML Open Gateway. CA recommends making a backup of the UI themes XML write file as a precaution. See the XML Open Gateway Developer Guide for more information.

Chapter 13: UI Themes 249

Chapter 14: Add-ins


This section contains the following topics: About Add-ins (see page 251) Updates to Add-Ins (see page 251) Apply an Update for an Add-In to CA Clarity PPM (see page 252)

About Add-ins
An add-in is a collection of content that can include portlets, pages, access groups, processes, reports, and jobs. The content in an add-in provides an efficient way to get started with CA Clarity PPM. For the content from the add-in to be available to use in CA Clarity PPM, the add-in must be deployed to your environment by a system administrator. Important! If your environment was customized prior to installing or updating an add-in, note the following: Customizations to Studio objects (that is, views, portlets, pages, and so on) can be overwritten when an add-in is applied. If your system contains Studio customizations, it is important to consider what is being applied as part of the add-in to avoid overwriting the Studio configurations.

Updates to Add-Ins
When updates or fixes for add-ins become available, they can be applied by a system administrator. Once the update has been applied by the system administrator, you have an opportunity to accept the changes being delivered in the add-in. While this option is not always available (for example, a fix being delivered must be installed directly to the database), typically you can review and accept updates to items being delivered.

Chapter 14: Add-ins 251

Apply an Update for an Add-In to CA Clarity PPM

Apply an Update for an Add-In to CA Clarity PPM


Follow these steps: 1. Open Administration, and from Studio, click Add-ins. The add-ins page appears. 2. Click the name of the add-in from which you want to apply items. The add-in details page appears showing the following columns. Status Indicates whether the add-in item is applied in CA Clarity PPM. Values:

Not Installed. New items that are new to this add-in version or that you did not apply from a previous add-in version. Upgrade Ready. Modified items that you applied from a previous add-in version and then configured. An update to the item is included in the current add-in 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 becomes the ID of the applied add-in item. 3. Review each selected item and accept only those changes you want. Only those items you select are updated. Note: When items are selected to be updated, any items that are dependent on the selected items are also selected to be updated. 4. Click Apply when the selected list of items to be updated is acceptable.

252 Studio Developer's Guide

Appendix A: Access Rights


This section contains the following topics: Basic Studio Access Rights (see page 253) Object Access Rights (see page 253) Portlet Access Rights (see page 254) Portlet Pages Access Rights (see page 255) Partition Model Access Rights (see page 256) Menu Manager Access Rights (see page 256) Add-in Access Rights (see page 257)

Basic Studio Access Rights


The following basic access rights are required so that you can access the Administration menu and the Studio menu: Administration - Access Allows the user to access the Administration menu. Type: Global Administration - Studio Allows a user to navigate to Studio menus. Without this right, a user does not see the CA Clarity Studio menu in the Administration menu. This right is dependent on having a license to Studio. Type: Global

Object Access Rights


The following rights can be used to work with objects in Studio: Custom Objects Editor Allows users to edit the definition of a custom object. Type: Global

Appendix A: Access Rights 253

Portlet Access Rights

Object - Create Definition Allows a user to create a custom object. Type: Global Object Administration Allows a user to administer all custom objects. Type: Global

Portlet Access Rights


The following access rights can be used to work with portlets: Portlet Create Allows a user to create new portlets. Type: Global Portlet Definition Editor Allows the user to edit and view the definition of a specific portlet. Requires: Administration - Studio to access the Studio menu. Type: Instance Portlet Definition Editor - All Allows a user to edit and view the definitions of all portlets available from Studio. Requires: Administration - Studio to access the Studio menu. Type: Global Portlet Navigate Allows a user to navigate to the portlet configuration pages. Type: Global Portlet - View Allows users to view a specific portlet. Type: Instance Portlet Viewer - All Lets you view and add stock portlets to portlet pages. The right helps add a stock portlet to a personal dashboard. Type: Global

254 Studio Developer's Guide

Portlet Pages Access Rights

Portlet Pages Access Rights


The following rights can be used to work with portlet pages: Page Definition Editor Allows users to edit, view, and delete the definition of a specific page. Required: Administration - Studio access right to access the CA Clarity Studio menu. Type: Instance Page Definition Editor - All Allows users to edit, view, and delete the definition of all pages. Required: Administration - Studio access right to access the CA Clarity Studio menu. Type: Global Page Definition Viewer Allows the user to view the definition of a specific page. Required: Administration - Studio access right to access the CA Clarity Studio menu. Type: Instance Page Definition Viewer - All Allows the user to view the definition of all pages. Required: Administration - Studio access right to access the CA Clarity Studio menu. Type: Global Page - View Allows users to view a general page in CA Clarity PPM. For instance pages (such as portfolio pages), this right is not required. Type: Instance Page Viewer - All Lets the user view any configured portlet page. Before the users can view them, link the portlet pages to a menu. The user requires the rights to navigate the menu. For example, if a page links to the Administration menu, the users require the Administration - Access right. Type: Global

Appendix A: Access Rights 255

Partition Model Access Rights

Partition Model Access Rights


The following access rights can be used to work with partitions: Administration - Partition Models Allows users to manage partition models. Requires: Administration - Access Type: Global System Partition - Administer Allows a user to administer the System partition. Type: Global

Menu Manager Access Rights


The following access rights can be used to work with the menu manager: Menu Definition Editor - All Allows a user to edit and view the definitions of all menu items for the Navigator or Administration menu. Type: Global Menu Definition Viewer - All Allows a user to view the definitions of all menu items for the Navigator or Administration menu. Type: Global Note: To see all menu items in Studio, you must have the following rights:

Administration - Access Administration - Partition Models Administration - Studio Menu Definition Viewer - All

256 Studio Developer's Guide

Add-in Access Rights

Add-in Access Rights


The following access rights can be used to work with add-ins: Add-In Administer Allows a user to administer add-ins. Type: Global

Appendix A: Access Rights 257

Appendix B: Stock Objects


The following stock objects are provided with CA Clarity PPM: 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 help 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. 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 This object contains benefit plan information used for the Benefit Plan list page. Benefit Plan Detail This object describes benefit plan information used to enter proposed returns on an investment. Change Requests This object describes the criteria by which change requests are evaluated and approved. This is a subobject of the Project object. Company This object provides descriptive information about companies including as Account Manager, Category, Company Type, Industry, Contact, and Rating. Cost Plan This object contains the attributes used on the Cost Plan and Budget list pages. Cost Plan Detail This object details the cost plan information used to create cost projection scenarios and budget revisions for an investment. 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.

Appendix B: Stock Objects 259

Add-in Access Rights

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 This is an abstract object that contains the base attributes for all CA Clarity PPM investments. Issue This is a risk that has been realized. This object enables risk property management to help increase the likelihood of project success. Location This object represents a company's geographical location, or a unit it the company's location organizational breakdown structure (OBS). 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.

260 Studio Developer's Guide

Add-in Access Rights

Project

Project Financial Properties This object stores project properties information that appears on the Financial subpage for projects. Resource

Resource Financial Properties

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. 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. This is a subobject of the Project object. 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 a project to look at documents, discussions, calendars, and properties, but is 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

This is a subobject of the Project object. Transaction Header

Transaction Line

Appendix B: Stock Objects 261

Appendix C: Stock Portlets


This section contains the following topics: Stock Chart Portlets (see page 263) Stock Grid Portlets (see page 264) Stock Filter Portlets (see page 267) Restricted Stock Portlets (see page 267)

Stock Chart Portlets


The following list shows stock CA Clarity PPM chart portlets that you can use on a portlet page. Balance Balance. ID: Balance Category: Business Intelligence Type: Portfolio Benefits by Goal Benefits by goal. ID: Benefits by Goal Category: Business Intelligence Type: Portfolio Planned Cost/Benefit Planned cost and benefit. ID: Cost/Benefit Category: Business Intelligence Type: Portfolio Planned Costs Planned costs. ID: Budgeted Costs Category: Business Intelligence Type: Portfolio

Appendix C: Stock Portlets 263

Stock Grid Portlets

Portfolio Planned ROI/Alignment Zones Portfolio Planned ROI/Alignment Zones. ID: ROI/Alignment Zones Category: Business Intelligence Type: Portfolio Risk/Reward Quadrants Risk reward quadrants. ID: Risk/Reward Quadrants Category: Business Intelligence Type: Portfolio

Stock Grid Portlets


The following list shows stock CA Clarity PPM grid portlets that you can use on a portlet page. Allocation Discrepancy Team members who have an actuals as opposed to allocation discrepancy above or below a specified threshold. ID: projmgr.allocationDiscrepancy Category: Resource Type: Grid Booking Status Booking status. ID: projmgr.bookingStatus Category: Resource Type: Grid Financials Financials. ID: Financials Category: Business Intelligence Type: Grid

264 Studio Developer's Guide

Stock Grid Portlets

Gantt Gantt. ID: Gantt Category: Business Intelligence Type: Grid Investments Investments. ID: Investments Category: Business Intelligence Type: Grid OBS Investment Aggregation Investment demand aggregated by OBS. ID: projmgr.OBSInvestmentAggregation Category: Project Type: Grid OBS Resource Aggregation Resource demand aggregated by OBS. ID: projmgr.OBSResourceAggregation Category: Resource Type: Grid Resource Workloads Resource workloads. ID: projmgr.resourceWorkloads Category: Resource Type: Grid Rights by License Type Rights by license type. ID: rightsbylicensetype Category: Business Intelligence Type: Grid

Appendix C: Stock Portlets 265

Stock Grid Portlets

Rights by User Rights by user. ID: userrights Category: Business Intelligence Type: Grid Role Capacity Role capacity. ID: projmgr.roleCapacity Category: Resource Type: Grid Team Utilization Displays the team-based use for the current project. Provides a detailed picture of total usage as opposed to allocation. ID: projmgr.teamUtilization Category: Project Type: Grid Unfilled Requirements Unfilled allocations. ID: projmgr.unfilledAllocations Category: Resource Type: Grid User Count by License Type User count by license type. ID: usercountbylicensetype Category: Business Intelligence Type: Grid User List by License Type User list by license type. ID: userlistbylicensetype Category: Business Intelligence Type: Grid

266 Studio Developer's Guide

Stock Filter Portlets

Weekly Detail Weekly detail. ID: projmgr.weeklyDetail Category: Resource Type: Grid

Stock Filter Portlets


The following list shows stock CA Clarity PPM filter portlets that you can use on a portlet page. Scenario Toolbar Scenario toolbar. ID: ScenarioToolbar Category: Business Intelligence Type: General

Restricted Stock Portlets


The following list shows stock CA Clarity PPM restricted portlets that you can use on a portlet page. Restricted portlets cannot be modified. You can however create new portlets to fit your exact business needs. Action Items Action items assigned to a user or created by a user. ID: calendar.myActionItems Category: Collaboration Type: Restricted Chart List chart. ID: PriortizedListChart Category: Business Intelligence Type: Restricted

Appendix C: Stock Portlets 267

Restricted Stock Portlets

Favorite Links Links. ID: nde.homeFavLinks Category: Personal Type: Restricted Favorite Photo Photo. ID: nde.homePhoto Category: Personal Type: Restricted General General information for a project. ID: project.General Category: Project Type: Restricted Labor Effort Labor resource effort for a project. ID: project.Effort Category: Project Type: Restricted Links Links defined for a project. ID: project.Links Category: Project Type: Restricted My Projects Favorite projects. ID: projmgr.homeHotList Category: Project Type: Restricted

268 Studio Developer's Guide

Restricted Stock Portlets

My Reports Reports. ID:reporting.myReports Category: Personal Type: Restricted Notifications Summary count of notifications by category. ID: personal.notificationsNuggest Category: Collaboration Type: Restricted Scenario Filter for selecting scenarios. ID: project.scenarioFilter Category: Project Type: Restricted

Appendix C: Stock Portlets 269

Appendix D: Data Providers


This section contains the following topics: About Data Providers (see page 271) System Type Data Providers (see page 271)

About Data Providers


Data providers, the source of list and chart portlet data, are special data constructs that can be accessed directly with portlets or through queries. The following list shows the data provider types: Queries CA Clarity PPM provides a query language named NSQL, which is similar to SQL and can be used 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. System System types are data providers for the restricted portlets. You can use these data providers in addition to stock CA Clarity PPM object data providers. Objects The stock CA Clarity PPM objectand any objects you createcontain fields that you can use to access database information.

System Type Data Providers


System types are data providers that are not based on a specific CA Clarity PPM object. The following table describes each system type. Type Action Item System Data Provider Actuals vs Allocation Discrepancy Aggregation Investment List Description The data provider recommended for building action item portlets. Data provider for the Team object that can be filtered to show team members that have an actual vs allocation discrepancy over a certain threshold. Data provider for displaying a list of investments aggregation.

Appendix D: Data Providers 271

System Type Data Providers

Type Assigned Change Requests Assigned Issues Assigned Risks Entity Hierarchy Key Tasks OBS Investment Aggregation OBS Resource Aggregation Portfolio: All Investment Types

Description Data provider for displaying assigned change requests. Data provider for displaying assigned issues. Data provider for displaying assigned risks.

This is a subset of the Task object and contains data about key tasks. Data provider for displaying investments OBS aggregation. Data provider for displaying resources OBS aggregation. Data provider for portfolios that contain mixed investment types. (All)

Portfolio: Projects only Data provider for portfolios that contain only the Project investment type. Portfolios Resources with Aggregation Resources with Availability Roles with Resource Aggregation Scenario List Task Dependencies Team Allocations Data provider for displaying a portfolio list. Data provider for resources with time-scaled and team-based aggregation support. Data provider to showing a list of resources with availability. Data provider for role resources with time-scaled and resource/team-based aggregation support. Data provider for the list of portfolio and capacity planning scenarios. Data provider for displaying task dependencies. Data provider for the Team object with time-scaled and aggregation support.

272 Studio Developer's Guide

Appendix E: Stock Object Actions


The following table lists the stock object actions that are available with CA Clarity PPM. The following definitions apply:

Generic. Indicates that an object action can be added to tabs on the Project Default Layout portlet page. Global. Indicates that an object action can be added to any view for any object and to the Home menu. Object Action ID Generic Global Can Be Added to All Views of the Object

Object

Object Action Description Name

Action Item

New Action Item

Creates a new action item

npt.setObjectUserP No artitions projmgr.baselineRe No visionProperties projmgr.baselineRe No visionUpdateClick

Yes

Yes

Baseline Baseline Baseline

New Baseline Creates a new baseline Update Baseline Update Cost Totals Add Benefit Plan Detail Updates a baseline

No No No

Yes No Yes

Update earned projmgr.baselineRe No value cost totals visionEarnedValueU pdate Adds benefit revmgr.benefitplan plan detail rows detailProperties to a benefit plan Approves the budget No

Benefit Plan Detail

No

Yes

Cost Plan

Approve Budget

revmgr.costplanList No ApproveBudget revmgr.costplanList No RejectBudget

No

Yes

Cost Plan Cost Plan

Reject Budget Rejects the budget

No No

Yes Yes

Set as Plan of Sets the revmgr.markPlanCu No Record selected cost rrent plan as the plan of record

Appendix E: Stock Object Actions 273

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Cost Plan

Submit Plan of Record for Approval

Submits the cost plan of record for budget approval

revmgr.submitForA pproval

No

No

Yes

Cost Plan Detail

Add Cost Plan Adds cost plan revmgr.costplandet No Detail detail rows to a ailNew detail cost plan New Budget Plan Detail Adds budget revmgr.budgetplan plan detail rows detailNew to a budget plan No

No

Yes

Cost Plan Detail

No

Yes

Cost Plan Detail

Populate from Investment Team Populate from Task Assignments Submit for Approval

Creates cost revmgr.populateFro No plan detail rows mResourcePlan from the investment team Creates cost revmgr.populateFro No plan detail rows mTaskAssignments from the task assignments Submits the cost plan of record for budget approval Adds a department Creates a new department revmgr.submitForA pproval No

No

Yes

Cost Plan Detail

No

Yes

Cost Plan Detail

No

Yes

Department Department Fiscal Time Period Fiscal Time Period

Add Department New Department Activate

revmgr.locationDep No artmentsToAdd revmgr.department No PropertiesNew No

No Yes No

No Yes No

Makes the fiscal revmgr.activateTim time period ePeriods active

Deactivate

Makes the fiscal revmgr.deactivateTi No time period mePeriods inactive

No

No

274 Studio Developer's Guide

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Fiscal Time Period GL Account Location Location Portfolio Project

New Fiscal Time Period New GL Account Add Location

Creates a new fiscal time period Creates a new GL account Adds a location

revmgr.timePeriod New revmgr.glAccountN ew

No

No

Yes

No

Yes No Yes Yes No

Yes No Yes Yes No

revmgr.department No AddLocations revmgr.locationNe w No

New Location Creates a new location New Portfolio Creates a new portfolio Add Dependency Add Subproject Add to My Projects Adds a dependent project Adds a subproject to the project Adds the project to the My Projects portlet Creates a project from the selected project template

pma.portfolioNewO No bjectAction projmgr.selectProje No ctDependencies projmgr.selectSubPr No ojects projmgr.hotListMe mberInsert No

Project

No

No

Project

No

No

Project

Copy Project from Template

projmgr.selectProje Yes ctTemplate

No

Yes

Project Project Project Project Project

Create Baseline Go to Links page Go to Notes page New Benefit Plan New Change Request

Creates a new projmgr.createBasel No project baseline ine Navigates to the Links page Navigates to the Notes page Creates a new benefit plan projmgr.linkList projmgr.noteList revmgr.newBenefit plan Yes Yes Yes Yes

No No No No No

Yes No No No No

Creates a new itl.changeNew change request

Appendix E: Stock Object Actions 275

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Project

New from Investment Team New from Task Assignments New Issue New Manual Plan New Project New Risk New Task New WBS Task

Creates a new cost plan from the Investment Team Creates a new cost plan from the task assignments Creates a new issue Creates a new manual cost plan Creates a new project Creates a new risk Creates a new task

revmgr.newCostpla No nFromInvTeam

No

No

Project

revmgr.newCostpla No nFromTaskAssgn

No

No

Project Project

itl.issueNew

Yes

No No

No No

revmgr.newCostpla Yes n projmgr.projectNew No itl.riskNew projmgr.newTask Yes Yes

Project Project Project Project

Yes No No No

Yes No No No

Creates a new projmgr.newWBSTa No task and adds it sk to the WBS page

Project

Remove from Removes the projmgr.hotListItem No My Projects project from Delete the My Projects portlet Book Resources New Resource Replace Books the resources for the project Creates a new project resource Replaces the resource resource.loadResou No rcesForBooking projmgr.resourceNe No wOptions_odf resource.replaceRes No ources

No

No

Resource

No

No

Resource

Yes

Yes

Resource

No

No

276 Studio Developer's Guide

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Task Task

Add Existing Tasks Add Hyperlinks to Task Add Notes to Task Assign Resource to Task Copy Task from Template Link Tasks

Adds selected tasks

projmgr.wbsLinkToT No asks No

No No

No No

Adds hyperlinks projmgr.linkList to the task Adds notes to the task projmgr.noteList

Task Task

No

No No

No No

Assigns the projmgr.wbsTaskLis No resource to the tAssignClick task Creates a new task as a copy of a template task Creates task dependencies for selected tasks Updates the earned value cost totals in the Task list page Updates the earned value cost totals on the WBS page projmgr.selectProje No ctTemplate

Task

No

No

Task

projmgr.wbsGridCre No ateDependency

No

No

Task

Update Cost Totals

projmgr.updateEarn No edValueAction

No

No

Task

Update Cost Totals

projmgr.wbsupdate No EarnedValueAction

No

No

Team

Accept Hard Allocation Accept Hard Allocation

Confirms projmgr.resourcePr No acceptance of a ojectsSelitemCheck hard allocation Confirm2 Accepts hard allocation for the selected team projmgr.teamSelite mCheckConfirm No

No

No

Team

No

No

Team

Add Resource Allocates the Allocation selected team resource

pma.selectResource No Investments

No

No

Appendix E: Stock Object Actions 277

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Team Team

Add Team Member Add/update by OBS

Adds a team member Adds or updates team properties by OBS

projmgr.resourceOb No jectSelectionList projmgr.staffOBSUp No dateProperties

No No

No No

Team

Allocate from Updates the Estimates team's allocation based on the new estimates Assignment Roles Commit Planned Allocation

projmgr.teamUpdat No eForAllocation

No

No

Team Team

Selects a role to projmgr.assnRoleSw No assign apClick Commits the planned allocation for the selected resource Commits the planned allocation for the selected team projmgr.resourcePr No ojectsSelitemCheck Confirm3

No No

No No

Team

Commit Planned Allocation

projmgr.teamSelite mCheckConfirm1

No

No

No

Team

Estimate from Generates projmgr.teamUpdat No Allocation resource eForEstimate estimates based on allocation Set Allocation Sets the staff allocation Shift Allocation Shift or scale the selected resource allocation projmgr.staffSetAllo No cationClick projmgr.resourceShi No ftScaleSelection

No

No

Team Team

No No

No No

Team

Shift Allocation

Shift or scale projmgr.teamShiftS No the selected caleSelection team allocation

No

No

278 Studio Developer's Guide

System Type Data Providers

Object

Object Action Description Name

Object Action ID

Generic

Global

Can Be Added to All Views of the Object

Transaction Header Transaction Header Transaction Header Transaction Line Transaction Line

New Transaction

Creates a new transaction

npt.setObjectUserP No artitions revmgr.postSelecte dHeaders No

Yes

Yes

Post Selected Posts the selected transaction Recalculate Selected New Transaction Line Recalculates the selected transaction

No

No

revmgr.recalculateS No electedHeaders

No

No

Inserts a new npt.setObjectUserP No transaction line artitions revmgr.postSelecte dLines No

No

Yes

Post Selected Posts the Lines selected transaction lines Recalculate Recalculates Selected Lines the selected transaction lines

No

Yes

Transaction Line

revmgr.recalculateS No electedLines

No

Yes

Appendix E: Stock Object Actions 279