Clarity PPM Studio Portlets

ccppmop158
As a 
Clarity PPM
 Studio developer, use this article to develop and configure portlets. The software supports the following portlet types:
  •  Chart portlets are graphic views into your data. Examples include heat maps, tree maps, bubble charts, and pie charts. 
  •  Grid portlets provide lists or tables of data that can be filtered on demand.
  •  Filter portlets coordinate filtering operations between portlets on a page.
  •  HTML portlets capture web page content and plug it into a page in HTML format. Data can be extracted from internal or external web sites.
  •  Interactive portlets display dynamic imported content including Flash-based .swf or Xcelsius visualizations. Legacy Xcelsius features are deprecated; they are available only for users of a previous release. Advanced reporting functionality supersedes Xcelsius.
 Interactive portlets are no longer supported in any environment. In FedRAMP environments, HTML portlets are also not supported.
Similar to reports, portlets provide snapshots of data and can appear as grids, as charts, or as any HTML content on a page. As a portlet designer, you select the data to display in the portlet. You can design a portlet page with one or more portlets that appear automatically for other users with the appropriate access. Users can 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:
  • The 
    Clarity PPM
     database.
  • Other enterprise databases.
  • Optional external sources available in HTML, such as business news and network status information.
An object or an NSQL query provides the data for the portlet. An object automatically becomes a data provider when you create it. Identify a data provider or create an object or an NSQL query for the portlet data. Users can populate portlets with charts, tables, workflows, best practices, documents, and forms. Portlet data can refresh automatically.
 
 
2
 
 
This diagram shows the steps involved in developing CA PPM portlets
This diagram shows the steps involved in developing CA PPM portlets
Develop Chart Portlets
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, or start date) is a dimension. If a query also contains resource data, then the data contains two dimensions. Metrics are measured query values. For example, 
Actual Hours
 is a metric.
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, collaboration, project, resource, or personal information. You can add a chart to 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. Configure at least the minimum number of metrics in the query data. The following image describes the different chart types:
 
Image illustrating area, bar, bubble, column, donut, funnel, heat map, line, pie, scatter, and tree map chart types.
 
The following table explains the attributes of the available chart types:
Serial Number
 
Chart Type
 
 
Description
 
 
One-dimensional
 
 
Minimum Metrics
 
 
One-dimensional
 
 
Maximum Metrics
 
 
Three-dimensional
 
 
Minimum Metrics
 
 
Three-dimensional
 
 
Maximum Metrics
 
1
 
Area
 
Displays data points that are connected by lines along the axes.
Displays different colors to fill in the area below the line.
1
Unlimited
1
1
2
 
Bar
 
Displays each dimension of the data in a horizontal bar.
1
Unlimited
1
Unlimited
3
 
Bubble
 
Displays metrics on the horizontal and vertical axes.
The size of each bubble represents a third metric.
3
3
3
3
4
 
Column
 
Displays each dimension of the data in a vertical bar.
1
Unlimited
1
Unlimited
5
 
Donut
 
Displays the data dimension objects in proportional segments, like a pie chart.
1
1
1
1
6
 
Funnel
 
Displays the data dimension objects in proportional rows in a funnel shape similar to a pie chart.
1
1
1
1
7
 
Heat Map
 
Displays a primary attribute or metric in a two-dimensional grid with values along the X-axis and Y-axis. The primary attribute values are represented using colors or shades of the same color.
3
3
1
3
8
 
Line
 
Displays data points connected by lines along the axes.
1
Unlimited
1
1
9
 
Pie
 
Displays the data dimension objects in proportional slices.
1
1
1
1
10
 
Scatter
 
Displays metrics across the X-axis and Y-axis.
2
2
2
2
11
 
Tree Map
 
Displays data in a hierarchical tree with branched nodes. Chart values appear in different colors and can include clickable shapes that show the relative size of each subgroup. Tree maps progressively reveal more detailed information in deeper levels. The user can expand each subgroup to reveal the child data points in deeper levels.
3
3
1
3
Create a Chart Portlet in Studio
You can create a chart portlet and can populate it with data from an object or query. Decide the type of chart you want based on the dimensions and metrics in the query.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlets.
  2. Click New, select Chart Portlet, and 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.
    •  
      Portlet ID
      : Defines a unique alphanumeric identifier for the portlet.
    •  
      Content Source
      : Specifies where the data that appears in a portlet or portlet page originates.
      Default:
       Customer
    •  
      Category
      : Specifies the general area on which the portlet reports data.
      Default:
       Business Intelligence
    •  
      Description
      : Defines the purpose of the item being created and provides any relevant information.
    •  
      Base Size
      : Specifies the initial size for the portlet. To create a single chart portlet on a page that users can personalize, select Large as the base size. To share a page with other portlets, select Small.
      Default:
       Small
    •  
      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 on which a portlet can be placed. If you select General for this field, the portlet can be placed on any page.
      Default:
       General
    •  
      Data Provider
      Indicates the data construct that provides information to the portlet. Specify a provider by type:
      •  
        Queries
        : Use the built-in data providers and NSQL query language to create queries.
      •  
        System
        : System types are data providers for the restricted portlets. You can use these data providers in addition to stock object data providers.
      • Objects: The stock object and any objects that you create contain fields that you can use to access database information.
  3. (Optional) Click 
    Browse
     in the Data Provider field to specify a query, object, or system provider. Select a provider and then click Add.
  4. Click 
    Next
     and specify a chart type. The type of charts that you can create varies based on the dimensions and metrics of the data provider.
     If the chart type is similar to another type, you can change the chart type later. Open the portlet and click the Chart Section tab and select Chart Type.
  5. Click 
    Next
    .
  6. Depending on the type of chart, complete the Select Metrics page. The metrics page is specific to the type of chart that you are creating.
    1. If you are creating a bubble chart, complete the following fields:
      X Axis: 
      Specifies the metric to display on the X-axis for the chart.
      Y Axis: 
      Specifies the metric to display on the Y-axis for the chart.
      Bubble Radius: 
      Specifies the metric to display in each bubble for a bubble chart. The relative size of each bubble corresponds to the value for the selected field.
    2. If you are configuring a heat map, complete the following fields:
      X Axis
      : Select the metric that you want to track along the horizontal axis of the heat map. For example, to view the projects that are Started from those that are Not Started, choose Progress.
      Y Axis
      : Select the metric that you want to track along the vertical axis of the heat map. For example, to view the metric that you select next in color-coded cells, choose Technical Risk.
      Metric
      : Select the metric that you want to track using a color scale to group values in the heat map. This metric is also known as the Z Axis value. For example, choose Planned Cost.
      Grouping Function
      : Select an optional function that you want to apply to the metric in the heat map. Values include Sum, Count, Average, Maximum, or Minimum. To view the combined planned costs of all projects choose Sum.
      The examples cited here define a heatmap that color-codes the metric, applies a function to group the data, and plots it along the X and Y axes. This heatmap shows the sum of planned cost data for projects by technical risk and by progress.
    3. If you are creating a tree map, complete the following fields:
      Metric
      : Select the primary attribute that you want to track. For example, to track the remaining cost of projects select Estimate-to-Complete (ETC).
      First Grouping
      : Select the attribute that you want to use to categorize the data shown in units of the metric you selected. For example, to view project ETC by organizational breakdown structure, select OBS. You can also select a second and even a third grouping level. For example, you might want to view ETC for projects by OBS (level 1), then by manager (level 2), and then by status (level 3).
  7. Click 
    Next
     or 
    Finish and Open
    .
Configure a Chart Portlet Filter
A chart can be complex if it contains a lot of data. Filters help users view only the information that is important to them. For each chart, you can select the specific data that you want to display from the available data that are 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.
 
Follow these steps:
 
  1. Continue from the previous procedure or open Administration, and from Studio, click Portlets and open the chart portlet.
  2. Click the Chart Filter Section tab and click Layout.
    The Chart Filter Layout page appears.
  3. Select the fields that you want to appear in the filter in the Available column and move the fields to the appropriate column using the arrows.
  4. Complete the following fields:
    •  
      Section Title
      Defines the text that appears at the top of the section for the filter.
    •  
      Default Filter State
      Specifies whether the initial display of the filter is expanded or collapsed.
    •  
      Allow Power Filter
      Specifies whether the filter provides advanced search features.
  5. Click 
    Save
    .
  6. Click the Chart Filter Section tab and click Fields.
    The Chart Filter Fields page appears.
  7. From the Display menu, select one of the following values:
    •  
      All
      : Displays all data that are provided by the query.
    •  
      Selected
      : Displays only the fields that you selected in the Layout menu (above).
    •  
      Available
      : Display all available data that are provided by a query.
  8. Click the Properties icon for a field to modify its behavior in the filter.
  9. Click 
    Save and Return
    .
Configure the Chart Portlet Source Data and Appearance Options
You can determine the data that appears in a portlet and how you want the data to be presented to users.
 This procedure explains the basic procedure for all charts. All fields for all chart types are included. The current chart that you are configuring may not display all of the same options.
 
Follow these steps:
 
  1. Continue from the previous procedure or open Administration, and from Studio, click Portlets and open the chart portlet.
  2. Click the Chart Section tab and click 
    Source Data
    .
  3. Select the metrics that you want included in the chart.
  4. Click 
    Save
    .
  5. Click the Chart Section tab and click 
    Options
    .
  6. In the Options field, select one of the following:
    • Entire Chart
    • X-Axis
    • Y-Axis
  7. Depending on the type of chart that is selected, complete the following display options and save your changes:
     The options appear in alphabetic order in the documentation. Their appearance on the 
    Chart Section - Options
     page varies.
    •  
      Allow Configuration
      : Indicates that users can modify the appearance of a portlet. Default: Selected
    •  
      Allow Label Configuration: 
      Indicates that users can modify portlet labels. 
    •  
      Allow Drilldown
      : Enables users to click data slices in a tree map to view the next level in more detail.
    •  
      Angle of First Slice
      : Defines the position of the first slice or wedge. Use with pie and donut 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 the labels that appear along the category axis for the X-axis of column and line graphs and the Y-axis of bar graphs. For example, consider a column graph that 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.
    •  
      Crosses Opposite Axis At
      : Defines the intersection point of the axis. Use with bubble and scatter charts.
    •  
      Datapoint Labels
      : To show the data at specific points in the chart, select Value. To hide the values, select None. To allow the user to see a value when their mouse pointer is over a point, set the Mouseover Labels.
    •  
      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. Also available for heat maps and tree maps.
    •  
      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 on a page.
    •  
      Group By Column
      : Specifies a column from the data provider that is used to organize the chart metrics data. This field is designated to provide a data scaling mechanism for chart display. For example, if you are using the Project object data provider, you can select Manager as the group-by column. The metrics that you select for the x-axis or y-axis are then organized by manager. The data provider that is selected determines the columns that are available as group-by columns. This option is not available for scatter charts or bubble charts.
    •  
      Group By Function
      : Specifies the default aggregate function that is applied to the Group By metric results. The field defaults to Sum unless you change the value. For example, if you select Manager in the Group By Column field and Sum in the Group by Function field, the SUM aggregate is applied to the results of the chosen metrics. The totals can be displayed as values on the chart using labels. This field has an override function in the Metrics section of the Options page. You can override the default functions for individual metrics. If you select a date metric, the override is automatically set to Maximum. The only aggregate functions available for date fields in the metrics are Maximum and Minimum.
    •  
      Layout Type
      : Determines the appearance of the proportional shapes that represent the relative value of the data to the whole group in tree maps. Use the default 
      Slice and Dice
       setting to best view the implied hierarchy that the data suggests. For example, the groupings with the most values will appear larger and smaller groupings can appear divided into two or more rows. Choose 
      Squarified
       to compare the data points and attempt to normalize your view of the parts relative to the whole. Rectangular shapes in the 
      Slice and Dice
       layout are adjusted to appear more like squares. Groupings appear in normalized aspect ratios to help you better visualize and compare proportional values. The 
      Strip
       layout adjusts the 
      Squarified
       shapes so they fit side by side in subgrouped columns and in one primary row or strip. Choose 
      Stripes
       to compare the data in vertical columns. The width of the stripe represents the proportion of the part to the whole.
    •  
      Logarithmic
      : Plots the data points on the graph using a logarithmic scale for the Y-axis and major grid lines. Instead of a standard linear scale, the graph measures the relationship between data points using a power of 10 rather than a regular linear scale.
    •  
      Link
      : Specifies a page link that appears as a secondary value that the user can select.
    •  
      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
      : To enable the user to see the value at specific points in the chart with their mouse, select Value. To hide the values, select None. To display values at all major data points, set the Datapoint Labels.
    •  
      Number of Rows: 
      Divides the data points along the Y axis of a heat map into groups or ranges of values. As a suggestion, set this to a low number such as 2, 3, or 4 to aid in visualizing the data. If you do not set a value, the heat map plots each unique data value along the Y axis.
    •  
      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
    •  
      Reverse
      : Shows the data points aligned to the Y-axis scale in reverse order from the maximum value to the minimum value. The axis values typically appear in order from the minimum value to the maximum value.
    •  
      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, bubble, column, heat map, line, and scatter chart types. 
    •  
      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. 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 separates 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
      : Displays the chart portlet name above the chart.
    •  
      Show Subtitle
      : Displays the subtitle for heat maps and tree maps. The subtitle shows the chart metric and indicates the grouping function for heat maps and grouping attributes for tree maps.
    •  
      Sort Column
      : Indicates that a column is the default sort item. This option is available for column and line charts.
    •  
      Sub-type
      : Indicates the metrics that 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 that is used with tick marks. Use this option with: Bar. X-axis. Column. X-axis. Line. X-axis. Bubble and Scatter. X-axis.
 
Example Chart Portlet
 
In this example, the following chart displays the sum of effort data by manager. Red lines appear only in this example to demonstrate the concept of data in groups by manager.
 
Image displays an example chart portlet grouped by column and function.
 
Configure a Line Chart
  1. (Optional) If you are configuring a line chart, select Guides in the Options field and click New, then complete the following fields:
    •  
      Axis
      Specifies the axis for which guides are being set.
    •  
      Label
      Defines the name for the axis.
    •  
      Show Label
      Determines whether the name of the axis displays.
    •  
      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.
      Default:
       Attribute
    •  
      Color
      Specifies the color for the guide.
      Default:
       Black
  2. Click Save.
Configure Consistent Colors for Studio Chart Portlets
You can configure color options for the standard chart portlets so that the values of common attributes appear in a consistent color. For example, you have a portlet page that contains multiple chart portlets. Each portlet uses the same attribute named Priority. For each chart portlet, you can specify Priority as the key attribute in each portlet. In all charts, 
High
 priority values appear in red and 
Low
 priority values appear in gray.
 Before you can configure consistent colors for chart portlets, you must select the 
Use Consistent Chart Colors
 option under 
Administration
General Settings
System Options
. See Configure General System Settings for details. 
 
Follow these steps:
 
  1. Continue from the previous procedure or open Administration, and from Studio, click Portlets.
  2. Click the 
    Chart Section
     tab and select 
    Options
    .
  3. Complete the following fields:
    •  
      Consistent Color Key
      Specifies a metric or an attribute that determines which colors are assigned to the attribute values in all charts in the portlet. Select an attribute, such as Priority.
    •  
      Use Consistent Colors
      Enables consistent chart colors for the chart portlet that are based on the color key. Select Yes.
  4. Save your changes.
  5. Repeat for each chart portlet that uses the same color key, using the same attribute value.
    When you display the portlet page with chart portlets, the values for the attribute key have consistent colors on each chart.
 The color consistency fields do not apply to heat map and tree map charts.
Configure the Colors for Heat Maps
You can determine the color gradients that are used to represent data values in a heat map.
 If your heat map uses an attribute with its own colors derived from custom-defined display mappings, you cannot change the map colors. These values are read-only. However, you can change the display mappings.
 
Follow these steps:
 
  1. Click Administration, and from Studio, click Portlets and open the heat map chart portlet.
  2. Click the Chart Section tab and click Options.
  3. In the Options field, select Map Colors.
    1. In the Select Color field for row one, select a color.
    2. (Optional) Enter a description to explain what the color value means in the chart.
    3. In the From field, enter the low end of the range of values to appear in the lightest shades of this color.
    4. In the To field, enter the high end of the range of values to appear in the darkest shades of this color.
  4. Click Save and Return.
Configure the Chart Color Palette
You can specify chart colors at the system level or at the Studio chart portlet
 
level. When you create custom colors, they override the default palette. You can configure the chart color palette to achieve the following goals:
  • Represent a common attribute with the same color consistently in all chart portlets.
  • Create a chart palette by adding custom colors.
  • Remove colors from the custom palette.
Create a chart color palette at the system level to specify which colors, and in what order, the system assigns colors to a chart. You can add an unlimited number of colors to a color palette. For example, specify colors that represent your corporate identity.
 You can use only one palette at a time. The values that you specify for these settings affect all users.
 
Follow these steps:
 
  1. Open Administration, and from General Settings, click System Options.
  2. In the Other section, select Use Consistent Chart Colors. When you enable this option, settings for using consistent colors become available when you create and configure the chart portlets. If Use Consistent Chart Colors is disabled, the chart portlet settings are not available.
  3. Click Save and Return. To customize the colors, continue to the next step.
  4. In the Chart Colors field, click the [Color Palette] link.
    The chart colors page appears.
  5. Click New and complete the following fields:
    •  
      Name
      : Specifies the name of the custom color value.
    •  
      RGB
      : Specifies the hexadecimal value that represents a color for your chart. For example, 0000FF specifies the color blue.
  6. Click Save and Return.
  7. Repeat for each additional color that you want to add to the palette.
  8. To change the sequence of colors, click Order and move the colors up or down in the list.
  9. (Optional) To restore the default color palette, select all of the custom colors in the palette list and click Delete.
  10. Click Save and Return.
Develop Grid Portlets
To display data in rows and columns, use a grid portlet. For example, you can use a grid portlet to display the following information:
  • Lists of resources or transactions
  • Capacity and assignment demand for resources over time
  • The number of overdue action items for each resource for each OBS unit
Grid portlets are suitable when query data contains only one or two dimensions. For example, project-related data such as the project ID, name, and start date is one dimension of data. You can present the following information elements in a virtual column in the grid:
  • Gantt charts
  • Progress bars
  • Bar or column charts
  • Aggregation rows
  • Links to other information
Refer to the following guidelines when designing grid portlets:
  • Static dependent list lookups that are configured as multi-valued lookups are not supported in grid portlets.
  • Autosuggest is not supported with static dependent lists.
  • 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 cannot view data from the subpage in a grid portlet.
  • Use a hierarchical grid portlet 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.
  • A grid portlet can also include time-scaled values that cover specific time periods in a virtual column.
 
Follow these steps:
 
Create a Grid Portlet in Studio
Use grid portlets to display lists of data for users. For example, you can create a grid portlet to show the following information for all of your projects: planned cost, actual cost, planned hours, and actual hours. You can include a Gantt chart in the portlet to show project milestones and highlight how the milestones are being met.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Click 
    New
     and select 
    Grid Portlet
    .
  3. Complete the fields.
    •  
      Content Source
      Specifies where the data that appears in a portlet or portlet page originates.
      Default:
       Customer
    •  
      Category
      Specifies the general area on which the portlet reports data.
      Default:
       Business Intelligence
    •  
      Instance Type
      Specifies the type of page on which a portlet can be placed. If you select General for this field, the portlet can be placed on any page.
      Default:
       General
    •  
      Data Provider
      Indicates the data construct that provides information to the portlet.
      • Queries: Use the built-in data providers and NSQL query language to create queries.
      • System: System types are data providers for the restricted portlets. You can use these data providers in addition to stock object data providers.
      • Objects: The stock object and any objects that you create contain fields that you can use to access database information.
    •  
      Partition
      Specifies the partition that is associated with the portlet. After you specify a partition, the portlet is aware of partition-specific lookup values. If you are using partitions and create a system partition portlet, it will not behave like stock list pages which recognize the partition membership of the logged in user.
    • The source data for virtual 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.
    • 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.
  4. Click 
    Next
    .
    The portlet finish page appears.
  5. Click 
    Finish and Open
    .
Configure the Column Layout and Appearance of a Grid Portlet
Specify the fields that appear in the columns and the order in which they appear.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Click the 
    List Column Section
     tab, and click 
    Layout
    .
  4. In the 
    Column Layout
     section, select the attributes to include in the portlet in the 
    Available Columns
     and move the attributes to the 
    Selected Columns
     list.
  5. Click Save.
  6. In the 
    Column Sorting
     section, indicate the primary sort column by selecting an attribute in the 
    First Field
     row.
  7. To indicate the direction of the sort, select 
    Ascending
     or 
    Descending
    .
  8. To indicate additional sort columns, select attributes for the 
    Second Field
    Third Field
    , and 
    Fourth Field
     rows.
  9. Save your changes.
  10. Click the List Column Section tab and click Fields.
  11. For each field that you selected as a column:
    1. To edit the field label, enter the existing label.
    2. To change the appearance of the field in a column of the grid, click Properties.
    3. To designate that the field data appears as an icon in the grid, click Indicator Images.
  12. Click Save and Return.
Add a Gantt Chart to a Studio Grid Portlet
Use a Gantt chart in a grid portlet to show the duration and progress over time. For example, you can use a Gantt chart to show the milestone completions for each project that is included in a grid portlet. The Gantt chart appears in a virtual column on the row for each project.
The default position for a Gantt chart in a grid portlet is a virtual column in the far right column of the grid. You can move the virtual column containing the Gantt chart to a different position in the List Column layout.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Open the 
    List Column Section
     menu, and click 
    Fields
    .
    The 
    List Column Fields
     page appears.
  4. Click New.
  5. Select 
    Gantt
    , and click Next.
  6. Complete the General section, including the following fields:
    •  
      Show Column Label
      Indicates whether the column label appears at the top of the column list.
    •  
      Allow Word Wrapping in Column Header
      Indicates whether you want text in the column label to wrap.
  7. Complete the requested information in the Time Scale section. The following fields require explanation:
    •  
      Start Date
      Indicates the start date for the column spread.
    •  
      Time Scale
      Specifies the time period by which data displays (for example, days or weeks).
    •  
      Number of Time Periods
      Defines the number of time periods that display.
    •  
      Time Period Offset
      Defines how to shift the beginning of the Gantt bar relative to the start date. Enter a positive or negative number of time periods into the field.
    •  
      Show Group Header Row
      Indicates whether the timescale displays above the Gantt bar. If you select this option, select a timescale value.
  8. Complete the requested information in the Primary Bar section. The following fields require explanation:
    •  
      Item Name Attribute
      Defines the type of information to display in the corresponding Gantt bar.
    •  
      Start Date Attribute
      Defines the start date of the corresponding Gantt bar display.
    •  
      Finish Date Attribute
      Defines the finish date of the corresponding Gantt bar display.
    •  
      Milestone Attribute
      Defines the attribute to designate as a milestone. You can only assign a milestone attribute for a task.
    •  
      Progress Through Date Attribute
      Defines the length of the black overlay line that shows 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 that is used to move the green progress line relative to the length of the taskbar to indicate the completed work. If you select a value for this field, it overrides the Progress Through Date Attribute selection.
    •  
      Label for Bar
      Specifies the label text to display above each taskbar.
    •  
      Additional Information Attribute
      Specifies the field that is used in the text note when you hover over a taskbar. For example, to display the assigned resources for a task, when the cursor is over a taskbar, complete the following steps:
      • Select Assigned Resources from the Additional Information Attribute field.
      • Select Additional Information in the Show Mouseover field.
    •  
      Show Mouseover
      Specifies the information that you want to display in a text note when the mouse scrolls over an area of the Gantt chart.
  9. Indicate the dates to show in the primary bar by selecting the desired dates in the Available list and moving the dates to the Selected list.
    Change the order of the dates in the Selected list to suit your Gantt chart needs.
  10. 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.
  11. Save your changes.
Add a Bar or Column Graph to a Studio Grid Portlet
To compare values for the same attribute spanning multiple entries in a list, use a bar or column graph. For example, you can display the planned cost for projects over a period of time. The default position for a bar or column chart in a grid portlet is a virtual column in the far right column of the grid.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Open the 
    List Column Section
     menu, and click 
    Fields
    .
  4. Click the 
    Properties
     icon in a row.
  5. Change any of the following options. The options that appear depend on the data and display type of the attribute.
    •  
      Column Label
      Defines the name that appears at the top of the column.
    •  
      Show Column Label
      Indicates whether the column label appears at the top of the column list.
    •  
      Allow Word Wrapping in Column Header
      Indicates whether the text in the column label wraps within the column.
  6. Select the type of chart in the Display Type field, and click Save.
  7. Complete the Primary Bar or Column section including the following fields:
    •  
      Thickness
      Specifies the width of the bar or column graph.
    •  
      Maximum Length
      Define the length of the bar (in pixels).
    •  
      Length Scaling
      Select from the following options:
      •  
        Relative to Same Column
        Makes the bar length proportional to other bars in the same column. This option is most useful when displaying horizontal bars. For example, a bar that represents $500,000 displays as twice the height of a bar that represents $250,000.
      •  
        Relative to Same Row
        Makes the bar proportional to all other bars in the same row. This option is most useful when displaying vertical bars. For example, a bar that represents $500,000 displays as twice the height of a bar that represents $250,000 in the same row.
      •  
        Relative to Entire Table
        Makes the bar proportional to all bars of the same type (vertical or horizontal) in the entire table. For example, a vertical bar that represents $500,000 displays as twice the height of a bar that represents $250,000 in another row.
      •  
        No Scaling
        Draws all bars to the maximum length. This option 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 the threshold 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 a color for the primary bar.
    •  
      Threshold Line Attribute
      Specifies the attribute whose value is the threshold value. The threshold line attribute must be in the same object as the attribute that is being measured. In bar charts, a vertical line marks the threshold value.
    •  
      Over-threshold Color
      Specifies a color to represent values greater than the threshold value. 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.
    •  
      Secondary Value
      Specifies the attribute whose value displays when the user moves a cursor over the primary bar.
    •  
      Link
      Specifies 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.
  8. 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.
  9. Save your changes.
Add a Progress Bar to a Studio Grid Portlet
Use the following procedure to add a progress bar field to a grid portlet. The progress bar shows progress over time. The default position for a progress bar in a grid portlet is a virtual column in the far right column of the grid.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Open the 
    List Column Section
     menu, and click 
    Fields
    .
  4. Click New.
  5. Click 
    Progress Bar
     and click Next.
  6. Complete the Progress Bar Column Settings page including the following fields:
    •  
      Show Column Label
      : Indicates whether the column label appears at the top of the column list.
    •  
      Allow Word Wrapping in Column Header
      : Indicates whether the text in the column label wraps within the column.
    •  
      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 of the progress bar.
    •  
      Show Label
      : Indicates whether the name of the current stage is displayed in the progress bar.
    •  
      Column Width
      : Defines the percentage of the row width that is allocated to the progress bar column.
  7. Save your changes.
Add an Image Link to a Studio Grid Portlet
To allow users to navigate to another page from the portlet, add an image link. For example, add an image link that lets a user go to a specific dashboard page. When you add an image link to a grid portlet, the link automatically displays in a new virtual field in the far right column.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Open the 
    List Column Section
     menu, and click 
    Fields
    .
  4. Click 
    New
    .
  5. Select 
    Image
     and click 
    Next
    .
  6. Complete the List Column Field page including the following fields:
    •  
      Column Label
      : Defines the name that appears at the top of the column.
    •  
      Show Column Label
      : Indicates whether the column label appears at the top of the column list.
    •  
      Allow Word Wrapping in Column Header
      : Indicates whether the text in the column label wraps within the column.
    •  
      Image
      : Specifies the image to use in the grid column.
    •  
      Link
      : Specifies a page link that appears as a secondary value that the user can select.
    •  
      Open as Pop-up
      : Indicates whether the target page of the image link appears 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. The following values determine how the attribute appears:
      • Text only. The value of the attribute that is selected equals zero.
      • Hyperlink. The value of the attribute is not zero or a value is not selected.
      This field applies only when the Link field has a value that is selected.
  7. Save your changes.
Add an Aggregation Row to a Studio Grid Portlet
You can show collective information about the number or money attributes in the rows of a grid portlet. You can create virtual columns with aggregated data derived from query data. The following table describes the available virtual column types.
 
Virtual Column
 
 
Description
 
 
Aggregation
 
Operates on a large set (column) of data and typically returns 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 that is involved, you can select from the following functions:
  • Sum
  • Average
  • Count
  • Minimum
  • Maximum
  • Variance
  • Standard deviation
 String attributes cannot be aggregated. When the query data is a date, only the COUNT, MIN, and MAX functions are available.
For data with at least two dimensions, you can create a 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.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Open the 
    List Column Section
     tab, and click 
    Aggregation
    .
  4. Click 
    Add
    .
  5. Complete the page including the following fields:
    •  
      Label: 
      Defines the name for the aggregation row. Enter the name that you want to appear.
    •  
      Show
      : Indicates whether to display the name of the aggregation row.
    •  
      Attribute
      : Defines the field value to use for aggregation.
    •  
      Function
      : Specifies the aggregation function to use to calculate values for a selected field (cell) in the row.
  6. Save your changes.
    The aggregation row list appears.
  7. 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.
  8. To reorder the rows, click Reorder.
  9. Save your changes.
Configure the Grid Portlet Display Options
Display options determine how the product appears to users. For example, you can control how secondary values in a grid cell appear, how specific data appears, and whether users can change a portlet.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Select the 
    List Column Section
     tab, and click 
    Options
    .
  4. Complete the page, including the following fields:
    •  
      Secondary Value Display
      : Indicates how the secondary values display in a grid cell.
      Values
      :
      • Mouseover only. Specifies no secondary value display.
      • Mouseover and redline text.
         S
        pecifies the display of a secondary, comparison value when you place the cursor over a cell in a grid. For example, if you have two columns that are named Cost and Baseline Cost, you can display both values in a cell. To display both, select Baseline Cost as the secondary value. The Cost value displays as usual. However, when you move the cursor 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 on a page.
    •  
      Rows per Page
      : Specifies the number of rows to display per page.
    •  
      Highlight Row by Attribute
      : Specifies the attribute whose row is highlighted when the attribute value is not zero.
    •  
      Display Currency Code in Column
      : Specifies whether to display the currency code in the column for money attributes.
    •  
      Allow Configuration
      : Specifies if a user can change the appearance of a page or a portlet.
    •  
      Allow Label Configuration
      : Specifies whether a user can change a page or portlet label. This option works with the Allow Configuration option. To make labels unconfigurable while other items can be configured, select the Allow Configuration option and clear the Allow Label Configuration option.
    •  
      Attribute Value Protection
      : Indicates whether an attribute is protected or displayed. You can protect attributes from appearing using display conditions, secured subpages, or both.
  5. Save your changes.
Configure the Filter for a Studio Grid Portlet
Display a filter to help users manage the volume of information in a grid portlet. For example, if the portlet displays a list of projects, users can filter by specific criteria. The filter can appear in a collapsed state that shows only the filter field or in an expanded state that shows 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. You can add virtual fields to a list filter; however, some virtual fields are not available for use in a power filter.
You can display the filter fields and can adjust their properties. For example, decide if a filter field is required in a filter and specify a filter default value. To improve performance, reduce the amount of data in the results. Select the fields that you want to display in the filter. For example, you can select from the fields that are selected for the filter layout or you can select from other options.
 
Follow these steps:
 
  1. Open 
    Administration
    , and from 
    Studio
    , click 
    Portlets
    .
  2. Open the portlet.
  3. Click the 
    List Filter Section
     tab and select 
    Layout
    .
  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.
  5. Complete the following fields in the 
    Settings
     section:
    •  
      Section Title
      : Defines the text that appears at the top of the section for the filter.
    •  
      Allow Power Filter
      : Specifies whether the filter provides advanced search features.
  6. Click Save.
  7. Click the 
    List Filter Section
     tab and select 
    Fields
    .
    The 
    List Filter Fields
     page appears.
  8. In the 
    Display
     field, select 
    one 
    of the available options to identify the fields that you want to display.
  9. Save your changes.
Develop Filter Portlets
A filter portlet coordinates the filtering of data in portlets. You can configure a filter portlet to share filter values at the following levels:
  •  
    Page Level: 
    Filter values are not shared across pages.
  •  
    Application Level: 
    Filter values are shared across pages. To implement an application level filter, add the same filter portlet to each page.
The scope, precedence, and persistence of the filter determine how it behaves. The scope of 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 and the mapping of the filter portlet fields to the attributes of portlets on the pages.
When a user clicks the Filter button, all portlets that are 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. The affected portlets still filter on the filter portlet values, even if the values do not appear.
When multiple filters are mapped to a filter portlet, the filter portlet has precedence and determines the filter values for all portlet attributes mapped to filter portlet fields. The user sees the following behavior:
  • Show All selected at the filter portlet level initiates a Show All behavior for all portlets that are 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 that is combined with the portlet’s filter criteria of unmapped portlet attributes.
  • Portlets that have no mapped attributes are not affected by the filter portlet.
In a grid or chart portlet filter, the portlet filter has precedence.
  • 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.
The following rules determine which filter 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.
Create a Filter Portlet in Studio
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.
  2. Click New, select Filter Portlet, and 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.
    •  
      Portlet ID
      : Defines a unique alphanumeric identifier for the portlet.
    •  
      Content Source
      : Specifies where the data that appears in a portlet or portlet page originates.
      Default:
       Customer
    •  
      Category
      : Specifies the general area on which the portlet reports data.
    •  
      Description
      : Defines the purpose of the field and provides any relevant information.
    •  
      Active
      : Indicates that 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 on which a portlet can be placed. If you select General for this field, the portlet can be placed on any page.
      Default:
       General
  3. Save your changes.
Add a Field to a Filter Portlet in Studio
Add the fields that you want to include in the filter.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlets.
  2. Open a filter portlet and click the Fields tab.
  3. Click Add.
  4. Complete the following fields. The fields vary according to the data type selected.
    •  
      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 used (Text Entry or Exact Text).
    •  
      Show as Percent
      : Indicates if the value entered in the field displays as a percent.
    •  
      Filter Default
      : Defines the value that 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, 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 you execute a filter request. Select the check box to hide the field in the filter.
    •  
      Read-Only in Filter
      : Specifies that the field displays with a default value that you cannot edit. Select the check box to make the field read-only in the filter.
    •  
      Hint
      : Defines a short message of no more than 512 characters that reminds other users of the purpose of the field.
    •  
      Tooltip: 
      Provides a short message that displays when the user moves their cursor over the field.
  5. Save your changes.
Configure the Filter Portlet Layout
Configure the placement of the fields in the filter portlet. 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. Open Administration, and from Studio, click Portlets.
  2. Open a filter portlet and click the Layout tab.
    The layout page appears.
  3. Click the left or right arrows to move the fields to the Selected (Left Column) or Selected (Right Column) lists.
  4. Click the up or down arrows to set the order of appearance in the filter portlet.
  5. 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 initial display of the filter is expanded or collapsed.
  6. Save your changes.
Add a Studio Filter Portlet to a Portlet Page
Use this procedure to add a filter portlet to a page and to map the filter portlet fields to the attributes of other portlets that appear on the page. 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
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlet Pages.
    The portlet pages
     
    list page appears.
  2. Select a page.
    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.
  4. Click Add.
  5. 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 that is 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 that are 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 that is 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.
View the Portlet Pages for a 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 a filter portlet.
    The properties page appears.
  3. Click the Portlet Pages tab.
Develop HTML Portlets
You can use an HTML portlet to display web or network data including the following examples:
  • News from a company intranet site
  • Corporate telephone information
  • Portions of external web sites
  • A pre-recorded message
  •  
    Static Data
    : The primary purpose of HTML portlets is to display static data. 
  •  
    No Custom Javascript
    : Do not introduce your own embedded Javascript inside HTML portlets. The injection of custom code with redirected links or references to dynamic external resources is not supported.
  •  
    Do not reload the current page
    : Clarity PPM is a single-page Ajax-style application. Reloading the page such as setting window.location.href in Javascript. is not optimal and can result in loss of application state data.
  •  
    Not Supported in All Environments
    : HTML portlets are not supported in FedRAMP environments.
  •  
    Test Your CSS
    : Always test and verify the compatibility of your CSS style names.
  •  
    Avoid Weak Security Syntax
    : For security, the application does not allow you to use the following syntax inside an HTML portlet script:
    •  
      alert|eval|expression|prompt|confirm)[\r\n\s]*\((.*?)\)
       
    •  
      javascript|vbscript)[\r\n\s]*:
       
    •  
      document.write
       
    •  
      </script[\r\n\s]*>
       
    •  
      <base[^>]*href[\s]*=[^>]*>
       
    •  
      <script(.*?)>
       
  •  
    No Comments
    : Do not use 
    <!--
     or 
    -->
     to include comments. For example, in the following image, remove all of the red lines:
    image2019-6-12_11-54-13.png
     
Create an HTML Portlet in Studio
Use this procedure to create an HTML portlet.
 
Follow these steps:
 
  1. Click 
    Administration
    Studio
    Portlets
    .
  2. Click 
    New
     and select 
    HTML 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
    •  
      Category
      Specifies the general area on which the portlet reports data.
    •  
      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:
       Department
      Required:
       Yes
    •  
      HTML Code 
      Defines the HTML you want to display in the portlet.
      Required:
       Yes
  4. Save your changes.
Develop Interactive Portlets (Legacy Feature)
Use an interactive portlet to display robust Xcelsius visualizations of your project and portfolio data. An Xcelsius developer exports their visualization as a vector-based Adobe Flash (.SWF) file. As a 
Clarity PPM
 Studio developer, you can import the visualization into an interactive portlet. Global and object parameters with associated Flash variables create context-aware visualizations and establish secure data transfer.
Use interactive portlets to:
  • Perform what-if analyses
  • Set up alerts
  • Drill down to more detailed information
  • Mouseover areas to view more information
After your 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 add interactive portlets and personalize pages including their Overview page.
 Interactive portlets are not supported in release 14.4 or newer. As an existing customer on a previous release, you might already have Xcelsius software licensed and installed. However, Xcelsius Designer and other Business Objects products are no longer available or supported by CA Technologies. This software is not available to new customers who are installing for the first time. All customers can take advantage of the new Advanced Reporting features.
Create an Interactive Portlet in Studio
Use this 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.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlets.
  2. Click New and select Interactive 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
    •  
      Category
      Specifies the general area on which the portlet reports data.
    •  
      Description
      Defines the purpose of the portlet 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:
       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 an Object or Global Parameter for an Interactive Portlet
Interactive portlet object parameters or global parameters define the data that is exchanged between the application and the Xcelsius visualization. Your administrator defines the Flash variables in Xcelsius while designing the visualization. The Flash variables allow the visualization to accept data. You use the Flash variable name when you create the interactive portlet.
Before you can create object or global parameters, your administrator must first create the Xcelsius visualization and the required Flash variables and you must create the interactive portlet.
 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.
  2. Click Parameters.
  3. Click New and select either Object Parameter or Global Parameter.
  4. Complete the following required 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: 
      PPM (formerly Clarity) Session ID in SOAP Header, PPM User Internal ID, PPM User Name, PPM Web Service URL, and Language
    •  
      Object
      (Object Parameter only) Displays the name of the object to which this object parameter is associated.
      Default:
       Department
    •  
      Field
      (Object Parameter only) Specifies the field name.
      Values:
       The values displayed are associated with the selected object.
    •  
      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.
  5. (Optional) In the Description field, enter no more than 240 characters to describe the parameter.
  6. Save your changes.
Portlet Configuration
After you design a portlet, perform one or more post-design configuration tasks.
Add a Portlet to a Page
Add the portlet to a page so that it can be placed into the menus and viewed in the product. For example, you can add a portlet page to serve as a dashboard for several project-level portlets.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlet Pages.
  2. Click New.
  3. Complete the information on the page.
    •  
      Content Source
      Identifies where the content for the portlet originates.
    •  
      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. You can also select default portlet pages for master objects and custom objects.
    •  
      Layout
      Specifies how portlets added to a page or a tab appear. The number of columns indicates the number of portlets for each row and the percentage of the page that is given to each portlet. The Row layout can have one to three portlets in a row with equal space provided for each portlet.
    •  
      Personalizable
      Specifies if a user can make personal changes to a page or a tab. Only the user who changes the page or tab sees the changes.
  4. Click Save and Continue.
    The properties page for the portlet page appears.
  5. Click 
    Content
    .
  6. Click 
    Add
    .
  7. Select the portlet to add and click 
    Add
    .
  8. Click 
    Layout
    .
  9. Use the arrows to move the portlet to the appropriate column on the page.
    If you have multiple portlets to lay out on the page, use the arrows to order the portlets in the columns.
  10. Save your changes.
  11. Add the page to the main menu or the actions menu.
Assign User Access to a Portlet
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.
As an administrator, you have different access to user portlets based on where you are in the application. In Studio, you can view all user portlets, make changes to the portlets, and publish the changes. In the application, you can view only the portlets that you created or portlets that are shared.
Assign access for users so that they can see one or more portlets and the content that appears inside them. For example, if you create a portlet to show project data, provide access for users to see the portlet and the project data. You can assign access in the following ways:
  • Assign the global access right 
    Portlet - Viewer - All
     to let users view all portlets in the product.
  • Assign the access right to view a specific portlet only.
To assign individual users access to a specific portlet, complete this procedure. You can also assign access by group or OBS unit.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Portlets.
  2. Open the portlet.
  3. Click the Access to this Portlet tab and select one of the following options:
    • Full View
    • Resource
    • Group
    • OBS Unit
  4. Click Add.
  5. Select the rights that you want to enable:
    •  
      Portlet - Edit
      Allows a user to edit and view the definition of a portlet.
    •  
      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.
  6. Click Add and Continue.
    A list of resources, groups, or OBS units appear.
     Click the + icon to expand an OBS unit to see child OBS units.
  7. Select the check box next to each resource, group, or OBS unit to be granted access rights.
  8. (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.
  9. Click Add.
  10. Select one or more users, groups, or units and click 
    Add
    .
    If you have a long list of users to add, click Add and Select More.
  11. Save your changes.
Test the Portlet in the Application
Test the new portlet by viewing it in the user interface.
 
Follow these steps:
 
  1. Log in as a user with permissions that represent the target users of the portlet.
  2. Verify that the data in the portlet is accurate and meaningful to users.
  3. Verify that the filter is useful and allows users to adjust what is in the portlet.
  4. If changes are required, log in as a developer.
  5. Open the portlet and make the appropriate changes to the layout or appearance.
    When the portlet appears as you intended, you have successfully created and displayed the portlet.
Static lookups that you configure with the 
Pull-Down
 display type can automatically change to 
Browse
. This change in display type improves performance and usability. This automatic change in appearance only occurs when all of the following conditions exist:
  • You develop an editable list view. This behavior does not occur on other types of views.
  • Your list view contains a static lookup and the 
    Display Type
     field is set to the 
    Pull-Down
     value.
  • Your lookup contained up to 20 original values.
  • You add at least one additional lookup value.
When the number of possible lookup values exceeds 20, the display type changes from 
Pull-Down
 changes to 
Browse
. The display type for OBS, Dynamic, and Dependent lookups on editable list views is always 
Browse
. If you add a lookup attribute to a properties view, we recommend the 
Pull-Down
 display type for 20 or fewer lookup values. When the number of potential lookup values exceeds 20, we recommend the Browse display type. You can also manually change the display type.
Publish Changes to a Portlet
You can update portlets for users by publishing the portlet. When you publish changes to a portlet, the new portlet overwrites the existing portlet. Publishing overwrites the following changes:
  • Changes a user has created by personalizing the portlet
  • Changes an administrator has created and previously published.
If you are using partitions, the new published portlet affects only the partition you have selected.
During a release upgrade or when installing add-ins, personalized user portlets are not upgraded. To keep users current, you may want to publish any new portlets that are provided by an upgrade or from an add-in.
 
Follow these steps:
 
  1. Click 
    Administration
    Studio
    Portlets
    .
  2. Select the check box next to the name of the portlet you want to publish, and click 
    Publish
    .
    The changes are published to future instances of the portlet as seen by users.
Restrict User Configuration of Portlets
When you create a portlet, users can configure the portlet by default. You can restrict the ability to configure an individual portlet grid, graph, or filter view.
 
Follow these steps:
 
  1. In Studio, open a portlet.
  2. For a grid portlet, open the List Column Section menu, and click Options.
  3. For a chart portlet, open the Chart Section menu, click Options.
  4. On the options page for the portlet, clear one or both of the following check boxes:
    •  
      Allow Configuration
      When this option is turned off for a portlet, users cannot see the Configure icon in the 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
    •  
      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)
  5. Save your changes.
Set a System View for a Portlet
You can design a grid or chart portlet that has the same view for all users.
 
Follow these steps:
 
  1. In Studio, open the portlet.
  2. For a grid portlet, open the List Column Section menu, and click Options.
  3. For a chart portlet, open the Chart Section menu, and click Options.
  4. On the options page for the portlet, clear the Allow Configuration check box.
  5. Click Save.
  6. Click General.
  7. Click Publish.
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 properties page.
When users select a data provider for a user portlet, the attributes for each provider appear to help them select the correct provider. You can provide more user-friendly attribute names to help users select the correct data provider.
 
Follow these steps:
 
  1. Open Administration, and from Studio, click Queries.
  2. Select a query.
  3. Click Attributes.
  4. Click the name of the attribute you want to relabel.
  5. Click the Translate icon next to the Attribute Name field.
  6. Enter the name that you want to appear for users in the data provider attribute list.
  7. Save your changes.