XOG Schema, Sample XML Files, and Special Characters

ccppmop1591
Use these XOG tips and guidelines to learn how to use schema files, read and write files, special characters, date and time format, filtering, and values to pass with the XOG.
2
2
Schema Files
Schemas are templates that contain the rules for creating valid XML files that are run using XOG. The schema definitions apply to all read and write requests and responses. You can access the schemas from the 
Classic PPM
 server or from the XOG client directories on your computer. To find the schema definitions on the 
Classic PPM
 server, navigate to the
$installDir
/webroot/WEB-INF/xog/xsd directory.
In this directory,
$installDir
 is the customer installation directory. For example, 
E:/niku/install
.
To find the schema definitions in the XOG client directories on your computer, navigate to the directory where the XOG client is installed and look in the 
xsd 
directory. The directory contains common schema definitions and object-specific definitions.
The xsd folder contains schema definitions which assist you to create valid XML files. However, we recommend you to verify that the attributes are documented in the XOG Object Reference before proceeding to use them. Some attributes in the xsd files might be deprecated or unsupported.
Schema Definitions
These schema definitions are found in the 
xsd 
folder:
  • nikuxog_read.xsd (read request)
    . This schema definition includes these items:
    • nikuxog_readTypes.xsd. This schema defines the NikuDataBus request element.
    • nikuxog_readQueryTypes.xsd. This schema defines the Query request element.
The nikuxog_readQueryTypes.xsd also includes the XSD files that define the read/write schemas for special stock objects.
  • nikuxog_<object>.xsd (read response and write request)
    . This schema definition applies to a read object response or a write object request.
  • status.xsd (write response)
    . This schema definition applies to all write object responses.
NikuDataBus Header Element
All read and write objects require the header element. This element is also common to all request schemas. The header defines the base version of the XOG service and the external source. The header element has these attributes:
  • version
    . Required. The version of the XOG in standard XML format.
    Type:
     String
  • externalSource
    . Required for Writes only. Here are the supported values:
    • NIKU
    • ORACLE-FINANCIAL
    • PEOPLESOFT
    • SAP
    • OTHER
    • OTHER-EXPENSE
    • OTHER-TIME
    • REMEDY
Default:
NIKU when reading from 
Classic PPM
.
Type:
String
Attribute Information in the Schema
You can find the following attribute information in the schema:
  • Sequence
  • Attribute name
  • Maximum field length
  • Required field indicator
The following image shows attribute information in a schema file.
This image shows attribute information in a schema file.
XML Read and Write Files
You can use the sample XML read and write files for 
Classic PPM
 objects that are provided with the XOG client to import or export data. These files are stored in the
xml
directory that was created when you installed the XOG client.
XML Read Files
You can edit an example XML read file to create a new XML read file or to export the information that you want for an object. Each example read file contains the necessary header information, arguments, and query filters to complete a read for the object the file represents. The following image shows an example XML read file for the project object (prj_projects_read.xml).
This image illustrates a sample XML read file.
  • In the header section, the action
    read
    and the objectType
    project
    indicate that this file is for exporting (reading) project data.
  • The arguments indicate the type of project information that you want included in the data export. The default is to order the output first by name (order_by_1) and then by project ID (order_by_2). You can change the order by swapping the numbers
    1
    and
    2
    in the argument names. The default value for arguments that include data is true. Set arguments to false if you do not want to include project information in the output.
  • The query section and its filter criteria selection limit the data to only what is necessary.
XML Write Files
You can create an XML write file in these ways:
  • Manually
    . You can use the XML write file examples in the
    xml
    folder that were created when the XOG client was installed. These files are templates that can be modified to create XML files for almost any write purpose.
  • Use the output of an XML read file
    . The output file of an XML read file is returned in the well-formed format of an XML write file. Edit the output file to create a new XML write file. We recommend that you use an advanced XML editor to edit this file.
Example: Create an XML Write File from the Output of an XML Read File
The following example illustrates how to create an XML write file for the project object using the output file of an XML read file.
Follow these steps:
  1. Create an example project in 
    Classic PPM
     that contains the information that you want in the final XML write file.
    In this example, a project that is named project1 is created, with two resources and a task with assignments. This project information appears in the correct XML write format in the output file.
  2. Create the XML read file. This code sample shows the XML read file for the project object.
    <?xml version="1.0" encoding="UTF-8"?> <NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_read.xsd"> <Header version="6.0.11" action="read" objectType="project" externalSource="NIKU"> <!-- you change the order by simply swap 1 and 2 number in the name attribute --> <args name="order_by_1" value="name"/> <args name="order_by_2" value="projectID"/> <args name="include_tasks" value="true"/> <args name="include_dependencies" value="true"/> <args name="include_subprojects" value="true"/> <args name="include_resources" value="true"/> <args name="include_baselines" value="true"/> <args name="include_allocations" value="true"/> <args name="include_estimates" value="true"/> <args name="include_actuals" value="true"/> <args name="include_custom" value="true"/> <args name="include_burdening" value="false" /> </Header> <Query> <Filter name="projectID" criteria="EQUALS">project1</Filter> </Query> </NikuDataBus>
    The header section indicates a read action for the object type
    project
    with the list of arguments for the data. The query section indicates the name of the project for the returned data.
  3. Run the XOG using the read file for the project object as input to create the output XML file.
  4. Examine the output XML file and make any necessary edits so that you can use the file as an XML write file.
  5. Save the changes. This code sample shows the well-formed XML output file.
    <?xml version="1.0" encoding="UTF-8"?> <NikuDataBus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../xsd/nikuxog_project.xsd"> <Header version="6.0.11" action="write" objectType="project" externalSource="NIKU"> <Projects> <Project active="true" alignment="100" approved="true" approvedForBilling="1" asOf="2009-01-02T00:00:00" billingCurrencyCode="USD" billingType="S" calculateFinancialMetrics="true" chargeCodeExtID="Expense" clientID="Internal" clientName="Internal" closed="false" currencyISOcode="USD" description="A Test Project Description" entityCode="CORP" equipmentCostSource="Financial Cost and Rate Matrix" equipmentExchageRateType="AVERAGE" equipmentRateSource="Financial Cost and Rate Matrix" expenseCostSource="Financial Cost and Rate Matrix" 12.0.0.5028 expenseExchageRateType="AVERAGE" expenseRateSource="Financial Cost and Rate Matrix" financialStatus="O" finish="2009-12-31T17:00:00" flexibilityRisk="0" setBudgetValuesEqualToPlannedValues="true" format="0" fundingRisk="0" goalCode="IMPROVE_INFRASTRUCTURE" humanInterfaceRisk="0" implementationRisk="0" interdependenciesRisk="0" laborCostSource="Financial Cost and Rate Matrix" laborExchageRateType="AVERAGE" laborRateSource="Financial Cost and Rate Matrix" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:42:05" managerResourceID="paulMartin" materialCostSource="Financial Cost and Rate Matrix" materialExchageRateType="AVERAGE" materialRateSource="Financial Cost and Rate Matrix" name="A Test Project" objectivesRisk="0" openForTimeEntry="true" organizationalCultureRisk="0" pageLayoutCode="projmgr.projectPageFrame" plannedBenFinish="2010-01-01T00:00:00" plannedBenStart="2009-12-01T00:00:00" plannedBenTotal="1000" plannedBreakEven="2010-01-01T00:00:00" plannedCostFinish="2010-01-01T00:00:00" plannedCostStart="2009-01-01T00:00:00" plannedCostTotal="1000" plannedNPV="0" plannedROI="0" priority="10" processCode="IT" program="false" progress="0" projectID="project1" requiredForScenarios="false" resourceAvailabilityRisk="0" sponsorshipRisk="0" stageCode="CSK_INITIATION" start="2009-01-01T08:00:00" status="1" statusComment="Status Comment Text" statusIndicator="1" supportabilityRisk="0" syncInvestmentAndBudgetDates="true" technicalRisk="0" template="false" trackMode="2"> <ProjectBaselines/> <Resources> <Resource availFrom="2009-01-01T08:00:00" availTo="2009-12-31T17:00:00" bookingStatus="5" defaultAllocation="1" isProjectManager="false" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:39:40" openForTimeEntry="true" projectRoleID="csk.Architect" resourceID="artKatect"> <Baselines/> <AllocCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> <SkillAssocs/> </Resource> <Resource availFrom="2009-01-01T08:00:00" availTo="2009-12-31T17:00:00" bookingStatus="5" defaultAllocation="1" isProjectManager="true" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:40:11" openForTimeEntry="true" projectRoleID="csk.Project Manager" resourceID="paulMartin"> <Baselines/> <AllocCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> <SkillAssocs/> </Resource> </Resources> <Tasks> <Task finish="2009-12-31T17:00:00" internalTaskID="5000578" key="false" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:39:40" lockedForScheduling="false" milestone="false" name="A Test Project" orderID="1" outlineLevel="1" percComp="0" start="2009-01-01T08:00:00" status="0" summary="false" taskID="~rmw" topDownPercent="0"> <Baselines/> <Assignments> <TaskLabor actualWork="0" baselineWork="0" estPattern="3" finish="2009-12-31T17:00:00" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:39:41" remainingWork="2088" resourceID="artKatect" roleID="csk.Architect" start="2009-01-01T08:00:00" unpostedActuals="0"> <Baselines/> <EstCurve> <Segment finish="2010-01-01T00:00:00" start="2009-01-01T00:00:00" sum="2088.0000"/> </EstCurve> <ActCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </TaskLabor> <TaskLabor actualWork="0" baselineWork="0" estPattern="3" finish="2009-12-31T17:00:00" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:40:11" remainingWork="2088" resourceID="paulMartin" roleID="csk.Project Manager" start="2009-01-01T08:00:00" unpostedActuals="0"> <Baselines/> <EstCurve> <Segment finish="2010-01-01T00:00:00" start="2009-01-01T00:00:00" sum="2088.0000"/> </EstCurve> <ActCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </TaskLabor> </Assignments> <estimateRules/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </Task> <Task chargeCodeExtID="Expense" finish="2009-12-31T17:00:00" internalTaskID="5000585" key="true" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:41:22" lockedForScheduling="false" milestone="false" name="Task1" nextSiblingOf="~rmw" orderID="2" outlineLevel="1" percComp="0" start="2009-01-01T08:00:00" status="0" summary="false" taskID="Task1"> <Baselines/> <Assignments> <TaskLabor actualWork="0" baselineWork="0" estPattern="3" finish="2009-12-31T17:00:00" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:41:03" remainingWork="2088" resourceID="artKatect" roleID="csk.Architect" start="2009-01-01T08:00:00" unpostedActuals="0"> <Baselines/> <EstCurve> <Segment finish="2010-01-01T00:00:00" start="2009-01-01T00:00:00" sum="2088.0000"/> </EstCurve> <ActCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </TaskLabor> <TaskLabor actualWork="0" baselineWork="0" estPattern="3" finish="2009-12-31T17:00:00" lastUpdatedBy="admin" lastUpdatedDate="2009-02-11T09:41:03" remainingWork="2088" resourceID="paulMartin" roleID="csk.Project Manager" start="2009-01-01T08:00:00" unpostedActuals="0"> <Baselines/> <EstCurve> <Segment finish="2010-01-01T00:00:00" start="2009-01-01T00:00:00" sum="2088.0000"/> </EstCurve> <ActCurve/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </TaskLabor> </Assignments> <estimateRules/> <CustomInformation> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> </Task> </Tasks> <Dependencies/> <Subprojects/> <Allocations/> <scenarioDependencies/> <InvestmentAssociations> <Allocations/> <Hierarchies/> </InvestmentAssociations> <CustomInformation> <ColumnValue name="obj_align_factor1">50</ColumnValue> <ColumnValue name="obj_align_factor2">50</ColumnValue> <ColumnValue name="obj_align_factor3">50</ColumnValue> <ColumnValue name="obj_align_factor4">50</ColumnValue> <ColumnValue name="partition_code">NIKU.ROOT</ColumnValue> </CustomInformation> <General addedBy="admin" addedDate="2009-02-11"/> <OBSAssocs complete="false"> <OBSAssoc id="Business Unit" name="Business Unit" unitPath="/All Business Units/Business Operations/Operational Systems"/> <OBSAssoc id="corp_dept" name="CORP Department OBS" unitPath="/CORP IT"/> <OBSAssoc id="Security OBS" name="Security OBS" unitPath="/Corporate/IT/Portfolio"/> </OBSAssocs> <BurdeningAssocs> <BurdeningAssoc transactionType="Labor"/> <BurdeningAssoc transactionType="Material"/> <BurdeningAssoc transactionType="Expenses"/> <BurdeningAssoc transactionType="Equipment"/> </BurdeningAssocs> </Project> </Projects> <XOGOutput> <Object type="project"/> <Status state="SUCCESS"/> <Statistics failureRecords="0" insertedRecords="0" totalNumberOfRecords="1" updatedRecords="0"/> <Records/> </XOGOutput> </NikuDataBus>
Special Characters
Escape special characters in XOG requests to ensure a successful XOG read or write request. You can escape special characters or can use CDATA.
Escape Rules
You can use one of the escape rules in the following table to escape special characters in the XML file:
Special Character
Rule
& (Ampersand)
&amp;
' (Apostrophe)
&apos;
> (Greater-than)
&gt;
< (Less-than)
&lt;
" (Quotes)
&quot;
Example:
This example shows how to handle the term
E1&P2
in the XML text by escaping the term:
<ColumnValue name ="abn_vendor_names">E1
&amp;
P2</ColumnValue>
CDATA
You can use CDATA instead of escaping special characters. CDATA is a section of the element content in XML that is marked so that it is interpreted only as character data, and not as markup data. To start a CDATA section, use
<![CDATA[
. To end a CDATA section, use 
]] >
.
CDATA Example
This example shows how to handle the term
E1&P2
in the XML text using CDATA.
<ColumnValue name ="abn_vendor_names">
<![CDATA[E1&P2]] >
</ColumnValue>
Date and Time Format
Use this standard format for date and time strings for the XOG:
  • Date format: YYYY-MM-DD
  • Time format: HH24MMSS
Consider this important information:
  • Date and time values for custom objects
    . The date and time value of a date attribute is stored in Greenwich Mean Time (GMT). For a custom object, offset the date and time value that is being stored from your locale to GMT. For example, if the date and time that you want is November 20th, 2008, 15:15 (3:15PM) in Tokyo, the date and time value in the XOG write file must be formatted and adjusted to GMT time (which in Tokyo is +9 hours). The resulting offset-formatted value to be entered in the XOG import file is 2008-11-21T00:15:00.
  • Timestamps for task finish dates
    . Include a timestamp for task finish dates in the prj_projects_write.xml file. If you do not, the time defaults to 00:00:00. The effect of the default is that in the Portfolio portlets, the finish dates with the default timestamp applied display a day later. For example, The Portfolio portlets show 2009-01-01, when the actual finish date is 2008-12-31. To avoid the addition of an extra day to a finish date, use 17:00:00 as the timestamp when one is not provided.
Use of EQUALS, OR, BETWEEN, AFTER, and BEFORE
Filtering in a XOG read request requires criteria values. Here are some possible criteria values:
  • EQUALS
  • OR
  • BEFORE
  • AFTER
  • BETWEEN
Examples:
<Filter name="projectID" criteria="
EQUALS
">test</Filter>
<Filter name="projectID" criteria="
OR
">project1,project2</Filter>
<Filter name="projectID" criteria="
AFTER
">A</Filter>
<Filter name="projectID" criteria="
BEFORE
">Z</Filter>
<Filter name="start" criteria="
BETWEEN
">2007-01-07,2009-01-15</Filter>
Do not use spaces around comma-separated entries for
OR
and
BETWEEN
filters.
Values to Pass
The following table shows the values that the XOG expects in specific cases:
Field Type
Value Type Passed
Lookup
lookup_code, lookup_enum, or lookup ID. The type that is passed depends on the configuration of the lookup.
Custom Boolean field
1 or 0