Signature Journal (Timeline History)

Note: This script requires an API Token to run.

Simscope includes a script simscope-sig-search --journal to search and dump timeline-based Signature Updates from the command-line (or from API) in CSV (comma-separated) or TSV (tab-separated value) formats.

• These updates can either be manual assignment updates, rule executions, or signature/job comments.

Output

The output is returned as a CSV or TSV file (tab-separated value).

The assignee and issue fields are special case fields. They can have any of the following values:

• Blank string — ignore the value (keep the previous record value for this field)
• <null> — special string meaning to clear the field value to a blank value
• Any other string (for example hello) — update the field to this literal string

Each record is a single update to a single Signature job.

NOTE: the results are returned in ascending signature and time order (ie oldest first/newest last), so updates can be applied in order of the results.

Output to File

To output to a file (instead of STDOUT), use the option --output=FILENAME

TSV Output Format

To emit as TSV format, use the option --output-format=tsv

Filter Updates by Signature ID or Job ID

To filter by Signature ID, use the option: --sigid=SIGID

• Example: --sigid=1249

To filter by Job ID, use the option: --sigid=SIGID/JOBID

• Example: --jobid=1249/abcdef

CSV Example

This example dumps all updates between the dates 2020-02-03 to 2020-02-04 in CSV format:

> simscope-sig-search --journal --date-low=2023-02-03 --date-high=2020-02-04

jobid,transaction-type,timestamp,ruleid,state,assignee,issue,comment
1190/cq6yw9t8yszc,rule-extra,2023-02-01 00:13:32.410493052 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq6z8ph9e5wg,rule-extra,2023-02-01 00:29:45.250423014 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq8ie9g57wvc,rule-extra,2023-02-02 19:43:17.688051032 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cq9e23a4dgwo,rule-extra,2023-02-03 20:31:51.339249042 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1190/cqa01gwe4qls,rule-extra,2023-02-04 13:45:40.909727045 -0500 -5:00,1190.5,OPEN,pdq,SIM-39,
1230/cpooqenysqls,jobs-update,2023-02-01 21:37:05.530047032 -0500 -5:00,,,,,Hello world: this is a comment
1230/cpkqnygdetfs,jobs-update,2023-02-01 21:37:05.530047032 -0500 -5:00,,,,.HELLO,
1230/cpooqenysqls,jobs-update,2023-02-01 21:37:39.027759037 -0500 -5:00,,NEW,<null>,<null>,
1230/cpkqnygdetfs,jobs-update,2023-02-01 21:38:00.025863043 -0500 -5:00,,NEW,<null>,<null>,

Job Metadata Fields

Simscope can dump any additional job metadata fields into the TSV output. Use the --metadata argument for each field.

See Job Metadata on the Administration Guide for more details on setting up job metadata.

Note: adding metadata will slow down the search dramatically.

For example, this command will request two additional metadata fields:

> simscope-sig-search --journal --days=1 --metadata=classification --metadata=num_instructions

To see all available metadata registered in Simscope, click the Job Search Help link at the bottom of any Simscope web page.

Metadata Fields available

There are many available builtins metadata fields:

• classification
• designation
• category
• host
• regr
• component
• branch
• or any Custom Job Metadata Field