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. .. code-block:: http 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. .. code-block:: json { "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) .. code-block:: http 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' .. code-block:: http 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"