Data Events

The core sheepCRM emits data events in response to system changes. The most common and most useful data events are lifecycle 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.

Key concepts:

Term	Description
data event	Base name for the event, e.g. new_membership.
variations	Date/time variations; event and variation are joined with an underscore, e.g. 2wk creates new_membership_2wk (new membership + 2 weeks), or 90d creates lapsed_90d (lapsed + 90 days).

General Variations

Days	Modifier
180	180d
90	90d
28	4wk
21	3wk
14	2wk
7	1wk
1	1d
0	(none)
-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.

General Data Events

Data Event	Variations	Data Present	Date	Notes
action_required_summary		text	daily	Summary of actions required
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	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	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 one reference exists on a payment, only one trigger will fire using the following precedence: membership, ticket, donation, reservation, invoice, finally payment_received.

The payment record is the context to these events:

Data Event	Date	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

The following events are deprecated and should not be used for new integrations:

• 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 of 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-json-webhook	Send a webhook. URL field must be a full URL to POST to (only POST to secure URLs is supported).
send-webhook	Deprecated. Send a webhook. URL field must be a full URL to POST to.
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).

Note

Only one type of action is supported per trigger. For example, send-templated-email and send-json-webhook are supported but not two send-templated-email actions.

Viewing the events and actions configured

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

GET https://api.sheepcrm.com/api/v1/{flock}/triggers/
Authorization: Bearer $API_KEY

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 at 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 does not get a 200 or 201 response it will retry for approximately 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. This allows you, for example, to design one 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.

Parameter	Description
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).

POST https://api.sheepcrm.com/api/v1/example/bulk_action/
Authorization: Bearer $API_KEY
Content-Type: application/json

{
    "action": "set-single-field",
    "query": {"first_name": "Bob"},
    "value": "Robert",
    "field": "first_name",
    "description": "bob->robert"
}

POST https://api.sheepcrm.com/api/v1/example/bulk_action/
Authorization: Bearer $API_KEY
Content-Type: application/json

{
    "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"
}