Exercise 29.3 - Browsing RESTful repositories and creating relations
- Manas Bajaj
- Rose Yntema
This is the third hands-on exercise to learn about the Syndeia RESTful Integration capability introduced in Syndeia 3.5.
In this exercise, we will browse the RESTful Requests and Collections added in the previous exercises and create relations to artifacts in other repositories, such as Jama (for requirements management), Jira (for project tracking), GitHub (for software development), and Windchill (for hardware design). We understand that as a Syndeia user you may or may not be working with these specific repositories (Jama, GitHub, Jira, and Windchill). Follow the general steps in this tutorial to connect to other types of repositories you may be using with Syndeia, e.g. DOORS NG, Confluence, TestRail, and so on.
Objectives
The learning objectives of this exercise are as follows:
Browse Requests and Collections
View responses to Requests
Create relations between response data and artifacts in other repositories
Browse relations in the Digital Thread Explorer
Preparation
This exercise assumes that the student has done the following preparations.
Reviewed the content presented in Introduction to REST APIs and Syndeia RESTful Integration
Able to access Syndeia Cloud 3.5 with a valid user account
Successfully completed the first two tutorials:
Exercise
This tutorial includes step-by-step instructions to browse RESTful Requests and Collections, view responses to Requests, and create relations to artifacts in other repositories.
1/ As a first step, it is important to review the following concepts that have been introduced in the previous tutorials.
RESTful Repository - Any enterprise service or tool that provides a RESTful API and is added to Syndeia as a repository
RESTful Collection - Logical groupings of Requests. In the previous tutorials, you created two collections to manage all requests related Rockets and Payloads respectively.
RESTful Request - Request (command) sent to a repository (tool/service) via its RESTful API. In the previous tutorials, you created three GET Requests to: (1) Get data for all rockets, (2) Get data for a specific rocket (Falcon Heavy), and (3) Get all Payloads.
RESTful Response / RESTful Artifact - Response to the RESTful Request from the repository. The Response is available in Syndeia as a RESTful Artifact that can be connected with artifacts from other repositories to build a digital thread. The full JSON data in the Response is available as attributes of the RESTful Artifact.
2/ In the SpaceX Data repository tree view, expand the GET all Rockets Request (green G icon). This action sends the Request to the SpaceX Data repository. The response received from the repository is shown under the Request and labeled as Response from [GET ‘rockets’]. This response is a RESTful Artifact in Syndeia.
RESTful artifact (Response) is shown with the following icons that match standard JSON syntax.
Square brackets [ ] indicate arrays of JSON objects
Curly braces { } indicate a single JSON object with key-value pairs
“ “ indicate primitive data, e.g. Strings, Integers, Booleans, Float/Double, etc.
3/ Expand the RESTful Artifact Response from [GET ‘rockets’] and you should see details { } of four specific rockets. Expand the first rocket { } and you will see attributes and values of a specific rocket, such as the mass, stages, and rocket_name for the Falcon 1 rocket.
4/ Similarly, expand the RESTful Request Get Falcon Heavy. This action sends the Request to the SpaceX Data repository to fetch the “Falcon Heavy” rocket data. The response received from the repository is shown under the Request and labeled as Response from [GET ‘rockets/falconheavy’]. This response is a RESTful Artifact in Syndeia. Select the Details tab on the right-hand side (RHS), as shown in Figure 4 below. This will show the details of the RESTful Artifact tracked by Syndeia.
5/ Note two specific attributes of the RESTful Artifact in the Details tab.
Click on the value of attributes.request to view details of the RESTful Request that resulted in the given RESTful Artifact (response).
Click on the value of attributes.response to view the full JSON data in the response that is available as an attribute of the RESTful Artifact. This same JSON data is viewed in the tree view shown in Figure 3 above.
6/ Select the RESTful Artifact Response from [GET ‘rockets/falconheavy’] and then select the Relations tab on the RHS, as shown in the figure below.
7/ Now, we will create inter-model relations from and to the Falcon Heavy rocket. Click the + button to add a new relation, as shown in the figure below. The general steps to create relations are described here: Creating Relations on the Web Dashboard. You may already be familiar with them.
8/ Select an existing Syndeia (Digital Thread) project or create a new one.
The next few steps demonstrate creation of reference relations from/to RESTful artifact to artifacts in Jama (for requirements management), Jira (for project tracking), GitHub (for software development), and Windchill (for hardware design). We understand that as a Syndeia user you may or may not be working with these specific repositories (Jama, GitHub, Jira, and Windchill). Follow the general steps to connect to artifacts in other repositories you may be using with Syndeia, e.g. DOORS NG, Confluence, TestRail, and so on.
9/ Follow the steps below to create a reference relation from a Jama requirement to the RESTful artifact.
Select a Jama repository in the Select target artifact repository drop-down
Navigate to a specific requirement spec, e.g. Rocket Requirement Specification, that you want to connect to the Falcon Heavy RESTful artifact. In this case, the Rocket Requirement Specification is intended to be satisfied by the Falcon Heavy artifact.
Select the direction from the Jama requirement to the RESTful artifact, e.g. Rocket Requirement Specification → Response from [GET ‘rockets/falconheavy’]
Click on the Create Reference Relationship button to create a reference relation.
10/ You should see the new relationship listed in the Inter-model relations panel, as shown below.
11/ Follow the steps 9-10 to create a reference relation from the Falcon Heavy artifact to the Rocket Assembly part in Windchill. In this case, the Rocket Assembly is the hardware design for the Falcon Heavy rocket.
12/ Follow the same steps as above to create a reference relation from the Falcon Heavy artifact to the Rocket Controller software module in GitHub, as shown below. In this case, the Rocket Controller module represents the software code for the Falcon Heavy rocket controller assembly.
13/ Follow the same steps as above to create a reference relation from the Falcon Heavy artifact to the Rocket development task in Jira, as shown below. In this case, the Rocket development task in Jira (SDB-2728) represents the main task (with sub-tasks) for the Falcon Heavy rocket development.
14/ If you select the Falcon Heavy RESTful artifact in the Tree View, you should see four (4) inter-model relations, as shown below.
15/ Right-click on the Falcon Heavy RESTful artifact in the Tree View and select Graph View, as shown in the figure above. This will open the Digital Thread Explorer. You should now see the Falcon Heavy artifact in the Graph View as a node. Right-click on the node and select Expand, as shown in the figure below.
16/ You should now see the four (4) inter-model relations creates in steps 9-14 in the Graph View. The nodes in the graph are color-coded indicating the repository to which they belong. Falcon Heavy RESTful artifact is shown in red, Jama requirement is shown in orange, Jira issue is shown in blue, Windchill part is shown in green, and GitHub file is shown in gray. The directions of the edges correspond to the direction of the relationships created in steps 9-14. You can further expand any of the nodes shown in the graph to fetch both inter-model relations (from/to artifacts in other repositories) and intra-model relations (from/to artifacts in the same repository).
To learn more about Digital Thread Explorer, refer to Digital Thread Explorer (DTE).
This is the end of the tutorial.
If you were able to complete all the steps in this tutorial successfully, Congratulations! You have successfully connected artifacts originating from RESTful repositories to artifacts in other repositories and viewed the relations in the Digital Thread Explorer.
If you were not able to complete the steps in this tutorial successfully, feel free to contact us via our helpdesk. Our team will be happy to assist you.