Exercise 1.5 - Creating a GitHub-to-JIRA Model Transform Connection
Objectives
The new learning objectives of this exercise are to familiarize the user with
setting up a model transform connection from a GitHub issue to a JIRA issue using the Syndeia Standalone client,
opening either issue from the Syndeia dashboard
comparing contents of the issues across the connection, and
syncing contents of the issues across the connection in either direction.
Preparation
This exercise assumes the student has
Syndeia Standalone (3.2 beta or 3.3) installed with JIRA and GitHub interfaces and valid licenses for use.
Syndeia Cloud installed on an accessible server (see Syndeia Cloud installation instructions) with a valid user account. The user will need to contact the Syndeia Cloud administrator for their organization to get access credentials.
Repository connections to JIRA and GitHub projects for which the student has edit account permissions to create and update issues. The JIRA project should contain one or more issues. The user may need to contact the JIRA and GitHub administrators for their organization to get access credentials.
The Syndeia Standalone client stores inter-model connections only in a Syndeia Cloud project. If you need to transfer connections from an earlier version to Syndeia Cloud, contact Intercax for assistance (www.intercax.com/help).
Restrictions
JIRA and GitHub restrict the allowable values for certain fields in the contents of issues. When Syndeia attempts to violate those restrictions in creating or updating issues, the model transform process may be all or partially unsuccessful.
Related fields have different names in JIRA and GitHub. The current default mapping is
JIRA | GitHub |
Summary | Title |
Description | Body of first comment |
Issue Type | Labels |
Assignee | Assignee |
Reporter | Author |
Potential restrictions include
User Account Privileges – In order to create or update issues in either JIRA or GitHub, the Syndeia user's account should have Write privileges in the target repository. If the JIRA account has Read-only privileges, a JIRA issue may not be created or updated. If the GitHub account has Read privileges, a GitHub issue may be created, but certain fields (e.g., Assignee) may not be filled or updated.
Reporter/Author – When a new issue is created by model transform in the target repository (in either tool), the Reporter/Author field shows the ID of the Syndeia user that performed the model transform, not the ID of the issue creator in the source repository. The Reporter/Author field is not available for compare and sync.
Assignee – The ID of the Assignee must be from the list of allowable assignees for that list. If the Assignee for the source issue is not available on that list for the new issue in the target repository, then Syndeia assigns the Syndeia user's ID to that field. If the same user has different IDs in JIRA and GitHub, GitHub will not recognize the JIRA ID and vice versa.
Issue Type/Labels –JIRA and GitHub have separate lists for allowable values for these fields. If the issue type in JIRA does not have a matching label in GitHub, the model transform connection will fail during creation ("ERROR: Unable to create issue: Validation failed" message in the Syndeia notification window). It is generally easy to add new labels to a GitHub project to accommodate specific JIRA issue types.
Comments – Issue comments are included in the initial model transform in either direction, but are not available for compare and sync.
Exercise
Launch the Syndeia Standalone client and choose the project created in Exercise 1.1, PROJ_001 (or create a new project).
From the Connection Manager tab,
Click the header title Repository on the left column and select your first repository (GitHub @Intercax.com in this example). Expand the tree to show the issue (Data Mgmt in this example) to be brought over into JIRA.
Click the header title Repository on the right column and select your second repository (JIRA @Intercax.com). Expand the tree to show the JIRA project to receive the issue (Syndeia Demo Box in this example).
The dashboard should appear similar to Figure 1. Note that Model Transform is selected in the center column.
Figure 1 Connection Manager showing GitHub and JIRA repositories
Drag and drop the issue from the left column on top of a project in the right column (GitHub Issue Data Mgmt and Syndeia Demo Box in this example). Click Yes to confirm.
Open the Connection Search tab and click the Get All button element to see the connection created, as shown in Figure 2.
Figure 2 New Model Transform connection (red highlight) viewed in the Connection Search tab
Right-click the connection row in the table at the bottom and select Open Source. In this case, the Source is a JIRA issue and will open JIRA in your default web browser, as shown in Figure 3. Note that the Description field contains a footer with a link back to the GitHub source issue.
Figure 3 JIRA issue opened from Syndeia dashboard
Right-click the same connection row and select Compare Source and Target. The Comparison Result tab will open, as shown in Figure 4. All lines in the comparison should be green.
Figure 4 Comparison Result tab, Syndeia dashboard (initial)
Right-click the connection row in the table at the bottom and select Open Target. In this case, the Target is the GitHub issue and will open GitHub in your default web browser, as shown in Figure 5.
Figure 5 GitHub issue opened from Syndeia dashboard
While the GitHub issue is open, modify the title and first comment above the footer and save the changes.
Return to the Connection Search on the Syndeia dashboard. Right-click the model transform connection row again and select Compare Source and Target. The Comparison Result tab will open and appear similar to Figure 6, with the connection, summary and description rows in red.
Figure 6 Comparison Result tab after modifying GitHub issue
Right–click the connection and select Sync Target to Source. The row colors should change to green and indicate that the source and target are now synchronized.
