Orchestra Bots¶
Below, we’ll walk through the various bots available in Orchestra.
StaffBot¶
Setup¶
StaffBot
provides a simple way to ask a group of Workers
if they would
like to work on a particular Task
. The goal is reduce the human load when
finding a Worker
for a Task
. StaffBot
allows a user to interact
with Orchestra via Slack or can be configured to automatically find
Workers
for a Task
when it is available by setting up an Assignment
Policy.
StaffBot
works by reaching out to qualified Workers
and offering them a
Task
to work on. Workers
can then either accept or reject the task (via
Slack or email) and start working on it.
Slack¶
To interact with StaffBot
via Slack, you first need to configure a Slack
Slash Command. Below is a sample
configuration for the /staffbot
command.
Once the command is created, copy the token for the command into your project
settings as follows: ORCHESTRA_SLACK_STAFFBOT_TOKEN = 'your-token-here'
.
The token is used to authenticated requests sent to the staffbot url. It is
important to keep this token secret since otherwise anyone may make a HTTP
POST
and execute the staffing logic!
In addition to the ORCHESTRA_SLACK_STAFFBOT_TOKEN
setting, you can further
restrict access to the endpoint by specifying the following:
STAFFBOT_CONFIG = {
'allowed_team_ids': ['allowed_team_ids'],
'allowed_team_domains': ['allowed_domains'],
'allowed_channel_ids': ['allowed_channel_ids'],
'allowed_channel_names': ['allowed_channel_names'],
'allowed_user_ids': ['allowed_user_ids'],
'allowed_user_names': ['allowed_user_names'],
'allowed_commands': ['allowed_commands'],
}
StaffBot
will use the STAFFBOT_CONFIG
to filter messages that do not
match items in the list. If a parameter is not specified, all values are
accepted by default.
Once this configuration is complete, you can test it by typing
/staffbot staff <task-id>
where <task-id>
is an unassigned
task id. By default, StaffBot
will reach out to Workers
who
have the appropriate WorkerCertification
for the task you are
staffing, in batches of
settings.ORCHESTRA_STAFFBOT_WORKER_BATCH_SIZE Workers
every
settings.ORCHESTRA_STAFFBOT_BATCH_FREQUENCY
time units (the
frequency is a datetime.timedelta
object).
StaffBot
looks at two fields when prioritizing Workers
to
reach out to when a task is available. The
WorkerCertification.staffbot_enabled
field (True
by default)
tells StaffBot
whether to reach out to a Worker
because they
have a given certification. If you set it to False
, the
Worker
will still be able to pick up tasks requiring certification
(e.g., you can still manually assign tasks to that Worker
), but
StaffBot
will not reach out to them for those tasks. The
WorkerCertification.staffing_priority
integer field (0
by default) helps
StaffBot
prioritize amongst certified Workers
. If Workers
have the same staffing_priority
, StaffBot
will prioritize them
randomly.
Utility functions¶
There are several utility functions to help operationalize StaffBot
. You should call these through cron
or some other scheduling utility:
orchestra.communication.staffing.send_staffing_requests
looks for tasks that can be staffed and reaches out to the next set ofsettings.ORCHESTRA_STAFFBOT_WORKER_BATCH_SIZE
workers everysettings.ORCHESTRA_STAFFBOT_BATCH_FREQUENCY
.orchestra.communication.staffing.remind_workers_about_available_tasks
sends a reminder to any worker who has unclaimed task still available.orchestra.communication.staffing.warn_staffing_team_about_unstaffed_tasks
warns administrators on the internal Slack channelORCHESTRA_STAFFBOT_STAFFING_GROUP_ID
about tasks that have not been staffed for more thanORCHESTRA_STAFFBOT_STAFFING_MIN_TIME
.
Assignment Policy¶
StaffBot
can also automatically staff projects by specifying an Assignment
Policy. Orchestra supports custom logic for assigning Workers
to tasks, and
StaffBot
leverages this by asking qualified Workers
if they would like
to work on a Task
as soon as the Task
is available. To specify the
StaffBot
auto-assignment policy, which uses the same logic as the
/staffbot staff
command, add the following to the Step
configuration in
your version.json
file. Following the Journalism Workflow Example we have:
[...step definition...]
"assignment_policy": {
"policy_function": {
"entry_level": {
"path": "orchestra.bots.assignment_policies.staffbot_autoassign"
}
}
},
[...step definition...]
Now, for entry-level tasks within the defined step, StaffBot
will
automatically try to staff this Task
. If the task requires review, manual
assignment is necessary unless we add a reviewer
key to the policy
function:
[...step definition...]
"assignment_policy": {
"policy_function": {
"entry_level": {
"path": "orchestra.bots.assignment_policies.staffbot_autoassign"
},
"reviewer": {
"path": "orchestra.bots.assignment_policies.staffbot_autoassign"
}
}
},
[...step definition...]
Detailed Description Function¶
The detailed_description_function
is used to dynamically describe a
Task
when StaffBot
makes requests to Workers
, offering them the
opportunity to work on the Task
. The function is given a task_details
dictionary and can be passed extra kwargs
as shown below:
[...step definition...]
"detailed_description_function": {
"path": "my_project.orchestra_helpers.get_detailed_description",
"kwargs": {
"text": "Task text"
}
}
[...step definition...]
# my_project/orchestra_helpers.py
def get_detailed_description(task_details **kwargs):
return '''A new task is available!
Find out more about {} at example.com/projects/{}!'''.format(
kwargs.get('text'), task_details['project']['id'])
Usage¶
Automatic Task Staffing in Orchestra¶
StaffBot
allows interaction with Orchestra via Slack to assign or reassign
an expert to a task. To use StaffBot
, simply type /staffbot
into your
slack window, and will see an autocomplete similar to:
You can send two different commands to StaffBot
: 1) staff
, and 2)
restaff
.
Using the staff
command¶
To use the staff
command, you need to specify a <task-id>
of a task
that is unassigned. You can find the <task-id>
in the project view (shown
below) or from notification emails/Slack messages about a project.
In this example, you have just finished the client_interview
task and need
to add someone to the communication_delivery
task with id 4
(shown in
red), so you can type:
/staffbot staff 4
Staffbot
will then reach out to eligible experts asking them if they would
like to work on the task. Once one of them accepts, they will be added to the
private Slack channel for the project and can begin working on the task.
If a task has a review step, you can use StaffBot
to assign an expert to
the review step once the first expert has submitted their work for review.
Using the restaff
command¶
You can also use the restaff
command to offer a task to a different expert.
This will be useful if a expert is unable to complete the task. Following the
example above, assume that the worker joshblum
accepted the task 4
.
To restaff this task you can type:
/staffbot restaff 4 joshblum
This will offer the task again to eligible experts, and once a new expert
accepts, joshblum
will be removed and the new expert will be added.
SanityBot¶
Setup¶
SanityBot
periodically looks at the state of a project and reminds
the project team about various things that seem off. For details and
motivation, see the original project description. SanityBot
currently warns project team members in the project team’s Slack
channel.
Project Configuration¶
To specify which sanity checks to run, and how frequently to run them,
update version.json
for the workflow you are sanity-checking with
an optional sanity_checks
entry. As an example:
[...workflow definition...]
"sanity_checks": {
"sanity_check_function": {
"path": "path.to.sanity.check.function"
},
"check_configurations": {
"check_slug1": {
"handlers": [{"type": "slack_project_channel", "message": "<message here>", "steps": ["step_slug1", ...]}],
"repetition_seconds": 3600
},
...
},
}
...
Here’s a walkthrough of the configuration above:
sanity_check_function
is called periodically and generates SanityCheck objects. The function prototype isdef sanity_check_function(project: Project) -> List[SanityCheck]:
.check_configurations
mapsSanityCheck.check_slug
values to a configuration, which consists of a list of handlers and a repetition interval.- in v1, the only handler is
slack_project_channel
, which messages the team slack project, tagging the experts assigned to the tasks specified by in steps. - An optional
repetition_seconds
contains the number of seconds to wait before re-issuing/re-handling aSanityCheck
. Ifrepetition_seconds
does not appear in the map, thatSanityCheck
is not repeated.
Scheduling function¶
To operationalize SanityBot
, you should call
orchestra.bots.sanitybot.create_and_handle_sanity_checks
through
cron
or some other scheduling utility. This function will look at
all active projects with sanity_checks
in their workflow
definitions, and call the appropriate sanity_check_function
to
trigger sanity checks.