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	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-json-webhook	send a webhook, URL field must be to a full url to POST to (only POST to secure URLs is supported)
send-webhook	deprecated 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)

Note

only one type of action is supported per trigger. e.g. 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.

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"