XOG: Content Pack

ccppmop1561
Use the Content Pack XOG object to create new content for 
Clarity PPM
. A content item is any item that displays in 
Clarity PPM
 but is not considered data. For example, a graph portlet is considered a content item, but a project is considered data.
Use this object to view inbound and outbound add-in items.
Schema Names
The following schema names are associated with the content pack XOG object:
  • nikuxog_contentPack.xsd
  • nikuxog_pageTypes.xsd
  • nikuxog_filter_portlet.xsd
Read and Write XML Files
The following XML files are included:
  • content_pack_read.xml. Use this file to export content packs from 
    Clarity PPM
    .
  • content_pack_write.xml. Use this file to import content packs that were previously exported from 
    Clarity PPM
    .
Terms
The following terms are used when describing the content pack XOG object:
  • Content Item
    Defines the user-defined add-in item that adds or extends
    Clarity PPM
    .
  • Queries
    Defines the queries.
  • Reports and Jobs
    Defines the reports or jobs. You can migrate (import and export) report and job definitions using the XOG.
  • Portlets (graph or grid)
    Defines the portlets. You cannot import or export system-supplied portlets using the XOG. They are not considered user-defined add-in items.
  • Pages
    Defines the pages.
  • Lookups
    Defines the lookups. You can export system-supplied lookups.
  • Menus (menu manager sections and links)
    Defines the menus.
  • Content Pack
    Defines the collection of content that is bundled into a single distributable package.
Business Rules and Processing
The following business rules and processing apply to this XOG:
  • When creating add-in items, set up a staging server that is separate from the production server. After reviewing, testing, and verifying the effectiveness and usability of the new add-in items, you can determine that the add-in items are ready for production. You can then transfer the items to the production server. During this process, the items are exported from the staging server and imported to a production server.
  • Instead of exporting and importing a series of add-in item XML (XOG) files, you can export many add-in items, then import them as a single XML file.
For example, you can do the following:
  1. Create a page that contains add-in items (portlets, queries, and lookups).
  2. Add the portlets to a menu.
  3. Run the XOG and export the content.
    The resulting XML file contains all of the add-in items. The file is fully annotated to describe how each element is filtered.
The attribute values for the filterMapping element (part of the PortletReferenceType complex type) have the following prerequisites that are unique to the filter portlet type:
  • The filterPortletCode attribute value must match the portlet code of a valid filter portlet that is defined in the filter portlet schema.
  • The fieldCode attribute value must match the field code of a valid filter portlet that is defined in the filter portlet schema.
  • The dataProviderItemCode attribute value must match the column code of a valid grid or graph portlet column.
  • The dataProviderItemCode and fieldCode attribute values must reference an attribute of the same data type.
  • If the data type is a lookup, then the lookup type codes must  be the same between the attributes.
Dependencies
Add-in items have dependencies that are automatically resolved by the XOG. For example, if a query depends on a lookup and the query is imported, the lookup must also be imported (if it does not already exist). The dependencies in the following table exist when exporting add-in items:
Content Item Depends On
Content Item
Queries
Lookups
Graphs and Grids
Queries or Lookups
Jobs
Lookups
Pages, Portlets, and Queries
Lookups (sometimes Objects if data provider of portlet is object)
Menu Links
Pages
All items
Security
Objects
Lookups
OBS associations for pages, portlets, and jobs are exported. They are also imported if the OBS and OBS unit (including parentage) exist in 
Clarity PPM
. The same is true of security, which is imported if the user, group, or OBS unit exists.
Import Rules
Each add-in import request is regarded as a single transaction. If one item fails, the entire add-in is not imported. Add-in items are imported from XML files, which can be produced during the export or created manually.
If an item is modified to include new entries before an item is imported, the new entry is not affected by the import process; the import operation ignores the new entry.
Example
Consider a static lookup that is named SAMPLE_LOOKUP that contains the following values:
  • OPEN
  • CLOSED
  • IN PROGRESS
You add a new lookup value of SUSPENDED and change the existing label from CLOSED to FINISHED. You import a Best Practice Accelerator that includes the definition for SAMPLE_LOOKUP. That lookup contains three lookup values (OPEN, CLOSED, and IN PROGRESS) and the new lookup value (DELAYED). When the import operation completes, 
Clarity PPM
 contains the following lookup values:
  • OPEN
  • CLOSED (the change is overwritten)
  • IN PROGRESS
  • SUSPENDED (addition made to 
    Clarity PPM
     using the application user interface is preserved)
  • DELAYED (new item that was present in the input Best Practice Accelerator file is also added)
When you import an add-in item, it is updated with the definition that is present in the file. If a content item contains a new addition that does not exist in 
Clarity PPM
, the new addition is also created in 
Clarity PPM
. When importing an existing lookup, all rules that are described in the following table apply. The following table shows the various import rules that are associated with a lookup and the lookup values. The user interface honors these rules. As a result, the XOG import process for lookups honors the rules in the following table:
Function
Restricted
System
User-defined
Static List Lookups
Change Lookup Name and Description
Yes
Yes
Yes
Change Sort Order (Manual or Alphanumeric)
No
Yes
Yes
Deactivate or Activate Lookup
No
No
No
Delete Lookup
No
No
Yes
Change Lookup Value Name and Description
Yes
Yes
Yes
Create New Lookup Values
No
Yes
Yes
Deactivate or Activate Lookup Values
No
Yes (user-defined values)
No (seeded values)
Yes
Reorder Lookup Values
Yes
Yes
Yes
Dynamic Niku Query Lookups
Change Lookup Name and Description
Yes
Does not apply
Yes
Edit Query
No
Does not apply
Yes
Edit Parent Window Fields
No
Does not apply
Yes
Edit Browse Window Name and Label Fields
Yes
Does not apply
Yes
Edit Browse Window Field Element Type
No
Does not apply
Yes
Edit Browse Window Selected Fields for Filter and List
No
Does not apply
Yes
Edit Browse Window Filter Field, List Column Order
Yes
Does not apply
Yes
Edit Browse Window Default Sort Column/Order
Yes
Does not apply
Yes
Export Rules
You can export multiple add-in items simultaneously. Add-in items can be filtered so that a subset of items can be exported. For example, a system may contain four HTML portlets. The export interface allows for two HTML portlets to be exported simultaneously.
  • Portlets
    This feature does not implement business rules for portlets. Most of the attributes and elements are either optional or have default values. While the XML schema does not validate such instances, the import mechanism does validate and generate an error for invalid grids or graphs.
    For example, if a grid portlet is based on a query that does not contain metrics, then no <metricColumn> elements should be present in the imported XML schema.
  • Job definitions
    During import, the imported attributes of the definition match the user interface exactly. When parameters are changed, the old parameters are deleted and new ones are added. Existing scheduled jobs are canceled, because the parameters no longer exist. All saved parameters are deleted. If the update flag is set to
    True
    , then only captions (job and parameters) can be changed. If the update flag is set to
    False
    , the content item is assumed to contain all the parameters and existing parameters are deleted as described above.
  • Pages
    The export of a page includes all non-system portlets. OBS and security associations can be specified and, as with other items, a Warning is written to the log file if the target principal (OBS unit, Group, or User) does not exist.
  • Lookups
    Lookups are either static or dynamic. Dynamic lookups are based on NSQL. Static lookups do not contain the NSQL values that are contained in dynamic lookups. Static lookups are generated by executing the NSQL at runtime when they are rendered on a page as a pull-down or as a browse page. Static lookup values are seeded and persist as individual rows in 
    Clarity PPM
     (in the table named CMN_LOOKUPS).
    While it is true that for any content item that is part of a Best Practice Accelerator, system objects are not imported or exported, there are exceptions for  lookups. Lookups are classified into three categories: System-restricted, System, and User-defined. All lookup types (dynamic and static) can be exported.
  • Queries
    This feature follows all business rules for the query user interface. Items that can be updated using the user interface can be updated with an import request. Although the queries schema allows for multiple, vendor-specific NSQL text, only valid text is imported into 
    Clarity PPM
    . For example, an import request on an Oracle system that contains both dbVendor="mssql" and dbVendor="oracle" imports only the dbVendor="oracle".
    Text with dbVendor="all" is always imported.
    When creating queries, the user interface in the Administration Tool always sets dbVendor="all". This value cannot be changed in the user interface. Should a query be vendor-specific, you can set the dbVendor attribute value in the XML document.
    When querying for items to create a Best Practice Accelerator, you must explicitly query for each type of item in the export (read) request. The following statement returns all portlets that include source="acme.com". Without the <PortletQuery> element in the read request, no portlets are imported. For example:
    <PortletQuery>
    <Filter name="source"
    criteria="EQUALS">acme.com</Filter>
    </PortletQuery>
All add-in items have a source attribute which is used to differentiate originating-system items from
Clarity PPM
-supplied items. The source attribute maps to the column source in various database tables. To change the source for add-in items that are created with the user interface, use SQL to change the defaultValue for this column; then new add-in items will have the source specified.
This applies to the following tables:
  • CMN_PORTLETS
  • CMN_PAGES
  • CMN_SCH_JOB_DEFINITIONS
  • CMN_LOOKUP_TYPES
  • CMN_GG_NSQL_QUERIES
The SQL to change this is:
ALTER TABLE CMN_LOOKUP_TYPES MODIFY SOURCE VARCHAR (80) DEFAULT 'acme.com'
Error Handling
PageTypes filter mappings that do not meet the dependencies (described earlier), will not throw an error, but the mapping will not be implemented.
Schema Mapping
The following schema tags and attributes define the ContentPack filter portlet schema (nikuxog_pageTypes.xsd).
Filter Mapping (filterMapping) Schema Tag
The filter mapping tag is part of the schema mapping for the Content Pack XOG object. The following attributes describe the mapping of a field on a filter portlet to a data provider attribute of a grid or graph portlet. This element is only valid as a child of a grid or graph portlet reference.
The filerMapping schema tag has the following attributes:
  • filterPortletCode
    (Required) Defines the code of the filter portlet.
    Table and Column:
    Portlet ID
    Type:
    String
  • fieldCode
    (Required) Defines the code of the filter field.
    Table and Column:
    Field ID
    Type:
    String
  • dataProviderItemCode
    (Required) The code of the data provider property or metric.
    Table and Column:
    Attribute ID
    Type:
    String
  • hidePortletWhenEmpty
    When true, the referenced grid or graph portlet is hidden when no filter value is present.
    Table and Column:
    Hide If Empty
    Type:
    Boolean
portlet Schema Tag
This tag is part of the schema mapping for the Content Pack XOG object. The following schema tags and attributes define the ContentPack filter portlet schemas (nikuxog_contentPack.xsd and nikuxog_filter_portlet.xsd):
  • filterPortlet
  • Field
  • lookupParam
The Portlet schema tag has the following attributes:
  • defaultFilter
    The default filter for the page. It can be true for only one portlet on the page.
    Table and Column:
    Default
    Type:
    Boolean
  • pageLevelFilter
    Defines whether the filter values persist across the page.
    Values:
    • True. The filter values persist across this page only.
    • False. The filter values apply throughout 
      Clarity PPM
      .
    Table and Column:
    Persist
    Type:
    Boolean
filterPortlet Schema Tag
The filterPortlet schema tag inherits existing PortletAttributesTypes found in nikuxog_portlet.xsd and NLS, OBSAssocs, Security, and FilterViewTypes. These items are consistent across all portlets and not specific to filterPortlet. They are not explicitly listed.
The filterPortlet schema tag has the following attributes:
  • uiType
    Defines the UI rendering type.
    Table and Column:
    Render As
    Type:
    FilterPortlet UI Type (section, toolbar)
  • isCollapsed
    Defines the default section state.
    Table and Column:
    Default Filter State
    Type:
    Boolean
  • bgColorKey
    The session key that controls the background color of the toolbar filter portlets.
    Table and Column:
    None
    Type:
    String
Field Schema Tag
The Field schema tag is a filter field, and has the following attributes:
  • nls
    Required. The name and description of the field.
    Table and Column:
    Field Name/Description
    Type:
    NlsType
  • tip
    Defines the tool tip.
    Table and Column:
    Tooltip
    Type:
    NlsType
  • hint
    Defines the hint or instructional text.
    Table and Column:
    Hint
    Type:
    NlsType
  • defaultValue
    Defines the default value for the field.
    Table and Column:
    Filter Default
    Type:
    Any type
  • lookupParam
    Defines a parameter of a parameterized lookup.
    Table and Column:
    Lookup Parameter Mappings
    Type:
    See the lookupParam table
  • code
    Required. Defines the code of the field.
    Table and Column:
    Field Id
    Type:
    String
  • dataType
    Required. Defines the data type of the field.
    Table and Column:
    Data Type
    Type:
    String
  • extDataType
    Defines the extended type of the field.
    Table and Column:
    N/A
    Type:
    String
  • widgetType
    Required. Defines the display type of the field.
    Table and Column:
    Display Type
    Type:
    String
  • extWidgetType
    Required. The extended display type of the field.
    Table and Column:
    N/A
    Type:
    String
  • lookupTypeCode
    Defines the lookup code for a lookup field.
    Table and Column:
    Lookup
    Type:
    String
  • width
    Defines the width of the filter field.
    Table and Column:
    Width
    Type:
    Integer
  • position
    Defines the position of the filter field.
    Table and Column:
    Layout
    Type:
    Integer
  • multiValued
    Defines the lookup style of a lookup field.
    Table and Column:
    Lookup Style
    Type:
    Boolean
  • multiValuedLookup
    Indicates if the lookup field is a Multi Valued Lookup data type.
    Table and Column:
    N/A
    Type:
    Boolean
  • fixedWidget
    Indicates if the field is fixed.
    Table and Column:
    N/A
    Type:
    Boolean
  • hidden
    Indicates if the field is hidden.
    Table and Column:
    Hidden in filter
    Type:
    Boolean
  • required
    Indicates if the field requires a value.
    Table and Column:
    Required in Filter
    Type:
    Boolean
  • readOnly
    Indicates if the field's value is read only.
    Table and Column:
    Read-Only in Filter
    Type:
    Boolean
  • minValue
    Defines the minimum default value of a date or numeric range field.
    Table and Column:
    Filter Default From
    Type:
    String
  • maxValue
    Defines the maximum default value of a date or numeric range field.
    Table and Column:
    Filter Default To
    Type: S
    tring
  • columnNumber
    Defines the field's column or row in the corresponding section or toolbar filter.
    Table and Column:
    Layout
    Type:
    Integer
  • depParentLookupTypeCode
    Defines the lookup code of a dependent lookup.
    Table and Column:
    Lookup
    Type:
    String
  • depEntry
    Defines the lookup code for entry into dependent lookup.
    Table and Column:
    Entry
    Type:
    String
  • depExit
    Defines the lookup code for exit into dependent lookup.
    Table and Column:
    Exit
    Type:
    String
lookupParam Schema Tag
The lookupParam schema tag is a parameter of a parameterized lookup, and has the following attributes:
  • code
    Required. Defines the field code of the parameter.
    Table and Column:
    Field Code
    Type:
    String
  • dpCode
    Required. Defines the NSQL parameter that is specified in the lookup.
    Table and Column:
    Lookup Parameter
    Type:
    String