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:

DSSScenarioRun

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:: DSSTriggerFire

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, 4, 15, 12, 3, 41, 690854))#

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:: DSSScenarioRun

get_last_successful_run()#

Get the last run that completed successfully.

Return type:: DSSScenarioRun

get_current_run()#

Get the current run of the scenario.

If the scenario is not running at the moment, returns None.

Return type:: DSSScenarioRun

get_run(run_id)#

Get a handle to a run of the scenario.

Parameters:: run_id (string) – identifier of the run.
Return type:: DSSScenarioRun

get_status()#

Get the status of this scenario.

Return type:: DSSScenarioStatus

get_settings()#

Get the settings of this scenario.

Returns:: a StepBasedScenarioSettings for step-based scenarios, or a PythonScriptBasedScenarioSettings for scenarios defined by a python script.
Return type:: DSSScenarioSettings

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:: dataikuapi.dss.discussion.DSSObjectDiscussions

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:

DSSTriggerFire

get_definition(with_status=True)#

Get the definition of the scenario.

Attention

Deprecated, use get_settings() and get_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 by DSSScenarioStatus.get_raw()
Return type:: dict

set_definition(definition, with_status=True)#

Update the definition of this scenario.

Attention

Deprecated, use get_settings() and DSSScenarioSettings.save()

Parameters:

definition (dict) – a scenario definition obtained by calling get_definition(), then modified
with_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() and get_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() and DSSScenarioSettings.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() or DSSScenario.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 via DSSScenarioRun.get_details(), then the returned list is made of instances of DSSStepRunDetails.

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 of DSSScenarioRunDetails obtained via DSSScenarioRun.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:: DSSScenarioRun

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:: DSSScenarioRun

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:: DSSScenario

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