Issue REST API

If you want to build a custom Simscope bug integration/plugin, here is a basic introduction.

Python Issues API

The Simscope Python script simscope-issue-update can be run in 3 different modes:

List issues (bugs).
Update an issue's fields (e.g. change bug title, owner, state).
Resolve bug.

Simscope Server address

Note: append --addr=simscope-host:8080 to the command, to set the Simscope server address.

Mode 1: List Issues

To get a list issues from Simscope:

# List all issues
> bin/simscope-issue-update --list

# List active issues
> bin/simscope-issue-update --list-active

# List active bugs
> bin/simscope-issue-update --list-active --list-bugs-only

Example Listing:

> bin/simscope-issue-update --list --addr=simscope-host:8080

SIM-10
SIM-100
SIM-11
SIM-13
SIM-14
SIM-16
SIM-18
SIM-25
SIM-32
SIM-33
SIM-34
SIM-36
SIM-37
...

Mode 2: Update Issue via --CLI arguments

To update an issue's fields, use:

simscope-issue-update ISSUEID --field=X

Example Update:

> bin/simscope-issue-update BUG-22 --addr=simscope-host:8080 \
--title='Fifo underflow in state machine' \
--project='Gamma' \
--assignee_email=payton@verops.com \
--reporter_email=freddy@verops.com \
--state=in-progress \
--priority=blocker \
--resolved='2024-06-11T22:30:53+07:00' \
--updated='2024-06-11T22:30:53+07:00' \

Updated BUG-22

Mode 3: Update Issue via JSON file

To update an issue from a JSON file, use:

simscope-issue-update ISSUEID --json-file FILENAME.json

Store the JSON object into FILENAME.json:

{
    "bugid": "SIM-44",
    "project": "Simscope",
    "title": "Simscope Signature 1190: FAIL TestRabbitTunnelToSimscope ...",
    "component": "",
    "branch": "",
    "designation": "",
    "state": "To Do",
    "priority": "Medium",
    "reporter_email": "payton@verops.com",
    "assignee_email": "payton@verops.com",
    "created": "2024-05-24T12:39:34.739-05:00",
    "updated": "2024-05-24T12:39:34.739-05:00",
    "resolved": "0001-01-01T00:00:00Z",
    "url": ""
}

Example:

> bin/simscope-issue-update BUG-33 --addr=simscope-host:8080 --json-file bug33.json

Updated BUG-33

Curl prerequisites

To run any of the following commands, make sure you have the Curl API working.

Note: replace SERVER with your simscope server hostname (or IP address).

Sample JSON Issue

Here is a sample Issue SIM-37 rendered via JSON:

{
    "bugid": "SIM-37",
    "project": "Simscope",
    "title": "Simscope Signature 1183: FAIL TestJobSearchParse ...",
    "component": "Server",
    "branch": "",
    "designation": "DV",
    "state": "To Do",
    "priority": "Medium",
    "reporter_email": "payton@verops.com",
    "assignee_email": "fred@verops.com",
    "created": "2019-11-13T20:40:13.531-05:00",
    "updated": "2019-11-14T14:20:11.102-05:00",
    "resolved": "0001-01-01T00:00:00Z",
    "url": ""
}

Get issue via Curl

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" -G \
"http://SERVER:8080/api/issues/BUG-ID"

replace BUG-ID with your bug ID

replace server with your simscope server hostname (or IP address)

Example JSON response:

{
    "bugid": "SIM-37",
    "project": "Simscope",
    "title": "Simscope Signature 1183: FAIL TestJobSearchParse ...",
    "component": "Server",
    "branch": "",
    "designation": "DV",
    "state": "To Do",
    "priority": "Medium",
    "reporter_email": "payton@verops.com",
    "assignee_email": "payton@verops.com",
    "created": "2019-11-13T20:40:13.531-05:00",
    "updated": "2019-11-14T14:20:11.102-05:00",
    "resolved": "0001-01-01T00:00:00Z",
    "url": ""
}

Post issue via Curl

To add (or update) an issue:

Save the issue metadata as a JSON file called bug-test.json:

{
    "bugid": "SIM-1",
    "project": "Simscope",
    "title": "Hello world, this is a bug",
    "component": "test-bug-component",
    "branch": "",
    "designation": "RTL",
    "state": "To Do",
    "priority": "Medium",
    "reporter_email": "payton@verops.com",
    "assignee_email": "john@verops.com",
    "created": "2020-12-18T13:43:07.462-05:00",
    "updated": "2020-12-18T13:43:07.462-05:00",
    "resolved": "0001-01-01T00:00:00Z",
    "url": ""
}

Run the following command (replace SERVER:8080):

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" \
--header "Content-Type: application/json" \
-XPOST "http://server:8080/api/issues/TEST-BUG-1000" --data @bug-test.json

If successful, you should see a JSON response:

{
    "bugid": "TEST-BUG-1000",
    "project": "Simscope",
    "title": "Hello world, this is a bug",
    "component": "test-bug-component",
    "branch": "",
    "designation": "RTL",
    "state": "To Do",
    "priority": "Medium",
    "reporter_email": "payton@verops.com",
    "assignee_email": "john@verops.com",
    "created": "2020-12-18T13:43:07.462-05:00",
    "updated": "2020-12-18T13:43:07.462-05:00",
    "resolved": "0001-01-01T00:00:00Z",
    "url": ""
}

View the bug metadata

Open your browser and go to http://server:8080/issues/TEST-BUG-1000 :

Error 409: Stale update timestamp

If you get an response similar to the following:

{
    "code": 409,
    "error": "issue {TEST-BUG-1000} stale update timestamp: 2020-12-18T13:43:07-05:00"
}

This is a warning, indicating you are updating a bug with an updated timestamp that is not newer than Simscope's cache of the bug, so Simscope has skipped updating it.

This prevents Simscope from doing a redundant bug update.
To override this, use a newer updated timestamp.

Download list of all bugs in Simscope (via curl)

To download a list of all bugs known in Simscope (so you can query a list of bugs in an external bug tracker):

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" -G \
"http://server:8080/api/issues/?all"

If successful, you should see a JSON array response similar to the following:

[
    ".842-fixed",
    ".LOW_PRIORITY",
    ".bzCompileFailed",
    ".my-tag",
    ".rule-tag-without-hits",
    ".testbench",
    ".timeout",
    ".verops-86",
    ".working",
    "12345",
    "1249",
    "12888x"
]

Simscope Administration Guide