Skip to content

Activity playbook

Feedback

If your company has processes that need certain tasks to be done regularly, you can use playbooks to implement those processes. The activity playbook helps you to automatically put events on calendars. These events can always be rescheduled by people, but they can't be deleted.

The following types of activities can be scheduled:

  • Activities with leads and partners, such as calls or follow-ups
  • Internal activities, such as team meetings
  • Automatically schedule meetings for as many activity types as needed
  • Specify the assignees and participants
  • Specify when the scheduling job is run
  • Suggest the next best action after a meeting is done

Creating a playbook

Playbooks work through the business rules that you define for activity, frequency, and role-based participation.

No UI

To create playbooks, you must use JSON code.

Before you begin

To create a playbook rule, you need the following information:

  • The activity to be scheduled
  • The frequency of scheduling
  • The duration of the activity
  • The assignee for the activity
  • The participants for the activity
  • The criteria to be used for selecting the leads, partners, or users

Steps

  1. Log in to the Vymo web app.
  2. Click Customize > Global Settings > Custom Configurations.
  3. Expand the additionalConfigs object and add a JSON object to it named choreography_rules (see How to add a JSON object).

  4. Use the code snippet in Example configuration as guidance to define the rule. For an explanation of the parameters, see Parameter reference.

    Specify what Specify where
    The activity to be scheduled activity_code
    The frequency of scheduling frequency
    The duration of the activity duration_config, slot_repitition_allowed
    The people in the activity type, ignore_parents_with_same_user, user_config
    The criteria for selecting leads or partners vo_config

  5. When done, click Save. Then, release the changes.

Running a playbook

To run a playbook, either manually or through cron, use the following command.

node app/tasks/run-activity-playbook.js --clientId=short_code_of_company

The options for the command are listed at Parameter reference.

Example configuration

For explanations of these parameters, see Parameter reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "channel": "banca",
  "name": "Branch Visit",
  "activity_code": "partner_visit",
  "module": "partners",
  "start_state": "partners_new",
  "slot_repitition_allowed": "No",
  "type": "single",
  "frequency": "daily",
  "ignore_parents_with_same_user": true,
  "duration_config": {
    "roundRobin": true,
    "daysOfWeek": [
      {
        "type": "range",
        "start": 1,
        "end": 6
      }
    ],
    "weeksOfMonth": [
      {
        "type": "range",
        "start": 1,
        "end": 5
      }
    ],
    "hoursOfTheDay": [
      {
        "type": "range",
        "start": 9,
        "end": 10
      }
    ]
  },
  "duration": 30,
  "user_config": {
    "host": [
      {
        "type": "attribute",
        "attributeCode": "role",
        "attributeValue": [
          "BDO",
          "Senior BDO"
        ]
      }
    ]
  },
  "vo_config": {
    "primary_vo": [
      {
        "reporting_category": "self",
        "reporting_category_enabled": true
        "vo_types": [
          {
            "type": "attribute",
            "attribute_value_fetch": "dynamic",
            "attributeCode": "updates_inputs_map.partners_new.list",
            "attributeType": "array",
            "attributeValue": {
              "source": "host",
              "attribute": "bro_code"
            }
          }
        ]
      }
    ]
  },
  "ruleId": "bancar1"
}

For explanations of these parameters, see Parameter reference.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
  "channel": "direct",
  "name": "Performance Review",
  "activity_code": "prev",
  "slot_repitition_allowed": "No",
  "type": "single",
  "frequency": "weekly",
  "ignore_parents_with_same_user": true,
  "duration_config": {
    "weeksOfMonth": [
      {
        "type": "range",
        "start": 1,
        "end": 5
      }
    ],
    "daysOfWeek": [
      {
        "type": "discrete",
        "values": [
          5
        ]
      }
    ],
    "hoursOfTheDay": [
      {
        "type": "range",
        "start": 12,
        "end": 19
      }
    ]
  },
  "duration": 60,
  "user_config": {
    "host": [
      {
        "type": "attribute",
        "attributeCode": "role",
        "attributeValue": [
          "Group Head"
        ]
      }
    ],
    "primary_participants": [
      {
        "participant_category": "direct_reports",
        "participant_types": [
          {
            "type": "attribute",
            "attribute_value_fetch": "static",
            "attributeCode": "role",
            "attributeValue": [
              "Zonal Manager"
            ]
          }
        ]
      }
    ]
  },
  "ruleId": "direct12"
}

Parameter reference

To create a playbook, you define a choreography_rules object. To run a playbook, you issue commands either manually or through a cron. The parameters for these actions are different.

To create a playbook

The same choreography_rules object is used for both module activities and user activities.

Tree view of choreography_rules

mermaid graph LR choreography_rules --> rule_id choreography_rules --> channel choreography_rules --> name choreography_rules --> activity_code choreography_rules --> type choreography_rules --> |if_module_activity| module choreography_rules --> |if_module_activity| start_state choreography_rules --> frequency choreography_rules --> duration_config choreography_rules --> duration choreography_rules --> user_config choreography_rules --> |if_module_activity| vo_config duration_config --> |if_specific_day| scheduleDay duration_config --> |if_range| objects_for_days_weeks_hours_or_weekdays user_config --> host user_config --> primary_participants

The following table shows the differences when using this object for module activities and for user activities.

Parameter In module activities In user activities
channel Don't use; leave blank. Don't use; leave blank.
name Is a human-understandable name by which you can refer to the rule. Is a human-understandable name by which you can refer to the rule.
activity_code Is the code for the activity to be scheduled Is the code for the activity to be scheduled
module Is the module code. - not present -
start_state Is the code for the start state for a lead record in the module. - not present -
slot_repitition_allowed If set to Yes, all activities are created in the same slot. Useful if people need to manually reschedule their activities. Is a Boolean. If set to Yes, all activities are created in the same slot. Useful if people need to manually reschedule their activities.
type Is either single (for a one-on-one meeting) or group (for a meeting with everyone who qualifies through the user_config settings). Is either single (for a one-on-one meeting) or group (for a meeting with everyone who qualifies through the user_config settings).
frequency Specifies how often the rule must be run. Can be one of daily, weekly, or monthly. Specifies how often the rule must be run. Can be one of daily, weekly, or monthly.
ignore_parents_with_same_user Is a Boolean. Can be used only if type is single. To create activities to only the person at the lowest level in the hierarchy, set this value to true. Is a Boolean. Can be used only if type is single. To create activities to only the person at the lowest level in the hierarchy, set this value to true.
duration_config Specifies how often the activities are to be put on the calender. See duration_config. Specifies how often the activities are to be put on the calender. See duration_config.
user_config Specifies the host and participants of the activity. See user_config. Specifies the host and participants of the activity. See user_config.
module Is the code of the module. - not present -
start_state Is the code of the start state of records in the module. - not present -
vo_config Specifies the records to pick for the activity. See vo_config. - not present -

duration_config

Tree view of duration_config

mermaid graph LR choreography_rules --> duration_config choreography_rules --> many_other_parameters duration_config --> |range_of_days| daysOfMonth duration_config --> |range_of_weeks| weeksOfMonth duration_config --> |range_of_weekdays| daysOfWeek duration_config --> |range_of_hours| hoursOfTheDay duration_config --> |specific_days| scheduleDay duration_config --> |round_robin| scheduleDay

The parameters for this object depend on the frequency with which the activity is to be scheduled. The following table shows which parameters must be used for a specific duration. For example, for a weekly frequency, you need three parameters: weeksOfMonth, daysOfWeek, and hoursOfTheDay.

Frequency weeksOfMonth daysOfWeek daysOfMonth hoursOfTheDay scheduleDay
Weekly Yes Yes No Yes No
Daily Yes Yes No Yes No
Monthly, on certain days No No Yes Yes No
Certain days after the rule is run No No No Yes Yes

See the following code snippets for guidance on the parameter values.

  • Lines 4 and 14: The type parameter can either be range or discrete, but not both.
  • Lines 5 and 6: Use only for the range type. The days of the week start from Monday. Therefore, 1 is Monday and 5 is Friday.
  • Lines 14 and 15: Use only for the discrete type. The value is the day of the week, where Monday is 1.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "weeksOfMonth": [
    {
      "type": "range",
      "start": 1,
      "end": 5
    }
  ]
}
\\OR
{
  "weeksOfMonth": [
    {
      "type": "discrete",
      "values": [
      5
      ]
    }
  ]
}
  • Lines 4 and 14: The type parameter can either be range or discrete, but not both.
  • Lines 5 and 6: Use only for the range type. The days of the week start from Monday. Therefore, 1 is Monday and 5 is Friday.
  • Lines 14 and 15: Use only for the discrete type. The value is the day of the week, where Monday is 1.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "daysOfWeek": [
    {
      "type": "range",
      "values": [
        2,
        3
      ]
    }
  ]
}
\\OR
{
  "daysOfWeek": [
    {
      "type": "discrete",
      "values": [
        3
      ]
    }
  ]
}
  • Lines 4 and 14: The type parameter can either be range or discrete, but not both.
  • Lines 5 and 6: Use only for the range type.
  • Lines 14 and 15: Use only for the discrete type.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "daysOfMonth": [
    {
      "type": "range",
      "start": 1,
      "end": 30
      }
  ]
}
\\OR
{
  "daysOfMonth": [
    {
      "type": "discrete",
      "values": [
        2
      ]
    }
  ]
}
  • Lines 4 and 14: The type parameter can either be range or discrete, but not both.
  • Lines 5 and 6: Use only for the range type. The hours start from 0, for midnight, and follow the 24-hour clock format. Therefore, 2130 is 9:30 PM.
  • Lines 14 and 15: Use only for the discrete type. The hours start from 0, for midnight, and follow the 24-hour clock format. Therefore, 2130 is 9:30 PM.
1
2
3
4
5
6
7
"hoursOfTheDay": [
    {
      "type": "range",
      "start": 1030,
      "end": 11
    }
  ]
  • Line 5: The number of days, counting from today as 0, after which the activity must be done. Therefore, tomorrow is 1.
1
2
3
4
5
6
7
8
9
{
  "scheduleDay": [
    {
    "values": [
      "2"
    ]
  }
  ]
}

user_config

Tree view of user_config

mermaid graph LR choreography_rules --> user_config choreography_rules --> many_other_parameters user_config --> host user_config --> primary_participants host --> see_the_following_table primary_participants --> see_the_following_table

Parameter Description
host Is an object. See the next few rows.
host.type Is a system attribute. Don't change. The value is always attribute.
host.attributeCode Specifies the code of the attribute to use.
host.attributeValue Specifies the values that host.attributeCode can have. Can be a comma-separated list. If host.attributeType is used, the value must be a negative or positive integer. For example, -30 means 30 days before the date as specified through host.attributeCode.
host.attributeType Is used only if the attribute type is a date field.
primary_participants Is an object. Can be a list of objects, where each object contains the parameters described in the next few rows.
primary_participants.participant_category Specifies the relationship with the host. Can be one or more of these values: subordinates, direct_reports, subordinates_group (if group hierarchy exists), direct_reports_group (if group hierarchy exists), peers_group (if group hierarchy exists), none (if participants neither report to the host nor belong to a group hierarchy)
primary_participants.participant_types Is an array of objects (see the tree view that follows this table). Specifies the conditions to be used for selecting participants. participant_types.attribute_value_fetch is the parameter that specifies how the attribute value is to be fetched (static or dynamic).
primary_participants.secondary_participants Is optional. When used, is dependent on the primary participant. Contains two attributes. One is type, the value of which is always hierarchy. The other is levels, the value of which can be either or both of all and immediate.
Tree view of participant_types

mermaid graph LR primary_participants --> participant_types participant_types --> |value is always attribute| type participant_types --> |either static or dynamic| attribute_value_fetch participant_types --> |code of the attribute to use| attributeCode participant_types --> |is an object if fetch type is dynamic| attributeValue attributeValue --> |if dynamic| source attributeValue --> |if dynamic| attribute

vo_config

Tree view of vo_config

mermaid graph TD vo_config ----> vo_types vo_types --> |value is always attribute| type vo_types --> |value is always array|attributeType vo_types --> |either static or dynamic| attribute_value_fetch vo_types --> |code of the attribute to use| attributeCode vo_types --> |is an object if fetch type is dynamic| attributeValue attributeValue --> |if dynamic| source attributeValue --> |if dynamic| attribute vo_config --> |either self or subordinates|reporting_category vo_config --> |if leads are owned by self|reporting_category_enabled

Parameter Description
vo_types Specifies the object for which the activities are to be created.
reporting_category
reporting_category_enabled

To run a playbook

The following table has the options to use with the node app/tasks/run-activity-playbook.js command. Required options are denoted by an asterisk.

Parameter Description
clientId * Is the short name of the company for whom the playbook is being run. For example, show.
forwardMonths Specifies the month for which the playbook is being run. The current month is 0, and the next month is 1, for example.
channelCode Specifies the channel for which playbook is being run. Can be a comma-separated list.
ruleName Specifies the name of the rule to run. If not specified, all rules for the clientId are run.
ruleCodes Specifies the code of the rule to run. Cab be a comma-separated list. If not specified, all rules for the clientId are run.
userId Specifies the ID of the user for whom the rule is being run. If not specified, activities are created for all users who meet the criteria in a rule.
teamsEnabled Used for creating Microsoft Teams activities.

See also

Did this page help? No help at allYes, totally!
Back to top