Syndeia API for Open Digital Thread, Part 5 – Syndeia Cloud 3.5 Jama Notebook

A key benefit of the Syndeia digital thread platform is that it enables the user to retrieve data from all the federated repositories through a single interface, the Syndeia Cloud REST API. This and the next several Jupyter notebooks released with Syndeia 3.5 will each focus on a specific repository type. This post will cover Jama Connect from Jama Software. While many of the queries are similar to Part 3 of this series for JIRA repositories, JIRA data has a relatively simple hierarchy; JIRA projects contain a single level of JIRA issues. Jama can contain much more complex hierarchies, where the number of levels and the data type at each level is not fixed. Notebook authors must be prepared to drill down through multiple levels to find the data they need.

The Syndeia_Cloud_3.5 Jama notebook illustrates request and response for six common questions.

  • What projects are in a Jama repository?
  • What components are in a Jama project?
  • What (requirement) sets are in a Jama component?
  • What requirements are in a Jama set?
  • What attribute values are in a Jama artifact (e.g. requirement)?
  • What is a Jama requirement connected to (in other models)?

For each section, we will identify the question being asked and what the results look like. More detail about the API call/Python code patterns used to make these queries are described in the accompanying TechNote(s).

Getting Started

All Syndeia documentation can be accessed most easily through the Help icon on the Syndeia Web Dashboard once Syndeia Cloud has been installed. Regarding these queries, it may be especially helpful to review the Syndeia data model under API – Overview. Intercax periodically offers online live training classes that comprehensively review all things Syndeia. Check out the Syndeia Training Page on our website for latest course details. You can also reach out to info@intercax.com for upcoming course schedules.

Parts 1 and 2

Jama Repositories available to Syndeia Cloud

Figure 1 Jama Repositories available to Syndeia Cloud

As in the previous notebooks, the initial cells are devoted to

  • Importing Python libraries, including the Syndeia Cloud Python language client,
  • Authenticating into Syndeia Cloud through its own REST API, and
  • Retrieving a list of repositories (Jama repositories in this example) that this instance of Syndeia Cloud is set up to access.

The results for this list are shown in Figure 1. This query was made to the Syndeia Cloud database, not a Jama repository, but we will need a Jama Repository Key, REPO4 in this example for Jama @ Intercax, in our next Jama-specific requests. For more information on the Syndeia-related Python code in this section, see the TechNote, “Queries to Syndeia Cloud Database”.

What Jama Projects are in a Repository?

Figure 2 Projects in Jama @ Intercax repository (partial)

The cell labelled Step 3.1 asks, “What Jama projects are contained in the Jama @ Intercax repository?” Before this request could be passed to Jama, the user is asked at run-time to enter their Jama password, which is required along with their username for all requests. For the, we used the JamaAPI class with the get_jama_containers() endpoint. The results are tabulated as in Figure 2. This report includes only the name, but both name and project key are returned; we will need the project key for later requests. For more information on the Syndeia-related Python code in this section, see the TechNote, “Jama Authentication and Projects”. Link shared below.

What Jama Components are in a Project?

Figure 3 Jama components in Syndeia Applications project

The next several steps illustrate how to drill down through the Jama requirements hierarchy. Jama projects map to Containers in Syndeia nomenclature; components, sets, requirements, test cases, etc., all map to Artifacts. We can use the get_jama_artifacts() method to get the Jama items owned directly by the “Syndeia Applications” project and the results are tabulated in Figure 3 with name and Jama ID. In this case, these are all Jama components but other artifact types, e.g. sets, could also appear. The JamaAPI query could be configured to filter by artifact type if desired. For more information on the Syndeia-related Python code in this section, see the TechNote, “Navigating Jama Components, Requirements and Sets”. Link shared below.

What Jama Sets are in a Component?

Jama sets in Maritime_ESOH component

Figure 4 Jama sets in Maritime_ESOH component

Step 3.3 applies the get_jama_artifacts() method one level down, to get the artifacts in the “Maritime_ESOH” component (Figure 4). In this case, all these are of Jama artifact type Set, although this is not necessarily true for all cases. For more information on the Syndeia-related Python code in this section, see the TechNote, “Navigating Jama Components, Requirements and Sets”. Link shared below.

What Jama Requirements are in a Set?

Figure 5 Jama requirements in ESOH Subsystem Requirements set

Figure 5 Jama requirements in ESOH Subsystem Requirements set

Step 3.4 identifies a Jama set “ESOH Subsystem Requirements” in the Jama @ Intercax repository and requests all artifacts belonging to that set, including the attributes priority, status, and globalID. The results are reported in Figure 5.  The color coding by Status is added to the table by defining  the highlight(row) function in the first cell of the notebook and using it within the DataFrame method form the Pandas Python plotting library. For more information on the Syndeia-related Python code in this section, see the TechNote, “Navigating Jama Components, Requirements and Sets”. Link shared below.

What Jama Attributes are in a Requirement?

The request shown in Figure 6 specifies a particular requirement by Jama key, “SYNAPP-REQ-6” in this case and uses the get_jama_artifact_by_external_key() method with the optional parameter include_attributes = “all”. For more information on the Syndeia-related Python code in this section, see the TechNote, “Navigating Jama Components, Requirements and Sets”. Link shared below.

Figure 6 List of attributes and attribute values in Jama requirement “Fresh Water Control”

Figure 6 List of attributes and attribute values in Jama requirement “Fresh Water Control”

What is a Jama artifact connected to (in other models)?

In Figure 7, we display a list of the Syndeia inter-model relations to or from the Jama requirements identified in Step 3.4 earlier and stored in the Syndeia container (digital thread project) “DZSB19”. Unlike the previous requests described in this post, this request is directed to the Syndeia Cloud database, not the Jama repository and it is made in the form of a Gremlin language query repeated for each requirement in the set. The results are displayed in a table where the first two columns identify a requirement ID and name and the third shows a list of relationships to or from that requirement with the Syndeia relation key and the external key of the opposite end of the connection.

List of inter-model relations to or from a list of Jama requirements.

Figure 7 List of inter-model relations to or from a list of Jama requirements.

For more information on the Syndeia-related Python code in this section, see the TechNote, “Queries to Syndeia Cloud Database”. Link shared below.

Conclusions

This Jupyter notebook shows how basic information about projects, components, sets, requirements and their attributes can be retrieved from a Jama repository via the Syndeia Cloud REST API. In the same notebook, we also get data about the inter-model connections those Jama artifacts are participating in. In this way, the full depth of the digital thread is made available for analysis and reporting.

Download TechNote(s).

Click here to download our Technotes.

Next in this series

The next set of posts in this series will use Jupyter notebooks as the primary means for demonstrating the Syndeia API and will focus on the following topics.

Contributions by

The notebook was created by Dr. Manas Bajaj, Chief Systems Officer at Intercax, who leads product research and development. He was a contributor to the SysML (Systems Modeling Language) 1.0 open standard and leads the SysML v2 API and Services standards development as part of the SysML v2 Submission Team (SST).

Dirk Zwemer

Dr. Dirk Zwemer (dirk.zwemer@intercax.com) is President of Intercax LLC (Atlanta, GA), a supplier of MBE engineering software platforms like Syndeia and ParaMagic. He is an active teacher and consultant in the field and holds Level 4 Model Builder-Advanced certification as an OMG System Modeling Professional.