Manage portlet definitions

This topic provide an overview of portlet definitions and the details on how to create and maintain portlet definitions.

Overview of portlet definitions

A portlet definition defines the following of a specific portlet:

How the portlet is displayed
What the preferences fields of the portlet are
How the portlet communicates with other portlets
Who can add the portlet to their Dashboard pages and who can edit the portlet definition
The user help of the portlet

The following table summarizes the portlet definition types as well as the source, editability, and the corresponding portlet type of each portlet definition type.

Portlet Definition Type		Come From	Editability	Corresponding Portlet Type
Custom portlet definition	Standard portlet definition	Created and maintained by using the Create Portlet Definition Wizard	Can be deleted Can have any of their settings changed	Builder portlet
	Java portlet definition	Imported and maintained by using the Import Portlet Definition Wizard	Cannot be copied Can be deleted Can have the user and administrator access changed Can have the general information changed	Java portlet
	WSRP portlet definition	Imported and maintained by using the Import Portlet Definition Wizard	Cannot be copied Can be deleted Can have the user and administrator access changed Can have the general information changed	WSRP portlet
PPM-supplied portlet definition	Standard portlet definition	Provided by PPM as part of a PPM module	Cannot be deleted Cannot have the displays or preferences changed Can be copied Can have the user and administrator access changed Can have the user help changed	Builder portlet
	Java portlet definition	Imported by PPM as part of a PPM module	Cannot be deleted Cannot be copied Can have the user and administrator access changed Can have the general information changed	Java portlet
	WSRP portlet definition	Imported by PPM as part of a PPM module	Cannot be deleted Cannot be copied Can have the user and administrator access changed Can have the general information changed	WSRP portlet

Create standard portlet definitions

To create an entirely new standard portlet definition, use the Create Portlet Definition wizard.

Do either of the following to open the Create Portlet Definition wizard.
- From the menu bar, select Open > Administration > Portlet Definitions > Create Portlet Definition.
- From the menu bar, select Create > Administration > Portlet Definition.

In Step 1: Choose Portlet Type, select a portlet type for which you want to create the portlet definition.

Note: HTML+ Portlet is available for selection when the HTML+ Builder Portlets feature toggle is turned on.

Click Next to go to Step 2: Enter Portlet Information. Provide the portlet details as described in the table below.

Field Name (*Required)	Description
Portlet Information section
*Name	Specify a unique name for the portlet. Type any alphanumeric string (up to 80 characters in length).
Category	Select one or more categories. Choices are limited to those categories available on your PPM instance.
Manage Categories	Click to add or delete portlet categories. See Manage portlet categories for details.
Description	Specify the portlet definition. Type any alphanumeric string (up to 1,800 characters in length). It's helpful to describe the main function of the portlet, such as "Shows projects for a desired program." This description is available when you add a portlet to your Dashboard page.
Default Width	Select the default width of the portlet. Choices include: Narrow Wide Note that the default width can be changed when the portlet is personalized.
Enabled	Indicate whether or not the portlet can be added to the Dashboard page. If a portlet is added to a PPM Dashboard, then disabled, the portlet remains on the Dashboard page.
Enable users to display this portlet without a border	Available in HTML+ portlet definitions only. Select this option if you want to allow users to select whether or not to display the portlet border. If you want the portlet to be displayed without a border, select the By Default, display this portlet without a border check box. When a portlet is displayed without a border, the portlet title is not displayed, and the edit portlet preferences option is not available.
Data Source section
*Data Source	Select the data source for the current portlet. The portlet data source defines the columns or chart entity, and preferences fields for a portlet definition.
New Data Source	Opens the PPM Workbench and create a new portlet data source. For details, see Create portlet data sources in Workbench.

Click Next to go to Step 3: Set up Display Options. This step requires different information for different portlet types.
- For list portlets, see List portlet.
- For pivot table portlets, see Pivot table portlet.
- For bar charts, see Bar chart portlet.
- For clustered bar charts, see Clustered bar chart portlet.
- For stacked bar charts, see Stacked bar chart portlet.
- For pie charts, see Pie chart portlet.
- For line charts, see Line chart portlet.
- For bubble charts, see Bubble chart portlet.
- For html+ portlets, see HTML+ portlets.

Click Next to go to Step 4: Define Preferences.

Initially, all preference fields are mapped from the portlet data source, which indicates the name of the field, type of the field (such as auto-complete or text field), and any default value. Note that preferences that require default values are shown with a red asterisk.

How to	Details
Change the width of preferences	Click the Sizing icon ().
Rearrange preferences	Select a preference. Drag and drop the preference into the desired location.
Edit preferences	Select a preference, and click Edit. In the Edit Portlet Preferences dialog box, provide the following information: Field Prompt: Specify the prompt that appears on the Portlet Preference page. Type any alphanumeric string (up to 200 characters in length). Display: Select the manner in which this preference is displayed. Editable. Allows the user to edit the field. Required and Editable. Requires the user to provide a value. Non-Editable. Allows user to view, but not edit the field. Hidden. The information is not viewable (or editable) by the user. Default Value: Specify the default value that is shown when editing the portlet. This field is required if a default value is required by the portlet data source. Click Done to save your changes.
Show Preferences summary on this portlet (user can choose to hide it)	Select this option if you want the users to have this capability.
Require user to edit preferences before viewing portlet for the first time	Select this option if you require users to edit portlet preferences before viewing the portlet.
Show Total	Select this option if you want the users to see Total data in the portlet. This option is only available when you create portlet definitions for the following portlet types: Bar Chart Stacked Bar Chart Clustered Bar Chart Pie Chart

If you do not want to change any of the remaining default values, click Finish. Otherwise, click Next to go to Step 5: Configure Portlet Communication.
1. (Optional) Select Enable portlet communication (user can choose to disable it) if you want the user to have this capability.
2. If portlet communication is enabled, you must provide an event topic. Use the auto-complete button to provide an existing event topic or click Manage event topics to add a new topic or delete an existing topic.
If you do not want to change any of the remaining default values, click Finish. Otherwise, click Next to go to Step 6: Configure Access.
1. (Optional) In the User Access section:
  1. Require users to have one of these privileges: Select one or more access grants (privileges) a user must have in order to add the portlet to a Dashboard page.
  2. Give Access to: Select one or more users or security groups allowed to add the portlet to a Dashboard page.
    
    By default, access is given to all users belonging to the PPM User security group.
    
    Tip: Whenever there is no specific (individual or group) user access, this setting reverts to its default.
2. (Optional) In the Administrator Access section:
  - Give Access to: Select one or more users or security groups allowed to modify the portlet.
    
    By default, access is given to all users belonging to the PPM User Admin security group.
    
    Tip: Whenever there is no specific (individual or group) administrator access, this setting reverts to its default.
3. (Optional) In the WSRP Access section:
  - Make Portlet available to WSRP Consumers: Select the option if you want to make the portlet available to WSRP consumers.
  - Click Preview to review the layout and make sure that you have presented the information as desired.
4. (Optional) In the Drilldown Access section:
  - This portlet supports drilling into: Select the option if you want the portlet to support drill-down access.
Click Next to go to Step 7: Add User Help.

In the Portlet Help Text field, type the help text. This field supports HTML. Use valid HTML tagging when typing the information that defines the functionality of the portlet and lists and describes all of the portlet fields.

Click Preview Help to review the help content make sure that you have presented the information as desired.
In the Portlet Help Text field, type the help text.

This field supports HTML. Use valid HTML tagging when typing the information that defines the functionality of the portlet and lists and describes all of the portlet fields.

Tip: Click Preview Help to review the help content make sure that you have presented the information as desired.

Click Preview to review the layout and make sure that you have presented the information as desired.
Click Preview to review the layout and make sure that you have presented the information as desired. Click Finish.

The help data is saved, the portlet definition is created, and a status message displayed.

Note: If your PPM instance supports multiple languages, any portlet definition you create is defined in the language you selected at logon (your session language). After the portlet definition is created, it can be modified only in its definition language. For more information, see Multilingual User Interface Guide.

Modify a portlet definition

To modify an existing portlet definition:

From the menu, select Search > Administration > Portlet Definitions.
Provide the search criteria to search for the portlet definition.

Note: If your PPM instance supports multiple languages and the portlet definition is defined in a language other than your session language, you cannot edit the portlet definition. For more information, see Multilingual User Interface Guide.
Click the link of the target portlet definition to open the Configure Portlet Definition page.
For information about what can be modified, see Overview of portlet definitions.

For information about how to modify the portlet definition, see Create standard portlet definitions.

Copy a portlet definition

You can create a new portlet definition by copying an existing one. Java portlet definitions and WSRP portlet definitions cannot be copied.

To copy a portlet definition:

From the menu, select Search > Administration > Portlet Definitions.
Provide the search criteria to search for the portlet definition.
Click the link of the target portlet definition to open the Configure Portlet Definition page.
Click Copy.
Edit the copied portlet definition as described in Create standard portlet definitions.
Click Preview to verify your changes and click Create.

Delete a portlet definition

See Overview of portlet definitions to understand which portlet definition can be deleted.

To delete an existing portlet definition:

From the menu, select Search > Administration > Portlet Definitions.
Provide the search criteria to search for the portlet definition.
Click the delete icon in the front of the target portlet definition name.
Click Delete in the confirmation dialog box.

Import Java portlet definitions

Java portlets are written in Java and imported into PPM using the Import Portlet Definition wizard. Java portlets consist of a Java portlet definition (XML file) and the Java code.

The WAR files used for Java portlet definitions must be placed on the server file system in the <PPM_Home>/server/<PPM_Server_Name>/deploy directory.

To import a Java portlet definition using the Import Portlet Definition wizard:

Log on to PPM.
From the menu bar, select Open > Administration > Portlet Definitions > Import Portlet Definition.
In step 1: Choose Portlet Type, select Java Portlet - Created according to the Java Portlet specification, and click Next to go to Step 2: Select from Available Portlets.
Select a portlet.

Note that only one portlet can be selected at a time.

If no portlet definitions are available (that is, all of the portlet definitions are selected):
- Click Back to return to the previous page.
- Click Cancel to stop.
Click Next to go to Step 3: Enter Portlet Information.

For details, see Create standard portlet definitions.
Click Next to go to Step 4: Configure Portlet Communication.

If portlet communication is enabled, you must provide an event topic.

Use the auto-complete button to provide an existing event topic or click Manage event topics to add a new topic or delete an existing topic.
Click Next to go to Step 5: Configure Access.

For details, see Create standard portlet definitions.
Click Finish.
Review the Import Portlet Definition page and verify that the import was successful.
(Optional) Select the link of your choice.

Import WSRP portlet definitions

WSRP portlets are defined by a producer Web service and imported into PPM using the Import Portlet Definition wizard. WSRP portlets have a WSRP portlet definition (XML file) that references the URL of the WSRP portlet. That is, WSRP portlet definitions are a proxy to a remote portlet definition maintained by the producer and accessible through a Web service.

To import a WSRP portlet definition using the Import Portlet Definition wizard:

Make sure that the producer Web URL is available.
Log on to PPM.
From the menu bar, select Open > Administration > Portlet Definitions > Import a Portlet Definition to open the Import Portlet Definition wizard.
In Step 1: Choose Portlet Type, select WSRP Portlet - Created according to WSRP specifications, and click Next to go to Step 2: Define Producer Web Service.
Select either a Predefined Producer URL (define new producers by clicking the Manage WSRP Producers button) or Producer URL (provide the URL for the Web service providing portlet definitions using WSRP).

Note: If you are importing a portlet from another PPM instance, use the following URL: http://<Host>:<Port>/dashboard/wsrp4jproducer.wsdl.
Click Next to go to Step 3: Select from Available Portlets.
Select a portlet.

Note that only one portlet can be selected at a time.

If no portlet definitions are available (that is, all of the portlet definition are selected):
- Click Back to return to the previous page.
- Click Cancel to stop.
Click Next to go to Step 4: Enter Portlet Information.
Provide the general information using the details from the Portlet Information section.
Click Next to go to Step 5: Configure Portlet Communication.

If portlet communication is enabled, you must provide an event topic.

Use the auto-complete button to provide an existing event topic or click Manage event topics to add a new topic or delete an existing topic.
Click Next to go to Step 6: Configure Access.

For details, see Create standard portlet definitions.
Click Finish.
Review the Import Portlet Definition page and verify that the import was successful.
(Optional) Select the link of your choice.

Migrate portlet definitions

Use the PPM Portlet Definition Migrator object type to migrate portlet definitions. The following are things to consider when migrating portlet definitions:

When migrating a PPM-supplied portlet definition, the portlet's data source file is automatically migrated at the same time as the portlet definition.
When migrating a standard portlet definition, the portlet's data source file is automatically migrated at the same time as the portlet definition.
When migrating a Java portlet definition, you must configure the source and destination servers with the same set of Web applications (such as WARs) before migrating the Java portlet definition.
When migrating a WSRP portlet definition, the migration of the portlet definition is sufficient for the WSRP portlet to work. Migrating a WSRP portlet definition might fail under the following conditions:
- If the URL uses a port number. If you move that portlet to a different machine whose WSRP provider runs on a different port number, the portlet stops working.
- If a WSRP portlet definition shares a firewall or a private network with a WSRP producer. You cannot migrate the portlet definition outside of that private network or firewall protected area (because the machine is not accessible).