Integrate Custom Bug Tracker to Simscope

Note: please contact VerOps for additional help with creating bug plugins.

Simscope can connect to any bug tracker and create a bug automatically, by using a custom plugin.

This can be written in any language: Python, Ruby, Perl, shell, etc.
- See Issue REST API's for more details.

Skeleton Bug Template

Use the Python script simscope-custom-bug-skeleton.py

Instructions:

Update your simscope.config file to add a createplugin configuration:

[bugtracker "My Bug Tracker"]
createplugin = "/path/to/simscope-custom-bug-skeleton.py --create"
refreshplugin = "/path/to/simscope-custom-bug-skeleton.py %s"

# Bug autorefresh interval ("30m", "2h", etc).
# Note: this is only used if at least one [bugtracker] has a 'refreshplugin' set
# autorefresh = "60m"

# Auto resolve rules.  This enables automatic resolving of rules when a bug
# has been set to a fixed/resolved/closed state.
# See https://admin-docs.simscope.com/bugs/update.html
# autoresolverules = true

# Optional: auto-refresh bug batch size.  When auto-refreshing, Simscope splits the list of
# known bugs into batches, and calls the bug refresh script once per batch.
# (Default is 100 bugs per batch.)
# autorefreshbatchsize = 100

# Optional: auto-refresh script timeout.  Simscope will terminate scripts after this amount of time (to prevent hangs)
# (Default is 2 minutes.)
# autorefreshtimeout = "2m"

Restart Simscope server.
From a Simscope Rule page, click "Create My Bug Tracker" button.
If this plugin is successful, Simscope should get a SKELETON-1 bug ID response in Simscope.
Now, convert the script to use your bug tracker.

Testing bugs from the Command Line

You can test the bug create script from the command-line, without needing to use Simscope from the web browser.

Simscope sends a JSON input message to the bug create plugin, to create a bug. This contains:

Signature and rule info
Bug assignee
Bug reporter
etc.

The Bug create plugin script must:

Read the JSON input from Simscope
Create a bug (or return an error via stderr)
print a JSON bug response to stdout

1. Create a fake JSON input file

Save this to a file fake-bug-input.json

{
    "update": {
        "sigid": 1199,
        "subrule": 0,
        "initialns": 0,
        "finalns": 0,
        "query": "component=simscope",
        "statename": "ASSIGNED",
        "assignee": "pdq",
        "issue": "",
        "count": 4,
        "model_finalns": 0,
        "user": "pdq",
        "oldkeys": [
            "1199/cgh0tlk1pir4",
            "1199/c9a83howoy0w",
            "1199/c8q4q5jdj4ko",
            "1199/c8q0k1peqrbk"
        ]
    },
    "component": {
        "id": 29,
        "name": "simscope",
        "project": "simscope",
        "ownerid": "pdq",
        "inactive": false,
        "createdns": 1444863228616872830,
        "updatedns": 1534796519663230838
    },
    "assignee": {
        "uid": "pdq",
        "login": "pdq",
        "name": "Payton Quackenbush",
        "email": "payton@verops.com",
        "group": "",
        "admin": true,
        "manager": false,
        "subdaily": true,
        "subimport": false,
        "disabled": false,
        "foreground": 16777215,
        "background": 2317899,
        "initials": "PQ",
        "short_name": "Payton Q."
    },
    "reporter": {
        "uid": "pdq",
        "login": "pdq",
        "name": "Payton Quackenbush",
        "email": "payton@verops.com",
        "group": "",
        "admin": true,
        "manager": false,
        "subdaily": true,
        "subimport": false,
        "disabled": false,
        "foreground": 16777215,
        "background": 2317899,
        "initials": "PQ",
        "short_name": "Payton Q."
    },
    "signature": {
        "sigid": 1199,
        "active": true,
        "category": "test",
        "title": "FAIL TestLanding ...",
        "state": {
            "name": "ASSIGNED"
        },
        "firstrev": "9621x",
        "first_model_ts": 1611282125000000000,
        "lastrev": "12437",
        "last_model_ts": 1639687111000000000,
        "jobs": {
            "count": 4,
            "first": {
                "sigid": 1199,
                "active": true,
                "jobns": 1611351843497570000
            },
            "last": {
                "sigid": 1199,
                "active": true,
                "jobns": 1639687819896958000
            }
        },
        "new": 3,
        "assigned": 1,
        "open": 0,
        "wontfix": 0,
        "fixed": 0,
        "ignore": 0,
        "issue_count": 0,
        "issues": "",
        "prune_count": 0,
        "createdns": 1611351843497570000,
        "updatedns": 1639687855373538038,
        "priority": "",
        "classification": ""
    },
    "first_job": {
        "sigid": 1199,
        "active": true,
        "jobns": 1639687819896958000,
        "start_time": "0001-01-01T00:00:00Z",
        "finish_time": "0001-01-01T00:00:00Z",
        "componentid": 29,
        "userid": "pdq",
        "extid": "2",
        "seed": "",
        "model_ts": 1639687111000000000,
        "regrname": "release/12437",
        "model_branch": "default",
        "model_version": "12437",
        "category": "test",
        "build": "release",
        "testgroup": "selftest",
        "config": "sh -c \"cd env && make -j1 test-verops 2>& 1\"",
        "compute_ms": 35437,
        "runtime_ms": 0,
        "simcycles": 0,
        "message": "--- FAIL: TestLanding (0.10s)",
        "host": "quackbook-pro",
        "path": "/Users/pdq/v/simscope/run/release/12437/2",
        "exitcode": 2,
        "result": "fail",
        "assignee": "pdq",
        "issue": "",
        "rulenum": "1",
        "stateid": 1,
        "testname": "",
        "testargs": "",
        "jobid": "",
        "component": "",
        "state": ""
    },
    "sig_url": "http://localhost:8080/sigs/1199",
    "job_url": "http://localhost:8080/sigs/1199/cgh0tlk1pir4"
}

2. Run bug plugin

On the command-line, run the bug plugin, using the sample JSON input

> cat fake-bug-input.json | /path/simscope-bug-create-skeleton.py

NOTE: the script must print JSON response to stdout, or errors to stderr

If successful, you should see a JSON message printed to stdout:

{
    "bugid": "SKELETON-1",
    "url": "https://mybugtracker.com/SKELETON-1",
    "title": "Simscope Signature 1199: FAIL TestLanding ...",
    "state": "To Do",
    "priority": "Medium",
    "project": "SATURN",
    "component": "RTL-ABC",
    "assignee_email": "payton@verops.com",
    "reporter_email": "payton@verops.com",
    "created": "2021-08-02T16:16:38.874-05:00",
    "updated": "2021-12-16T17:43:44.726581-06:00"
}

3. Refresh Bug (inside Simscope)

To refresh a bug manually within Simscope:

Click on the Bug in Simscope.
Then click the Refresh circle.

This will call your custom bug plugin and refresh the bug inside Simscope (if it has changed).

Simscope Administration Guide