Carleton Onboarding
AlumnIQ Platform Onboarding Guide for Carleton College
material change log
20211011 - shifted tasks from october into november/december to clarify focus on reunion build-out
20210817 - removed directory module from consideration and adjusted timing to build toward reunion support
20210810 - first draft
Purpose
This document is intended to help customers identify, extract, transform, and share data with the AlumnIQ team for a successful onboarding. As much as possible we've limited the content in here to cover the areas that customers can have an impact on; tasks undertaken solely and silently by the AlumnIQ team are not listed here.
Even with that limit imposed there is plenty of food for thought in here. Regarding the warehouse specifically, we'll be actively guiding you through the decision making process - there is a lot to consider and even more to build once we get to wave 2. The baseline essential warehouse won't surprise you content-wise but the work to build the automated scripts to move the file and get it loaded to AlumnIQ are likely new territory for many.
Modules to be deployed
AlumnIQ Core ("everyday")
Events ("everyday events")
Signature Events ("reunion", already available, but needs remapping to core warehouse)
Email
Updated to remove the profile and directory piece for the time being.
Systems
AlumnIQ Everyday Platform : single-day events, email, directory, profiles, and the master warehouse integration hub
AlumnIQ Signature Events : reunion registration and management
The signature system pulls constituent data from the platform warehouse and pushes contact information update candidates back. Otherwise it's largely self-sufficient. Registration data lives in this system and does not (currently) get sent to the main platform.
From an API perspective: Everyday API - warehouse ingestion, change retrieval, single-day event data retrieval, mail behavioral data retrieval. Signature API - reunion registration data
High Level Sequencing
The sequence below is intended to give you a feel for how we approach onboarding. The inclination is to rush to the end first -- but we can't give you real data (of your own provenance) until we have it under our management and there's a general understanding of operations and process. You can start some of your integration work using sample data, but it is only useful for structural replication not actual import. Hence the emphasis on getting things up, using that for orientation and training which will generate decent data volumes for extract, and building from there.
Bootstrap shell online
Warehouse feeds (wave 1) provided
Events brought online
Signature events module remapped to core services
Everybody generates a pile of "test" registrations in both systems so we have testable data for the sync process
Sync feed integration
Email brought online
Warehouse feeds (wave 2) provided
List builder brought online
Data exfiltration from AlumnIQ
Specific reunion-related requests
Capturing the major AlumnIQ commitments in this document so we are all aware of what's pending and accomplished as we complete the timeline.
[Done - August 2021] Implement realtime email address validation for public registration
[Done] Implement realtime address validation and cleansing for public registration
[Pending] Implement realtime address validation and cleansing for admin interfaces
[Pending] Build report of reservation records that haven't received a confirmation email
[Done! - September] Flow detected changed address records through the platform's sync service for single point of pickup
[Done - No.] Decision whether the diff report needs any additional functionality; it'll likely be completely superseded by the address flow process
[Pending] Hide all hint of balance values when no financial component to a given a reservation record
[Pending] Per-org confirmation email subject line customization
Timeline
Responsibilities/tasks listed next to each entity are the expected delivery weeks for those items.
August Responsibilities and Deliverables
General theme: bootstrapping and data. We need your warehouse to do the most valuable onboarding work.
[AlumnIQ]
[DONE] rough project timeline, assuming fair weather and good winds for CC efforts
[DONE] revised project timeline after first meeting given altered priorities
[DONE] defining warehouse feed structures (wave 1) and keeping notes on what is likely necessary for wave 2
[DONE] soliciting and sharing customer contacts to advise on integration strategy
[DONE] create DNS records for QA and prod
[DONE] deploying QA server for receipt and processing of warehouse feeds
[DONE] issue API key for CC to automate warehouse import
[DONE] schedule date for September events training using QA server and warehouse data
[Carleton]
[Pending] contacting references regarding integration efforts
[DONE] building wave 1 warehouse extracts per the spec
[DONE] building the scripts to move warehouse extracts to AlumnIQ on an automated basis
[DONE] establishing the regular meeting schedule for the next couple months
[DONE] run script to move files and trigger imports
[Pending] preparation of responses to all items under Events Module : Items to Provide (below) (can in parts be completed jointly)
Intial State
UP: a primordial warehouse feed specifically for reunion, but so far only moved to S3 manually.
August - Accomplishments and Notes
[All] met to discuss this document and overall process
[Carleton] set dates for followup project meetings
[All] Faux General Reunion setup starting September 1
[All] Faux 50th Reunion setup starting September 1
[All] New full-up date 1 February 2022
[AlumnIQ] this guide updated with revised timeline establishing the primary intent to support reunion and removal of directory from immediate plans
[AlumnIQ] sent two contacts (CUA, UD) for CC to discuss implementation style and best practices with
[AlumnIQ] QA server provisioned; config file pending approval
[AlumnIQ] reunion - email validation deployed
Week of 23 August
[All] discussion (if necessary) on SSO and any exceptions to SSO that need accommodation
separate decisions on admin access vs. public site access
[DONE][Carleton] primary warehouse just about built (consult the warehouse overview docs as needed)
[DONE][Carleton] begins work on lookup feed delivery (for use across warehouse feeds and profile/directory)
[DONE][Carleton]
begins work on fund feed delivery (for gifts made as part of event registration)(REMOVED 8/25 - no gifts during registration)[DONE][Carleton] discuss supplemental feed file just for reunion data (heywood society membership and other related special-purpose fields)
[DONE][Carleton] design automated file move and webhook script (review API basics for how this works)
[DONE][AlumnIQ] ongoing consultation on feed builds and transfer
[DONE][AlumnIQ] share API key with CC for warehouse delivery (CC already has IAM credentials for S3)
[DONE][AlumnIQ] schedule event setup/training
[DONE][AlumnIQ] QA site bootstrapping for orientation and training purposes
Week of 30 August The good news this week is that the domain has been settled on so we are moving expeditiously to get that configuration taken care of (Amy has a procedure to follow) after which time we'll invite you in to the QA environment for real with local accounts until the SSO steps are taken care of.
The best news this week is that Tony managed to successfully push over data and get it loaded into the platform warehouse, which has triggered our internal task to review and test our configurations against it. This work is ongoing.
[All] Preparation of responses to all items under Events Module : Items to Provide (below) as a joint/live effort as much as needed
[DONE][Carleton] Expansion of primary warehouse content completed [DONE][Carleton] Implementation of automated delivery and webhook call underway
consult the warehouse overview and API basics documentation
[DONE][AlumnIQ] QA site available for event setup/training - conditional on the warehouse phase 1 loading
September Responsibilities and Deliverables
General theme: configuration of events module and reunion simulation for data sync experience
[AlumnIQ]
[DONEISH] validation and adjustments to QA system as onboarding continues
[DONE] remapping reunion system to pull data from platform warehouse
[DONE] cloning and modifying or building an entirely fake reunion in a Carleton QA environment to aid in data experimentation
[DONE] implementation of address validation service within reunion product
[DONE] connecting reunion to platform sync process
[DONE] configuration and activation of all selected config options
[DONE] host events module orientraining session sufficient to generate additional sample data
[Carleton]
[DONE] SSO clarification and activation for QA admin access
[DONE] confirmation of access to QA
[DONE] participation in creating many, many "fake" reunion registration records in QA
[DONE] participation in orientraining on platform events
October Responsibilities and Deliverables
General theme: consuming sync feed and doing something with it,
[All]
[Done] creation of many, many test registration records to exercise address sync data flow
[AlumnIQ]
[Done] Poised to respond to requests/clarifications regarding address change API as well as event participation data
[Done] advise on reunion package composition strategy
[Done] finalize any kids camp/child entertainment complexities (they always are)
[Done] review/finalize housing rules (currently: child on floor should only appear for 11 and under)
[Done] implement classmate-only product restrictions (will save on package count if delivered)
[Done] (external request) implement extra data capture for products (like event extra fields)
[Carleton]
[Done] focus on reunion address update + registration data fetch focus
[Done] continuing to build/learn package composition strategies
[Done] consuming sync endpoint data reliabily daily (or more frequently) and processing what comes across
November Responsibilities and Deliverables
General theme: level flight for reunion preparations
[All]
[DONE] discussion about email behavioral data export and processing
[AlumnIQ]
[Pending] email module orientation and training
[Carleton]
December Responsibilities and Deliverables
General theme: this year has been long enough already.
[AlumnIQ]
[Pending] tbd
[Carleton]
[Pending] implementation of email behavioral data export
January Responsibilities and Deliverables
General theme: preparing for reunion and production maneuvers
[AlumnIQ]
[Pending] finalize housing matters (they always wiggle a bit)
[Pending] provision and deploy Carleton platform production environment
[Carleton]
[Pending] complete the reunion registration build ASAP
February Responsibilities and Deliverables
General theme: test until you're sick and tired of testing
[AlumnIQ]
[Pending] thorough testing of reunion configuration in preparation for launch
[Pending] have mail module ready to rock early in Feb to open reunion registration through it
[Carleton]
[Pending] thorough testing of reunion configuration in preparation for launch
[Pending]
March Responsibilities and Deliverables
General theme: all systems go!
[All]
[AlumnIQ]
[Pending] monitor data transfer between products, advise and support Carleton in the live environment
[Carleton]
[Pending] monitor transfer and processing of data from AlumnIQ systems and provide feedback as needed
Tabled
[Pending] discussion about additional feeds for profiles and directory (aka "wave 2 warehouse feeds")
[Pending] documentation of wave 2 feeds (with field structure)
[Pending] implementation of wave 2 feed delivery
[Pending] build list filters around anticipated structures
[Pending] finalization of all the items under "Events Module : Items to Provide" (below)
[Pending] building test platform events, faking registration activity, developing expertise with admin capabilities
[Pending] implementation of event participation data export
[Pending] consuming platform event endpoint data reliabily daily (or more frequently) and processing what comes across
General Configuration Guide
We will guide you through all of this - don't be overwhelmed. A good bit of it is described beyond what we'd communicate in person for ease of reference.
Domain(s)
The operating domain name for this deployment takes the form CUST.alumniq.com. If you have a preference for what CUST should be, please share that with us.
What we need: what CUST will be.
Process
Host Records
CC decides on a host domain 1a. [DONE] CC will send AlumnIQ what those hostnames will be, one for QA and one for prod. We recommend qa-alumniq.carleton.edu and alumniq.carleton.edu. 1b. [DONE] AlumnIQ will send over two CNAME records to be created, one for each environment 1c. [DONE] AlumnIQ will also generate a certificate signing request for an SSL cert provisioned by Amazon. The email requesting approval will go to the email address attached to the @carleton.edu domain registration. 1d. [DONE] CC will have 72 hours from the initiation of that process to click and approve the cert. 1e. [DONE] AlumnIQ will then redeploy config to match the new hostnames for both environments. 1f. AlumnIQ will request whitelisting of the hosts in CC's IDP so that SSO can be activated for administrative access. 1g. A decision about public logins has been deferred until such time as CC moves ahead with profiles/directory services.
Email Records
CC decides on a mail sending domain (@{subdomain}.carleton.edu or @carleton.edu) 2a. in either case we'll need to have them create a SPF (for delivery), DKIM (for delivery), and CNAME record (for open tracking) 2b. AlumnIQ will send the contents of those records once a sending domain has been decided upon. 2c. CC will let AlumnIQ know when those entries have been created. 2d. AlumnIQ will validate that the settings are active and correct.
Warehouse, Lists, and Filters
The AlumnIQ data warehouse is a set of relational tables that contain all data pushed to us from your system, preferably nightly. This warehouse can be quite large and very detailed. This is why the bulk of the release timeline is dedicated to getting it right.
To de-risk this process, we've split the warehouse generation and delivery into two waves, the first of which you should be able to create relatively quickly:
Wave 1: a core warehouse of commonly used fields with minimal decisions required, a feed of funds (for the giving module), and a shared lookup warehouse feed to map codes and labels for any related information.
Once field content is determined and sourced, you'll build the feeds then write a simple exporter to push the data to AlumnIQ. Once we have the data, we'll tweak the importer and build the list filters for the fields identified as filterable in the mail module. Some adjustments will likely be made to the feed structure once you see it live - that's perfectly normal and we're ready to adjust.
We'll do all of that for Wave 1.
** But where is X?**
You're wondering where degrees, activities, athletics, affinity groups, and other "one to many" data is in wave 1, right?
We don't need it until Wave 2 - and that you've already latched on to at least one of those data streams early is a good sign. We want you to get a comfortable process down around the straightforward, essential feeds before we add more on -- because by that time it'll be a far simpler process for you to extend.
Wave 2: extensions that we'll apply as we onboard additional modules. We'll add more tabs for tables of data used for email segmentation - degrees, interests, volunteer activities, student activities, and similar - all of that 1:many data you rely on every day. What form those take will be the subject of more involved conversations about what you use so we can minimize the substance and scope of what you send us to only the necessary.
To prepare you for Wave 2 deliberations, these are some guardrails we've successfully used to guide conversations elsewhere:
Where is this used? Warehouse data is a vital driver for list generation, profile matching, registrant matching, variable email content, and targeted dynamic gift form prepopulation.
We can't use data that you don't provide to us. Also: provide atoms, not molecules. First, Middle, Last, Maiden, Prefix, Suffix as distinct fields is better than "Name" because we can use these atoms for things like pre-filling a first name in the event module, but parsing them out of a Name molecule ("John Jacob Jingleheimer Schmidt '67 P'98") would be nearly impossible.
Similarly, don't apply too many filters right out of the gate. As long as proper record type data exists, we would rather have too many constituents than not enough.
There is such a thing as too much. If it doesn't have a known use in the platform (list segmentation, pre-filling bio data, ask1/2/3, prospect manager) then we probably don't need it.
To paraphrase: Be generous with rows (who), conservative with columns (what)
Normalized data is better. One of the files you will need to send to us is code-to-label lookups, so don't be shy about sending us encoded values unless we've specifically requested a label string.
Related fields Particularly applicable to some list filters. Degree school + type + class year are usually treated as an implicit "AND" when used as a filter term. Please take note those whenever you spot them.
Typical files for sync (by no means an inclusive list)
Warehouse (AlumnIQ-defined spec core feed for platform operations)
WarehouseB (institution-specific 1:1 attributes used for segmentation, reporting, etc.)
Affiliation(s)
Record Type(s)
Degree(s)
Designations
Various lookups/crosswalks
What we need: We've shared a google sheet with you that will be our living source of truth not just for onboarding, but for subsequent modifications throughout your time with us. That document will have a tab for each supplemental warehouse feed we co-design and build to contract around. We'll create them as the need is identified and the structure is mutually agreed upon.
xid is the internal id number (alphanumeric ok) that you typically use to refer to a constituent. We also support xid2 if you have a secondary id number you'd like to send along for the ride. Let's work together to make certain that the correct id number is imported as xid because changing them later is painful. You will see XID mentioned all over the place!
What we need: In your case this will be Advance ID.
Record type seems to frequently be far more granular than you would want to display to constituents. You should be prepared to map your record types to a set of 8-10 "displayable" record types for self-selection in event registration, profile creation, etc.
Ex: Alum, Student, Parent, Spouse, Family, Staff, Faculty, Community/Friend/Other
Mappings would indicate "Undergraduate alum || graduate alum || former student => Alumnus"
What we need: a mapping table that maps your record types into a more generic set. the core warehouse expects a primary record type for shorthand identification.
Global opt-out/removal flags
Which warehouse field(s) need to be obeyed across the board (if any)?
What we need: which fields need to be automatically applied and made 100% unescapable
What we need: a column representing your global do not contact flag. this will be subject to much internal deliberation, which is why the control for who gets flagged is entirely driven in code on your end of the pipeline.
Directory controls (if deploying the directory module)
The constituent directory exposes a significant amount of constituent information to other human beings. With this exposure comes the consideration for healthy limits. So that you retain tight control in alignment with your own internal business rules, we require that you provide the following columns in your base warehouse table, set accordingly:
directory_access - grants permission to access and search the directory
directory_visible - whether this individual should be searchable and visible
directory_contactable - for a listed individual, whether they should be allowed to be contacted by other constituents through the directory messaging tool
directory_can_email - for an individual who can access and search the directory, whether they are allowed to send messages (this is our passive aggressive persona non grata setting)
all of these should be in 0/1 format
if not using the directory, set all four values to 0.
Sending this data to us
This process is documented in our warehouse overview and API basics documentation.
Super short version:
You'll move each file to a private Amazon S3 bucket accessible only using an access key and access secret we'll provision for you. This is easily scripted.
After the file is moved, you'll call a webhook (really just a glorified URL) telling AlumnIQ to pick up a file named X and load it as warehouse feed Y.
You'll get an email or webhook callback (your choice) when each job completes. If there's a problem, you'll be notified as well.
Every warehouse table is replaced in its entirety every night. We run off of your snapshot for ease of diagnosis and stable content.
Events Module
Items to provide
Categories
one per event
typically used to make each department/org's events easily findable, but that's certainly not a rule
categories typically resemble org chart units, broken down as atomically as you may require
Examples: Alumni Association, Annual Fund, Colleges
What we need: category names
Subcategories
one or more per event
used to further refine the definition of the nature of the event
Examples: Affinity, Athletics, New York Alumni Club, Trustees, Alumni Board
What we need: a set of labels
Email Sender
Default Sender and Reply-To names and email addresses for confirmation emails. The address must be from an authorized domain (see Email for more information).
What we need: a label and an email address. Sender: "Carleton College" no-reply@carleton.edu Reply-To: "Carleton College Alumni" alumni@carleton.edu as one example. The sender must be from the "sending domain" as identified later on (@alumniq.carleton.edu, @adv.carleton.edu, or one we manage @carleton.alumniq.email). Reply-to can be (and we recommend) any @carleton.edu address that is monitored.
Default Configuration
Default for address collection for free events. When true, we will ask for the mailing address of the primary registrant even if no money is collected. For some, if the registration is free this information does not provide enough value to slow down the registration process for the registrant.
What we need: your default election
Visibility defaults for the following fields (required, visible, or hidden):
Prefix
Nickname
Suffix
Phone
Mobility Needs
What we need: your defaults for each
Event Location seeds (Optional)
AlumnIQ builds a database of event/activity locations over time for each customer. You're welcome to start fresh, but if there are key locations that you've used many times we can bulk load them up front and save some work.
What we need: Name, URL, Phone, Address 1/2, City, State, Postal Code, Nation, Latitude, Longitude
Accounts
AlumnIQ records event revenues in a double entry accounting system
All events must be attached to an income account
Activities within that event can be attached to separate income accounts
You can add more accounts over time as needed and deactivate old ones.
To get started we need your initial set of accounts.
What we need: a spreadsheet of account label, account code (your internal account reference), and subaccount code (a secondary internal account reference, optional)
Zoom API Keys (optional/recommended)
We can integrate with Zoom for meetings and webinars; to do so we need JWT API Keys (not OAuth!). If you want to activate this capability, start conversations with your campus Zoom admin early. They take a close eye to third parties who want to use their keys.
What we need: see https://help.alumniq.com/events/webinars#managed-zoom-activation
Default Site Skin
We will clone your site layout. We will need you to provide the officially sanctioned/permitted logo artwork
What we need: graphics (if we can't source it ourselves)
Payment Gateway Credentials
We will connect to your payment gateways to process payments and gifts using the Spreedly service.
Spreedly will need credentials to connect to your gateway(s); those requirements vary per gateway
Once we identify what you're using we'll tell you exactly what we need.
What we need: gateway types and roles, and credentials once we know what you use
Email Marketing Module
Email sending domain (CUST.alumniq.email or @SUBDOMAIN.carleton.edu if your DNS admins are so generous)
If you want to send from @CUST.edu addresses, DNS entries will need to be made (attached to your sending domain) to maximize deliverability. We can't do this for you - it's a central IT function.
Reply-To addresses are exempt from this requirement, though we cannot ensure that some mail servers won't look sideways at the domain mismatch.
Mailgun requires all sending domains to be validated. This means we cannot send from @CUST.edu addresses without these DNS modifications
What we need: what your sending domain(s) will be and contact info for the DNS administrator (if necessary)
Subscription categories
These categories are visible to constituents on their profiles.
When message recipients unsubscribe, it's from these individual categories. This limits the 'blast radius' of an unhappy recipient to just a certain class of messages.
"Not too many, not too few". You'll want enough granularity that people aren't clicking unsubscribe 12 times, but also not so general that unsubscribing from one category removes the individual from 80% of your email messages.
Categories can be generic (Events, Solicitation, Newsletters) and more targeted (NYC chapter, LGBTQ+ affinity organization) depending on how many choices you want to present to your alumni.
Categories can be easily added. Reorganizing and removing categories is perlious and requires careful coordination to realign/reassign existing preferences to the new structure.
What to provide: label for each subscription category, a human-friendly description, and an optional code. We will have a lengthy conversation about how these are structured and the implications for how you break them down.
Categories - entirely separate from subscription categories.
one per message
typically used to make each department/org's messages easily findable, but that's certainly not a rule
What we need: category name and the color you'd like each to appear in on the message calendar (hex preferred)
Subcategories
zero or more per message
Used to capture the nature of the message at a high level. Examples include: Affinity, Engineering, Events.
What we need: label for each
Tags
zero or more per message
Editor-created/selected terms that help with future quantification and roll up of message performance.
Examples include: service, baseball, affinity, fundraising, happy hour
Messages and Images share a tag library so whatever tags you preload or create in the course of using the system, you'll have available in both areas. We did this deliberately since the features are so intimately bound.
You don't need to seed the list of tags but you're welcome to. These may have perfect overlap with Subcategories but also allow for user-created tags to be applied. This is another layer of metadata useful for reporting purposes.
What we need: optional list of labels
Default sender info
As an editor, you can change the sender name and email address. We default both fields to a common/acceptable value.
What we need: a label (like "EDU Alumni Association") and email address (like "alumni@school.edu"). Only one label/address pair can be set as the default.
Personalization/Tokens
The subject line and all editable body regions support token replacement - strings that are replaced with personal information that represents the recipient.
Not every field in your data warehouse should be made available for tokenization
Typical fields include: xid, first name, salutation, spouse/partner name, ask 1/2/3, prior fiscal year giving, address information, and so on.
What we need a list, based on your specific warehouse implementation
Default list filters: E.g. excluding constituents who have been marked "do not contact ever" and "do not solicit." The idea is to save the list builder the effort of remembering to add these filters in every time and prevent sending to people you shouldn't.
We can do a mix of global defaults and per-person defaults so that people who work on different teams with different goals can have different default filters.
Default filters can be marked "protected" on a per-filter basis, which prevents them from being removed by the staff member unless they have been granted permission to do so.
What we need: your most common filters, and with that whatever questions you've formulated from looking at your current segmentation strategy so we can recommend optimal defaults.
What we need: a single column in your warehouse that represents the "global do not contact" flag. People with this flag "up" will not be contactable through the AlumnIQ platform at all - consider this your institutionally-driven failsafe. We will respect this warehouse value above all others.
Mail Templates
Places we send email:
mail module - several layout templates can be built right in the AlumnIQ admin using the drag and drop template builder
event confirmation - one layout template is required (default), multiple supported
transactional messages (one common template)
[events] request for payment / confirmation / receipt
[profile] email address control confirmation
[profile] password reset
[profile] match available (customer dependent)
[admin] password reset
[mail] threshold notifications (unsubs/opens/clicks)
giving messages
confirmation/receipt
scheduled payment notification
card expired/expiring
payment failure
membership messages (pending refinement)
confirmation
card expired/expiring
payment failure
What to provide: a logo/header image to park at the top of the template for notifications (max 600px wide, however tall); we'll build a starter templates that you can then maintain as needed. Any templates we create will be responsive and mobile-friendly.
Preparing to pull data from AlumnIQ
Until you have data to pull, getting too far ahead on this is putting the cart ahead of the horse.
But that said, here are the endpoints we expect you'll want to pull from and why/how frequently.
Platform Events
Notes
A policy decision should precede any movement of registrant data. Namely: do you want it as they come in (potentially maintaining future cancels in Advance forever) or do you want it once the event is "closed" (meaning it's an immutable permanent record that you can rely on)?
In-progress pulls get data into Advance faster, but post-closure pulls are more certain (and will rightfully indicate actual attendance).
Either way, the event will need to exist in Advance before you can map registrants/attendees to it. This isn't something we can do for you -- but once it's done, be sure to add the Advance activity code to AlumnIQ in the External Event ID (and/or External Activity ID) field as appropriate. Which one(s) you'll use depends entirely on the level of tracking granularity you're implementing. In most cases the code will reside at the activity level.
Object Model
An event has at least one activity. The activities are what people are signing up to attend.
Reservation = the party. A reservation has one or more Person records under it.
The first Person is the primary registrant, and the one responsible for payment (and hard credited for any gift as a result)
A party may make at most one gift to one fund during checkout.
An individual reservation may have multiple transactions executed against it (this is not how iModules works); keep that in mind as you dig into the financials.
For You
ensure the advance activity codes are added into AlumnIQ
if you want registrants regardless of what they signed up for: GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/attendees?apikey=API_KEY_GOES_HERE
if you only one one activity's worth of registrants: GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/activities/ACTIVITY_ID_GOES_HERE/attendees?apikey=API_KEY_GOES_HERE
DAILY retrieve gifts across all events GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/gifts?giftDate=2021-04-01&apikey=API_KEY_GOES_HERE gifts are safe to pull on a daily basis because they are immutable and non-refundable.
Event Metadata
Events have a lifecycle. Creation, operation, and then closure. Closure is a deliberate action taken by the event manager to say "we're done and the data will not change further." We strongly recommend creating attendance records in Advance ONY for CLOSED events as the data will not subsequently change.
Consider that when choosing how to add event attendee and financial data into Advance.
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events?createdonorafter=2020-06-01&apikey=API_KEY_GOES_HERE
three options for filters:
onOrAfter=yyyy-mm-dd
createdOnOrAfter=yyyy-mm-dd
closedOnOrAfter=yyyy-mm-dd
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE?apikey=API_KEY_GOES_HERE
neat feature: eventid = the AlumnIQ event id. But if you put the Advance event ID on the event, you can also fetch by the Advance event ID using a slightly different syntax.
Advance event ID = b1234
then GET /events/x-b1234 will work too
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/activities?apikey=API_KEY_GOES_HERE
activity metadata
Attendees
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/attendees?apikey=API_KEY_GOES_HERE
all people registered regardless of what they signed up for
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/activities/ACTIVITY_ID_GOES_HERE/attendees?apikey=API_KEY_GOES_HERE
all people signed up for this activity specifically
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/attendees/PERSON_ID_GOES_HERE?apikey=API_KEY_GOES_HERE
an individual human's registration meta
PUT https://{API_BASE_HOSTNAME}/api/v1/index.cfm/attendees/PERSON_ID_GOES_HERE?apikey=API_KEY_GOES_HERE
the mechanism to set an XID for a registrant
Finances and Accounting
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/transactions?txDate=2020-06-01&apikey=API_KEY_GOES_HERE
all transactions regardless of method that happened on that date
primarily helpful for credit card reconciliation purposes
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/gifts?giftDate=2020-06-01&apikey=API_KEY_GOES_HERE
just gifts received and paid on the given date (reminder: only gifts given incidentally as part of event registration)
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/transactions/detail?apikey=API_KEY_GOES_HERE
only the transactions related to a specific event
useful after the event is closed (maybe)
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/balance-sheet?apikey=API_KEY_GOES_HERE
tells you where to put actual dollars post-event closure
GET https://{API_BASE_HOSTNAME}/api/v1/index.cfm/events/EVENT_ID_GOES_HERE/ledger/detail?apikey=API_KEY_GOES_HERE
awesome detail to complement the balance sheet report
tells you how we arrived at the bottom line numbers for this event
Sync/Contact Update Data
We're finalizing the API spec now; detailed docs update to follow.
Most critical data is under three molecule endpoints:
GET /sync/address-change/home
GET /sync/address-change/work
GET /sync/identity-change
Each should be pulled no less frequently than daily using the changedOnDate or changedSinceDate parameter.
Reunion Data
Continue to use the reunion system's API for participation data exfiltration. Remember there's a separate API key for access to that system.
Subscription Preference Data
Daily retrieval of new opt-outs (and resubscribes) to categories based on the category structure implemented as part of the email module onboarding process. NOTE: some unsubscribe data will not come with an XID attached since we do not exclusively require/demand an xid to be attached to every possible recipient of an email.
Email Behavior Data
Last updated