CA Clarity PPM Data Providers Used for CA Clarity PPM Web Parts

CA Clarity PPM Data Providers Used for CA Clarity PPM Web Parts

This section contains the following topics:

About CA Clarity PPM Data Providers for CA Clarity PPM Web Parts

CA Clarity PPM Stoplights Available in CA Clarity PPM List Web Parts

CA Clarity PPM Project Sub-Objects Accessible from CA Clarity PPM List Web Parts

About Using Studio Queries as Data Providers for CA Clarity PPM Web Parts

About CA Clarity PPM Data Providers for CA Clarity PPM Web Parts

You can use CA Clarity PPM data providers to source data for CA Clarity PPM Web Parts. The data providers that are available in CA Clarity PPM Web Parts are stock and custom sub-objects of CA Clarity PPM projects and Studio queries.

The available data providers depend on the CA Clarity PPM server, proxy user, and project that the CA Clarity PPM project site is bound to. Or, for a non-CA Clarity PPM project site, the CA Clarity PPM Web Part. The configuration of the selected server, the access rights of the selected proxy user, and the partition of the selected project can all affect the list of data providers presented when configuring a CA Clarity PPM Web Part.

You require writing Studio queries to conform to certain requirements before you can use them as data providers in Microsoft SharePoint. Regardless of adding a CA Clarity PPM Web Part to a CA Clarity PPM project site, or to a non-CA Clarity PPM project site, the query requires executing on the particular CA Clarity PPM server that retrieves information.

CA Clarity PPM Stoplights Available in CA Clarity PPM List Web Parts

In CA Clarity PPM, you can define a display mapping for numeric attributes. Display mappings can define an icon mapping or a color mapping. Icon mappings map values or ranges of values to a certain iconic image that can then be optionally shown in CA Clarity PPM lists and forms instead of, or in addition to, the value. The set of available images is fixed in Clarity. Color mappings are icon mapping where the configuration declares the colors that represent a certain range of values. The system uses a standard set of images with the corresponding color. These images can be shown in lists and forms in CA Clarity PPM.

To make these images available in lists in CA Clarity PPM List Web Parts, all numeric attributes in CA Clarity PPM are represented twice in CA Clarity PPM. The attribute shown with the attribute name (for example, “MyAttribute”) is the value and the attribute shown with the trailing asterisk. For example, “MyAttribute*” is the iconic image. Columns for some stoplights appear by default in CA Clarity PPM List Web Parts. Modify the list view to display additional stoplight columns.

CA Clarity PPM Project Sub-Objects Accessible from CA Clarity PPM List Web Parts

Sub-objects of CA Clarity PPM projects can be stock objects or custom objects created in the organization implementation of CA Clarity PPM. Team, Risks, and Tasks are examples of stock objects. Additionally, each sub-object can have stock attributes, which are predefined in CA Clarity PPM, and custom attributes, which are user-defined.

You can define the following kinds of attributes for CA Clarity PPM objects:

• Large strings
• Multi-valued lookups
• Document attachments
• Time-varying attributes

Note: The attributes are not exposed in Microsoft SharePoint.

The following table provides information about the stock CA Clarity PPM project sub-objects that you can access using CA Clarity PPM List Web Parts and the associated pages in CA Clarity PPM from which the lists are retrieved.

The columns that appear by default in the All Items view of the list in a CA Clarity PPM List Web Part are the columns that are in the System partition default list view for that object in CA Clarity PPM. Additional information about some of the available data providers is included in the following list:

• Documents. All the documents contained in the CA Clarity PPM project Document Manager are displayed in a non-hierarchical list. The Parent Folder column, which appears by default, indicates each document's parent folder.

  Note: Document Manager security is honored when you access documents. Therefore, you can provide appropriate access rights to the CA Clarity PPM proxy user account for the project Document Manager to allow, or disallow access to certain documents.

• Task. A CA Clarity PPM List Web Part that displays tasks from a CA Clarity PPM project displays all the tasks in the entire work breakdown structure, regardless of the level that they are at. That is, the CA Clarity List Web Part displays task breakdown from the WBS page of project tasks. Additional fields, such as Work Breakdown Structure (WBS) Level and WBS Sequence, can be added by as columns by modifying the Web Part view.

  Note: For CA Clarity PPM List Web Part to display tasks in the same order as in the project Work Breakdown Structure (WBS) page, sort the Web Part by the WBS Sequence attribute. To show the tasks at a certain level of the work breakdown structure, filter the list by the WBS Level attribute. For example, to show all top-level tasks, filter the list to show only those items whose WBS Level is 1.

About Using Studio Queries as Data Providers for CA Clarity PPM Web Parts

You can use the Studio queries that you create and configure in CA Clarity PPM as data providers for CA Clarity PPM Web Parts. However, the queries require conforming to certain requirements before using them as data providers for CA Clarity PPM Web Parts.

Important! Using Studio queries as data providers for CA Clarity PPM Web Parts can produce unexpected results if the queries do not conform to the requirements described in this section.

Note: Standard Studio queries used for grid and graph portlets in CA Clarity PPM do not work in Microsoft SharePoint and Studio queries created for use in Microsoft SharePoint do not work in CA Clarity PPM.

Query Requirements for Use in Microsoft SharePoint

The queries created using Studio need to meet the following requirements before you can use them as data providers for CA Clarity PPM Web Parts:

• The query ID begins with “sp_qry_”.

  “sp_qry_” is in lower case.

• The query category is Project.

  Queries that do not belong to the Project category do not appear in the CA Clarity PPM Data Provider list in the tool panes of CA Clarity PPM Web Parts.

• The WHERE statement in the NSQL query includes a filter that confines the scope of the query to the project that the CA Clarity PPM project site is bound to. For a CA Clarity PPM Web Part in a non-CA Clarity PPM project site, the project that the Web Part is bound to.

  You can write a WHERE statement that restricts the query to run on a particular CA Clarity PPM project.

• The following two properties, which enable incremental synchronization with the information in CA Clarity PPM Web Parts, are included in the NSQL query:

  change_key

  A string value that changes whenever the query-returned values change. Using the LAST UPDATED DATE, cast to a string, is a good choice for CA Clarity PPM sub-objects.

  merge_key

  A string value that uniquely and persistently identifies each record retrieved by the query. It is used as a key to determine the items in SharePoint required to be updated, created, and deleted. Using the ID, cast to a string, is a good choice for CA Clarity PPM sub-objects.

• For the query, define a link that begins with sp_link_ to allow the user to be able to use the Link to Clarity feature provided in CA Clarity PPM List Web Parts.
• The query is required to be a single-dimension query.

Note the following:

• Do not omit the change_key and merge_key properties from the NSQL query. If you omit these properties from the query, all items for that list in SharePoint will be completely replaced when you synchronize the list. This will have undesirable results, such as synchronization being slow, all items in the list being incorrectly shown as new and changed, and excessive notifications.
• LAST_UPDATED_DATE from multiple source tables can be concatenated in a query to generate a single change key that will change whenever any data in the source tables change.
• The first string property in the query will become the “Title” field (column) in SharePoint.
• The first six fields in the query will by default be included in the All Items view in SharePoint.
• Only the properties defined in the query will appear as fields and available choices for creating charts in SharePoint. Metrics will not.

Restrict a Studio Query to Execute on a Particular Project

You can include the following WHERE statement to restrict queries to run on particular project in CA Clarity PPM. The WHERE statement has the following format:

project ID = @WHERE:PARAM:USER_DEF:INTEGER:SP_PROJECT_ID@

project ID

Any valid SQL expression that can represent the ID of the CA Clarity PPM project.

The right-hand side of the statement retrieves the project ID that the CA Clarity PPM project site is bound to. For a CA Clarity PPM Web Part in a non-CA Clarity PPM project site, the project to which the Web Part is bound.

Note: You can include the WHERE statement multiple times in the same query. You require to use multiple WHERE statements in a query that includes UNION expressions or WHERE statements.

How to Write Useful Studio Queries for Microsoft SharePoint

Use the following hints to write useful queries to use as data providers for CA Clarity PPM Web Parts. Or, to display important project information on the sites that you create. More hints are included in other sections of the guide.

• Filtering the items in a list by using a Studio query is generally faster and better than retrieving all of the items and then filtering the list in the SharePoint view. Therefore, consider writing Studio queries to filter down large lists.

  Example: If Work Breakdown Structure has a large number of tasks, use a query to retrieve only key or current tasks.

• Write and use NSQL queries that use the WBS Level attribute to filter a task list to show tasks that are at the top level of the work breakdown structure (where WBS Level equals 1).