Usage Guidelines

This section contains the following topics:

About the Schema Files

About the XML Read and Write Files

Special Characters

Date and Time Format

Use of EQUALS, OR, BETWEEN, AFTER, and BEFORE

Values to Pass

About the Schema Files

Schemas are templates that contain the rules for creating valid XML files that are run using the XOG. The schema definitions apply to all read and write requests and responses. You can access the schemas from the CA Clarity server or from the XOG client directories on your computer.

To find the schema definitions on the CA Clarity server, navigate to:

$installDir/webroot/WEB-INF/xog/xsd

where, $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.

More information:

Schema Definitions

NikuDataBus Header Element

Attribute Information in the Schema

Schema Definitions

The following schema definitions are found in the xsd folder:

nikuxog_read.xsd (read request)

This schema definition includes:

nikuxog_readTypes.xsd. This schema defines the NikuDataBus request element.
nikuxog_readQueryTypes.xsd. This schema defines the Query request element.

Note: 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.

More information:

NikuDataBus Header Element

Attribute Information in the Schema

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 the following attributes:

version

Required. The version of the XOG in standard XML format.

Type: String

externalSource

Required for Writes only. Values include:

NIKU
ORACLE-FINANCIAL
PEOPLESOFT
SAP
OTHER
OTHER-EXPENSE
OTHER-TIME
REMEDY

Default: NIKU when reading from CA Clarity PPM

Type: String

More information:

Schema Definitions

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 figure shows attribute information in a schema file.

Illustration shows attribute information in a schema file.

About the XML Read and Write Files

Example XML read and write files for CA Clarity objects you can export and import are provided with the XOG client. These files are stored in the xml directory created when you installed the XOG client.

More information:

What is in an XML Read File

How to Create an XML Write File

XOG Client Directories

What is in an XML Read File

You can modify an example XML read file to create a new XML read file. Each example read file contains the necessary header information, arguments, and query filters to complete a read for the object the file represents. You can edit an example XML read file to export the information you want for an object.

The following figure shows the example XML read file for projects (prj_projects_read.xml).

The illustration shows the sample Project XML file.

In the Header section, the action read and the objectType project indicates that this file is for exporting (reading) project data.
The arguments indicate the types of project information you want included in the 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 any to false that you do not want to include in the output.
The Query section and its filter criteria selection limit the data to only what is necessary.

More information

How to Create an XML Write File

Example: Create an XML Write File from the Output of an XML Read File

How to Create an XML Write File

You can create an XML write file in the following ways:

Create the XML write file manually
You can use the XML write file examples in the xml folder installed 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. It is recommended 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.

Create an example project in CA Clarity that contains the information you want in the final XML write file.
In this example, a project named project1 was created, with two resources and a task with assignments. This project information will appear in the correct XML write format in the output file.

Create the XML read file.

The following code sample shows the XML read file.

<?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="12.0.0.5028" action="read" objectType="project" externalSource="NIKU">
    <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"/>
  </Header>
  <Query>
    <Filter name="projectID" criteria="EQUALS">project1</Filter>
  </Query>
</NikuDataBus>

The Header section indicates that this is a read action for the object type "project" with the list of arguments indicating the data that is to be read. The Query section indicates the name of the project for which data is to be returned.

Run the XOG using the read file as input.
The output XML file is created.
Examine the output XML file and make any edits necessary so that you can use the file as an XML write file.

Save the changes.

The XML write file is created.

The following code sample shows the output file. It is a well-formed XML write 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 action="write" externalSource="NIKU" objectType="project" version="12.0.0.5028"/>
<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>
            The topics that follow describe how to perform the tasks most routine to this interface.
                <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 completed="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

You must escape special characters in XOG requests to help ensure a successful XOG read or write request. You can escape special characters or use CDATA.

Use Escape Rules

You can use one of the following escape rules to escape special characters in the XML file.

Special Character	Rule
& (Ampersand)	&
' (Apostrophe)	'' Apostrophes must be double-escaped as shown.
> (Greater-than)	>
< (Less-than)	<
" (Quotes)	"

Escape Example

The following example shows how to handle the term E1&P2 in XML text by escaping the term:

Use CDATA

You can use CDATA instead of escaping special characters. CDATA is a section of element content in XML that is marked so that it is interpreted only as character data, not markup data.

To start a CDATA section, use:

<![CDATA[

To end a CDATA section, use:

]]>

CDATA Example

The following example shows how to handle the term E1&P2 in XML text using CDATA.

Date and Time Format

You must format date and time strings in the following standard format for the XOG:

Date format: YYYY-MM-DD
Time format: HH24MMSS

Note the following:

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, you must offset the date and time value being stored from the locale you are in to GMT. For example, if the desired date and time is November 20th, 2008, 15:15 (3:15PM) in Tokyo, the date and time value in the XOG write file needs to be formatted and adjusted to GMT time (which in Tokyo is +9 hours). So the resulting offset-formatted value to be entered in the XOG import file would be 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 Portfolio portlets, the finish dates with the default timestamp applied display a day later. For example, 2009-01-01 shows in the Portfolio portlets, 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. Possible criteria values include:

EQUALS
OR
BEFORE
AFTER
BETWEEN

Examples:

<Filter name="projectID" criteria="OR">project1,project2</Filter>

Important! No spaces should be used around comma-separated entries for OR and BETWEEN filters.

Values to Pass

The following table shows the values expected by the XOG in specific cases.

Field Type	Value Type Passed
Lookup	lookup_code, lookup_enum, or lookup ID. The type passed depends on the configuration of the lookup.
Custom Boolean field	1 or 0