It's all about the answers!

Ask a question

[OSLC] How to query the hierarchy of requirements within a module


0
1
Eike Stepper (262) | asked Jan 21 '22, 10:54 p.m.
retagged Jan 24 '22, 12:41 p.m. by Ian Barnard (1.9k613)

 Hi,


I've installed a test project in DOORS Next (don#t remember how it was called, something with an "Automatic Meter Reader").

When I clilck on the module "AMR Hazards and Risks" I see a nice outline of the contained (?) artifacts (requirements?).

I'm able to query all requirements via OSLC. I can also detect what requirements are actually modules and what these modules contain (actually "use").

But how can I detect via OSLC in what order and hierarchy the requirements appear in their module?


Accepted answer


permanent link
Eike Stepper (262) | answered Feb 06 '22, 11:39 p.m.

 Hi Davyd,


Your last paragraph made my day. You were right in that my initial GET request was incorrect. The reason is that Ian's description at https://jazz.net/forum/questions/272284/example-working-code-for-adding-requirements-to-a-module-via-oslc is not exactly correct: He suggests to use the header "DOORS-RP-Request-Type", but apparently that's wrong. The first dash between "DOORS" and "RP" must be removed, as in your comment above, and then it works.

Thanks for all your help!

But I must say that I find it extremely irritating that external access to DNG data (like import/export/sync) requires so much voluntary forum help, so much spec reading, so much web hunting for example code (which is often completely outdated and disfunctional). From my perspective https://www.omg.org/news/meetings/tc/ca-15/special-events/oslc-presentations/ruehlin.pdf brings it to the point.

AFAIK, Jazz is implemented in Java, so why doesn't IBM, at least for the most fundamental data concepts (such as Folder, Requirement, RequirementCollection, Module, ModuleBinding), provide a concise and functional Java library that allows to do the common CRUD operations? Possibly Eclipse Lyo could serve as a base for such a high-level library. I mean, now that I at least know all the protocol details to work with the RM module structures, I still need to figure out how to read and manipulate the RDF bodies of requests and responses, deal with ETags and thelike. I assume that's all totally easy for you because you're the ones who made it, and thereby have built up a lot of knowledge about RDF, OSLC, Lyo, and DNG (and therefore know where to use dashes in headers, and where not). For a single developer in a tiny company that wants to integrate a modeling tool with multiple requirement management systems (such as DNG, CodeBeamer, JIRA, Polarion, etc.) this is really not a very pleasant undertaking. I'm really hoping you take my comments as constructive criticism, because I think with very little effort from your side you could make the Java tool integration a bombastic experience ;-)

Ralph Schoon selected this answer as the correct answer

Comments
Ralph Schoon commented Feb 07 '22, 2:45 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Integrations are complex and always will be complex. They are expensive and greatly desired, but usually no one wants to pay for them. Everyone has different opinions about what an integration between tool A and B should do. Creating, maintaining and documenting public APIs costs money and effort that are taken away from features that users request. I would personally like to have all APIS being public and documented, but unfortunately the reality is different. 


The language that is used to develop a tool, has nothing to do with APIs being available. OSLC is also not a solution for everything. E.g. there would not be a need for a module API, if OSLC would have a module API. Eclipse Lyo is not the solution for everything. It has complexities that actually make it hard to use for certain things. I have switched from Java Lyo to Python, because it is way easier for me to track request and response contents. In Lyo I always struggled to be able to see what goes back and forth. You would need to use Fiddler or similar software.
 


Ian Barnard commented Feb 07 '22, 6:45 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Apologies for the typo! Yes DOORSRP-Request-Type: public 2.0 is the correct header.


Eike Stepper commented Feb 07 '22, 7:21 a.m.

@Ian No worries. I'm glad we could sort it out.


@Ralph Please allow me to disagree with the first part of your reply. Our integration experience with CodeBeamer was great. It was neither complex, nor expensive. An OpenAPI description was freely available and within an hour we could generate a REST client out of it and start reading and modifying everything that there is. I strongly recommend to review Jim Ruehlin's (IBM) presentation about "OSLC Adoption" (see my link above). I do agree with your statement, though, that OSLC should have a module API!


Ralph Schoon commented Feb 07 '22, 7:35 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

 Eike,


I have spent a lot of time in trying to help users with the APIs. Mainly EWM, where an SDK is available. The SDK is not a great documentation and I have shared what I learned with users to allow integration and automation here. I am working on OSLC APIs at the moment and have also explained other public APIs. I have used Lyo client and server. 

I am an absolute fan of documented APIs, automation, integration and all that. I am not satisfied with the current situation with respect to Jazz public APIs. I am currently working with Jim trying to find out if we could enhance/enable API documentation. Only time will tell.

Note that DNG has a ton of internal APIs that are not documented, not supposed to be used, but absolutely essential if one needs certain functions. The Module API is published. See https://jazz.net/wiki/bin/view/Deployment/CLMProductAPILanding , but others are not. I think there is no module concept in OSLC RM as a standard it usually is only a subset.


Eike Stepper commented Feb 07 '22, 7:49 a.m.

Hi Ralph,


I really appreciate all the time and effort you take to help us. And I hope you don't take my words as personal offense. I didn't intend that.

I very much liked the approach of https://jazz.net/wiki/bin/view/Main/OSLCWorkshopDownload , a suite of executable samples. Perhaps it could be modernized (it's 6 years old and uses even older libs) and made more complete w.r.t. the core concepts such as RM Modules and Folders (the latter are covered, but did not work).


Ralph Schoon commented Feb 07 '22, 7:59 a.m. | edited Feb 07 '22, 8:01 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Hi Eike,


no, I don't take this as personal offense.

I am just unhappy with the API situation for quite some time. The OSLC Workshop is absolutely something that should be updated. Rosy has updated it at some point. I have considered updating it as well, but that required me to look into OSLC more and create examples. I have struggled with RDF XML for so long that I preferred other APIs. But I made progress now and I try to get there.

At the moment I publish my findings on my blog e.g. see https://rsjazz.wordpress.com/2022/02/02/ewm-work-item-oslc-cm-api/ . Once I am through the series and have published what I found out in the past 2 years, I will likely revisit the OSLC workshop. 

You might want to check with the blog, especially about the recent blog about authentication.

showing 5 of 6 show 1 more comments

3 other answers



permanent link
Ian Barnard (1.9k613) | answered Jan 24 '22, 4:14 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER
edited Feb 07 '22, 6:45 a.m.

Hi Eike


You can access the module structure using the DNG Module API (not OSLC) see here https://jazz.net/wiki/bin/view/Main/DNGModuleApiOverview

When accessing this you'll be switching from the OSLC API where you always use header OSLC-Core-Version: 2.0, so
  • Don't use header OSLC-Core-Version
  • Use the header:DOORSRP-Request-Type: public 2.0 - capitalized exactly as I've put here
  • Provide the configuration using header vvc.configuration - only accepts a local configuration
There's an example (in Python) of using the module API in my OSS client code on github.com here  - it's not exactly polished, but includes example code to calculate section number from the structure.

It's also possible to get the module structure using the DNG Reportable REST API (not OSLC) which doesn't use/need headers; you can put all the parameters in the URL and also you can access it using a logged-in browser which can be very convenient to test the URL.

For example the following query will return the content of the module, with each value showing the section number of the artifact:

https://SERVER:PORT/rm/publish/modules?moduleUri=MD_COUvD0B5Eeuh3Iiax2L3Ow&oslc_config.context=https%3A%2F%2FSERVER%3APORT%2Frm%2Fcm%2Fstream%2F_B7GQsEB5Eeuh3Iiax2L3Ow

HTH
Ian


permanent link
Eike Stepper (262) | answered Jan 24 '22, 11:09 p.m.
edited Jan 24 '22, 11:10 p.m.

 Hi Ian,


Thank you very much for your reply. In the meantime I had already found the "/rm/publish/modules?" approach (mentiones in some other post here). With that I came up with some code:

  private static void processModuleDescription(Map<String, IRMRequirement> requirements, DocumentBuilder builder, RMModule module, ClientResponse response)
  {
    try (InputStream input = response.getEntity(InputStream.class))
    {
      Document document = builder.parse(input);
      Element root = document.getDocumentElement();
      NodeList contextBindings = root.getElementsByTagName("rrm:contextBinding");
      for (int i = 0, length = contextBindings.getLength(); i < length; i++)
      {
        Node contextBinding = contextBindings.item(i);
        Map<String, String> properties = getXMLProperties(contextBinding);
        String section = properties.get("rrm:section");
        int depth = Integer.parseInt(properties.get("rrm:depth"));
        int bookOrder = Integer.parseInt(properties.get("rrm:bookOrder"));
        boolean heading = Boolean.parseBoolean(properties.get("rrm:isHeading"));
        String identifier = properties.get("rrm:identifier");
        RMRequirement requirement = (RMRequirement)requirements.get(identifier);
        RMModuleRequirement parentRequirement = getParentRequirement(module, section, depth);
        RMModuleRequirement moduleRequirement = new RMModuleRequirement(requirement, module, parentRequirement, section, depth, bookOrder, heading);
        if (parentRequirement == null)
        {
          module.addSubRequirement(moduleRequirement);
        }
        else
        {
          parentRequirement.addSubRequirement(moduleRequirement);
        }
      }
    }
    catch (IOException | SAXException ex)
    {
      throw WrappedException.wrap(ex);
    }
  }
  private static RMModuleRequirement getParentRequirement(RMModule module, String section, int depth)
  {
    RMModuleRequirement parent = null;
    StringTokenizer tokenizer = new StringTokenizer(section, ".");
    for (int i = 0, parents = depth - 1; i < parents; i++)
    {
      int segment = Integer.parseInt(tokenizer.nextToken()) - 1;
      IRMModuleRequirement[] subRequirements = parent == null ? module.getSubRequirements() : parent.getSubRequirements();
      parent = (RMModuleRequirement)subRequirements[segment];
    }
    return parent;
  }

But I'll definitely read the DNGModuleApiOverview document and have a look at your Github code, too.

Thank you very much again!

Cheers
/Eike


permanent link
Eike Stepper (262) | answered Feb 05 '22, 9:53 a.m.

It turns out that the "/rm/publish/modules" approach does not work for us because we'll need to update the module structure later.



But I seem to struggle on the "NOTE" in step 5, i.e., my response contains lots of <oslc_rm:uses ...> tags. Here are the request details from my Rest client:

{ "method": "GET", "transformRequest": [ null ], "transformResponse": [ null ], "jsonpCallbackParam": "callback", "url": "https://192.168.99.3:9443/rm/resources/MD_rmNNhnbjEeyVS6HRXK_XDw", "headers": { "Accept": "application/rdf+xml", "DOORS-RP-Request-Type": "public 2.0" }, "data": "", "timeout": {} }

What am I missing?



Comments
Davyd Norris commented Feb 05 '22, 6:46 p.m.

Fropm memory I thought the oslc_rm:uses tags are the references to the artefacts being used in the module, so you unpack those to get to the actual requirements


Eike Stepper commented Feb 06 '22, 12:15 a.m.

Thank you for you reply. What you say is correct, but it does not answer my question. I know how to access to actual requirements that are bound in the module. I asked how to access (read and modify) the module bindings of these requirements, i.e., their structure within the module.


Davyd Norris commented Feb 06 '22, 6:56 p.m. | edited Feb 06 '22, 6:57 p.m.
So looking further at your comment, I think you've mixed a few things around. There are three APIs that can be used to work with modules:
 - the Reportable REST API, which the rm/publish one, and is read only as you state
 - the OSLC API, which is read/write but generic, and is the one that generates oslc_rm:uses sections in the response
 - the Module API, which is DNG specific and which generates the module structure as a set of bindings and child bindings.

You are seeing oslc_rm:uses tags, which means you haven't got the GET call right. Your first get call with return RDF that has a structure tag with the modules structure URL. Use that to get the module structure.

Make sure you have the DOORSRP-Request-Type: public 2.0 header and that the spelling is exactly as shown here. The returned data should be a small RDF document, and it should contain the structure tag. Your response shows you're getting back an OSLC response

Ian Barnard commented Jul 21 '23, 5:51 a.m.
FORUM ADMINISTRATOR / FORUM MODERATOR / JAZZ DEVELOPER

Also when accessing the Module API:

  • Don't use header OSLC-Core-Version
  • Use the header:DOORSRP-Request-Type: public 2.0 - capitalized exactly as I've put here
  • Provide the configuration using header vvc.configuration - only accepts a local configuration

Your answer


Register or 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.