Python API¶

`botcity.maestro.sdk.BotMaestroSDK` ¶

`access_token` `property` `writable` ¶

The access token

`organization` `property` `writable` ¶

The organization label

`server` `property` `writable` ¶

The server address

`task_id` `property` `writable` ¶

The Current Task ID

`version` `property` `readonly` ¶

The BotCity Maestro Backend version

`init(self, server=None, login=None, key=None)` `special` ¶

Main class to interact with the BotMaestro web portal.

This class offers methods to send alerts, messages, create log entries, post artifacts and more.

Parameters:

Name	Type	Description	Default
`server`	`Optional[str]`	The server IP or name	`None`
`login`	`Optional[str]`	The username provided via server configuration. Available under `Dev. Environment`	`None`
`key`	`Optional[str]`	The access key provided via server configuration. Available under `Dev. Environment`	`None`

Attributes:

Name	Type	Description
`access_token`	`str`	The access token obtained via login.

`alert(self, task_id, title, message, alert_type)` ¶

Register an alert message on the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`task_id`	`str`	The activity label	required
`title`	`str`	A title associated with the alert message	required
`message`	`str`	The alert message	required
`alert_type`	`AlertType`	The alert type to be used. See AlertType	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`create_credential(self, label, key, value)` ¶

Create credential

Parameters:

Name	Type	Description	Default
`label`	`str`	Credential set name	required
`key`	`str`	Key name within the credential set	required
`value`		Credential value	required

`create_datapool(self, pool)` ¶

Create a new datapool on the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`pool`		The DataPool DataPool instance.	required

Returns:

Type	Description
`DataPool`	DataPool instance. See [DataPool][ [DataPool][botcity.maestro.datapool.DataPool] instance.

`create_task(self, activity_label, parameters, test=False, priority=0, min_execution_date=None)` ¶

Creates a task to be executed on the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`activity_label`	`str`	The activity unique identified.	required
`parameters`	`Dict[str, object]`	Dictionary with parameters and values for this task.	required
`test`	`bool`	Whether or not the task is a test.	`False`
`priority`	`int`	(Optional[int], optional) An integer from 0 to 10 to refer to execution priority.	`0`
`min_execution_date`	`Optional[datetime.datetime]`	Minimum execution date for the task.	`None`

Returns:

Type	Description
`AutomationTask`	Automation Task. See AutomationTask

`delete_log(self, activity_label)` ¶

Fetch log information.

Parameters:

Name	Type	Description	Default
`activity_label`	`str`	The activity unique identifier.	required

Returns:

Type	Description
`ServerMessage`	Log entry list. Each element in the list is a dictionary in which keys are Column names and values are the column value.

`error(self, task_id, exception, screenshot=None, attachments=None, tags=None)` ¶

Create a new Error entry.

Parameters:

Name	Type	Description	Default
`task_id`	`int`	The task unique identifier.	required
`exception`	`Exception`	The exception object.	required
`screenshot`	`Optional[str]`	File path for a screenshot to be attached to the error. Defaults to None.	`None`
`attachments`	`Optional[List[str]]`	Additional files to be sent along with the error entry. Defaults to None.	`None`
`tags`	`Optional[Dict[str, str]]`	Dictionary with tags to be associated with the error entry. Defaults to None.	`None`

Exceptions:

Type	Description
`ValueError`	If the request fails, a ValueError exception is raised.

`finish_task(self, task_id, status, message='', total_items=None, processed_items=None, failed_items=None)` ¶

Finishes a given task.

Parameters:

Name	Type	Description	Default
`task_id`	`str`	The task unique identifier.	required
`status`	`AutomationTaskFinishStatus`	The condition in which the task must be finished. See AutomationTaskFinishStatus	required
`message`	`str`	A message to be associated with this action.	`''`
`total_items`	`int`	Total number of items processed by the task.	`None`
`processed_items`	`int`	Number items processed successfully by the task.	`None`
`failed_items`	`int`	Number items failed to be processed by the task.	`None`

Note

Starting from version 0.5.0, the parameters total_items, processed_items and failed_items are available to be used. It is important to report the correct values for these parameters as they are used to calculate the ROI, success rate and other metrics.

Keep in mind that the sum of processed_items and failed_items must be equal to total_items. If total_items is None, then the sum of processed_items and failed_items will be used as total_items. If you inform total_items and processed_items, then failed_items will be calculated as the difference.

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`get_artifact(self, artifact_id)` ¶

Retrieve an artifact from the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`artifact_id`	`int`	The artifact unique identifier.	required

Returns:

Type	Description
`Tuple[str, bytes]`	Tuple containing the artifact name and an array of bytes which are the binary content of the artifact.

`get_credential(self, label, key)` ¶

Get value in key inside credentials

Parameters:

Name	Type	Description	Default
`label`	`str`	Credential set name	required
`key`	`str`	Key name within the credential set	required

Returns:

Type	Description
`str`	Key value that was requested

`get_datapool(self, label)` ¶

Get datapool on the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`label`	`str`	Label DataPool.	required

Returns:

Type	Description
`DataPool`	DataPool instance. See [DataPool][ [DataPool][botcity.maestro.datapool.DataPool] instance.

`get_execution(self, task_id=None)` ¶

Fetch the BotExecution object for a given task.

Parameters:

Name	Type	Description	Default
`task_id`	`Optional[str]`	The task ID. Defaults to None.	`None`

Returns:

Type	Description
`model.BotExecution`	The BotExecution information.

`get_log(self, activity_label, date='')` ¶

Fetch log information.

Parameters:

Name	Type	Description	Default
`activity_label`	`str`	The activity unique identifier.	required
`date`	`Optional[str]`	Initial date for log information in the format DD/MM/YYYY. If empty all information is retrieved.	`''`

Returns:

Type	Description
`List[Dict[str, object]]`	Log entry list. Each element in the list is a dictionary in which keys are Column names and values are the column value.

`get_task(self, task_id)` ¶

Return details about a given task.

Parameters:

Name	Type	Description	Default
`task_id`	`str`	The task unique identifier.	required

Returns:

Type	Description
`AutomationTask`	Automation Task. See AutomationTask

`interrupt_task(self, task_id)` ¶

Request the interruption of a given task.

Parameters:

Name	Type	Description	Default
`task_id`	`str`	The task unique identifier.	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`list_artifacts(self, days=7)` ¶

List all artifacts available for the organization.

Returns:

Type	Description
`List[botcity.maestro.model.Artifact]`	List of artifacts. See Artifact

`login(self, server=None, login=None, key=None)` ¶

Obtain an access token with the configured BotMaestro portal.

Arguments are optional and can be used to configure or overwrite the object instantiation values.

Parameters:

Name	Type	Description	Default
`server`	`Optional[str]`	The server IP or name	`None`
`login`	`Optional[str]`	The username provided via server configuration. Available under `Dev. Environment`	`None`
`key`	`Optional[str]`	The access key provided via server configuration. Available under `Dev. Environment`	`None`

`logoff(self)` ¶

Revoke the access token used to communicate with the BotMaestro portal.

`message(self, email, users, subject, body, msg_type, group=None)` ¶

Send an email message to the list of email and users given.

Parameters:

Name	Type	Description	Default
`email`	`List[str]`	List of emails to receive the message.	required
`users`	`List[str]`	List of usernames registered on the BotMaestro portal to receive the message.	required
`subject`	`str`	The message subject.	required
`body`	`str`	The message body.	required
`msg_type`	`MessageType`	The message body type. See MessageType	required
`group`	`Optional[str]`	The message group information.	`None`

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`new_log(self, activity_label, columns)` ¶

Create a new log on the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`activity_label`	`str`	The activity unique identifier.	required
`columns`	`List[botcity.maestro.model.Column]`	A list of Columns	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`new_log_entry(self, activity_label, values)` ¶

Creates a new log entry.

Parameters:

Name	Type	Description	Default
`activity_label`	`str`	The activity unique identifier.	required
`values`	`Dict[str, object]`	Dictionary in which the key is the column label and value is the entry value.	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`post_artifact(self, task_id, artifact_name, filepath)` ¶

Upload a new artifact into the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`task_id`	`int`	The task unique identifier.	required
`artifact_name`	`str`	The name of the artifact to be displayed on the portal.	required
`filepath`	`str`	The file to be uploaded.	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`restart_task(self, task_id)` ¶

Restarts a given task.

Parameters:

Name	Type	Description	Default
`task_id`	`str`	The task unique identifier.	required

Returns:

Type	Description
`ServerMessage`	Server response message. See ServerMessage

`botcity.maestro.model.AlertType (str, Enum)` ¶

Type of alerts to be emitted.

Attributes:

Name	Type	Description
`INFO`	`str`	Information alert type
`WARN`	`str`	Warning alert type
`ERROR`	`str`	Error alert type

`botcity.maestro.model.MessageType (str, Enum)` ¶

Type of message body.

Attributes:

Name	Type	Description
`TEXT`	`str`	Plain text message body
`HTML`	`str`	HTML message body

`botcity.maestro.model.AutomationTaskState (str, Enum)` ¶

State of a Task.

Attributes:

Name	Type	Description
`START`	`str`	The task was started.
`RUNNING`	`str`	The task is running.
`FINISHED`	`str`	The task is finished.
`CANCELED`	`str`	The task was canceled.

`botcity.maestro.model.AutomationTaskFinishStatus (str, Enum)` ¶

Finish status of a task.

Attributes:

Name	Type	Description
`SUCCESS`	`str`	The task finished successfully.
`FAILED`	`str`	The task failed to finish.
`PARTIALLY_COMPLETED`	`str`	The task completed part of the expected steps.

`botcity.maestro.model.ServerMessageType (str, Enum)` ¶

The server message type.

Attributes:

Name	Type	Description
`SUCCESS`	`str`	Success message
`ERROR`	`str`	Error message

`botcity.maestro.model.ServerMessage` `dataclass` ¶

Server response message.

Attributes:

Name	Type	Description
`message`	`str`	The response message sent by the BotMaestro portal.
`type`	`ServerMessageType`	The message type. See ServerMessageType
`payload`	`str`

`from_json(payload)` `staticmethod` ¶

Instantiate a ServerMessage object from a JSON payload obtained from the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`payload`	`str`	A JSON string containing message and type.	required

Returns:

Type	Description
`ServerMessage`	Server response message instance.

`to_json(self)` ¶

Returns:

Type	Description
`str`	JSON string representation of this object.

`botcity.maestro.model.AutomationTask` `dataclass` ¶

Automation Task.

Attributes:

Name	Type	Description
`id`	`int`	The task unique identifier.
`state`	`AutomationTaskState`	The task state. See AutomationTaskState.
`parameters`	`Dict[str, object]`	Dictionary with parameters and values for this task.
`input_file`	`Artifact`	The input file for this task.
`activity_id`		Identifier of the automation. (Deprecated)
`activity_label`	`str`	Automation label identifier.
`agent_id`	`int`	Identifier of the agent which created the task.
`user_creation_id`		Identifier of the user which created the task.
`user_creation_name`	`str`	Name of the user which created the task.
`org_creation_id`		Identifier of the organization which created the task.
`date_creation`	`str`	Datetime information of when this task was created.
`date_last_modified`	`str`	Datetime information of when this task was last modified.
`finish_status`	`AutomationTaskFinishStatus`	The finish status of this task. See AutomationTaskFinishStatus.
`finish_message`	`str`	The finish message of this task.
`test`	`bool`	Whether or not this task was a test.
`interrupted`	`bool`	Whether or not this task received an interrupt request.
`killed`	`bool`	Whether or not this task received a termination request.
`machine_id`	`str`	Identifier of the machine that performed the automation.

`from_json(payload)` `staticmethod` ¶

Instantiate a AutomationTask object from a JSON payload obtained from the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`payload`	`str`	A JSON string containing the required metadata.	required

Returns:

Type	Description
`AutomationTask`	Automation Task instance.

`is_interrupted(self)` ¶

Whether or not this task received an interrupt request.

Returns:

Type	Description
`bool`	Whether or not this task received an interrupt request.

`to_json(self)` ¶

Returns:

Type	Description
`str`	JSON string representation of this object.

`botcity.maestro.model.Artifact` `dataclass` ¶

Artifact.

Attributes:

Name	Type	Description
`id`	`int`	The task unique identifier.
`type`	`str`	The type of artifact.
`task_id`	`int`	The task unique identifier.
`name`	`str`	Display name for artifact.
`filename`	`str`	File name as provided during upload.
`storage_filename`	`str`	Internal file name.
`storage_filepath`	`str`	Internal absolute path to file.
`organization`	`int`	The organization unique identifier.
`user`	`Optional[int]`	The user unique identifier.
`date_creation`	`str`	Datetime information of when this artifact was created.

`from_dict(data)` `staticmethod` ¶

Instantiate a Artifact object from a dict payload obtained from the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	A dictionary containing the required metadata.	required

Returns:

Type	Description
`Artifact`	Artifact instance.

`from_json(payload)` `staticmethod` ¶

Instantiate a Artifact object from a JSON payload obtained from the BotMaestro portal.

Parameters:

Name	Type	Description	Default
`payload`	`str`	A JSON string containing the required metadata.	required

Returns:

Type	Description
`Artifact`	Artifact instance.

`to_json(self)` ¶

Returns:

Type	Description
`str`	JSON string representation of this object.

`botcity.maestro.model.Column` `dataclass` ¶

Representation of a Log column.

Attributes:

Name	Type	Description
`name`	`str`	The column display name.
`label`	`str`	The column unique identifier.
`width`	`int`	The suggested log column width when rendering it on the BotMaestro portal.

`botcity.maestro.model.BotExecution` `dataclass` ¶

Bot execution parameters.

Attributes:

Name	Type	Description
`server`	`str`	The BotMaestro server hostname or IP.
`task_id`	`str`	The task unique identifier.
`token`	`str`	The access token to be used when communicating with the BotMaestro server.
`parameters`	`Dict[str, object]`	Dictionary with parameters and values for this task.

`botcity.maestro.datapool.datapool.DataPool` `dataclass` ¶

DataPool(label: str, default_automation: str, consumption_policy: str = , trigger: str = , schema: list = None, auto_retry: bool = True, max_auto_retry: int = 0, abort_on_error: bool = True, max_errors_before_inactive: int = 0, item_max_processing_time: int = 0, datapool_id: str = None, maestro: 'BotMaestroSDK' = None, active: bool = True)

`activate(self)` ¶

Enables the DataPool in Maestro. Returns: None

`create_entry(self, entry)` ¶

Create an entry by DataPool

Parameters:

Name	Type	Description	Default
`entry`	`DataPoolEntry`	Instance of DataPoolEntry	required

Returns:

Type	Description
`DataPoolEntry`	the entry that was created.

`deactivate(self)` ¶

Disable DataPool in Maestro. Returns: None

`from_json(payload, maestro)` `staticmethod` ¶

Instantiate class by payload to request maestro.

Parameters:

Name	Type	Description	Default
`payload`	`bytes`	Response to maestro.	required
`maestro`	`BotMaestroSDK`	Instance maestro class.	required

Returns:

Type	Description
`DataPool`	Datapool instance. See [DataPool][ [DataPool][botcity.maestro.datapool.DataPool].

`get_entry(self, entry_id)` ¶

Fetch an entry from the DataPool by its ID.

Parameters:

Name	Type	Description	Default
`entry_id`	`str`	The ID of the entry to fetch.	required

Returns:

Type	Description
`DataPoolEntry`	The entry that was fetched.

`has_next(self)` ¶

Checks if there are pending items in the DataPool.

Returns:

Type	Description
`bool`	True if there are pending items, False otherwise.

`is_active(self)` ¶

Check if the DataPool is active. Returns: bool

`is_empty(self)` ¶

Checks if the DataPool is empty.

Returns:

Type	Description
`bool`	True if the DataPool is empty, False otherwise.

`next(self, task_id)` ¶

Fetch the next pending entry.

Parameters:

Name	Type	Description	Default
`task_id`	`Optional[str]`	TaskId to be associated with this entry.	required

Returns:

Type	Description
`DataPoolEntry or None`	The next pending entry, or None if there are no pending entries.

`summary(self)` ¶

Get the DataPool counters. Returns: dict

`to_dict(self)` ¶

Get all properties class in dict.

Returns: dict

`botcity.maestro.datapool.entry.DataPoolEntry` `dataclass` ¶

DataPoolEntry(priority: int = 0, values: dict = , datapool_label: str = None, state: str = None, entry_id: str = None, task_id: int = None, parent: str = None, child: str = None, date_register: str = None, date_processing: str = None, date_finished: str = None, maestro: 'BotMaestroSDK' = None)

`get_value(self, key, default=None)` ¶

Get value by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	Key to get value.	required
`default`	`Optional[str]`	Default value if key not exists.	`None`

Returns: str

`json_to_update(self)` ¶

Create Json by properties to update.

Returns: str

`report_done(self)` ¶

Report state DONE to DataPool Entry. Returns: None

`report_error(self)` ¶

Report state ERROR to DataPool Entry. Returns: None

`save(self)` ¶

Update Entry in DataPool.

Returns: dict

`to_json(self)` ¶

Get properties class in dict.

Returns: str

`update_from_json(self, payload)` ¶

Update properties by response endpoint Maestro.

Parameters:

Name	Type	Description	Default
`payload`	`bytes`	Response to endpoint Maestro.	required

Returns: DataPoolEntry

Python API¶

botcity.maestro.sdk.BotMaestroSDK ¶

access_token property writable ¶

organization property writable ¶

server property writable ¶

task_id property writable ¶

version property readonly ¶

__init__(self, server=None, login=None, key=None) special ¶

alert(self, task_id, title, message, alert_type) ¶

create_credential(self, label, key, value) ¶

create_datapool(self, pool) ¶

create_task(self, activity_label, parameters, test=False, priority=0, min_execution_date=None) ¶

delete_log(self, activity_label) ¶

error(self, task_id, exception, screenshot=None, attachments=None, tags=None) ¶

finish_task(self, task_id, status, message='', total_items=None, processed_items=None, failed_items=None) ¶

get_artifact(self, artifact_id) ¶

get_credential(self, label, key) ¶

get_datapool(self, label) ¶

get_execution(self, task_id=None) ¶

get_log(self, activity_label, date='') ¶

get_task(self, task_id) ¶

interrupt_task(self, task_id) ¶

list_artifacts(self, days=7) ¶

login(self, server=None, login=None, key=None) ¶

logoff(self) ¶

message(self, email, users, subject, body, msg_type, group=None) ¶

new_log(self, activity_label, columns) ¶

new_log_entry(self, activity_label, values) ¶

post_artifact(self, task_id, artifact_name, filepath) ¶

restart_task(self, task_id) ¶

botcity.maestro.model.AlertType (str, Enum) ¶

botcity.maestro.model.MessageType (str, Enum) ¶

botcity.maestro.model.AutomationTaskState (str, Enum) ¶

botcity.maestro.model.AutomationTaskFinishStatus (str, Enum) ¶

botcity.maestro.model.ServerMessageType (str, Enum) ¶

botcity.maestro.model.ServerMessage dataclass ¶

from_json(payload) staticmethod ¶

to_json(self) ¶

botcity.maestro.model.AutomationTask dataclass ¶

from_json(payload) staticmethod ¶

is_interrupted(self) ¶

to_json(self) ¶

botcity.maestro.model.Artifact dataclass ¶

from_dict(data) staticmethod ¶

from_json(payload) staticmethod ¶

to_json(self) ¶

botcity.maestro.model.Column dataclass ¶

botcity.maestro.model.BotExecution dataclass ¶

botcity.maestro.datapool.datapool.DataPool dataclass ¶

activate(self) ¶

create_entry(self, entry) ¶

deactivate(self) ¶

from_json(payload, maestro) staticmethod ¶

get_entry(self, entry_id) ¶

has_next(self) ¶

is_active(self) ¶

is_empty(self) ¶

next(self, task_id) ¶

summary(self) ¶

to_dict(self) ¶

botcity.maestro.datapool.entry.DataPoolEntry dataclass ¶

get_value(self, key, default=None) ¶

json_to_update(self) ¶

report_done(self) ¶

report_error(self) ¶

save(self) ¶

to_json(self) ¶

update_from_json(self, payload) ¶

`botcity.maestro.sdk.BotMaestroSDK` ¶

`access_token` `property` `writable` ¶

`organization` `property` `writable` ¶

`server` `property` `writable` ¶

`task_id` `property` `writable` ¶

`version` `property` `readonly` ¶

`init(self, server=None, login=None, key=None)` `special` ¶

`alert(self, task_id, title, message, alert_type)` ¶

`create_credential(self, label, key, value)` ¶

`create_datapool(self, pool)` ¶

`create_task(self, activity_label, parameters, test=False, priority=0, min_execution_date=None)` ¶

`delete_log(self, activity_label)` ¶

`error(self, task_id, exception, screenshot=None, attachments=None, tags=None)` ¶

`finish_task(self, task_id, status, message='', total_items=None, processed_items=None, failed_items=None)` ¶

`get_artifact(self, artifact_id)` ¶

`get_credential(self, label, key)` ¶

`get_datapool(self, label)` ¶

`get_execution(self, task_id=None)` ¶

`get_log(self, activity_label, date='')` ¶

`get_task(self, task_id)` ¶

`interrupt_task(self, task_id)` ¶

`list_artifacts(self, days=7)` ¶

`login(self, server=None, login=None, key=None)` ¶

`logoff(self)` ¶

`message(self, email, users, subject, body, msg_type, group=None)` ¶

`new_log(self, activity_label, columns)` ¶

`new_log_entry(self, activity_label, values)` ¶

`post_artifact(self, task_id, artifact_name, filepath)` ¶

`restart_task(self, task_id)` ¶

`botcity.maestro.model.AlertType (str, Enum)` ¶

`botcity.maestro.model.MessageType (str, Enum)` ¶

`botcity.maestro.model.AutomationTaskState (str, Enum)` ¶

`botcity.maestro.model.AutomationTaskFinishStatus (str, Enum)` ¶

`botcity.maestro.model.ServerMessageType (str, Enum)` ¶

`botcity.maestro.model.ServerMessage` `dataclass` ¶

`from_json(payload)` `staticmethod` ¶

`to_json(self)` ¶

`botcity.maestro.model.AutomationTask` `dataclass` ¶

`from_json(payload)` `staticmethod` ¶

`is_interrupted(self)` ¶

`to_json(self)` ¶

`botcity.maestro.model.Artifact` `dataclass` ¶

`from_dict(data)` `staticmethod` ¶

`from_json(payload)` `staticmethod` ¶

`to_json(self)` ¶

`botcity.maestro.model.Column` `dataclass` ¶

`botcity.maestro.model.BotExecution` `dataclass` ¶

`botcity.maestro.datapool.datapool.DataPool` `dataclass` ¶

`activate(self)` ¶

`create_entry(self, entry)` ¶

`deactivate(self)` ¶

`from_json(payload, maestro)` `staticmethod` ¶

`get_entry(self, entry_id)` ¶

`has_next(self)` ¶

`is_active(self)` ¶

`is_empty(self)` ¶

`next(self, task_id)` ¶

`summary(self)` ¶

`to_dict(self)` ¶

`botcity.maestro.datapool.entry.DataPoolEntry` `dataclass` ¶

`get_value(self, key, default=None)` ¶

`json_to_update(self)` ¶

`report_done(self)` ¶

`report_error(self)` ¶

`save(self)` ¶

`to_json(self)` ¶

`update_from_json(self, payload)` ¶