Saltar a contenido

API de Python

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