Exercise 1.4 - Creating a JIRA-to-GitHub 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 JIRA issue to a GitHub 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. Comments – Issue comments are included in the initial model transform in either direction, but are not available for compare and sync.

Exercise

  1. Launch the Syndeia Standalone client and choose the project created in Exercise 1.1, PROJ_001 (or create a new project).

  2. From the Connection Manager tab,

    1. Click the header title Repository on the left column and select your first repository (JIRA @Intercax.com in this example). Expand the tree to show the issue to be brought over into GitHub.

    2. Click the header title Repository on the right column and select your second repository (GitHub @Intercax.com). Expand the tree to show the GitHub project to receive the issue.

    3. The dashboard should appear similar to Figure 1. Note that Model Transform is selected in the center column.


      Figure 1 Connection Manager showing JIRA and GitHub repositories

    4. Drag and drop the issue from the left column on top of a project in the right column (JIRA Issue VS-21 and Dirk-Sandbox in this example). Click Yes to confirm.

    5. 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

  3. Right-click the connection row in the table at the bottom and select Open Target. In this case, the Target is a GitHub issue and will open GitHub in your default web browser, as shown in Figure 3. Note that the first comment contains a link back to the JIRA source issue.

    Figure 3  GitHub issue opened from Syndeia dashboard

  4. 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)

  5. Right-click the connection row in the table at the bottom and select Open Source. In this case, the Target is the JIRA issue and will open JIRA in your default web browser, as shown in Figure 5.

    Figure 5  JIRA issue opened from Syndeia dashboard

  6. While the JIRA issue is open, modify the summary and description and save the changes.

  7. 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 JIRA issue

  8. Right–click the connection and select Sync Source to Target. The row colors should change to green and indicate that the source and target are now synchronized.

Â