What is the gcUri parameter that CLM RM DNG 6.0.3 requests?

Question

HTTP Get requests to the DNG Query Capability now fail with a Response asking for a mandatory gcUri parameter. What value should be supplied and in which Header or URL Parameter should it appear?

Answer 1

0

permanent link

Kathryn Fryer (503●1●4●7) | answered Feb 13 '17, 8:34 a.m.

Hi Lonnie,
Here's the syntax/explanation from the OSLC Configuration Management spec (https://tools.oasis-open.org/version-control/svn/oslc-ccm/trunk/specs/config-mgt/config-resources.html - Configuration Context section):

A client requests a specific configuration context in one of two ways:

When performing a GET on a concept URI, add a


                Configuration-Context

header, passing the URI of a configuration resource as the value:

Example 1

GET /resources/conceptResourceA HTTP/1.1
Configuration-Context: http://example.com/configurations/myConfiguration1
            </pre>
        </div>
    </li>
    <li>
        When performing a GET on a concept URI, add a query string
        <code>
            oslc_config.context
        </code>
        and the encoded configuration URI to the end of the request URI:
        <div class="example">
            <div class="example-title">
                <span>Example 2</span>
            </div>
            <pre class="example">

GET /resources/conceptResourceA?oslc_config.context=%3Chttp%3A//example.com/configurations/myConfiguration1%3E HTTP/1.1
            </pre>
        </div>
    </li>
</ul>
If a request contains both a header and a query string, the server <i class="rfc2119" title="MUST">MUST</i> use the query string. Servers <i class="rfc2119" title="SHOULD">SHOULD</i> reject requests that contain two or more different configuration contexts passed in query strings.
<p>
    Where the Configuration-Context header is used on a request, a server <i class="rfc2119" title="SHOULD">SHOULD</i> include in the response a header
    <code>
        Vary=Configuration-Context
    </code>
    so that different configuration contexts do not use a previously cached response.
</p>

If you don't specify a context, your link might resolve to the artifact in the default stream.
There are more details on how to integrate with config-management-enabled projects at https://jazz.net/wiki/bin/view/Deployment/IntegratingWithConfigurationManagementEnabledCLMApplications.
Hope that helps!

Comments

Lonnie VanZandt commented Feb 13 '17, 8:49 a.m.

Kathryn,

Thanks for the commiseration. However, the cited document (been there, done that) doesn't address two points:

How to perform the more complex oslc.query=true case, not the simpler GET of a single resource. (If well implemented, the tactics should be the same, but we know that they often can differ.)
How to diagnose the complaint response about the missing "gcUri" which appears whether oslc_config.context appears as a URL parameter, as an Configuration-Context header, or both.

Of course, there may be a subtle typo buried in the actual Request and so I will continue to scrutinize my requests. Meanwhile, documentation or implementer's advice on what the actual response means would be very helpful.

So, does anyone know how to explain or resolve a "missing gcUri parameter" response?

Kathryn Fryer commented Feb 13 '17, 9:28 a.m.

Re: getting at the logs... do you have application admin access on the RM server? If so, you can "manage all projects", go to the Debug page and select Logging from the left-hand menu to get to the logs in case there are more details there.

Lonnie VanZandt commented Feb 13 '17, 1:27 p.m.

No, not for this particular repo. It is a jazz.net system and the users there intentionally are not granted the Admin rights.

Lonnie VanZandt commented Feb 13 '17, 1:39 p.m.

Kathryn,

Your article is good; thank you for authoring it. It would be all-caps awesome if you included within it several REST API calls to a sandbox Jazz.net GC and DNG deployment. Known, good, working API calls.

With that, integrators could compare and contrast their broken attempts with the known good examples to track down missing parameters, missing headers, missing body content, typos, bad encodings, etc.

Examples with actual expected error responses are also very useful.

Lonnie VanZandt commented Feb 13 '17, 1:55 p.m. | edited Feb 13 '17, 1:59 p.m.

The OASIS specification provides the following example GET:

GET /resources/conceptResourceA HTTP/1.1 Configuration-Context: http://example.com/configurations/myConfiguration1

If the sought version of a resource exists within a particular Stream (which may be Local and it could be Global) then is that Configuration Context the URI of the contextual Stream? In DNG--as you may well know--those URIs look like:

https://jazz.net:443/sandbox01-rm/cm/stream/_4uP0cOVgEeazUcKMez0U3g

If not, is the URL supposed to be a URL into the /gc/configurations realm? If so, how are Local Configuration Streams supported? Does the contextual "Component" also need to be specified, somehow?

Lonnie VanZandt commented Feb 13 '17, 2:23 p.m. | edited Feb 13 '17, 2:24 p.m.

For example, with the GC app of Jazz.net's CLM 6.0.3 sandbox, the Local Stream of interest, the Stream within which I want to execute the OSLC Query (not a mere GET but an OSLC Query Specification query) has a URL of:

https://jazz.net/sandbox01-rm/cm/component/_M5CEQOTIEeazUcKMez0U3g?oslc_config.context=https://jazz.net/sandbox01-gc/configuration/1105

Within DNG, this context also has a Stream URL of:

https://jazz.net:443/sandbox01-rm/cm/stream/_4uP0cOVgEeazUcKMez0U3g

Which of these URLs must be provided in the Configuration-Context header value (and must it be URL encoded in that header) or which fragment of these URLs must be there as the configuration URI string?

showing 5 of 6 show 1 more comments

Answer 2

0

permanent link

Donald Nong (14.5k●6●14) | answered Feb 13 '17, 11:18 p.m.

I have done some testing using my jazz.net sandbox RM project (CM-enabled) but not been able to trigger the complaint about gcUri. All my attempts successfully returned the requirements that I wanted. Here are some observations.

1. Start with the queryCapability URI found in the RM project's service document.
2. Add oslc.prefix, oslc.where and/or oslc.select as desired.
3. Add oslc_config.context (preferred) or vvc.configuration to specify a stream (in the local configuration), which looks like https://jazz.net/sandbox01-rm/cm/stream/_rZ1hkPJlEeaL6Oj2reeudg.
4. Optionally, add HTTP header Configuration-context (may work as a URL parameter as well) to specify the GC configuration, which looks like: Configuration-context : https://jazz.net/sandbox01-gc/configuration/1218.
5. When both Configuration-context and oslc_config.context/vvc.configuration are present, Configuration-context takes precedence. This means, if an RM stream/configuration is found in the specified GC configuration, the OSLC query is done in this stream, regardless what oslc_config.context/vvc.configuration specifies. However, if the GC configuration contains no RM stream/configuration, Configuration-context gets ignored, and the stream specified by oslc_config.context/vvc.configuration takes effect. My understanding is that it is not necessary to specify Configuration-context.

I did not do back-to-back comparison with an RM 6.0.2 environment so cannot comment on the difference between the two versions. As of this writing, jazz.net sandbox is at 6.0.3 iFix001.

Comments

Lonnie VanZandt commented Feb 14 '17, 12:26 p.m.

Donald,

Yes, this sounds like exactly the same recipe that I started with and have attempted to debug. I am even using the same Jazz.net sandbox as you are.

Therefore, if you can share your exact character-for-character API call that you are using to try to recreate my odd "gcUri missing" response then I can compare the two HTTP requests byte by byte to spot where I have messed up.

Note, it may be the case that my HTTP request is entirely correct but that I somehow failed to set up the DNG and GC configurations, components, and streams properly. I hope it is not news to hear that the GC/Component/Stream capability is mildly complex.

Lonnie VanZandt commented Feb 14 '17, 12:29 p.m.

By the way, one of the differences between 6.0.2 and 6.0.3 is that the published QueryBase in 6.0.2 has hardcoded within it the Jazz-internal vvc.configuration URL Parameter. In 6.0.3, DNG no longer includes that parameter as part of the QueryBase.

I infer that this means that the support for oslc_config.context and Configuration-Context is more mature in 6.0.3! That's good news.

Lonnie VanZandt commented Feb 14 '17, 1:37 p.m.

Donald,

If you can, in addition to sharing your complete HTTP request of the full URL with all necessary encoding, all necessary non-encoding, and all Headers with their values (excepting of course the Authentication header), can you:

Describe your GC/RM setup. For example (a GC Stream, with a Component X, including an RM Local Stream)
Confirm that Configuration-Context is absolutely never necessary if one provides context in the oslc_config.context parameter.
Confirm that your OSLC Query result set is actually for only the resources visible within the expected context and that you are not getting a "False Positive" from a query run outside the intended context.

Thank you for your peer advice here.

Lonnie VanZandt commented Feb 14 '17, 3:02 p.m.

<oslc:queryBase rdf:resource="https://jazz.net/sandbox01-rm/views?oslc.query=true&projectURL=https%3A%2F%2Fjazz.net%2Fsandbox01-rm%2Fprocess%2Fproject-areas%2F_MxnNoeTIEeazUcKMez0U3g"/>

We can see here that the queryBase is merely the server, the RM servlet context, the views path, the oslc.query parameter, and the encoded projectURL. Here, in CLM 6.0.3, the vvc.configuration parameter from 6.0.2 is no longer included.

I use the URL up to and including the views path; I then add the oslc.query and the projectURL URL parameters as part of the actual request. Additional parameters and headers (as shown above) are then added to the request.

Therefore, the difference doesn't appear to be in this step of the process.

Answer 3

0

permanent link

Lonnie VanZandt (88●7●17) | answered Feb 14 '17, 3:14 p.m.

Darn picky server. I found the issue.

We switch between a private server and this public server. The private server uses 9443 for the HTTPS port while Jazz uses the default 443 port. Our code and scripts therefore encode the Host and the Port as the beginning of each URL. Everything works with our 6.0.2 private server because the port qualifier (9443) is necessary. The queries fail with the public 6.0.3 server because the port qualifier (443) is optional AND Jazz performs badly when it is included in the encoded URLs.

Remedy: do NOT include the ":443" portion of the URL in the query requests when the port is a default port like 443 for SSL or 80 for HTTP.

My recommendation is that this kind of URL sensitivity should be well handled by the Jazz server and not pushed out to the client to deal with.

Comments

Donald Nong commented Feb 14 '17, 6:50 p.m.

I'm glad that you've finally nailed it. Just to confirm, is it all about the port number, rather than the difference between 6.0.2 and 6.0.3?

Lonnie VanZandt commented Feb 14 '17, 8:43 p.m.

Well, I think ultimately the root cause is a horribly misleading error response! ;-)

Since I cannot switch the HTTPS port for Jazz.net and since it is too onerous to upgrade the private server to 6.0.3 (yet), I can't say that it is merely the handling of the port number.

However, I strongly suspect that to be the case.

It's all about the answers!

Related questions

What is the gcUri parameter that CLM RM DNG 6.0.3 requests?

3 answers

Your answer