Scenarios#
For usage information and examples, see Scenarios
- class dataikuapi.dss.scenario.DSSScenario(client, project_key, id)#
A handle to interact with a scenario on the DSS instance.
Important
Do not instantiate directly, use
dataikuapi.dss.project.DSSProject.get_scenario()
- abort()#
Abort the scenario.
This method does nothing if the scenario is not currently running.
- run_and_wait(params=None, no_fail=False)#
Request a run of the scenario and wait the end of the run to complete.
The method requests a new run, which will start after a few seconds.
- Parameters:
params (dict) – additional parameters that will be passed to the scenario through trigger params (defaults to {})
no_fail (boolean) – if False, raises if the run doesn’t end with a SUCCESS outcome
- Returns:
a handle on the run
- Return type:
- run(params=None)#
Request a run of the scenario.
The method requests a new run, which will start after a few seconds.
Note
This method returns a trigger fire, NOT a Scenario run object. The trigger fire may ultimately result in a run or not.
Usage example:
scenario = project.get_scenario("myscenario") trigger_fire = scenario.run() # When you call `run` a scenario, the scenario is not immediately # started. Instead a "manual trigger" fires. # # This trigger fire can be cancelled if the scenario was already running, # or if another trigger fires. Thus, the scenario run is not available # immediately, and we must "wait" for it scenario_run = trigger_fire.wait_for_scenario_run() # Now the scenario is running. We can wait for it synchronously with # scenario_run.wait_for_completion(), but if we want to do other stuff # at the same time, we can use refresh while True: scenario_run.refresh() if scenario_run.running: print("Scenario is still running ...") else: print("Scenario is not running anymore") break time.sleep(5)
- Params dict params:
additional parameters that will be passed to the scenario through trigger params (defaults to {})
- Returns:
a request for a run, as a trigger fire object
- Return type:
- get_last_runs(limit=10, only_finished_runs=False)#
Get the list of the last runs of the scenario.
- Parameters:
limit (int) – maximum number of last runs to retrieve
only_finished_runs (boolean) – if True, currently running runs are not returned.
- Returns:
a list of
DSSScenarioRun
- Return type:
list
- get_runs_by_date(from_date, to_date=datetime.datetime(2024, 11, 4, 21, 10, 25, 610835))#
Get the list of the runs of the scenario in a given date range.
- Parameters:
from_date (datetime) – start of the date range to retrieve runs for, inclusive
to_date (datetime) – end of the date range to retrieve runs for, exclusive
- Returns:
a list of
DSSScenarioRun
- Return type:
list
- get_last_finished_run()#
Get the last run that completed.
The run may be successful or failed, or even aborted.
- Return type:
- get_last_successful_run()#
Get the last run that completed successfully.
- Return type:
- get_current_run()#
Get the current run of the scenario.
If the scenario is not running at the moment, returns None.
- Return type:
- get_run(run_id)#
Get a handle to a run of the scenario.
- Parameters:
run_id (string) – identifier of the run.
- Return type:
- get_status()#
Get the status of this scenario.
- Return type:
- get_settings()#
Get the settings of this scenario.
- Returns:
a
StepBasedScenarioSettings
for step-based scenarios, or aPythonScriptBasedScenarioSettings
for scenarios defined by a python script.- Return type:
- get_average_duration(limit=3)#
Get the average duration of the last runs of this scenario.
The duration is computed on successful runs only, that is, on runs that ended with SUCCESS or WARNING satus.
If there are not enough runs to perform the average, returns None
- Parameters:
limit (int) – number of last runs to average on
- Returns:
the average duration of the last runs, in seconds
- Return type:
float
- delete()#
Delete this scenario.
- get_object_discussions()#
Get a handle to manage discussions on the scenario.
- Returns:
the handle to manage discussions
- Return type:
- get_trigger_fire(trigger_id, trigger_run_id)#
Get a trigger fire object.
Caution
Advanced usages only (see
run()
)- Parameters:
trigger_id (string) – identifier of the trigger, in the scenario’s settings
trigger_run_id (string) – identifier of the run of the trigger
- Return type:
- get_definition(with_status=True)#
Get the definition of the scenario.
Attention
Deprecated, use
get_settings()
andget_status()
- Parameters:
with_status (bool) – if True, get only the run status of the scenario. If False, get the raw definition of the scenario.
- Returns:
if with_status is False, the scenario’s definition as returned by
DSSScenarioSettings.get_raw()
. If with_status is True, a summary of the scenario as returned byDSSScenarioStatus.get_raw()
- Return type:
dict
- set_definition(definition, with_status=True)#
Update the definition of this scenario.
Attention
Deprecated, use
get_settings()
andDSSScenarioSettings.save()
- Parameters:
definition (dict) – a scenario definition obtained by calling
get_definition()
, then modifiedwith_status (bool) – should be the same as the value passed to
get_definition()
. If True, the only fields that can be modified are active, checklists, description, shortDesc and tags
- get_payload(extension='py')#
Get the payload of the scenario.
Attention
Deprecated, use
get_settings()
andget_status()
- Parameters:
extension (string) – the type of script. Default is ‘py’ for python
- set_payload(script, extension='py')#
Update the payload of this scenario.
Attention
Deprecated, use
get_settings()
andDSSScenarioSettings.save()
- Parameters:
script (string) – the new value of the script
extension (string) – the type of script. Default is ‘py’ for python
- class dataikuapi.dss.scenario.DSSScenarioStatus(scenario, data)#
Status of a scenario.
Important
Do not instantiate directly, use
DSSScenario.get_status()
- get_raw()#
Get the raw status data.
- Returns:
the status, as a dict. Notable fields are:
active : whether the scenario runs its automatic triggers
running : whether the scenario is currently running
start : if the scenario is running, the timestamp of the beginning of the run
- Return type:
dict
- property running#
Whether the scenario is currently running
- Return type:
boolean
- property next_run#
Time at which the scenario is expected to run next.
This expected time is computed based on the only triggers for which forecasts are possible, that is, the active time-based triggers. May be None if there is no such trigger.
This is an approximate indication as scenario run may be delayed, especially in the case of multiple triggers or high load.
- Return type:
datetime.datetime
- class dataikuapi.dss.scenario.DSSScenarioSettings(client, scenario, data)#
Settings of a scenario.
Important
Do not instantiate directly, use
DSSScenario.get_settings()
- get_raw()#
Get the raw definition of the scenario.
This method returns a reference to the settings, not a copy. Modifying the settings then calling
save()
saves the changes made.- Returns:
the scenario, as a dict. The type-specific parameters of the scenario are in a params sub-dict. For step-based scenarios, the params will contain the definitions of the steps as a steps list of dict.
- Return type:
dict
- property active#
Whether this scenario is currently active, i.e. its auto-triggers are executing.
- Return type:
boolean
- property run_as#
Get the login of the user the scenario runs as.
None means that the scenario runs as the last user who modified the scenario. Only administrators may set a non-None value.
- Return type:
string
- property effective_run_as#
Get the effective ‘run as’ of the scenario.
If the value returned by
run_as()
is not None, then that value. Otherwise, this will be the login of the last user who modified the scenario.Note
If this method returns None, it means that it was not possible to identify who this scenario should run as. This scenario is probably not currently functioning.
- Return type:
string
- property raw_triggers#
Get the list of automatic triggers.
This method returns a reference to the settings, not a copy. Modifying the settings then calling
save()
saves the changes made.- Returns:
list of the automatic triggers, each one a dict. An active boolean field indicates whether the trigger is running automatically.
- Return type:
list[dict]
- property raw_reporters#
Get the list of reporters.
This method returns a reference to the settings, not a copy. Modifying the settings then calling
save()
saves the changes made.- Returns:
list of reporters on the scenario, each one a dict.
- Return type:
list[dict]
- add_periodic_trigger(every_minutes=5)#
Add a trigger that runs the scenario every X minutes.
- Parameters:
every_minutes (int) – interval between activations of the trigger, in minutes
- add_hourly_trigger(minute_of_hour=0, year=None, month=None, day=None, starting_hour=0, repeat_every=1, timezone='SERVER')#
Add a trigger that runs the scenario every X hours.
- Parameters:
repeat_every (int) – interval between activations of the trigger, in hours
minute_of_hour (int) – minute in the hour when the trigger should run
year (int) – year part of the date/time before which the trigger won’t run
month (int) – month part of the date/time before which the trigger won’t run
day (int) – day part of the date/time before which the trigger won’t run
starting_hour (int) – hour part of the date/time before which the trigger won’t run
timezone (string) – timezone in which the start date/time is expressed. Can be a time zone name like “Europe/Paris” or “SERVER” for the time zone of the DSS server
- add_daily_trigger(hour=2, minute=0, days=None, year=None, month=None, day=None, repeat_every=1, timezone='SERVER')#
Add a trigger that runs the scenario every X days.
- Parameters:
repeat_every (int) – interval between activations of the trigger, in days
days (list) – if None, the trigger runs every repeat_every other day. If set to a list of day names, the trigger runs every repeat_every other week, on the designated days. The day names are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
hour (int) – hour in the day when the trigger should run
minute (int) – minute in the hour when the trigger should run
year (int) – year part of the date/time before which the trigger won’t run
month (int) – month part of the date/time before which the trigger won’t run
day (int) – day part of the date/time before which the trigger won’t run
timezone (string) – timezone in which the start date/time is expressed. Can be a time zone name like “Europe/Paris” or “SERVER” for the time zone of the DSS server
- add_monthly_trigger(day=1, hour=2, minute=0, year=None, month=None, run_on='ON_THE_DAY', repeat_every=1, timezone='SERVER')#
Add a trigger that runs the scenario every X months.
- Parameters:
repeat_every (int) – interval between activations of the trigger, in months
day (int) – day in the day when the trigger should run, when run_on is ON_THE_DAY or None
hour (int) – hour in the day when the trigger should run, when run_on is ON_THE_DAY or None
minute (int) – minute in the hour when the trigger should run, when run_on is ON_THE_DAY or None
minute_of_hour (int) – position in the hour of the firing of the trigger
year (int) – year part of the date/time before which the trigger won’t run
month (int) – month part of the date/time before which the trigger won’t run
timezone (string) – timezone in which the start date/time is expressed. Can be a time zone name like “Europe/Paris” or “SERVER” for the time zone of the DSS server
- Parma string run_on:
when in the month the trigger should run. Possible values are ON_THE_DAY, LAST_DAY_OF_THE_MONTH, FIRST_WEEK, SECOND_WEEK, THIRD_WEEK, FOURTH_WEEK, LAST_WEEK.
- save()#
Saves the settings to the scenario
- class dataikuapi.dss.scenario.StepBasedScenarioSettings(client, scenario, data)#
Settings of a step-based scenario.
Important
Do not instantiate directly, use
DSSScenario.get_settings()
.- property raw_steps#
Returns raw definition of steps.
This method returns a reference to the settings, not a copy. Modifying the settings then calling
save()
saves the changes made.- Returns:
a list of scenario steps, each one a dict. Notable fields are:
id : identifier of the step (unique in the scenario)
name : label of the step
type : type of the step. There are many types, commonly used ones are build_flowitem, custom_python or exec_sql
params : type-specific parameters for the step, as a dict
- Return type:
list[dict]
- class dataikuapi.dss.scenario.PythonScriptBasedScenarioSettings(client, scenario, data, script)#
Settings of a scenario defined by a Python script.
Important
Do not instantiate directly, use
DSSScenario.get_settings()
.- property code#
Get the Python script of the scenario
- Return type:
string
- save()#
Saves the settings to the scenario.
- class dataikuapi.dss.scenario.DSSScenarioRun(client, run)#
A handle containing basic info about a past run of a scenario.
Important
Do not instantiate directly, use
DSSScenario.get_run()
,DSSScenario.get_current_run()
orDSSScenario.get_last_runs()
This handle can also be used to fetch additional information about the run.
- property id#
Get the identifier of this run.
- Return type:
string
- refresh()#
Refresh the details of the run.
For ongoing scenario runs, this updates the set of outcomes of the steps and their results.
Note
This method performs another API call
- wait_for_completion(no_fail=False)#
Wait for the scenario run to complete.
If the scenario run is already finished, this method returns immediately.
- Parameters:
no_fail (boolean) – if False, raises an exception if scenario fails
- property running#
Whether this scenario run is currently running.
- Return type:
boolean
- property outcome#
The outcome of this scenario run, if available.
- Returns:
one of SUCCESS, WARNING, FAILED, or ABORTED
- Return type:
string
- property trigger#
Get the trigger that triggered this scenario run.
- Returns:
the definition of a trigger, as in the
DSSScenarioSettings.raw_triggers()
list- Return type:
dict
- get_info()#
Get the raw information of the scenario run.
- Returns:
the scenario run, as a dict. The identifier of the run is a runId field. If the scenario run is finished, the detailed outcome of the run is a result sub-dict, with notably an outcome field (SUCCESS, WARNING, FAILED, or ABORTED)
- Return type:
dict
- get_details()#
Get the full details of the scenario run.
This includes notably the individual step runs inside the scenario run.
Note
This method performs another API call
- Returns:
full details on a scenario run, as a dict with fields:
scenarioRun : the run definition and base status, as a dict (see
get_info()
)stepRuns : details about each step that has executed so far, as a list of dicts (see
DSSScenarioRunDetails.steps()
)
- Return type:
dict
- get_start_time()#
Get the start time of the scenario run.
- Return type:
datetime.datetime
- property start_time#
Get the start time of the scenario run.
- Return type:
datetime.datetime
- get_end_time()#
Get the end time of the scenario run, if it completed, else raises.
- Return type:
datetime.datetime
- property end_time#
Get the end time of the scenario run, if it completed, else raises.
- Return type:
datetime.datetime
- get_duration()#
Get the duration of this run (in fractional seconds).
If the run is still running, get the duration since it started.
- Return type:
float
- property duration#
Get the duration of this run (in fractional seconds).
If the run is still running, get the duration since it started.
- Return type:
float
- class dataikuapi.dss.scenario.DSSScenarioRunDetails(data)#
Details of a scenario run, notably the outcome of its steps.
Important
Do not instantiate directly, see
DSSScenarioRun.get_details()
- property steps#
Get the list of runs of the steps.
Only completed or ongoing steps are included.
Note
When the instance of
DSSScenarioRunDetails
was obtained viaDSSScenarioRun.get_details()
, then the returned list is made of instances ofDSSStepRunDetails
.- Returns:
a list of step runs, each as a dict. The runId in the dict is the identifier of the step run, not of the overall scenario run. A result sub-dict contains the outcome of the step.
- Return type:
list[dict]
- property last_step#
Get the last step run.
- Returns:
a step run, as a dict. See
steps()
.- Return type:
dict
- property first_error_details#
Get the details of the first error if this run failed.
This will not always be able to find the error details (it returns None in that case)
- Returns:
a serialized exception, as in
DSSStepRunDetails.first_error_details()
- Return type:
dict
- class dataikuapi.dss.scenario.DSSStepRunDetails(data)#
Details of a run of a step in a scenario run.
Important
Do not instantiate directly, see
DSSScenarioRunDetails.steps()
on an instance ofDSSScenarioRunDetails
obtained viaDSSScenarioRun.get_details()
- property outcome#
Get the outcome of the step run/
- Returns:
one of SUCCESS, WARNING, FAILED, or ABORTED
- Return type:
string
- property job_ids#
Get the list of DSS job ids that were run as part of this step.
- Returns:
a list of job ids, each one a string
- Return type:
list[string]
- property first_error_details#
Try to get the details of the first error if this step failed. This will not always be able to find the error details (it returns None in that case)
- Returns:
a serialized exception, as a with fields:
clazz : class name of the exception
title : short message of the exception
message : message of the exception
stack : stacktrace of the exception, as a single string
code : well-known error code, as listed in the doc
fixability : type of action to take in order to remediate the issue, if possible. For example USER_CONFIG_DATASET, ADMIN_SETTINGS_SECURITY, …
- Return type:
dict
- class dataikuapi.dss.scenario.DSSScenarioRunWaiter(scenario_run, trigger_fire)#
Helper to wait for a scenario to run to complete.
- wait(no_fail=False)#
Wait for the scenario run completion.
- Parameters:
no_fail (boolean) – if False, raises if the run doesn’t end with a SUCCESS outcome
- Returns:
the final state of the scenario run (see
DSSScenarioRun.get_info()
)- Return type:
dict
- class dataikuapi.dss.scenario.DSSTriggerFire(scenario, trigger_fire)#
A handle representing the firing of a trigger on a scenario.
Important
Do not instantiate directly, use
DSSScenario.run()
- get_raw()#
Get the definition of the trigger fire event.
- Returns:
the trigger fire, as a dict. The runId field in the dict is not an identifier of a scenario run, but of a run of the trigger.
- Return type:
dict
- wait_for_scenario_run(no_fail=False)#
Poll for the run of the scenario that the trigger fire should initiate.
This methos waits for the run of the sceanrio that this trigger activation launched to be available, or for the trigger fire to be cancelled (possibly cancelled by another trigger firing).
- Parameters:
no_fail (boolean) – if True, return None if the trigger fire is cancelled, else raise
- Returns:
a handle on a scenario run, or None
- Return type:
- get_scenario_run()#
Get the run of the scenario that this trigger fire launched.
May return None if the scenario run started from this trigger has not yet been created.
- Returns:
a handle on a scenario run, or None
- Return type:
- is_cancelled(refresh=False)#
Whether the trigger fire has been cancelled
- Parameters:
refresh – get the state of the trigger from the backend
- class dataikuapi.dss.scenario.DSSScenarioListItem(client, data)#
An item in a list of scenarios.
Important
Do not instantiate directly, use
dataikuapi.dss.project.DSSProject.list_scenarios()
- to_scenario()#
Get a handle corresponding to this scenario.
- Return type:
- property id#
Get the identifier of the scenario.
- Return type:
string
- property running#
Whether the scenario is currently running.
- Return type:
boolean
- property start_time#
Get the start time of the scenario run.
- Returns:
timestap of the scenario run start, or None if it’s not running at the moment.
- Return type:
datetime.datetime