Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
260 lines (201 sloc) 10.3 KB

Orchestra Bots

Below, we'll walk through the various bots available in Orchestra.



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.


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:

           '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 of settings.ORCHESTRA_STAFFBOT_WORKER_BATCH_SIZE workers every settings.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 channel ORCHESTRA_STAFFBOT_STAFFING_GROUP_ID about tasks that have not been staffed for more than ORCHESTRA_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/

def get_detailed_description(task_details **kwargs):
  return '''A new task is available!
            Find out more about {} at{}!'''.format(
            kwargs.get('text'), task_details['project']['id'])


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 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": ""
  "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 is def sanity_check_function(project: Project) -> List[SanityCheck]:.
  • check_configurations maps SanityCheck.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 a SanityCheck. If repetition_seconds does not appear in the map, that SanityCheck 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.

You can’t perform that action at this time.