Warning

The XML-RPC API is no longer under active development. While it is still supported, no further improvements or changes will be made to it.

We strongly recommend that you use the REST API instead.

Events

The APIs for the event system should be familiar if you've used ActionKit's database APIs. The main event-specific changes and additions are:

  • We'll send email when you use the API cancel someone's event signup, or change their role between host and attendee. You can disable this with suppress_email=True.
  • We'll do extra internal bookkeeping after some database updates. For example, creating an EventSignup can also create an EventSignupAction, and event addresses are geocoded before saving.
  • We provide some extra search methods like advanced_search() and public_search().

These APIs are low-level -- as close to direct database access as we can manage -- and they might or might not be the right way to do your particular extensions. Also consider:

  • Using the act() API. In particular, use act() if you want the normal "thanks" messages to be sent when someone signs up for or creates an event.
  • Customizing event pages and emails through the templateset editor.
  • Embedding event search/signup/creation forms on your own site. (Host and attendee tools aren't embeddable.)
  • Getting reports with SQL, either on client-db or through the reporting system in the admin.

Finally, if none of these customizations or the API work for your application, it might not be a good fit for our event system. Feel free to contact us to talk about it.

Managing Events

Before this code works, you'll need to create an event campaign and the corresponding event creation/signup pages through the admin.

e = actionkit.Event.create(dict(
    campaign_id=1,

    title=u'Test event',

    venue=u'Home',
    address1=u'3026 harper',
    zip=u'94703',

    starts_at=datetime.datetime(2099, 12, 31, 23, 59, 59),

    max_attendees=50L,
    creator_id=1L,
    public_description=u'beep'
))

The user whose ID you pass in creator_id is automatically signed up as a host (but isn't sent an email).

By default, events are created already confirmed and approved, and starts_at and title are set to the campaign's defaults. Addresses are normalized and geocoded.

create() doesn't send a thanks message to the host -- use the act() API if you want that.

Not all of the normal event validation applies, so be careful.

You can also update an event's location, time, etc. Updating an event's status to 'cancelled' or 'deleted' will also notify all of the users that the event is cancelled. Use suppress_email=True to stop the email notifications.

# Update settings (or event time, address, etc.)
actionkit.Event.update(dict(
    id=123,
    is_private=True
))

# Cancel event, sending email
actionkit.Event.update(dict(
    id=123,
    status='cancelled'
))

The main columns to know about are:

  • campaign_id (required)
  • creator_id (required; user ID of creator)
  • address1
  • address2
  • city
  • state
  • zip
  • plus4
  • country
  • title
  • max_attendees
  • venue
  • public_description
  • directions
  • note_to_attendees

Other columns are:

  • id
  • region
  • postal
  • created_at
  • updated_at
  • longitude
  • latitude
  • starts_at
  • ends_at
  • status
  • host_is_confirmed
  • is_private
  • is_approved
  • attendee_count
  • phone ("event contact phone")
  • notes

Managing Signups

You can create a signup with a user ID, akid, or email.

attendee = actionkit.EventSignup.create(dict(
    user_id=123,
    event_id=1
))
attendee2 = actionkit.EventSignup.create(dict(
    akid='1.2.abCde',
    event_id=1
))
attendee3 = actionkit.EventSignup.create(dict(
    email='moose@wawd.com',
    event_id=1
))

Adding signups this way doesn't send a thanks email. To do that, use act:

signup = actionkit.act({
    'event_id': 1,
    'page': 'fun_attend',
    'akid': '.2.abCde',
    'event_signup_ground_rules': '1',
})

You can also use a user ID or email. Notice that you need to 'act' on an 'attend' page, and need to signal agreement with the ground rules.

The API can also cancel users' signups and change hosts to attendees and vice versa; you do it by updating a signup's status or role fields. Unless you pass suppress_email=True, these will email the user a notification:

# Cancel user's signup
actionkit.EventSignup.update(dict(
    user_id=123,
    event_id=123,
    status='deleted'
))

# Promote an existing attendee to host
actionkit.EventSignup.update(dict(
    user_id=123,
    event_id=123,
    role='host'
))

Campaign Info

There are a couple of barebones methods to retrieve info and statistics about a campaign:

campaign = ak.EventCampaign.get(dict(id=1))
stats = ak.EventCampaign.stats(dict(id=1))

The campaign object includes the info entered on the "Campaign settings" page in the admin. The stats object includes counts of signups in a few categories (active signups (broken down into active hosts and active attendees), cancelled/deleted) and events in various categories (open, cancelled, etc.) as well as the path to the "browse events" page in the admin for each category.