Replication Script¶

Replication scripts allow for the creation and updating of bugs between a source and destination tracker, The script engine executes the user created Python script, which determines whether bugs should be replicated and if so what fields/values to set in the destination tracker.

Bug Tracker Formats/API¶

To allow for the most flexibility in bug replication, each bug tracker’s create/update operations are specific to that tracker. Below are the trackers supported in CI Bug Log and links to further documenation specific to each. It is advised that you read through this page first to get an understanding of the overall process.

Procedure¶

The script is executed in a secure environment, and as such, all system calls are not allowed. The python standard library is however usable (as long as it does not generate system calls), but you cannot load most external modules.

The script must define the function ‘replication_check’. This function determines whether the supplied bug should be replicated and returns a dict defining the bug replication. The format of this will be defined in the next section.

If the replication script is enabled in the database, than when a bug from the specified source tracker is polled this replication_check method will be executed on that bug.

It is important to note that the replication check function takes the source bug that is to be checked, as well as the replicated destination bug. If the bug has not previously been replicated, the dest_bug argument will be an empty dictionary.

If you need to handle updating an already replicated bug differently than creating a new bug, you can check if the dest_bug is not empty to determine what to return. This allows the script to handle each process separately

Below is the function signature that should be used:

def replication_check(src_bug, dest_bug)

Note

When creating a new replication script the script field will be prepopulated with a dummy script, as a very trivial example. You can simply delete it and leave the function signature.

Parameters:

src_bug: dict(): variable holding the current bug for evaluation. New comments added to the bug since last polling will also be accessible via the dictionary key ‘new_comments’. See the Bug Fields and Bug Comment Fields sections for information on the values.

dest_bug: dict(): variable holding the replicated bug. Will be empty dict if bug hasn’t been already replicated

Returns:

dict(): Defines fields used for replication. Consult the tracker specific information in the Bug Tracker Formats/API section for the proper formatting for your destination tracker.

Bug Fields¶

The following fields are accessible in the src_bug and dest_bug parameters passed to replication_check

Fields	Data Type
bug_id	str
title	str
description	str
tracker	str
created	str (YYYY-MM-DD hh:mm:ss.sTZD)
updated	str (YYYY-MM-DD hh:mm:ss.sTZD)
polled	str (YYYY-MM-DD hh:mm:ss.sTZD)
closed	str (YYYY-MM-DD hh:mm:ss.sTZD)
creator	str
assignee	str
product	str
component	str
priority	str
severity	str
features	list[str]
platforms	list[str]
status	str
tags	list[str]
custom_fields	dict[str, str]

Custom Fields¶

Different BugTracker projects may use fields that aren’t natively builtin to CI Bug Log’s Bug objects. To support these additional fields, there is a custom_fields dictionary that can store these. The values are stored using a string key and string value only. Lists, sets, dicts, or other structures are not allowed as values.

For more information on configuring custom fields for your trackers consult the following models documentation.

BugTracker: custom_fields_map field
Bug: custom_fields field

For additional information regarding how these fields are handled for specific trackers, consult the tracker specific replication pages: Bug Tracker Formats/API

Bug Comment Fields¶

The source bug also includes new comments that can be replicated as well. These are stored in the source bug dictionary under the key ‘new_comments’. This contains a list of comments dicts with the following fields for each comment.

Fields	Data Type
author	str
created	str (YYYY-MM-DD hh:mm:ss.sTZD)
body	str

Bug Replication Dictionary Format¶

The returned dictionary uses the keys described below. Any unneeded fields can simply be omitted. If the bug should not be replicated then return an empty dictionary.

set_fields: A dictionary where keys represent bug’s fields to be set in the destination bugtracker.

db_fields_update: A dictionary where keys are the names of the destination bug’s DB fields to be updated directly. NOTE: This is deprecated in favor of the below two options.

db_src_fields_update: A dictionary where keys are the names of the source bug’s DB fields to be updated directly.

db_dest_fields_update: A dictionary where keys are the names of the destination bug’s DB fields to be updated directly.

add_comments: A list of comments (str) to be added to the bug.

Replication Script UI¶

Information on the features and usage of the replication script UI can be found here: Replication Script UI