Developer Resources

Customizing the Workflow

Flow Production Tracking Jira Bridge is structured so that studios can tailor the workflow to meet their specific needs. Because both Flow Production Tracking and Jira are highly customizable, exposing a handful of settings would not be sufficient. Therefore, the bridge has been structured to allow subclassing the various components that control syncing and handling events in order to give full control over the logic of what is being done.

Structure Overview

Bridge

The Bridge is the main class for the sync. It handles the connections to both Flow Production Tracking and Jira, manages sync settings from the settings.py file, and initiates the calls to sync in Flow Production Tracking and Jira.

This class is intended to be used as-is without requiring customization since the details of the workflow logic are defined in the Syncer and SyncHandler. When creating a new instance of Bridge, typically you’ll use the Bridge.get_bridge() factory method and pass in the full path to the settings file.

Syncers

The Syncer is in charge of initially determining whether to accept or reject events from Flow Production Tracking and Jira for syncing. This is done with the accept_shotgun_event() and accept_jira_event() methods. It performs initial basic checks on the event to determine if it should immediately be rejected without needing to ask the handlers. These checks should be completely independent of the implementation details of the handlers. For example, a Flow Production Tracking event can be inspected to ensure it has the basic required fields in an event like the meta and project keys. Without either of these keys in the event, no handlers could process the event anyway.

If nothing in the event immediately disqualifies itself from consideration, the Syncer then hands the event off to each SyncHandler to accept the event or not. The first handler that accepts the event is then returned to process the event.

Note

Only one handler may process an event since having multiple handlers process a single event could cause issues where one handler undoes what a previous one did for the same event.

Syncers must be sub-classed from the base Syncer class in order to implement a list of Handlers to dispatch events to. The handlers() property must be overridden but additional parameters can be accepted by the class as well, to pass on to Handlers:

from .syncer import Syncer
from .handlers import TaskIssueHandler, NoteCommentHandler, EnableSyncingHandler


class TaskIssueSyncer(Syncer):
    """
    Sync Flow Production Tracking Tasks as Jira Issues.
    """
    def __init__(self, issue_type="Task", **kwargs):
        """
        Instatiate a new Task/Issue syncer for the given bridge.

        :param str issue_type: Jira Issue type to use when creating new Issues.
        """
        self._issue_type = issue_type
        super(TaskIssueSyncer, self).__init__(**kwargs)
        self._task_issue_handler = TaskIssueHandler(self, self._issue_type)
        self._note_comment_handler = NoteCommentHandler(self)
        # A handler combining the Task <-> Issue handler and the Note <-> Comment
        # handler. Task syncing to Jira starts if the Task "Sync in Jira" checkbox
        # is turned on. Notes linked to a Task being actively synced are automatically
        # synced without having to manually select them. A full sync is performed
        # when the Task checkbox is turned on.
        self._enable_syncing_handler = EnableSyncingHandler(
            self,
            [self._task_issue_handler, self._note_comment_handler]
        )

    @property
    def handlers(self):
        """
        Return a list of :class:`~handlers.SyncHandler` instances.
        """
        return [
            self._enable_syncing_handler,
            self._task_issue_handler,
            self._note_comment_handler
        ]

Sync Handlers

A SyncHandler holds the logic for syncing values between a Flow Production Tracking Entity type and a Jira resource and is owned by a Syncer instance. The base class defines the interface all handlers should support and provides a set of helper methods useful for implementations.

The following methods must be overridden from the Syncer base class:

# public methods
accept_shotgun_event()
accept_jira_event()
process_shotgun_event()
process_jira_event()

# private property
_sg_jira_status_mapping()

Setup

When a syncer is first loaded, it calls setup() on each SyncHandler. This can be used to check the Jira and Flow Production Tracking sites for specific conditions or setup requirements, ensuring that the sync can safely happen.

Additionally, this can be used to cache value(s) from either site if there are queries that might be done repeatedly that slow things down during the sync process.

Accepting the Event

After the Syncer has done its initial checks to decide whether to accept an event, it then passes the event off to its handlers to check for themselves. Each SyncHandler must define a accept_shotgun_event() and accept_jira_event() which overrides the Syncer base class. This is where the more specific logic for accepting or rejecting an event can occur. Checks for things like whether the event is for a Flow Production Tracking Entity type or Jira resource type that the handler cares about are appropriate. Or for example, you may wish to check a Flow Production Tracking event to see if the Task field that was changed, is one that is supported by your handler.

The goal of these methods is to quickly determine whether to process the event given the information provided. Queries are expensive. If after checking all of the given event info, there are still more questions to answer that require making additional queries to Flow Production Tracking or Jira, it is perfectly fine for these to be done in the process_shotgun_event() or process_jira_event() methods later.

Processing the Event

process_shotgun_event() and process_jira_event() process the event data, perform any additional validation required to determine whether to continue with the sync (which may include additional queries to Jira and/or Flow Production Tracking), and then do the actual update.

Once the event itself has been validated fully, the actual data that has changed is validated and converted to a format appropriate for the recipient of the sync. There are private methods in the base classes that perform some of the heavy lifting for this.

If the event was processed successfully, it returns True. If the event was not processed for any reason it returns False.

EntityIssueHandler

In addition to the base SyncHandler, there is also a EntityIssueHandler which serves as a base class for handlers that sync between a Flow Production Tracking Entity type and a Jira Issue resource. Since this is probably how a majority of workflows will work, it is provided to add an additional level of convenience.

It inherits from SyncHandler. When using EntityIssueHander as a base class, the following methods must be overridden in addition to the ones required by SyncHandler:

_get_jira_issue_field_for_shotgun_field()
_supported_shotgun_fields_for_jira_event()
_get_shotgun_entity_field_for_issue_field()

API

Connections to Flow Production Tracking and Jira

These classes manage the specific connections to Flow Production Tracking and Jira.

ShotgunSession

class sg_jira.shotgun_session.ShotgunSession(base_url, script_name=None, *args, **kwargs)[source]

Wraps a shotgun_api3.shotgun.Shotgun instance and provide some helpers and session caches.

Ensures all the values we get from Flow Production Tracking are unicode and not utf-8 encoded strings. Utf-8 encodes unicode values before sending them to Flow Production Tracking.

Instantiate a shotgun_api3.shotgun.Shotgun with the sanitized parameters.

property current_user

Return the Flow Production Tracking user used for the connection.

Returns:: A Flow Production Tracking record dictionary with an id key and a type key.

setup()[source]

Check the Flow Production Tracking site and cache site level values.

Raises:: RuntimeError – if the Flow Production Tracking site was not correctly configured to be used with this bridge.

assert_field(entity_type, field_name, field_type, check_unique=False)[source]

Check if the given field with the given type exists for the given Flow Production Tracking Entity type.

Parameters:

entity_type (str) – A Flow Production Tracking Entity type.
field_name (str) – A Flow Production Tracking field name, e.g. ‘sg_my_precious’.
field_type (str) – A Flow Production Tracking field type, e.g. ‘text’.
check_unique (bool) – When True, check the specified field is configured to only accept unique values. Default is False.

Raises:

RuntimeError – if the field does not exist or does not have the expected type.

get_field_schema(entity_type, field_name)[source]

Return the Flow Production Tracking schema for the given Entity field.

Note

Flow Production Tracking schemas are cached and the bridge needs to be restarted if schemas are changed in Flow Production Tracking.

Parameters:

entity_type (str) – A Flow Production Tracking Entity type.
field_name (str) – A Flow Production Tracking field name, e.g. ‘sg_my_precious’.

Returns:

The Flow Production Tracking schema for the given field as a dictionary or None.

clear_cached_field_schema(entity_type=None)[source]

Clear all cached Flow Production Tracking schema or just the cached schema for the given Flow Production Tracking Entity type.

Parameters:: entity_type (str) – A Flow Production Tracking Entity type or None.

static get_entity_name_field(entity_type)[source]

Return the Flow Production Tracking name field to use for the specified entity type.

Parameters:: entity_type (str) – The entity type to get the name field for.
Returns:: The name field for the specified entity type.

is_project_entity(entity_type)[source]

Return True if the given Flow Production Tracking Entity type is a project Entity, that is an Entity linked to a Project, False if it is a non-project Entity.

Parameters:: entity_type (str) – A Flow Production Tracking Entity type.

consolidate_entity(shotgun_entity, fields=None, retired_only=False)[source]

Consolidate the given Flow Production Tracking Entity: collect additional field values, ensure the Entity name is available under a “name” key.

Parameters:

shotgun_entity – A Flow Production Tracking Entity dictionary with at least its id and its type.
fields – An optional list of fields to add to the query.
retired_only – An optional boolean indicating if the entity we’re consolidating has been retired.

Returns:

The consolidated Flow Production Tracking Entity or None if it can’t be retrieved.

match_entity_by_name(name, entity_types, shotgun_project)[source]

Retrieve a Flow Production Tracking Entity with the given name from the given list of Entity types.

Project Flow Production Tracking Entities are restricted to the given Flow Production Tracking Project.

Parameters:

name (str) – A name to match.
entity_types – A list of Flow Production Tracking Entity types to consider.
shotgun_project – A Flow Production Tracking Project dictionary.

Returns:

A Flow Production Tracking Entity dictionary or None.

get_entity_page_url(shotgun_entity)[source]

Return the Flow Production Tracking page url for the given Entity.

Parameters:: shotgun_entity – A Flow Production Tracking Entity dictionary with at least a ‘type’ key and an ‘id’ key.

JiraSession

class sg_jira.jira_session.JiraSession(jira_site, *args, **kwargs)[source]

Extend jira.JIRA with helpers.

Instantiate a JiraSession.

Connect to the given Jira site with given parameters.

Parameters:: jira_site (str) – A Jira site url.
Raises:: RuntimeError – on Jira connection errors.

__init__(jira_site, *args, **kwargs)[source]

Instantiate a JiraSession.

Connect to the given Jira site with given parameters.

Parameters:: jira_site (str) – A Jira site url.
Raises:: RuntimeError – on Jira connection errors.

setup()[source]

Check the Jira site and cache site level values.

Raises:: RuntimeError – if the Jira site was not correctly configured to be used with this bridge.

property is_jira_cloud

Return if the site is a JIRA Cloud site.

Rerturns:: True if the site is hosted in the cloud, False otherwise.

get_jira_issue_field_id(name)[source]

Return the Jira field id for the Issue field with the given name.

Returns:: The id as a string or None if the field is unknown.

property jira_shotgun_type_field

Return the id of the Jira field used to store the type of a linked Flow Production Tracking Entity.

Two custom fields are used in Jira to store a reference to a Flow Production Tracking Entity: its Flow Production Tracking Entity type and id. This method returns the id of the Jira field used to store the Flow Production Tracking type.

property jira_shotgun_id_field

Return the id of the Jira field used to store the id of a linked Flow Production Tracking Entity.

Two custom fields are used in Jira to store a reference to a Flow Production Tracking Entity: its Flow Production Tracking Entity type and id. This method returns the id of the Jira field used to store the Flow Production Tracking id.

property jira_shotgun_url_field: Return the id of the Jira field used to store the url of a linked Flow Production Tracking Entity.

sanitize_jira_update_value(jira_value, jira_field_schema)[source]

Perform sanity checks for the given Jira value and ensure it can be used to update the Jira field with the given schema.

Returns:: A Jira value which can safely be used to update the Jira field.
Raises:: UserWarning – if a safe value can’t be obtained.

find_jira_assignee_for_issue(user_email, jira_project=None, jira_issue=None)[source]

Return a Jira user the given issue can be assigned to, based on the given email address.

A Jira Project must be specified when creating an Issue. A Jira Issue must be specified when editing an Issue.

Parameters:

jira_project – A jira.resources.Project instance or None.
jira_issue – A jira.Issue instance or None.
user_email – An email address as a string.

Returns:

A jira.resources.User instance or None.

Raises:

ValueError – if no Project nor Issue is specified.

find_jira_user(user_email, jira_project=None, jira_issue=None, for_assignment=False)[source]

Return a Jira an assignable user or with browse permission for the given Project or Issue, with the given email address. Either a jira_project or jira_issue must be provided.

Note

Due to problems with user searching in Jira, this method always returns assignable users for the time being.

Parameters:

user_email – An email address as a string.
jira_project – A jira.resources.Project instance or None.
jira_issue – A jira.Issue instance or None.
for_assignment – A boolean, if False the user just needs to have read permission. If True the user needs to be suitable for Issue assignments.

Returns:

A jira.resources.User instance or None.

Raises:

ValueError – if no Project nor Issue is specified.

set_jira_issue_status(jira_issue, jira_status_name, comment)[source]

Attempt to change the Jira Issue status to the given value.

Lookup for a Jira transition where the target status is the given one and try to apply it.

Parameters:

jira_issue – A jira.Issue instance.
jira_status (str) – A Jira status name, e.g. In Progress.
comment – A string, a comment to apply to the Jira transition.

Returns:

True if the status could be set, False otherwise.

create_issue_from_data(jira_project, issue_type, data)[source]

Create an Issue from the given data.

Sanity check the data against Jira create meta data. Try to amend the data, if possible, to complete the Issue creation. Raise ValueError if the data can’t be amended to complete the Issue creation.

Parameters:

jira_project – A jira.resources.Project instance.
issue_type (str) – The target Issue type name.
data – A dictionary where keys are Jira Issue field ids and values are Jira values.

Returns:

A jira.Issue instance.

Raises:

RuntimeError – if the Jira create meta data can’t be retrieved.
ValueError – if invalid and unfixable data is provided.

get_jira_issue_edit_meta(jira_issue)[source]

Return the edit metadata for the given Jira Issue.

Parameters:: jira_issue – A jira.Issue.
Returns:: The Jira Issue edit metadata fields property.
Raises:: RuntimeError – if the edit metadata can’t be retrieved for the given Issue.

Bridge

This is the main class that holds handles to both Flow Production Tracking and Jira and handles dispatching events to both sites.

class sg_jira.Bridge(sg_site, sg_script, sg_script_key, jira_site, jira_user, jira_secret, sync_settings=None, sg_http_proxy=None)[source]

A bridge between Flow Production Tracking and Jira.

The bridge handles connections to the Flow Production Tracking and Jira servers and dispatches sync events.

Instatiate a new bridge between the given PTR site and Jira site.

Note

Jira Cloud requires the use of an API token and will not work with a user’s password. See https://confluence.atlassian.com/x/Vo71Nw for information on how to generate a token. Jira Server will use PAT so please provide empty string as SGJIRA_JIRA_USER.

Parameters:

sg_site (str) – A Flow Production Tracking URL.
sg_script (str) – A Flow Production Tracking script user name.
sg_script_key (str) – The script user key for the Flow Production Tracking script.
jira_site (str) – A Jira site url.
jira_user (str) – A Jira user name, either his email address or short name.
jira_secret (str) – The Jira user password or API key.
sync_settings – A dictionary where keys are settings names.
sg_http_proxy (str) – Optional, a http proxy to use for the Flow Production Tracking connection, or None.

__init__(sg_site, sg_script, sg_script_key, jira_site, jira_user, jira_secret, sync_settings=None, sg_http_proxy=None)[source]

Instatiate a new bridge between the given PTR site and Jira site.

Note

Jira Cloud requires the use of an API token and will not work with a user’s password. See https://confluence.atlassian.com/x/Vo71Nw for information on how to generate a token. Jira Server will use PAT so please provide empty string as SGJIRA_JIRA_USER.

Parameters:

sg_site (str) – A Flow Production Tracking URL.
sg_script (str) – A Flow Production Tracking script user name.
sg_script_key (str) – The script user key for the Flow Production Tracking script.
jira_site (str) – A Jira site url.
jira_user (str) – A Jira user name, either his email address or short name.
jira_secret (str) – The Jira user password or API key.
sync_settings – A dictionary where keys are settings names.
sg_http_proxy (str) – Optional, a http proxy to use for the Flow Production Tracking connection, or None.

classmethod get_bridge(settings_file)[source]

Read the given settings and instantiate a new Bridge with them.

Parameters:: settings_file (str) – Path to a settings Python file.
Raises:: ValueError – on missing required settings.

classmethod read_settings(settings_file)[source]

Read the given settings file.

Parameters:: settings_file (str) – Path to a settings Python file.
Returns:: A tuple of settings: (logger settings, shotgun settings, jira settings, sync settings)
Raises:: ValueError – if the file does not exist or if its name does not end with .py.

property shotgun: Return a connected ShotgunSession instance.

property current_shotgun_user

Return the Flow Production Tracking user used for the connection.

Returns:: A Flow Production Tracking record dictionary with an id key and a type key.

property current_jira_username

Return the username of the current Jira user.

The jira API escapes special characters using %xx syntax when storing the username. For example, the username richard+hendricks is stored as richard%2bhendricks by the jira API. We decode the username here before returning it to ensure we return the exact value (eg. richard+hendricks)

Returns:: A string with the username.

property jira: Return a connected JiraSession instance.

property sync_settings_names: Return the list of sync settings this bridge handles.

reset()[source]

Reset the bridge.

Clears all caches.

get_syncer(name)[source]

Returns a Syncer instance for the given settings name.

Parameters:: str – A settings name.
Raises:: ValueError – for invalid settings.

sync_in_jira(settings_name, entity_type, entity_id, event, **kwargs)[source]

Sync the given Flow Production Tracking Entity to Jira.

Parameters:

settings_name (str) – The name of the settings to use for this sync.
entity_type (str) – The Flow Production Tracking Entity type to sync.
entity_id (int) – The id of the Flow Production Tracking Entity to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the Entity was actually synced in Jira, False if syncing was skipped for any reason.

sync_in_shotgun(settings_name, resource_type, resource_id, event, **kwargs)[source]

Sync the given Jira Resource to Flow Production Tracking.

Parameters:

settings_name (str) – The name of the settings to use for this sync.
resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the resource was actually synced in Flow Production Tracking, False if syncing was skipped for any reason.

Syncers

Base class in charge of initially determining whether to accept events from Flow Production Tracking and Jira for syncing. If accepted, it then passes on the event to a Handler to process the event.

This must be subclassed to implement a list of Handlers to dispatch events to. Additional parameters can be accepted as well to pass on to Handlers.

from .syncer import Syncer
from .handlers import TaskIssueHandler, NoteCommentHandler, EnableSyncingHandler


class TaskIssueSyncer(Syncer):
    """
    Sync Flow Production Tracking Tasks as Jira Issues.
    """

    def __init__(self, issue_type="Task", **kwargs):
        """
        Instatiate a new Task/Issue syncer for the given bridge.

        :param str issue_type: Jira Issue type to use when creating new Issues.
        """
        self._issue_type = issue_type
        super(TaskIssueSyncer, self).__init__(**kwargs)
        self._task_issue_handler = TaskIssueHandler(self, self._issue_type)
        self._note_comment_handler = NoteCommentHandler(self)
        # A handler combining the Task <-> Issue handler and the Note <-> Comment
        # handler. Task syncing to Jira starts if the Task "Sync in Jira" checkbox
        # is turned on. Notes linked to a Task being actively synced are automatically
        # synced without having to manually select them. A full sync is performed
        # when the Task checkbox is turned on.
        self._enable_syncing_handler = EnableSyncingHandler(
            self, [self._task_issue_handler, self._note_comment_handler]
        )

    @property
    def handlers(self):
        """
        Return a list of :class:`~handlers.SyncHandler` instances.
        """
        return [
            self._enable_syncing_handler,
            self._task_issue_handler,
            self._note_comment_handler,
        ]

Syncer

class sg_jira.Syncer(name, bridge, **kwargs)[source]

A class handling syncing between Flow Production Tracking and Jira.

All Syncers should define a list of SyncHandler which should reject or accept and process events.

Instatiate a new syncer for the given bridge.

Parameters:

name (str) – A unique name for the syncer.
bridge – A Bridge instance.

__init__(name, bridge, **kwargs)[source]

Instatiate a new syncer for the given bridge.

Parameters:

name (str) – A unique name for the syncer.
bridge – A Bridge instance.

property bridge: Returns the Bridge instance used by this syncer.

property shotgun: Return a connected ShotgunSession instance.

property jira: Return a connected Jira handle.

property handlers: Needs to be re-implemented in deriving classes and return a list of SyncHandler instances.

setup()[source]: Check the Jira and Flow Production Tracking site, ensure that the sync can safely happen and cache any value which is slow to retrieve.

get_jira_project(project_key)[source]

Retrieve the Jira Project with the given key, if any.

Returns:: A jira.resources.Project instance or None.

accept_shotgun_event(entity_type, entity_id, event)[source]

Accept or reject the given event for the given Flow Production Tracking Entity.

Returns:: A SyncHandler instance if the event is accepted for processing, None otherwise.

accept_jira_event(resource_type, resource_id, event)[source]

Accept or reject the given event for the given Jira resource.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

A SyncHandler instance if the event is accepted for processing, None otherwise.

SyncHandlers

Base class that handles a particular sync instance between Flow Production Tracking and Jira.

Handlers hold the main logic for syncing values between a Flow Production Tracking Entity type and a Jira resource. They are owned by a Syncer instance. This base class defines the interface all handlers should support and provides helpers methods useful to all implementations.

SyncHandler

class sg_jira.handlers.SyncHandler(syncer)[source]

Base class to handle a particular sync between Flow Production Tracking and Jira.

Handlers typically handle syncing values between a Flow Production Tracking Entity type and a Jira resource and are owned by a Syncer instance.

This base class defines the interface all handlers should support and provides some helpers which can be useful to all handlers.

Instantiate a handler for the given syncer.

Parameters:: syncer – A Syncer instance.

__init__(syncer)[source]

Instantiate a handler for the given syncer.

Parameters:: syncer – A Syncer instance.

get_jira_project(project_key)[source]

Retrieve the Jira Project with the given key, if any.

Returns:: A jira.resources.Project instance or None.

get_jira_issue(issue_key)[source]

Retrieve the Jira Issue with the given key, if any.

Parameters:: issue_key (str) – A Jira Issue key to look for.
Returns:: A jira.Issue instance or None.
Raises:: RuntimeError – if the Issue if not bound to any Project.

get_jira_user(user_email, jira_project)[source]

Given an email address, find the associated Jira User in the given Jira Project.

Parameters:

user_email – The email address of the user we want to retrieve
jira_project – An instance of jira.resources.Project we want to retrieve the user from

Returns:

A jira.resources.User instance or None.

get_sg_user(user_id, jira_user=None)[source]

Resolve the Flow Production Tracking user associated to the JIRA user passed in.

Parameters:

user_id (str) – Value of the to or from of a JIRA changelog.
jira_user (dict) – User resource, typically the assignee field on an issue. Can be None

Returns:

A FPTR user entity dictionary or None

setup()[source]

This method can be re-implemented in deriving classes to Check the Jira and Flow Production Tracking site, ensure that the sync can safely happen and cache any value which is slow to retrieve.

This base implementation does nothing.

accept_shotgun_event(entity_type, entity_id, event)[source]

Accept or reject the given event for the given Flow Production Tracking Entity.

Must be re-implemented in deriving classes.

Returns:: True if the event is accepted for processing, False otherwise.

process_shotgun_event(entity_type, entity_id, event)[source]

Process the given Flow Production Tracking event for the given Flow Production Tracking Entity

Must be re-implemented in deriving classes.

Parameters:

entity_type (str) – The Flow Production Tracking Entity type to sync.
entity_id (int) – The id of the Flow Production Tracking Entity to sync.
event – A dictionary with the event for the change.

Returns:

True if the event was successfully processed, False if the sync didn’t happen for any reason.

accept_jira_event(resource_type, resource_id, event)[source]

Accept or reject the given event for the given Jira resource.

Must be re-implemented in deriving classes.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event is accepted for processing, False otherwise.

process_jira_event(resource_type, resource_id, event)[source]

Process the given Jira event for the given Jira resource.

Must be re-implemented in deriving classes.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event was successfully processed, False if the sync didn’t happen for any reason.

EntityIssueHandler

Base class for syncing Flow Production Tracking Entities and Jira Issues. This inherits from SyncHandler.

class sg_jira.handlers.EntityIssueHandler(syncer, issue_type)[source]

Bases: SyncHandler

Base class for handlers syncing a Flow Production Tracking Entity to a Jira Issue.

Instantiate an Entity Issue handler for the given syncer.

Parameters:

syncer – A Syncer instance.
issue_type (str) – A target Issue type, e.g. ‘Task’, ‘Story’.

__init__(syncer, issue_type)[source]

Instantiate an Entity Issue handler for the given syncer.

Parameters:

syncer – A Syncer instance.
issue_type (str) – A target Issue type, e.g. ‘Task’, ‘Story’.

accept_jira_event(resource_type, resource_id, event)[source]

Accept or reject the given event for the given Jira resource.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event is accepted for processing, False otherwise.

process_jira_event(resource_type, resource_id, event)[source]

Process the given Jira event for the given Jira resource.

Parameters:

resource_type (str) – The type of Jira resource to sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event was successfully processed, False if the sync didn’t happen for any reason.

accept_shotgun_event(entity_type, entity_id, event)

Accept or reject the given event for the given Flow Production Tracking Entity.

Must be re-implemented in deriving classes.

Returns:: True if the event is accepted for processing, False otherwise.

get_jira_issue(issue_key)

Retrieve the Jira Issue with the given key, if any.

Parameters:: issue_key (str) – A Jira Issue key to look for.
Returns:: A jira.Issue instance or None.
Raises:: RuntimeError – if the Issue if not bound to any Project.

get_jira_project(project_key)

Retrieve the Jira Project with the given key, if any.

Returns:: A jira.resources.Project instance or None.

get_jira_user(user_email, jira_project)

Given an email address, find the associated Jira User in the given Jira Project.

Parameters:

user_email – The email address of the user we want to retrieve
jira_project – An instance of jira.resources.Project we want to retrieve the user from

Returns:

A jira.resources.User instance or None.

get_sg_user(user_id, jira_user=None)

Resolve the Flow Production Tracking user associated to the JIRA user passed in.

Parameters:

user_id (str) – Value of the to or from of a JIRA changelog.
jira_user (dict) – User resource, typically the assignee field on an issue. Can be None

Returns:

A FPTR user entity dictionary or None

process_shotgun_event(entity_type, entity_id, event)

Process the given Flow Production Tracking event for the given Flow Production Tracking Entity

Must be re-implemented in deriving classes.

Parameters:

entity_type (str) – The Flow Production Tracking Entity type to sync.
entity_id (int) – The id of the Flow Production Tracking Entity to sync.
event – A dictionary with the event for the change.

Returns:

True if the event was successfully processed, False if the sync didn’t happen for any reason.

setup()

This method can be re-implemented in deriving classes to Check the Jira and Flow Production Tracking site, ensure that the sync can safely happen and cache any value which is slow to retrieve.

This base implementation does nothing.

EnableSyncingHandler

A handler that controls the initial sync for a Flow Production Tracking Task and Jira Issue when the “Sync In Jira” checkbox is toggled in Flow Production Tracking. It combines multiple handlers to begin the syncing process by performing a full sync each time the checkbox is toggled on. This allows one to manually force a re-sync if needed by just toggling the checkbox off and then on again.

Inherits from SyncHandler.

class sg_jira.handlers.EnableSyncingHandler(syncer, handlers)[source]

A handler which combines multiple handlers to start syncing Tasks and Entities linked to them when a Task “Sync In Jira” (sg_sync_in_jira) checkbox field is changed in Flow Production Tracking.

A full sync is performed each time the checkbox is turned on. This allows to manually force a re-sync if needed by just setting off the checkbox, and then back to on.

Instantiate a new handler which combines the provided handlers.

The first handler in the list is assumed to be a primary handler, the others are assumed to be secondary handlers.

Events will be sent to secondary handlers for processing only if the primary handler was able to successfully process them.

This allows to control from the primary handler if a Flow Production Tracking Entity should be synced or not, and then automatically start syncing secondary Entities which are linked to this primary Entity, e.g. Notes on a Task, without having to explicitely enable syncing for the linked Entities.

Combined handlers shouldn’t accept the events which are accepted by this handler, but they need to be able to process them.

Parameters:

syncer – A Syncer instance.
handlers – A non empty list of SyncHandler instances.

__init__(syncer, handlers)[source]

Instantiate a new handler which combines the provided handlers.

The first handler in the list is assumed to be a primary handler, the others are assumed to be secondary handlers.

Events will be sent to secondary handlers for processing only if the primary handler was able to successfully process them.

This allows to control from the primary handler if a Flow Production Tracking Entity should be synced or not, and then automatically start syncing secondary Entities which are linked to this primary Entity, e.g. Notes on a Task, without having to explicitely enable syncing for the linked Entities.

Combined handlers shouldn’t accept the events which are accepted by this handler, but they need to be able to process them.

Parameters:

syncer – A Syncer instance.
handlers – A non empty list of SyncHandler instances.

setup()[source]

Check the Jira and Flow Production Tracking site, ensure that the sync can safely happen. This can be used as well to cache any value which is slow to retrieve.

Run all handlers setup.

accept_shotgun_event(entity_type, entity_id, event)[source]

Accept or reject the given event for the given Flow Production Tracking Entity.

Returns:: True if the event is accepted for processing, False otherwise.

process_shotgun_event(entity_type, entity_id, event)[source]

Process the given Flow Production Tracking event for the given Flow Production Tracking Entity

Parameters:

entity_type (str) – The Flow Production Tracking Entity type to sync.
entity_id (int) – The id of the Flow Production Tracking Entity to sync.
event – A dictionary with the event for the change.

accept_jira_event(resource_type, resource_id, event)[source]

Accept or reject the given event for the given Jira resource.

This handler rejects all Jira events.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event is accepted for processing, False otherwise.

get_jira_issue(issue_key)

Retrieve the Jira Issue with the given key, if any.

Parameters:: issue_key (str) – A Jira Issue key to look for.
Returns:: A jira.Issue instance or None.
Raises:: RuntimeError – if the Issue if not bound to any Project.

get_jira_project(project_key)

Retrieve the Jira Project with the given key, if any.

Returns:: A jira.resources.Project instance or None.

get_jira_user(user_email, jira_project)

Given an email address, find the associated Jira User in the given Jira Project.

Parameters:

user_email – The email address of the user we want to retrieve
jira_project – An instance of jira.resources.Project we want to retrieve the user from

Returns:

A jira.resources.User instance or None.

get_sg_user(user_id, jira_user=None)

Resolve the Flow Production Tracking user associated to the JIRA user passed in.

Parameters:

user_id (str) – Value of the to or from of a JIRA changelog.
jira_user (dict) – User resource, typically the assignee field on an issue. Can be None

Returns:

A FPTR user entity dictionary or None

process_jira_event(resource_type, resource_id, event)

Process the given Jira event for the given Jira resource.

Must be re-implemented in deriving classes.

Parameters:

resource_type (str) – The type of Jira resource sync, e.g. Issue.
resource_id (str) – The id of the Jira resource to sync.
event – A dictionary with the event meta data for the change.

Returns:

True if the event was successfully processed, False if the sync didn’t happen for any reason.

Utils

Common utility functions.

sg_jira.utils.utf8_to_unicode(value)[source]

Convert any string in the given input to unicode. Strings are expected to be in utf-8 encoding.

Treat containers by recursively iterating over all the values they contain.

Parameters:: value – A string, a list, a tuple, or a dictionary.
Returns:: The value with all strings converted to unicode.
Raises:: ValueError – if a converted UTF-8 decoded key is already present in the original value of a dictionary.

sg_jira.utils.unicode_to_utf8(value)[source]

Convert any unicode in the given input to an utf8 encoded string value.

Treat containers by recursively iterating over all the values they contain.

Parameters:: value – A string, a list, a tuple, or a dictionary.
Returns:: The value with all unicode values converted to strings.
Raises:: ValueError – if a converted UTF-8 encoded key is already present in the original value of a dictionary.

Errors

exception sg_jira.errors.InvalidSyncValue(field, value, *args, **kwargs)[source]

Base class for exceptions raised when a value can’t be translated to a valid value for a given field.

Parameters:

field (str) – The Jira or PTR field for which the exception was raised.
value – The Jira or PTR value for which the exception was raised.

property field: Return the field for which the exception was raised.

property value: Return the value for which the exception was raised.

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception sg_jira.errors.InvalidShotgunValue(field, value, *args, **kwargs)[source]

An exception raised when a Flow Production Tracking value can’t be translated to a valid Jira value for a given field.

Parameters:

field (str) – The Jira or PTR field for which the exception was raised.
value – The Jira or PTR value for which the exception was raised.

property field: Return the field for which the exception was raised.

property value: Return the value for which the exception was raised.

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception sg_jira.errors.InvalidJiraValue(field, value, *args, **kwargs)[source]

An exception raised when a Jira value can’t be translated to a valid Flow Production Tracking value for a given field.

Parameters:

field (str) – The Jira or PTR field for which the exception was raised.
value – The Jira or PTR value for which the exception was raised.

property field: Return the field for which the exception was raised.

property value: Return the value for which the exception was raised.

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Tests & CI

Unit tests are in the /tests folder. A requirements.txt file is available in this folder as well to install the required modules to run the tests.

Run the tests from the tests directory with python run_tests.py.

Continuous Integration (CI)

Azure Pipelines are used for the continuous integration and run the following validations:

Enforce reasonable PEP-8 conventions with Flake8.
Run unit tests on Linux, Mac and Windows with Python 3.9.

Azure Pipelines jobs are defined by the description files in the /azure-pipelines folder.