How to specify field order with RDF+XML content using the OSLC 2.0 REST API

Answer

Starting with ClearQuest version 7.1.2.4, we have added a new RDF ClearQuest specific property that allows you to specify the ordering of fields. If this new property is not used, then fields will be updated or set in random order.

The new property is: cq:fieldOrder

Using this new property will change the RDF syntax a bit. Here are some things you need to know before proceeding:

1. Your schema is what ultimately owns the ordering of the fields, so its up to the person creating the RDF syntax to understand what order the fields need to be processed in.
2. The number you assign to cq:fieldOrder can any number between 1 and the total number of fields in the record type.
3. Using cq:fieldOrder will guarantee that the XML/parsing will preserve the ordering you defined, however if that ordering isn't supported by your schema, then the request can fail depending on your schema logic.

Before you can actually use cq:fieldOrder you need to define the fields that are order dependent. For instance, assume that you have the following CQ fields and require that test_field5 be set before test_field4. Using RDF reification, the new RDF syntax will look something like this:

<cq:test_field4>test_field4 value</cq:test_field4>
<cq:test_field3>aaa1</cq:test_field3>
<cq:test_field1>ccc1</cq:test_field1>
<cq:test_field2>bbb1</cq:test_field2>
<cq:test_field5>test_field5 value</cq:test_field5>
<cq:Severity>3-Average</cq:Severity>

In the above code we have 5 fields defined (test_field1, test_field2, test_field3, test_field4, and test_field5).

Once you have your fields defined, then you need to define the order the fields will be processed. You use the following syntax to achieve that. We have included the new text in bold

<cq:test_field4 rdf:ID="test_field4">test_field4 value</cq:test_field4>

<cq:test_field5 rdf:ID="test_field5">test_field5 value</cq:test_field5>
<rdf:Statement rdf:about="#test_field4">
<cq:fieldOrder>2</cq:fieldOrder>
</rdf:Statement>
<rdf:Statement rdf:about="#test_field5">
<cq:fieldOrder>1</cq:fieldOrder>
</rdf:Statement>

The order in which you list the cq:fieldOrder statement does not matter, its the number you assign to the cq:fieldOrder that controls the order. It will always process the lowest cq:FieldOrder first. In the above example since test_field5 is given the cq:fieldOrder of 1, it will be processed first, and then test_field4 will be processed next, followed by the rest of the fields in random order.

Here is the entire rdf statement:

HTTP Method: POST or PUT
HTTP URL: https://localhost/cqweb/oslc/repo//db//record
HTTP Headers: OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
HTTP Content:

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
    xmlns:cq="http://www.ibm.com/xmlns/prod/rational/clearquest/1.0/&quot;
    xmlns:dcterms="http://purl.org/dc/terms/&quot;
    xmlns:oslc="http://open-services.net/ns/core#&quot;
    xmlns:oslc_cm="http://open-services.net/ns/cm#&quot;
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"&gt;
    <oslc_cm:ChangeRequest>
        <cq:test_field4 rdf:ID="test_field4">test_field4 value</cq:test_field4>
        <cq:test_field3>aaa1</cq:test_field3>
        <cq:test_field1>ccc1</cq:test_field1>
        <cq:test_field2>bbb1</cq:test_field2>
        <dcterms:type>Defect</dcterms:type>
        <dcterms:title>created using oslc2</dcterms:title>
        <cq:test_field5 rdf:ID="test_field5">test_field5 value</cq:test_field5>
        <cq:Severity>3-Average</cq:Severity>
    </oslc_cm:ChangeRequest>
    <rdf:Statement rdf:about="#test_field4">
        <cq:fieldOrder>2</cq:fieldOrder>
    </rdf:Statement>
    <rdf:Statement rdf:about="#test_field5">
        <cq:fieldOrder>1</cq:fieldOrder>
    </rdf:Statement>
</rdf:RDF>

For the content above, the fields with explicit ordering (test_field4 and test_field5) will be processed in the order specified, while the other fields (test_field1, test_field2, Severity, title and test_field3) will be processed in random order.

You only need to use this new syntax if field order matters within your schema. If it doesn't then no modification of your content is needed