This document describes the business logic for automated sync between ControlShift and either the EveryAction or VAN products from NGPVAN.

Permissions

The API integration requires an EveryAction/VAN API key with access to the following API endpoints enabled:

ControlShift Activity Sync to EveryAction

When certain member activity happens in ControlShift, we use the EveryAction API to sync that activity to EveryAction.

Events

When an event is created, unless it is a virtual event with no location, we first ensure that a location record exists in EveryAction for the event’s location (POST to /locations/findOrCreate). Then we create an event record (POST to /events). The eventType and the roles for host and attendee are set based on defaults configured during CRM integration setup. If we do not have a person record yet for the event’s host, we create one (POST to /people/findOrCreate). Finally, we create a signup (POST to /signups) for the host.

When an existing event is updated, we sync the new location if needed. Then we update the event (PUT to /events/{eventId}).

[FUTURE: This part is not implemented yet, but it should be soon] When an event’s host is changed, we create a person record for the new host if needed. Then we create a new signup for the new host, and delete the signup (DELETE to /signups/{eventSignupId}) for the old host.

When an event is deleted, we delete the event in EveryAction (DELETE to /events/{eventId}).

RSVPs

When a member RSVPs to an event, we ensure that a person record exists in EveryAction for the member (POST to /people/findOrCreate). If EveryAction indicates that the person did not previously exist, we record in ControlShift that the attendee created a “new member”. Then we create a signup for the attendee.

Groups & group members

When a group is created, we create a supporterGroup (POST to /supporterGroups) in EveryAction for the group. The supporter group record is a one to one match with the Local Group in ControlShift. 

When a member joins a group or becomes an organiser of a group, we first ensure that a person record exists in EveryAction for the member (POST to /people/findOrCreate). If EveryAction indicates that the person did not previously exist, we record in ControlShift that the group membership created a “new member”. Then we add that person to the group (PUT to /supporterGroups/{supporterGroupId}/people/{vanId}).

Petitions & signatures

When a member signs a petition or creates a new petition, we ensure that a person record exists in EveryAction for the member (POST to /people/findOrCreate) If EveryAction indicates that the person did not previously exist, we record in ControlShift that the signature created a “new member”. (This does not apply to the petition creator’s signature.)

Multi-region sync

If an event, group, or petition is associated with a region in ControlShift, and that region has its own EveryAction API key, then all EveryAction calls for syncing the associated data use the region’s API key instead of the default API key for the NGP VAN integration. This may affect which EveryAction users can see the synced data.

When an admin changes which region an event, group, or petition is associated with, we check whether that means a change in the appropriate API key for syncing that event, group, or petition. If so, we re-sync data using the new API key:

• For an event: we re-sync the event and host as if it was just created, and then we re-sync all its RSVPs
• For a group: we re-create the codes, and then we re-sync all the group members and organisers
• For a petition: we re-sync the petition’s creator and all its signatures

When we re-sync members as part of a region change, we do not update the “new member” flag in ControlShift.

External Events Ingest from EveryAction

Every hour, we ask the EveryAction API for a list of upcoming events. These are stored in ControlShift as external events. External events and native ControlShift events are listed together at the /events  and /local pages in ControlShift.

This feature is optional, and can be configured from the NGP VAN / EveryAction integration settings page (admin homepage > Settings > Integrations > EveryAction/VAN > Event Ingest tab).

We use EveryAction's tag feature to decide which events we should ingest and display on event lookup pages. The Event Ingest tab includes a dropdown of existing event tags in your connected EveryAction instance. Select the appropriate tag and click to Update. Once the tag has been chosen, you'll need to ensure that all existing and newly-created events are tagged appropriately. 

Please note: if you do not choose a tag, we will automatically ingest all events in EveryAction.

In more detail, how this works is: We fetch the list of upcoming events from EveryAction (GET to /events) and compare it to the external events we have previously ingested. External events in ControlShift are created, updated, or deleted as needed to make our list match the list retrieved from EveryAction. When we need to create a new external event in ControlShift, we look up the public URL for the event and store it.

Multi-region ingest

When there are regions with their own API keys configured, we repeat the EveryAction /events call with each regional API key in addition to the main API key.