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