Programs & Rules

The logic driving Village's intelligence engine

Progams & Rules

Programs & Rules: Overview

Every action that Village takes is the result of a rule being successfully evaluated and executed. Programs are a convenient way to group and manage similar sets of rules.

Each program contains one or more rules, and each rule within a program has its own logic defined by rule-specific parameters and conditions.

Programs are not just a way to easily group and administer similar rules, you can also use programs to set overarching conditions and restrictions that apply to all rules within a program, such as when those rules are active, who they apply to, and even what the maximum budget should be across all rules in a program.

Programs and rule logic is extremely flexible. That means there are many use cases for programs and rules, including incentives structures, compensation plans, loyalty programs, and even user-segmentation and comms.

Programs

This section walks through creating and managing programs. You can jump to creating and managing rules here.

How to group rules into programs

It’s totally up to you how you want to set up and group rules into programs within Village. Our recommendation is to group rules by the business unit or business goal that they are trying to achieve.

Here’s an example from a food delivery platform that has set up three separate programs:

1. The ‘Weekly Supply Incentives’ program groups together 10 rules that relate to driving week-to-week supplier engagement.

2. The ‘Power Dash Program’ contains 15 rules that govern the distribution of loyalty points and status badges to engage and retain demand-side users.

3. The ‘User Segmentation Flows’ contains 13 rules that automatically group users into different segments based on their status and activity on the platform.

Creating a Program

To create a new program, navigate to Programs within the Incentives section of the Network Manager. Click 'Create New Program'. This will open the 'Create New Program' screen.

Below are the necessary inputs and optional conditions when creating a new program. After you have set all the conditions for your program, click the green 'Create' button to create your program.

Required Inputs

Field	Description
Name	An internal identifier for your program. Consider adopting a common naming convention such as: Consumer - Incentives - [Program Name] Supplier - Incentives - [Program Name] Supplier - Segmentation - [Program Name]
Description	A brief description that makes the program easily identifiable to internal users.

You'll also notice that you can set conditions at the program level. Please refer to the Time, Segment, Budget and Multiplier Conditions pages to understand how these work.

Launching Programs

Your newly created program will appear in 'Drafts' and will not be active yet. Once you are happy with your program, you can launch it by clicking the green 'Launch' icon in 'Drafts'. Note that programs must contain at least one rule to be able to launch.

Editing Programs

To edit an active program, click 'Manage' to the right of the program. This will take you to the Program Detail Page where all active and draft rules within the program, as well as the program-level conditions, are displayed.

To edit the program-level conditions, click the purple 'Edit' icon in the top right of the screen. This will take you to a Program-level Conditions Edit page where you'll be able to edit the program's name, status, active dates, max payout conditions, segment eligibility conditions, and bonus multiplier conditions. Once you're happy with the changes, click 'Update'. Be aware that updating an active program will have immediate effect on that program.

Duplicating Programs

In the 'Drafts' section, you can duplicate a program by clicking the 'Duplicate' icon. This will add a new program to your draft programs section that contains exactly the same program-level details, conditions, rules and rule-level conditions as the duplicated program.

Deactivating Programs

To deactivate a live program, click ‘Manage’ and then the purple edit icon in the top right of the Program Details page. From here you can edit the Status of the program. Please note that deactivating a live program will also cause any active rules within the program to deactivate.

Deleting Programs

To delete a program, you can simply click on the 'Delete' icon next to the program in the 'Drafts' section. You’ll need to deactivate a program before you are able to delete it. Be sure to double-check before deleting, as this action cannot be undone and will also delete the rules and logic within the program.

Rules

Rules Overview

All output operations performed by Village are the result of logic being executed. We call this logic Rules. Rules can either be triggered by activity that happens on your platform, or on a predetermined schedule. Whenever a rule is triggered, all conditions of a rule are evaluated to determine whether or not to execute it. When a rule is successfully evaluated, the following output operations can be performed:

• 1. distribute some form of value to a user, called an Award (such as a payment, incentive or non-monetary award),

• 2. add or remove a user from a Segment, and/or

• 3. send a communication to a user, either through the end user dashboard, or 3rd-party CRM integrations (in beta).

The building blocks of a rule

At the highest level, a rule is made up of the following components:

Component	Overview
Trigger	The event or scheduled evaluation that causes a rule to be evaluated
Output Operation	The action or operation that occurs when a rule executes. This could be an award like a payment or incentive, or segment that adds or removes users from a specific group.
Recipient	Which user the output operation will be done to. For example, a transaction may have 2 associated users (the seller or supplier, and the buyer). You need to specify which one is being impacted by the rule.

A note on Recipients

Optional Rule Components

In addition to these mandatory components, you can add a variety of rule-level conditions to modify or restrict the rule. These include active dates, max budget conditions, segment eligibility conditions, and bonus multipliers.

Creating Rules

To create a rule, navigate to Programs, and either create a new Program or click ‘Manage’ on an existing program. This will open the Program Detail page. To create a rule, click the purple "Create New Rule" button on the right side of the screen. This will generate a new row in your "Draft Rules" section.

Once you have filled out the necessary information, click the green checkmark on the right side of the rule to create a new draft rule. To activate this rule, review your rule and then click the green "Launch" button to the right of the draft rule.

Here's an explanation of the inputs you'll see when creating a rule:

Component	Overview
Name	The internal-facing name used to identify this rule.
Trigger Type	The category of trigger that will start the rule evaluation. Trigger types include Activity (Actions or Sales) and Goals.
Trigger	Allows you to select from the triggers of this trigger type that have already been created. The trigger on a rule is the event, activity, goal or scheduled evaluation that will cause the evaluation of this rule to commence. When the evaluation is successful, the rule is executed. More complicated triggers like goals allow you to nest complicated logic within a rule by evaluating both the conditions of a rule, as well as the conditions of a goal, before successfully evaluating and executing a rule.
Output	Select an award or segment to add or remove from the dropdown. The dropdown will list available output operations (eg. awards or segments that you have previously created).
Amount	The total number of awards of this type to be distributed each time the rule is executed. The amount field will show "N/A" for Segments.
Recipient	The user who will receive the award. For many platforms, the only user type in the ecosystem is their buyer or customer, and the recipient will be the same for every rule. However, other two or three-sided platforms may have activity triggers that have multiple associated users and specifying who is the recipient of an executed rule is important.
Rule-level Conditions	You can set multiple rule-level conditions for each rule. These include active dates, max budget conditions, segment eligibility conditions, and bonus multipliers.
Rule Visibility	This setting controls whether a rule will be visible to end users. If you indicate that you want your end users to be aware of a given rule, you can also create a user-facing name for this rule. This rule will then appear as an active offer for users in their end-user dashboard.

Program-level versus rule-level conditions

Remember, any conditions that are set at the rule-level are additive to the conditions set at the program level and provide more specific control over the execution of each rule. To the extent of any conflict, the program-level rules will take precedence. For example, if a rule has a max budget of $1000 per user per day, but the program that the rule is in has a max budget of $500 per user per day, the max budget constraint will be $500 per user per day.

Editing Rules

To edit a draft or active rule, click the purple "Edit" button on an active rule or start editing a draft rule immediately. To edit rule-level conditions, click the expand icon on "Rule Level Conditions". This will open the rule-level conditions modal where you can edit active dates, max payout, segment eligibility, bonus multipliers, and rule visibility.

Please remember, any conditions set at the rule level are additive to the conditions set at the program level. In case of any conflict in these conditions (e.g., mismatch in active dates), the active dates at the program level will take precedence.

Duplicating Rules

To duplicate an active or draft rule, click the purple "Duplicate" button to the right of the rule. This will copy all the details and conditions of the duplicated rule into a new rule, although you will have to create a new name for this rule.

Deleting Rules

To delete a rule, click the red "Trash" icon to the right of the rule. Be cautious when deleting or editing an active rule as it will immediately affect any users who are eligible for this rule.