Run Object¶

Run Details¶

A RunDetails object in VOR Stream contains the following data:

Data	Description	Go Type	Python Type
Name	Name of the run	string	str
Study	Study selected for the run	*Study	Study
StartDate	Time when the run was started	*timestamppb.Time	Timestamp
Comment	Any comments entered for the run	string	str
Options	Runtime options provided by the user who started the run	map[string]*any	dict[str, Any]
Objects	Runtime objects by options key to list of object IDs	*RunObjects	RunObjects
Playpen	Playpen from which the run was started	string	str
PlaypenID	ID of the playpen	uint32	int
UserID	ID of the user who started the run	string	str
UserName	Name of the user who started the run	string	str
UserEmail	Email of the user who started the run	string	str

To retrieve data about a run, pass the run's unique numeric identifier to the GetRunDetails function in Golang or the get_run_details in Python.

Example: Go¶

runID := frgutil.GetRunID(u.hh)

runDetails, err := sdkClient.GetRunDetails(runID)
if err != nil {
   log.Fatal(err)
}

// Getter functions to retrieve specific data in a run object
runName := runDetails.GetName()
runStartDate := runDetails.GetStartDate()
runUserName := runDetails.GetUserName()

Example: Python¶

from sdk import run

runID = handle.options["RunID"]
run_details = run.get_run_details(runID)

# Who started the run?
>>> run_details.UserID
susan

# What is the name of the run?
>>> run_details.Name
test

#When was the start date for the run?
>>> run_details.StartDate.seconds
1652121071
>>> run_details.StartDate.nanos
324463000

Listing Runs¶

The ListRuns function in Go or list_runs in Python allows you to retrieve a list of runs matching specified filter criteria. All filter parameters are optional – if no filters are provided, all accessible runs are returned.

Filter	Description	Go Type	Python Type
ID	Filter by specific run ID (0 = no filter)	uint	int
ProcessID	Filter by process ID (0 = no filter)	uint	int
Approved	Filter by approval status, also known as "golden copy" (nil = no filter, true = approved, false = unapproved)	*bool	bool or None
PlaypenID	Filter by playpen ID (0 = no filter)	uint	int
Status	Filter by status (UNSPECIFIED = no filter)	JobStatus	JobStatus
ReportOnIDs	Retrieve reporting runs for the given run ID(s) (empty = no filter)	[]uint	list[int]

Note

When multiple filters are provided, they are combined with AND logic. For example, filtering by both PlaypenID and Approved=true returns only runs that are in that playpen AND are approved.

JobStatus Enum¶

The JobStatus enum defines valid run status values. Constants are available in both Go and Python:

Go: sdk.JobStatus_<CONSTANT> (e.g., sdk.JobStatus_JOB_STATUS_FINISHED)
Python: job_status_pb2.<CONSTANT> (e.g., job_status_pb2.JOB_STATUS_FINISHED)

Constant	Django String
JOB_STATUS_UNSPECIFIED	(no filter)
JOB_STATUS_INITIALIZED	Initialized
JOB_STATUS_COMPILING	Compiling
JOB_STATUS_CODE_COMPILE_ERROR	Code_Compile_Error
JOB_STATUS_RUNNING	Running
JOB_STATUS_JOB_FINISHED_WITH_ERRORS	Job_Finished_With_Errors
JOB_STATUS_JOB_FINISHED_WITH_WARNINGS	Job_Finished_With_Warnings
JOB_STATUS_FINISHED	Finished
JOB_STATUS_JOB_CANCELED	Job_Canceled
JOB_STATUS_NOT_EXECUTED	Not_Executed

RunListItem Fields¶

Each item in the returned list contains the following fields:

Field	Description	Go Type	Python Type
id	Unique identifier for the run	uint32	int
name	Name of the run	string	str
playpen_id	ID of the playpen	uint32	int
comment	Comments entered for the run	string	str
study_name	Name of the associated study	string	str
output_variables	Output variables from the run	map[string]string	dict[str, str]
user_id	ID of the user who started the run	string	str
approval_user_name	Name of approving user	string	str
approval_comment_text	Approval comment	string	str
approval_time	Time of approval	string	str
tags	Tags associated with the run	[]string	list[str]
process_id	Process ID	uint32	int
start_time	Start time of the run	*timestamppb.Time	Timestamp
end_time	End time of the run	*timestamppb.Time	Timestamp
approved	Whether the run is approved	bool	bool
status	Current status of the run	JobStatus	JobStatus

Example: Go¶

// List all runs in current playpen
runs, err := sdkClient.ListRuns(&sdk.ListRunsOpts{
    PlaypenID: uint(frgutil.GetPlaypenID(u.hh)),
})
if err != nil {
    log.Fatal(err)
}

for _, run := range runs {
    log.Printf("Run %d: %s (status=%s, approved=%t)",
        run.GetId(), run.GetName(), run.GetStatus(), run.GetApproved())
}

// List only approved runs with "Finished" status
approvedRuns, err := sdkClient.ListRuns(&sdk.ListRunsOpts{
    PlaypenID: uint(frgutil.GetPlaypenID(u.hh)),
    Status:    sdk.JobStatus_JOB_STATUS_FINISHED,
    Approved:  new(true),
})
if err != nil {
    log.Fatal(err)
}

// List only unapproved runs
unapprovedRuns, err := sdkClient.ListRuns(&sdk.ListRunsOpts{
    PlaypenID: uint(frgutil.GetPlaypenID(u.hh)),
    Approved:  new(false),
})
if err != nil {
    log.Fatal(err)
}

// List all accessible runs (no filters)
allRuns, err := sdkClient.ListRuns(nil)
if err != nil {
    log.Fatal(err)
}

// List reporting runs generated for specific run IDs
// For example, if run IDs 100 and 200 each had reports generated,
// this returns those reporting runs
reportingRuns, err := sdkClient.ListRuns(&sdk.ListRunsOpts{
    ReportOnIDs: []uint{100, 200},
})
if err != nil {
    log.Fatal(err)
}

Example: Python¶

import logging

from sdk import run
from sdk import job_status_pb2

# List all runs in current playpen
runs = run.list_runs(playpen_id=self.hh.playpenID)

for r in runs:
    # Use JobStatus.Name() to get the string name of the status enum
    status_name = job_status_pb2.JobStatus.Name(r.status)
    logging.info(f"Run {r.id}: {r.name} (status={status_name}, approved={r.approved})")

# List only approved runs with "Finished" status
approved_runs = run.list_runs(
    playpen_id=self.hh.playpenID,
    status=job_status_pb2.JOB_STATUS_FINISHED,
    approved=True
)

# List only unapproved runs (new capability with optional bool)
unapproved_runs = run.list_runs(
    playpen_id=self.hh.playpenID,
    approved=False
)

# List all accessible runs (no filters)
all_runs = run.list_runs()

# List reporting runs generated for specific run IDs
# For example, if run IDs 100 and 200 each had reports generated,
# this returns those reporting runs
reporting_runs = run.list_runs(report_on_ids=[100, 200])

Study Details¶

The study that is associated with a run is embedded in the run details object. Retrieve the study object by calling the GetStudy function in Golang or by accessing the Study attribute in Python.

Example: Go¶

runID := frgutil.GetRunID(u.hh)

runDetails, err := sdkClient.GetRunDetails(runID)
if err != nil {
   log.Fatal(err)
}

// Getter functions to retrieve specific data in a run object
study := runDetails.GetStudy()

Example: Python¶

This Python example shows that the study object in a run details object is the same as the study object retrieved by the get_study function.

from sdk import run
from sdk import study

run_details = run.get_run_details(run_id)
>>> run_details.Study.name
First Study
>>> run_details.Study.id
1

>>> study.get_study(run_details.Study.id).name
First Study

Runtime Options¶

Runtime options are user-customizable options that can be set or adjusted when building or running a study. A map of typed options can be retrieved by calling the GetRunOptions function in Golang or the get_run_options function in Python.

Tip

Runtime options can be configured through playpen configuration. See the Playpen Configuration page for more details.

Configurable options are user-customizable options that can be set or adjusted when building or running a study. Configurable options come in the following forms:

Option Type	Protobuf Well-Known Type
datepicker	String
dropdown	String
slider	Double
switch	Bool
text-box	String

To retrieve a combination of run options and study options directly without accessing other run details, pass the run's unique identifier to the GetRunOptions function in Golang or the get_run_options in Python. If the same option exists in both study and run options, the value from run options takes precedence.

Example: Go¶

runID := frgutil.GetRunID(u.hh)

runOptions, err := sdkClient.GetRunOptions(runID)
if err != nil {
    log.Fatal(err)
}

log.Printf("RUN OPTIONS:")
for k, v := range runOptions {
    log.Printf("\t\t%s (%T): %v", k, v, v)
}

log.Printf("%+v", runOptions)

Example: Python¶

from sdk import run

for k, v in run.get_run_options(15).items():
    print(f"{k} ({type(v)}): {v}")

Runtime Objects¶

Configuration Groups¶

Users can configure multiple configuration groups to be selected at runtime. The configuration groups are stored in the run object and can be retrieved by calling the get_run_config_groups function in Python. The result is a map of option keys to a list of configuration group objects.

Example: Go¶

Go support for retrieving configuration groups is not available at this time.

Example: Python¶

To pull all configuration groups attached to a run:

run_id = handle.options["RunID"]

for k, v in run.get_run_config_groups(run_id).items():
   logging.info(f"{k} CONFIG_GROUPS:\n")
   logging.info("====================================")
   for c in v:
      logging.info(f"{c.meta.ConfigGroupName} (id={c.meta.ConfigGroupID}) tables:")
      for table_name, table_df in c.tables.items():
         logging.info(f"{table_name}:\n{table_df}")
      logging.info("====================================")

Example output for a run with only one runtime configuration group option and only one configuration group selected for the option:

INFO [2024-08-05 08:41:32] sample_config_groups CONFIG_GROUPS:
INFO [2024-08-05 08:41:32]
INFO [2024-08-05 08:00:00] ====================================
INFO [2024-08-05 08:00:00] Sample Config Group (id=100) tables:
INFO [2024-08-05 08:00:00] Sheet1:
INFO [2024-08-05 08:00:00]   string_column  number_column  int_column         datetime_column
INFO [2024-08-05 08:00:00] 0        abcdef      1234.5678        1234 2024-08-02 17:50:32.920
INFO [2024-08-05 08:00:00] Sheet2:
INFO [2024-08-05 08:00:00]   string_column  number_column  int_column         datetime_column
INFO [2024-08-05 08:00:00] 0       ghijklm      9876.5432        9876 2024-08-02 17:51:16.970
INFO [2024-08-05 08:00:00] ====================================

If a specific option key is desired, use the get_run_config_groups_by_option_key method as shown below. This eliminates the need to iterate over all configuration groups and filter by option key. It also is more efficient if there are a large number of configuration groups attached to the run.

run_id = handle.options["RunID"]

for c in run.get_run_config_groups_by_option_key(run_id, "sample_config_groups"):
   logging.info(f"{c.meta.ConfigGroupName} (id={c.meta.ConfigGroupID}) tables:")
   for table_name, table_df in c.tables.items():
      logging.info(f"{table_name}:\n{table_df}")
   logging.info("====================================")

Continuing on the previous example, the above code will print the following:

INFO [2024-08-05 08:00:00] ====================================
INFO [2024-08-05 08:00:00] Sample Config Group (id=100) tables:
INFO [2024-08-05 08:00:00] Sheet1:
INFO [2024-08-05 08:00:00]   string_column  number_column  int_column         datetime_column
INFO [2024-08-05 08:00:00] 0        abcdef      1234.5678        1234 2024-08-02 17:50:32.920
INFO [2024-08-05 08:00:00] Sheet2:
INFO [2024-08-05 08:00:00]   string_column  number_column  int_column         datetime_column
INFO [2024-08-05 08:00:00] 0       ghijklm      9876.5432        9876 2024-08-02 17:51:16.970
INFO [2024-08-05 08:00:00] ====================================

Filters¶

Users can configure multiple filters to be selected at runtime. The filters are stored in the run object and can be retrieved by calling the GetRunFilters function in Golang or the get_run_filters function in Python. The result is a map of option keys to a list of filter objects.

Example: Go¶

To pull all filters attached to a run:

runID := frgutil.GetRunID(u.hh)

runFilters, err := sdkClient.GetRunFilters(runID)
if err != nil {
   log.Fatal(err)
}
for k, v := range runFilters {
   log.Printf("%s FILTERS:", k)
   for _, f := range v {
      log.Printf("\t\t%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
   }
}

Example output for a run with a single set of filters:

INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31]       Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

If a specific option key is desired, use the GetRunFiltersByOptionKey method as shown below. This eliminates the need to iterate over all filters and filter by option key. It also is more efficient if there are a large number of filters attached to the run.

runID := frgutil.GetRunID(u.hh)

portfolioFilters, err := sdkClient.GetRunFiltersByOptionKey(runID, "portfolio_filters")
if err != nil {
   log.Fatal(err)
}
for _, f := range portfolioFilters {
   log.Printf("%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
}

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

If a specific filter type is desired, use the GetRunFiltersFilters method as shown below. This allows for filtering by filter type and/or option key, but it always returns a map of option keys to a list of filter objects as GetRunFilters does.

runID := frgutil.GetRunID(u.hh)

runFilters, err := sdkClient.GetRunFiltersFilters(runID, "", "PORTFOLIO")
if err != nil {
   log.Fatal(err)
}
for k, v := range runFilters {
   log.Printf("%s FILTERS:", k)
   for _, u := range v {
      log.Printf("\t\t%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
   }
}

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31]       Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

Example: Python¶

To pull all filters attached to a run:

run_id = handle.options["RunID"]

for k, v in run.get_run_filters(run_id).items():
   logging.info(f"{k} FILTERS:")
   for f in v:
      logging.info(f"\t{f.name} (type={f.type}) (id={f.id}): {f.value}")

Example output for a run with a single set of filters:

INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31]  Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

If a specific option key is desired, use the get_run_filters_by_option_key method as shown below. This eliminates the need to iterate over all filters and filter by option key. It also is more efficient if there are a large number of filters attached to the run.

run_id = handle.options["RunID"]

for f in run.get_run_filters_by_option_key(run_id, "portfolio_filters"):
    logging.info(f"{f.name} (type={f.type}) (id={f.id}): {f.value}")

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 08:41:32] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

If a specific filter type is desired, use the get_run_filters, specifying optional parameters. This allows for filtering by filter type and/or option key, but it always returns a map of option keys to a list of filter objects.

run_id = handle.options["RunID"]

for k, v in run.get_run_filters(run_id, type_filter="PORTFOLIO").items():
   logging.info(f"{k} FILTERS:")
   for f in v:
      logging.info(f"\t{f.name} (type={f.type}) (id={f.id}): {f.value}")

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31]  Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"

Uploads¶

Users can configure multiple uploads to be selected at runtime. The uploads are stored in the run object and can be retrieved by calling the GetRunUploads function in Golang or the get_run_uploads function in Python. The result is a map of option keys to a list of upload objects, which contains the contents of the upload and metadata about the upload.

Example: Go¶

To pull all uploads attached to a run:

runID := frgutil.GetRunID(u.hh)

runUploads, err := sdkClient.GetRunUploads(runID)
if err != nil {
   log.Fatal(err)
}
for k, v := range runUploads {
   log.Printf("%s UPLOADS:", k)
   for _, u := range v {
      log.Printf("\t\t%s (type=%s) (id=%d)", u.GetName(), u.GetType(), u.GetId())
   }
}

For a run with two sets of uploads, history_uploads and scenario_uploads, the above code will print something like the following:

INFO [2024-08-01 07:07:31] history_uploads UPLOADS:
INFO [2024-08-01 07:07:31]       Domestic_history.xlsx (type=ME_HISTORY) (id=2)
INFO [2024-08-01 07:07:31] scenario_uploads UPLOADS:
INFO [2024-08-01 07:07:31]       Euro Zone Severe Impact Scenario.xlsx (type=ME_SCEN) (id=1)

If a specific option key is desired, use the GetRunUploadsByOptionKey method as shown below. This eliminates the need to iterate over all uploads and filter by option key. It also is more efficient if there are a large number of uploads attached to the run.

runID := frgutil.GetRunID(u.hh)

historyUploads, err := sdkClient.GetRunUploadsByOptionKey(runID, "history_uploads")
if err != nil {
   log.Fatal(err)
}
for _, v := range historyUploads {
   log.Printf("%s (type=%s) (id=%d)", v.GetName(), v.GetType(), v.GetId())
}

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 07:07:31] Domestic_history.xlsx (type=ME_HISTORY) (id=2)

If a specific upload type is desired, use the GetRunUploadsFiltered method as shown below. This allows for filtering by upload type and/or option key, but it always returns a map of option keys to a list of upload objects as GetRunUploads does.

runID := frgutil.GetRunID(u.hh)

runUploads, err := sdkClient.GetRunUploadsFiltered(runID, "", "ME_HISTORY")
if err != nil {
   log.Fatal(err)
}
for k, v := range runUploads {
   log.Printf("%s UPLOADS:", k)
   for _, u := range v {
      log.Printf("\t\t%s (type=%s) (id=%d)", u.GetName(), u.GetType(), u.GetId())
   }
}

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 07:07:31] history_uploads UPLOADS:
INFO [2024-08-01 07:07:31]       Domestic_history.xlsx (type=ME_HISTORY) (id=2)

Example: Python¶

To pull all uploads attached to a run:

run_id = handle.options["RunID"]

for k, v in run.get_run_uploads(run_id).items():
   logging.info(f"{k} UPLOADS:")
   for u in v:
      logging.info(f"\t{u.name} (type={u.type}) (id={u.id})")

For a run with two sets of uploads, history_uploads and scenario_uploads, the above code will print something like the following:

INFO [2024-08-01 08:36:13] scenario_uploads UPLOADS:
INFO [2024-08-01 08:36:13]  Euro Zone Severe Impact Scenario.xlsx (type=ME_SCEN) (id=1)
INFO [2024-08-01 08:36:13] history_uploads UPLOADS:
INFO [2024-08-01 08:36:13]  Domestic_history.xlsx (type=ME_HISTORY) (id=2)

If a specific option key is desired, use the get_run_uploads_by_option_key method as shown below. This eliminates the need to iterate over all uploads and filter by option key. It also is more efficient if there are a large number of uploads attached to the run.

run_id = handle.options["RunID"]

for u in run.get_run_uploads_by_option_key(run_id, "history_uploads"):
    logging.info(f"{u.name} (type={u.type}) (id={u.id})")

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 08:41:32] Domestic_history.xlsx (type=ME_HISTORY) (id=2)

If a specific upload type is desired, use the get_run_uploads, specifying optional parameters. This allows for filtering by upload type and/or option key, but it always returns a map of option keys to a list of upload objects.

run_id = handle.options["RunID"]

for k, v in run.get_run_uploads(run_id, type_filter="ME_HISTORY").items():
   logging.info(f"{k} UPLOADS:")
   for u in v:
      logging.info(f"\t{u.name} (type={u.type}) (id={u.id})")

Continuing on the previous example, the above code will print the following:

INFO [2024-08-01 08:36:13] history_uploads UPLOADS:
INFO [2024-08-01 08:36:13]  Domestic_history.xlsx (type=ME_HISTORY) (id=2)

Run Object¶

Run Details¶

Example: Go¶

Example: Python¶

Listing Runs¶

Filter Options¶

JobStatus Enum¶

RunListItem Fields¶

Example: Go¶

Example: Python¶

Study Details¶

Example: Go¶

Example: Python¶

Runtime Options¶

Example: Go¶

Example: Python¶

Runtime Objects¶

Configuration Groups¶

Example: Go¶

Example: Python¶

Filters¶

Example: Go¶

Example: Python¶

Uploads¶

Example: Go¶

Example: Python¶