Jazz Forum Welcome to the Jazz Community Forum Connect and collaborate with IBM Engineering experts and users

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

 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?

0 votes

Comments

Attempting to figure out the right set of Headers, URL Parameters, and Encodings for the OSLC Query interface for DNG RM 6.0.3, I encounter the following server Response. Can anyone spot and describe what mistake I made in the provided information or what information I neglected?


I've had OSLC Query working for both GC-ed and non-GC-ed RM before 6.0.3 and so I'm trying to adjust to the changes without a good set of documentation and samples. For example, a search for this "gcUri" across the net yields nothing.

A variety of educated guesses for various URL parameters, headers, and GC configuration URIs has yet to unlock the door.

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:err="http://jazz.net/xmlns/prod/jazz/foundation/1.0/"> <rdf:Description> <err:detailedMessage rdf:datatype="http://www.w3.org/2001/XMLSchema#string" >Your request is missing the gcUri mandatory parameter. (More info found at entry [3577496ef60a1486] in the RM application server log)</err:detailedMessage> <err:errorMessage rdf:datatype="http://www.w3.org/2001/XMLSchema#string" >Bad Request</err:errorMessage> <err:errorStatus rdf:datatype="http://www.w3.org/2001/XMLSchema#long" >400</err:errorStatus> </rdf:Description> </rdf:RDF>

 GET /sandbox01-rm/views?oslc.query=true

&projectURL= a project-areas URL, encoded
&oslc.prefix= some oslc namespaces, encoded
&oslc.where= a OSLC predicate expression, encoded
&oslc.select=* 

Headers OSLC-Core-Version: 2.0 
Configuration-Context:  a stream URI, encoded
Authorization: Basic 

 This site won't accept a dump of Markdown for API Blueprint and so some messy comments follow.

 I don't have access to RM's log and so can't go look at the error messages that may be there.

Here's another attempt to ask the question. The following request works fine for CLM DNG 6.0.2 and fails for CLM DNG 6.0.3. How are we supposed to tailor our requests to migrate them from 6.0.2 to 6.0.3?

{
  "name": "Paw Export 2/13/2017, 7:28:51 PM",
  "steps": [
    {
      "step_type": "request",
      "headers": {
        "OSLC-Core-Version": [
          "2.0"
        ],
        "Cookie": [
          "JSESSIONID=sessionid; JAZZ_AUTH_TOKEN=tokenhash; X-Node=jazzweb2|WKJn9"
        ],
        "Accept": [
          "application/rdf+xml"
        ]
      },
      "auth": {
        "auth_type": "basic",
        "username": "some",
        "password": "body"
      },
      "method": "GET",
      "note": "OSLC RM Query All-Not-0 ",
      "body": ""
    }
  ]
}

 Note that the url property shown above, in use, is UTF-8 URL encoded. This website will not allow that the actual strings to be submitted.

showing 5 of 7 show 2 more comments


3 answers

Permanent link

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!

0 votes

Comments

 Kathryn,


Thanks for the commiseration. However, the cited document (been there, done that) doesn't address two points:
  1. 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.)
  2. 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?

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.

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

 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.

 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?

 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:



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


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

Permanent link

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.

0 votes

Comments

 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.

 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.

 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.

 <oslc:queryBase rdf:resource="https://jazz.net/sandbox01-rm/views?oslc.query=true&amp;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.


Permanent link

 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.

0 votes

Comments

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?

 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.

Your answer

Register or log in to post your answer.

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Search context
Follow this question

By Email: 

Once you sign in you will be able to subscribe for any updates here.

By RSS:

Answers
Answers and Comments
Question details
× 10,937
× 7,495
× 516
× 201
× 116
× 5

Question asked: Feb 12 '17, 11:30 p.m.

Question was seen: 4,782 times

Last updated: Feb 14 '17, 8:43 p.m.

Confirmation Cancel Confirm