Exercise 28.2 - Gremlin Queries for Collaborator

Owned by Debesh Roy Chowdhury
Last updated: Jun 10, 2022
9 min read

OBJECTIVES:

The objective of this exercise is to help new users of Syndeia graph analysis to formulate Gremlin queries to analyze their graph with the Syndeia Web Dashboard. SmartBear Collaborator (Collaborator) is a code review tool from SmartBear Inc. The specific learning objectives of this exercise are to create lists of

·       Collaborator artifacts of a specific artifact type

·       Collaborator artifacts connected as part of a specific Syndeia Project

PREPARATION:

This exercise assumes the student has

·       Syndeia Cloud 3.5 installed with a valid user account, and

·       An existing Syndeia graph containing Collaborator elements connected to elements in other repositories.

Because the content of your Syndeia graph will be different, the specific examples in the following exercise instructions are only a guide and example for your actions. It is generally advisable to carry out these exercises in a non-production repository, a “sandbox”, set up for training and practice purposes.

See the tutorials under Syndeia Cloud Web-Dashboard/Part 19 – Syndeia Cloud Graph Analysis for an overview of this feature.

BACKGROUND-SYNDEIA CLOUD DATA MODEL:

Figure 1 provides a simplified schema for elements in the Syndeia Cloud graph. All graph nodes are either Repositories, Containers, or Artifacts, where each Artifact is owned by a Container and Each Container is owned by a Repository. Each has a Type; the set of Container Types and Artifact Types are owned by the Repository. How the Collaborator data model maps to the Syndeia Cloud data model is discussed in the next section.

Figure 1 : Syndeia Cloud Schema (simplified)

BACKGROUND-SMARTBEAR COLLABORATOR:

As envisioned by Intercax, the Digital Thread is composed of inter-model connections between models in different repositories, which Syndeia creates and manages, and intra-model connections between elements in the same repository, which the individual tool creates and manages. As of Syndeia release 3.5, the Syndeia Web Dashboard can extract and display some model information from the Collaborator repository. Figure 1 shows a tree view of this information, with labels identifying the Collaborator element types. Note the different icons. The label color coding indicates how the Collaborator element type is mapped to the Syndeia Cloud element types: Repository (green), Container (red), and Artifact (blue).

For Collaborator, reviews may be owned directly by the repository without an intervening Container, as in Figure 1. When Collaborator data is mapped to the Syndeia common data model, a default container with name My Action Items is created between the repository and the review and may appear in graph queries.

This information is important in formulating and interpreting Syndeia graph queries. A more complete diagram of the Collaborator data model as it is understood by Syndeia is available through the web dashboard help menu on the left.

Figure 2 : Tree view of Collaborator repository

It is also important to understand the limitations of graph queries with respect to Collaborator repositories. As of Syndeia 3.5, graph queries cannot extract the internal structure of an Collaborator repository, i.e. they cannot be used to obtain the full structure of the Collaborator repository or internal (intra-model) relations between Collaborator artifacts. In this way, graph queries are different than the Tree View or Graph View (Digital Thread Explorer) capabilities of the Repositories page in the Syndeia Web Dashboard. Graph queries are most useful in viewing inter-model connections from Collaborator elements to other repositories.

EXERCISE:

1. Log on to the Syndeia Cloud Web Dashboard (see Video 1.9) and click on the Graph Queries icon on the left border.

2. The first task is to compile a list of Collaborator Artifacts of a specific type. Per Figure 1, ArtifactTypes are owned by (specific to) a Repository. We typically want to begin by creating a list of Artifact types available in such a Repository.

a. If we use Query Builder (Figure 3), we select ArtifactType from the pull-down menu under Label.

Figure 3 : Graph Queries page (icon outlined in red) – Query Builder

b. To restrict the list of ArtifactTypes to our current Collaborator repository, we click Filters. We will filter by the name of our Repository, so we select Repository from the pull-down menu at the top marked Property of. Under Property Key, we select the Name property and under Property Value, we enter Collaborator @ Intercax. We then click the Plus (+) button to add the filter in the bottom list and the window should look similar to Figure 4. Click Close.

 

Figure 4 : Query Builder Filters window

3. Back on the Graph Queries page, click Run. The results, a list of all ArtifactTypes in Collaborator @ Intercax, may be displayed in table form as in Figure 5. Key ArtifactType properties in the table are Name and Key because we will use these in the next search. Click the Exports icon to export the list as a CSV file for future reference, if desired.

Note: only Collaborator artifact types actually present in the Syndeia graph will appear in this list, i.e. there must be at least one example of the artifact type connected to another domain by an inter-model connection in order for it to make the list.

Figure 5 : Graph Queries page, ArtifactTypes results in table format (Export icon highlighted in red)

4. Note at the top of Figure 5, the Query Builder utility has created a Gremlin query. We could have performed the same search with the same results by going to the Raw Query mode and entering this query directly.

g.V().has('sLabel','ArtifactType').where(outE().has('sLabel','ownedBy').inV().has('name','Collaborator @ Intercax'))

5. The final part of the first task is to generate a list of all Artifacts of type Review within the Collaborator @ Intercax Repository. Note that Syndeia will return only those Collaborator Parts that are connected within the Syndeia Cloud graph or own elements that are connected within the Syndeia Cloud graph, not all Reviews in the repository.

  1. We can search by ArtifactType Name (“Review”) or Key (ART-TYPE561), which we got from the table in Figure 5. Generally, it is better to search by Key, which is unique within the Syndeia Cloud database, rather than Name, which may not be unique.

  2. If we use Query Builder, we select Artifact from the pull-down menu under Label, as in Figure 6.

Figure 6 : Query Builder, Artifact search

3. To restrict the list of Artifacts to the Collaborator Requirement type, we click Filters. We will filter by the ArtifactType Key, so we select ArtifactType from the pull-down menu at the top marked Property of. Under Property Key, we select the sKey property and under Property Value, we enter ART-TYPE561, which we took from the table in Figure 5.  After we click the Plus (+) icon, the Filters window should look like Figure 7. Click Close.

Figure 7 : Query Builder Filters window, filter by ArtifactType sKey

6. Back on the Graph Queries page, click Run. The results, a list of all Artifacts of type ART-TYPE561, which is owned by the repository Collaborator @ Intercax, may be displayed in table form as in Figure 8. Click the Exports icon to export the list as a CSV file for future reference, if desired.

Figure 8 : Graph Queries page, Artifacts results in table format, truncated (Export icon outlined in red)

7. Note at the top of Figure 5, the Query Builder utility has created a Gremlin query. We could have performed the same search with the same results by going to the Raw Query mode and entering this query directly.

g.V().has('sLabel','Artifact').where(outE().has('sLabel','hasType').inV().has('sKey','ART-TYPE561'))

8. The second task is to compile a list of Collaborator Artifacts that are connected as part of a specific Syndeia Project. Syndeia Projects are partitions within the Syndeia Cloud graph database that separate different projects or system models. Syndeia Projects are Containers owned by the Syndeia Repository and contain only relations, the inter-model relations that define the “macrostructure” of the Digital Thread for that system or project. In this case, we are looking not for the Collaborator parts directly; we are looking for inter-model connections where one end is a Collaborator part.

9. We will begin by creating a list of Containers available in the Syndeia Repository.

  1. If we use Query Builder (Figure 9), we select Container from the pull-down menu under Label.

    Figure 9 : Graph Queries page (icon outlined in red) – Query Builder

  2. To restrict the list of Containers to the Syndeia repository, we click Filters. We will filter by the name of our Repository, so we select Repository from the pull-down menu at the top marked Property of. Under Property Key, we select the Name property and under Property Value, we enter Syndeia Repository. We then click the Plus (+) button to add the filter in the bottom list and the window should look similar to Figure 10. Click Close.

    Figure 10 : Query Builder Filters window

10. Back on the Graph Queries page, click Run. The results, a list of all Containers in the Syndeia Repository may be displayed in table form as in Figure 11. Key Container properties in the table are Name and Key because we will use these in the next search. Click the Exports icon to export the list as a CSV file for future reference, if desired.

Figure 11 : Graph Queries page, Containers results in table format, truncated

11. Note at the top of Figure 11, the Query Builder utility has created a Gremlin query. We could have performed the same search with the same results by going to the Raw Query mode and entering this query directly.

g.V().has('sLabel','Container').where(outE().has('sLabel','ownedBy').inV().has('name','Syndeia Repository'))

12. The next part of the task is to generate a list of all Relations within a specific Syndeia Project.

  1. We can search by Container Name (“Dirk Sandbox 16”) or Key (DZSB16), which we got from the table in Figure 11. Generally, it is better to search by Key, which is unique within the Syndeia Cloud database, rather than Name, which is not unique.

  2. If we use Query Builder, we select Relation from the pull-down menu under Label, as in Figure 12. Remember, the Syndeia Projects contain relations, not artifacts.

  3. To restrict the list of Relations to a specific Syndeia Project, we click Filters. We will filter by the Container Key, so we select Container from the pull-down menu at the top marked Property of. Under Property Key, we select the sKey property and under Property Value, we enter MBSB15, which we took from the table in Figure 11.  After we click the Plus (+) icon, the Filters window should look like Figure 13. Click Close.

    Figure 13 : Query Builder Filters window, filter by Container sKey

13. Back on the Graph Queries page, click Run. The results, a list of all Relations in Container MBSB15, which is owned by the Syndeia Repository, may be displayed in table form as in Figure 14. Note that all relations within the project appear, not just those with an Collaborator artifact at one end.

Figure 14 : Graph Queries page, Relations (Edges) results in table format, truncated.

14. The final step is to identify the Collaborator elements that participate in these relations, but this cannot be done in Query Builder alone. Note at the top of Figure 14, the Query Builder utility has created a Gremlin query.

g.E().has('sLabel','Relation').has('container','MBSB15')

We will use the Gremlin query language to append an additional condition. First, we will add an additional traversal step to go to the vertices at the end of the relations. Since we don’t know whether the Collaborator review will have an incoming or outgoing relation in the Syndeia project, we use the bothV() step to cover both ends.

g.E().has('sLabel','Relation').has('container','MBSB15').bothV()

Next, we will check all vertices for ArtifactType. Going back to the table in Figure 5, we choose Collaborator Review, ART-TYPE561.

g.E().has('sLabel','Relation').has('container','MBSB15').bothV().has(‘type‘,‘ART-TYPE561‘)

If we select Raw Query and enter this in the Gremlin Query field, we generate the table in Figure 15, showing all Collaborator elements of ART-TYPE561 used in the Syndeia Project MBSB15.

Figure 15 : Graph Queries page, Artifacts results in table format, truncated