Clarity
Studio Content Packages

ccppmop159
Use content packages to deploy multiple versions of content between development, test, and production environments. Content packages help you collect, export, and distribute custom content to internal teams or external third parties. The content package provides an easy mechanism for importing and exporting 
Classic PPM
 content.
Develop and assemble specific content items in a content package. You can deliver the content package and achieve the following goals:
  • Developers can import the package as a 
    content package
     and continue development.
  • Administrators can import the package as a 
    content add-in
     for their environments and then users can use the content.
For example, you can develop a series of pages, portlets, and queries at one site and can continue development at another site. You can even include resources and roles in your packages. You can also declare the content to be final and offer such pages, portlets, and queries to internal users or external customers. Add or modify content and use versions to track multiple builds of your content packages.
Note: 
(SaaS only)
 
Clarity
in FedRAMP compliant environments does not support the creation or editing of HTML or interactive portlets from content packages or any other method. The Add Content and Auto-Populate options on the Details tab for content packages are not supported. 
The following image shows the steps for developing and installing a content package:
Image showing how to develop and install a content package
Image showing how to develop and install a content package
 
 
Content Package Prerequisites
Review the following prerequisites before working with content packages:
  • This functionality requires the 
    Content Package - Administer
     and 
    Administration - Access
     global access rights. 
  • To build and view content package JAR files, contact your administrator to install and configure the Document Management System.
  • Content packages do not support custom partition models for content items. Partition model information is not extracted as part of a package even when you have views and other object types defined for a custom partition. Only the default system partition configuration for the item is migrated as part of a content package. To move any content items from custom partitions, use the XML open gateway (XOG).
Create a Content Package
Before you can add content and export content items, create a content package.
 
Follow these steps:
 
  1. Open Administration, and from Studio, select Content Packages.
  2. Click New.
  3. Enter a name and unique identifier for the content package.
  4. Select an option in the Status field to indicate the level of progress in your content development stages. This field is for your own knowledge as a reminder and is not used by any process.
  5. In the Version field, enter the initial value in the versioning series in the format 
    xx.x.x
    . For example, 1.0.0. For the next incremental update to the package in this series enter 1.0.1. For the next minor version, enter 1.1.0, and for the next major version, enter 2.0.0.
  6. In the Content Provider Details section:
    1. Enter the Contact Name that you want to publish as the owner or source of the content add-in.
    2. Enter the Email Address for a customer to contact you to obtain support for the content add-in.
    3. (Optional) Enter a phone number in the Contact Phone Number field.
  7. Click Save.
Add Content Items to a Package
You can add or remove the content in a package. Add content by type, by name, or by browsing for matching items. As a developer, verify that you have the corresponding access right for each content item that you want to add. Without access rights, you cannot add that specific content item to a content package.
 
Follow these steps:
 
  1. Open Administration, and from Studio, select Content Packages.
  2. Open a content package.
  3. Click the Details tab and select List or Hierarchy from the Details menu.
  4. (Optional) As a shortcut for the previous step, you can click the List or Hierarchy icons in the content package list.
  5. To add content by type, by name, or to browse content in a list, click the Add Content menu. To add multiple types of items, skip to the next step.
    1. Select one of the following types of content:
      • Pages
      • Portlets
      • Queries
      • Resources or Roles
      • Lookups
      • Processes
      • Objects
      • Views
    2. To add content by name, enter the name of the content item to view a list of matching entries. Select an entry from the list of matching entries and then click Add. A menu appears in the Add button when descendants are available.
      • Select Item to add only the selected item.
      • Select Item and descendants to add the selected item and its descendants such as portlets, lookups, queries, and other items lower in the hierarchy.
      When you add only an item, the hierarchy shows you the descendants for your convenience. For example, the subobjects for a master object appear for your reference as a developer. However, they are not included in the object definitions for the package and are not included when the package is exported. When you add an item and its descendants, all subobjects and child items are included in the package definition hierarchy. For example, a lookup for an attribute appears in the hierarchy. Descendants also appear on the Package Details - List page. For example, the portlets on a parent page appear.
      You cannot add references to System Restricted Lookups and Restricted Portlets in your content package. However, if an item refers to a System Restricted Lookup or Restricted Portlet and that item is added with its descendants, the reference is included. For example, you create a portlet page and add two portlets. You add a Restricted Portlet such as Action Items and a grid portlet such as Budget vs. Cost. You add the portlet page to your package as a content item by selecting Item and descendants. The Action Items portlet is not available on the Package Details - List page. It appears as a reference of its parent on the Package Details - Hierarchy page.
    3. To add content from a list, click Browse. A page appears for you to browse and add content.
      • Enter filter criteria and click Filter or click Show All to display all of the matching content.
      • Select one or more check boxes for the content that you want to add. Click Add or click Add and Select More. Both buttons provide options to add items with or without descendants.
      • Click Return.
  6. To add all matching content of any type by ID, Name, or Source click the Auto Populate menu:
    1. In the required list, select 
      Content ID
      Content Name
      , or 
      Content Source
      .
    2. Enter the identifier, name, or source of the content. You can use the * character for a wildcard in your search. For example, enter the following string to find matching content with the letters 
      region 
      in the name:
*region*
All content items of multiple types with a matching name, id, or source are automatically added to the current package. For example, all of the following items are added to the package:
Sales by 
Region
 page
Region
al Sales portlet
Users in 
Region
 7 portlet
Region
al Users query
 Some items, for example objects, do not have a content source. As a best practice, do not use open-ended filter expressions such as * to add all the available items. Apply strict naming conventions to Studio objects and other content items. Consistent names help you identify your content and add it to a package. For example, apply the names pj2.MyPortlet, pj2.MyQuery, and pj2.MyPage. Then, use the Auto Populate menu to add all items and descendants with pj2 in their ID.
  • To review the content items in a package, click the Details tab and select Hierarchy. Expand an entry to view its descendants. 
  • To remove a content item from a package, click the Details tab and select List. Select one or more check boxes and click Remove. The items are removed from both the List and Hierarchy pages. The original objects remain in the system and can be added again later if necessary.
Include or Exclude Item References in Packages
You can include or exclude content item references in the content package. When you create a package and add content items, their Studio object definitions are included by default. As a content developer or administrator, you can choose which content item references are included or excluded.
Icons in the Included column indicate the current inclusion status of each item.
  • The reference to a content item with no icon is always included and cannot be excluded. Examples include master objects and parent portlet pages. You also cannot exclude the lowest level item in a hierarchy if it is required by the parent. For example, you cannot exclude a query if the parent portlet is based on it.
  • The reference to a content item with a green check mark (
    Image to include this content (green check mark icon).
    ) is included in the content package.
  • The reference to a content item with a red circle and white x (
    Image to exclude this content (red circle with X icon).
    ) is excluded from the content package.
 
Follow these steps:
 
  1. Open Administration, and from Studio, select Content Packages.
  2. Click the Hierarchy icon for a content package.
  3. Expand an entry to view its descendants.
  4. To exclude an item:
    1. Select its check box.
    2. Click Exclude.
      The selected item and any descendants in the hierarchy are excluded from the package.
  5. To include an item:
    1. Select its check box.
    2. Click Include.
      The child item and its ancestor items in the hierarchy are included in the package.
  6. Click Return.
 When you change the inclusion status of an item, in an indirect way, you are modifying the parent item definition in the package. To alert you, a check mark icon appears in the Modified column of the Package Details - List page.
Build a New Instance of a Content Package
When you build a content package, the application creates a JAR file with XML files for the selected content. As a developer, you can design content items, build and export a package, and then re-import the content in another environment.
 
Follow these steps:
 
  1. Open Administration, and from Studio, select Content Packages.
  2. Open a content package and verify the version. To build a new version, update the Version field.
  3. Click the Details tab.
     Only the content items that appear on the Details - List page are exported with the next build of the package.
  4. Click the Package button.
    The Processes tab appears.
  5. (Optional) You can examine the export progress or allow it to continue unattended in the background.
    1. To determine status, view the Progress bar, Steps in Progress, Status, Start Date, and Finish Date columns.
    2. To view messages, click the icon in the Messages column. For example, a validation message appears if you exclude a dependent subobject or lookup from another object definition in the package. You can go back and include it in the export or choose to leave it out.
      • To view more details, click Show Details.
      • To return to the previous page, click Return.
    3. To update the progress, click the Refresh button periodically.
  6. Click the Properties tab.
    1. Click the 
      Package
       file link. You can identify different packages by the following naming structure:
      <content_package_ID>_<version>_<datetime_stamp>.jar
      For example, 
      MyPackage1_2.0.1_20150929163055.jar
      .
       
    2. To view the 
      Extracted Language File
       for your original source strings, click its JAR file. This file has the following naming structure:
      <content_package_ID>_nls.jar
      We recommend localizing the content items strings for each target language. To localize the strings, download this file and then unjar it. Translate the target language file strings and create a JAR file with the updated localized strings.
      When you develop the next version of a delivered package, the extracted language file contains the <CAPPM> translated properties. You do not need to translate these strings again. If you do make changes to the strings, the system automatically detects the modification to a content item. The next version (revision) number is set and the latest translations are applied to the affected content items. When the administrator installs the new instance of the add-in, the status of the content items appear as Upgrade Ready.
    3. To upload a 
      Translated Language File
      , click Choose File and select the translated JAR file.
    4. Click Save
    5. To re-package the content with a new translated language file, repeat Step 4 (click the Package button again).
  7. Right-click the package JAR file and choose Save link as.
    1. Select a folder.
    2. Click Save.
    Your content is now available to share with others and to upload as an add-in in another environment.
  8. (Optional) Examine the XML files in the JAR file to view the content elements and attributes in the package. Only the items that you designated as 
    included 
    appear. Excluded references do not appear.
    In the XML for the exported JAR, the version appears as a 4-digit number in the revision attribute. For example, version 12.0.3 appears as follows: 
    revision="1203"
Modify a Content Item in a Package
You can modify the content item definitions after you build a package. The original package JAR file serves as a baseline for the version. If you update the package version, only the items marked 
Modified
 are updated in the next build. Unmodified content items remain in the package and their definitions are not updated in the next build.
 
Follow these steps:
 
  1. Open the content package and update the version number in sequence.
  2. Change one or more content items.
  3. Click Details and select List.
  4. On the Details List page, select the items that were modified and that you want to update in the next version of the package.
  5. Click Modifications and select Set.
    Check marks appear in the Modified column.
     If no check mark appears when you set an item, that item is new and was not present in the original baseline content package.
Another way to capture modified content in the package is to exclude and then include the items in the hierarchy.
 
Follow these steps: 
 
  1. Click Details and select Hierarchy.
  2. Exclude one or more items and then include the new or changed items.
    When you include them again, the item references include any changes. The new or modified content is included in your next package.
     When you exclude and then include items, the Modified column is automatically updated.
Migrate a Content Package for Development
You can import content from packages that were developed internally or by third parties. For example, import a content package from team A on one environment and continue development by team B on another environment.
 
Follow these steps:
 
  1. Build a new instance of the package. You can also update the version.
  2. Upload the package as an add-in. See Upload a Content Package as an Add-in for Users.
     Select 
    Install in Migration Mode
    . This option forces all content items in the package to install and upgrades any existing content from a previous version. New content items overwrite old ones on the target system. Upgrade Ready status does not apply in migration mode. After installation, all content items display the 
    Installed 
    status.
  3. Open Administration, and from the Studio menu select Content Packages.
  4. Click Upload Package.
  5. On the Upload Content Package page:
    1. Click Choose File.
    2. Select a content package JAR file and click Open.
    3. Click Save.
  6. Click the Properties tab.
    1. Verify the value in the Status field (for example, set to 
      In Development
      ).
    2. Verify that the correct version information appears.
    3. Click Save.
  7. To view the installed objects and attributes in the package, click Items and select List or Hierarchy.
  8. To verify that the content appears correctly:
    1. Navigate to a known page or portlet in the package.
    2. Log in using several users with different access rights.
Upload a Content Package as an Add-in for Users
As an administrator, you can import content from packages that were developed internally or by third parties. Like other add-ins, the content add-in extends the functionality of the application.
 This procedure requires the 
Content Add-Ins - Administer
 and 
Administration - XOG
 global access rights.
 
Follow these steps:
 
  1. Open Administration, and from the Studio menu, select Content Add-ins.
  2. Click Upload Content Package.
  3. On the Upload Content Package page, click Choose File.
  4. Select a content package JAR file and click Open.
  5. To force all content items in the package to install and upgrade any existing content from a previous version, select Install in Migration Mode.
  6. Click Save.
    The Processes tab appears.
     The Processes tab does not appear for legacy add-ins that are bundled with 
    Classic PPM
    .
  7. To determine status, view the Progress bar, Steps in Progress, Status, Start Date, and Finish Date columns.
  8. To view content installation messages, click the icon in the Messages column.
    • To view more details, click a line item and then click Show Details.
    • To return to the previous page, click Return.
  9. Click the Properties tab.
    1. Verify that the Status field shows 
      Installed
      .
    2. Verify that the correct version information appears.
    3. Click Return.
  10. To view the installed content items in the package, click Items and select List or Hierarchy. Examine the Status field.
    1.  
      Upgrade Ready
       appears when a new item is available in a new version of a package you uploaded. These items were modified in the new version. To install items in an Upgrade Ready state, select them and click Install. Any new versions of items overwrite old items. Click Yes to confirm.
      The Status changes to 
      Installed 
      or 
      Processed
      .
    2.  
      Not Installed
       appears when the new item is not installed.
    3.  
      Upgrade Pending
       appears only for content add-ins that are available with the 
      Classic PPM
       application.
  11. To verify that the content appears correctly:
    1. Navigate to a known page or portlet in the package.
    2. Log in using several users with different access rights.
  12. (Optional) To examine the history, open Administration, and from Studio select Content Add-ins. Open an add-in, click History, and select Content Items.
     Any protected items show a 1 in their Revision column. For example, objects with protected views are not updated with a new version. Click the Items tab and select the 
    Upgrade Ready
     items that you want to install. For example, you can upgrade and overwrite protected views with object views in the new version of the package. On the Content Add-Ins History page content items are not localized. They are shown as they appear in the database tables.
 The system cannot update an 
Active
 process. To update a process with content from an add-in or Studio content package, set the process to 
On Hold
. Running instances are not disturbed. The process definition is updated when the content add-in is applied on the target system. Then, set the updated process back to 
Active
.
Content Add-in Versions
The following version information appears on the Properties page for a content add-in:
  •  
    Content Add-in Base Version 
    The original version of the content add-in or package when it was first installed.
  •  
    Clarity
    Base Version 
    The original version of 
    Classic PPM
     when the content add-in or package was first installed.
  •  
    Content Add-In Installed Version
    The current installed version of the content add-in.
  •  
    Clarity
    Installed Version
    The current installed version of 
    Classic PPM
     that was active when the selected add-in was last installed.
  •  
    Content Add-In Installed Date 
    The date and time when the content add-in or package was installed.
  •  
    Sample Data Installed Date
    The date and time when the optional PMO add-in sample data was installed.
For new installations, only the base versions appear. For 
Classic PPM
 upgrades with no corresponding upgrade to the add-in, the add-in continues to show only its base version. In other words, the installed version fields appear only when they are different from the base version.
 
Example
 
Your organization upgraded from 
Classic PPM
 Version 13.0 to Release 13.2. At the same time, you upgraded from PMO add-in 3.0 to 3.2. You did not upgrade to release 14.x yet. The 14.x version applies to both 
Classic PPM
 and the PMO add-in. As an administrator, you attempt to upload the PMO 14.x add-in. The Status field for the PMO add-in shows 
Upgrade Pending 
because it requires an application upgrade. The following version information appears:
  • Content Add-In Base Version: 3.0.00
  • Clarity
    Base Version: 13.0.00
  • Clarity
    Installed Version: 13.2.00
When you install 
Classic PPM
 14.x, the status of the PMO 14.x add-in upgrade changes to 
Upgrade Ready
.
  • Content Add-In Base Version: 3.0.00
  • Content Add-In Installed Version: 14.x.00
  • Clarity
    Base Version: 13.0.00
  • Clarity
    Installed Version: 14.x.00
After installation, the status changes to 
Installed
.
Troubleshoot Package Validation Message Dependent Items Are Missing
 
Symptom:
 
I receive the following validation warning message when I attempt to export a content package:
...installation might fail because some of the dependent items are missing. For more information, click 'Show Details' button.
 
Solution:
 
One or more descendants for one or more items in your content package are missing. For example, you or another content developer uploaded a portlet but did not upload its associated query. When the exported package is installed in a target destination, it can fail. The reason it can fail is because the same query does not already exist on the target system. Reset the content in the latest version of the package and build the package again.
 
Follow these steps:
 
  1. Wait for the status of the export to appear as Completed.
  2. On the Content Package Processes page in the Messages column, click the warning flag icon.
  3. Click Show Details.
  4. Identify the name of the parent item in the Message column and the child item in the Exception column. For example, the message shows 
    [Validation] Portlet - 'portlet_name'
    . To help you identify the descendant, 
    Query - query_name
     appears in the Exception column.
  5. Add the parent item and descendants to the package again so that nothing is missing.
Troubleshoot Package Status Installation Failed
 
Symptom:
 
When I upload a content package, its status shows 
Installation Failed
.
 
Solution:
 
A likely cause of failure is a missing parent for a descendant item. For example, you are uploading a package with a view definition for an object that does not exist in the target environment.
 
Follow these steps:
 
  1. Open Administration, and from the Studio menu select Content Add-ins.
  2. Click Upload Content Package and select a package JAR file.
    Installation Failed
     appears in the Status column.
  3. Open the contents of the package. Examine the type and ID of the items to determine the missing entity.
  4. Create or modify the missing item. For example, create a new parent object for a view that failed to install.
  5. You can also try re-adding the items and descendants to the original package and then exporting it again.
  6. Open Administration, and from the Studio menu select Content Add-ins.
  7. Click Upload Content Package and select the same or a new package JAR file.
    Installed
     appears in the Status column.