Using Clarity PPM XOG to Create or Update a Project via XML

Quick answer

You can insert or update Clarity PPM projects programmatically by posting an XML document to the XOG endpoint /niku/xog. The request must include basic‑auth or a valid session cookie, and the XML must follow the pattern with the required project attributes. A successful call returns Success; any validation errors appear in Failure with detailed messages.

How XOG works for a project write

Endpoint and authentication

The XOG service is exposed as a SOAP/HTTP API. For most on‑premise and SaaS installations the URL is:

https://<host>:<port>/niku/xog

Authentication can be done with HTTP Basic Auth (username/password) or by supplying a session cookie obtained from a prior login. In scripts it is safer to read credentials from environment variables or a secret store rather than hard‑coding them.

XML structure

A write request wraps one or more <Object> elements inside a root <XOGInput>. For a project the minimal payload looks like:

<?xml version="1.0" encoding="UTF-8"?>
<XOGOutput>
  <XOGInput>
    <Objects>
      <Object Name="project">
        <!-- Required attributes -->
        <Attribute Name="projectID">PROJ001</Attribute>
        <Attribute Name="name">Sample Project</Attribute>
        <Attribute Name="startDate">2026-11-01</Attribute>
        <Attribute Name="finishDate">2027-04-30</Attribute>
        <!-- Optional attributes (omit to keep existing values) -->
        <Attribute Name="description">A demo project for XOG testing</Attribute>
      </Object>
    </Objects>
  </XOGInput>
</XOGOutput>

Only the attributes listed as required for the project object in the target release must be present. Omitting an optional attribute on an update leaves the existing value unchanged.

Example call with curl

Run the following command from a terminal that has network access to the Clarity server. Replace placeholders with actual values.

curl -k -u "${CLARITY_USER}:${CLARITY_PASSWORD}" \
  -H "Content-Type: text/xml" \
  -d @project_create.xml \
  https://clarity.example.com/niku/xog

The file project_create.xml contains the XML shown above. The -k flag disables SSL verification for self‑signed certificates; remove it in production if the server has a trusted cert.

Limits and considerations

• Object‑specific required fields – each Clarity object (project, resource, task, etc.) has its own mandatory attributes. Missing any required field causes the entire <Object> to fail.
• Read‑only attributes – fields such as internalID or system‑generated timestamps cannot be supplied; attempting to do so returns a validation error.
• Dependency ordering – child objects (e.g., tasks) must reference a parent that already exists. If you need to create a hierarchy, send parent objects first in separate XOG files or ensure the parent appears earlier in the same file.
• No cross‑object transaction rollback – XOG processes each <Object> independently. If one object fails while others succeed, the successful updates are not rolled back.
• Version and deployment differences – the exact list of required attributes, supported objects, and even the endpoint path can vary between Clarity PPM releases and between on‑premise and SaaS offerings.

Common mistakes to avoid

• Omitting a required attribute such as projectID or startDate.
• Using an incorrect date format; XOG expects ISO‑8601 YYYY-MM-DD (or YYYY-MM-DDTHH:MM:SS for timestamps).
• Misspelling the object name (Name="project") or using the internal database table name instead of the API name.
• Ignoring the response status; always inspect <Status> and any <ErrorInformation> elements to detect partial failures.
• Trying to update read‑only system fields like createdBy or objectID.
• Hard‑coding internal IDs or assuming they are stable across environments.

How to verify that your XOG write works

1. Log into Clarity PPM, go to Administration → Data Administration → XOG, and click Object Metadata to confirm the required attributes for the project object in your release.
2. Create a minimal XML file with only the required attributes (as shown above) and submit it via curl or the XOG client.
3. Check the returned <XOGOutput>:
• If <Status>Success</Status> appears, log into the UI and verify that the project exists with the supplied values.
• If <Status>Failure</Status> appears, read the <Message> text to identify the missing or invalid attribute.
4. Optionally, repeat the call with an update XML (change only the description attribute) and confirm that the existing values for required fields remain unchanged.

Diagram

Labels illustrate the core pieces of a XOG write flow.

• XOG endpoint
• XML payload (required attributes)
• Success response
• Error response