Data Events

The core sheepCRM emits data events in response to system changes. The most common and most useful data events are life-cycle events such as new_membership. Data events are useful for auditing, reporting and for connecting to supplementary actions. The default expiry for data events is two years but a custom expiry can be added on a record by record basis.

data event

base name for the event e.g. new_membership

variations

date/time variations; event and variation are joined together with an underscore “_” e.g. 2wk creating new_membership_2wk new membership + 2 weeks or 90d => lapsed_90d lapsed + 90 days

General variations

days

modifier

180

180d

90

90d

28

4wk

21

3wk

14

2wk

7

1wk

1

1d

0

-1

minus_1d

-2

minus_2d

-7

minus_1wk

-14

minus_2wk

-21

minus_3wk

-28

minus_4wk

-90

minus_90d

-180

minus_180d

Note

state_{from}_to_{to} events only get created when the state change is through a flow board state_{to} events only get created when the state change is through a flow board

Note

donation and pledge are now the same event, use to fire a one off action when a new donation/pledge is made. Use donation_payment_received for actions that should fire for each donation payment e.g. each month in a regular monthly gift

data event

variations

data present

date

notes

action_required_summary

text

daily

summary of actions req’d

donation / pledge

pledge

pledge start date

use for one-off action

no_payment_invoice

180, 90, 28, 7

invoice

invoice date

contact

created

contact

creation date

people and orgs

evidence_draft_reference

1wk, 2wk, 3wk

evidence

creation date

form_response

created, submitted, withdrawn, scoring_complete

form_response

date/time of action

form_response

state_{from}_to_{to},

form_response

date/time of action

sent from flow changes

reservation

created, cancelled, state_{from}_to_{to},

reservation

creation / update date

ticket

confirmation

ticket

creation date

ticketed_event

7, 1, 0, -1, -2, -7, -14, -28, -90

ticket

date (booking start date)

vm_start

7, 1, 0, -1, -2, -7, -14, -21, -28, -30, -90

booking

booking start date

achievement

completed

achievement

marked as complete / finished

Membership Data Events

data event

variations

date

notes

cancelled_membership

end_date

at time of end date

cancelling_membership

date/time of action

at time of cancellation

expiring

1wk, 2wk, 3wk, 4wk, 6wk, soon

end_date minus

when auto renew has not been set, fires before the expiry date e.g. expiring_3wk is 3 weeks before expiry

lapsed

1d, 1wk, 2wk, 3wk, 4wk, 90d, 180d

end_date plus

fire after a membership end date where it has not been renewed

linked_member

added, removed, added_no_useraccount

time of action

welcome email sequence, linked member is the entity

new_membership

1d, 2d, 1wk, 2wk, 3wk, 4wk, 180d

date is membership start date+

use a receipt / confirmation on renewal

renewal

confirmation

time of renewal

use as a welcome to your renewed membership

renewed_membership

1wk, 2wk

start_date

renewing

1wk, 2wk, 3wk, 4wk, soon

end_date minus

no_payment_membership

1d, 1wk, 2wk, 3wk, 4wk, 90d

start_date plus

Payment Events

Note

Where more than on reference exists on a payment only one trigger will fire using the following precedence rules: membership, ticket, donation, reservation, invoice finally payment_received.

The payment record is the context to these events

data event

date

variations

notes

membership_payment_received

payment date

order_payment_received

payment date

where the payment reference is a booking

ticket_payment_received

payment date

where the payment reference is a ticket

donation_payment_received

payment date

reservation_payment_received

payment date

invoice_payment_received

payment date

payment_received

payment date

where the payment reference is none of the above

Deprecated Membership Events

  • renewing_1wk_no_dd_mandate

  • renewing_1wk_woo

  • renewing_2wk_no_dd_mandate

  • renewing_2wk_woo

  • renewing_3wk_no_dd_mandate

  • renewing_3wk_woo

  • renewing_4wk_no_dd_mandate

  • renewing_4wk_woo

  • renewing_soon_no_dd_mandate

  • renewing_soon_woo

Other Data Events

data event

date

variations

notes

application

date/time of action

accepted, rejected, submitted

application e.g. group membership

email_undeliverable

date/time of email send

failed email delivery

enrichment

date/time of action

when an enrichment token is used

export

date/time of action

data export from sheepCRM

failed_login

date/time of action

form_score_review_by

date/time of action

14, 7, 2, 1, 0, -1, -2, -7,

form_score_expiry

date/time of action

gocardless

date/time of action

sync, error

login

date/time of action

multiple_failed_login

date/time of action

multiple failures within short time window

mailchimp

open, click, bounce, sent, unsubscribe, sync

events from MailChimp

mandate

mandate date / date up update

active, created, cancelled, failed, pending_customer_approval, pending_submission, submitted

events from GoCardless

woocommerce

date/time of action

sync, error

Actions

Actions are the tasks which should be executed in response to a data event.

Common actions:

Action

notes

send-templated-email

send a templated email

draft-templated-email

create a draft templated email

send-webhook

send a webhook, URL field must be to a full url to POST to (only POST to secure URLs is supported)

send-email-to-fixed-address

send a templated email but always to the same address (use like a bcc or to alert someone to an error event)

Viewing the events and actions configured

The API offers a read-only view on events and actions.

http https://api.sheepcrm.com/api/v1/{flock}/triggers/
HTTP/1.1 200 OK

{
        "new_membership": [
                {
                        "trigger": "new_membership",
                        "action": "send-templated-email",
                        "template": "New member welcome",
                        "url": null,
                        "active": true,
                        "comment": ""
                }
        ],
        "new_membership_1wk": [
                {
                        "trigger": "new_membership_1wk",
                        "action": "send-templated-email",
                        "template": "New member (1 week)",
                        "url": null,
                        "active": true,
                        "comment": ""
        }
        ]
}

Configuring actions

Actions can be added and edited through the administrator interface: https://sheepcrm.com/{flock}/action/

Webhook Notes

The “standard template” will provide the data packet of the event (e.g membership + some basic people data about the contact)

If a webhook doesn’t get a 200 or 201 response it will retry for approx 7 days.

A trigger will successfully fire only once (a tag is added to the event when successfully fired - removing the tag will cause re-firing)

Advanced Actions

Conditional templates

Use conditional template rules when you want to choose a template based upon data. The template language support conditional statements which are useful for simple if / else statements however the templates can quickly become very complicated. Conditional templates allows you, for example, to design on template for your personal members and another for your corporate members.

{
        "template": [{
                        "order": 1,
                        "template": "new membership a",
                        "conditions": [{
                                "membership_type": "Graduate Member"
                        }]
                },
                {
                        "order": 4,
                        "template": "new membership b",
                        "conditions": [{
                                "membership_type": "ASSOCIATE MEMBERSHIP",
                                "tags": "special"
                        }]
                }
        ]
}

How it works

  • template rules are JSON (invalid JSON will not be evaluated, use a JSON validator to check your rules)

  • template rules are checked in number order from low to high

  • each rule can have any number of conditions

  • all conditions must evaluate to True for the rule to be used

  • if no rule is successful then the template field on the action is used

  • if no default action is desired do not configure the base template field

  • conditions can use any field available on the data event

  • only simple equality is implemented
    • list types: “tags”: “fish” (will evaluate to True if ‘fish’ is one of the tags)

    • reference types: the name of the reference or the URI can be used e.g. “membership_type”: “ASSOCIATE MEMBERSHIP” or “membership_type”: “/example/membership_type/123456/”

Bulk one-off actions

Bulk actions use a one-off action and a sheep_event to perform a background update based on a query. The text_body of the sheep_event is updated with details of the action when it has been completed.

action

add_tag, remove_tag, set-single-field, set-single-field-on-last-membership

query

lookup query

field

the field to change

value

the new value

description

name your bulk action for future reference

resource_type

optional resource_type to query against (default is contacts)

http POST https://api.sheepcrm.com/api/v1/example/bulk_action/ "Authorization: Bearer $API_KEY"
        action=set-single-field
        query:='{"first_name":"Bob"}'
        value='Robert'
        field='first_name'
        description='bob->robert'
http POST https://api.sheepcrm.com/api/v1/example/bulk_action/ "Authorization: Bearer $API_KEY"
        action=set-single-field-on-last-membership
        query:='{"first_name":"Peter"}'
        value='/example/payment_plan/5e62258ab4d5a22356535ce2/'
        field='next_payment_plan'
        description="Move all Peter's to invoice payment plans"