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.

Pages

Before you can record actions that Users take using your ActionKit instance, you'll need to create some Pages. Pages are the way you tell ActionKit that you're going to create a webpage to let Users take an Action.

Pages and Actions work together. You create the Page and the User takes the Action. For example, if you create a SignupPage, then a User signs up on that Page, the result will be a SignupAction.

The API gives you a way to create simple Pages remotely. There are some simple examples of creating Pages using the API below. You can also create pages using the admin and use them from the API.

Pages are broken down into three "sections" - the page object, a cms form and a page followup. Different page types have slightly different fields on both the page object and the cms form. See :doc:`the reference <reference>`_ for details of a particular page type or form.

Once you've created some Pages, you should read about Processing User Actions.

Page Types

The following PageTypes exist in ActionKit.

  • Call - Call
  • Donation - Donation
  • EventCreate - Event creation
  • EventSignup - Event signup
  • Import - Import
  • Letter - Letter
  • LTE - Letter to the editor
  • Petition - Petition
  • RecurringDonationCancel - Cancel recurring donation
  • RecurringDonation - Recurring Donation
  • RecurringDonationUpdate - Update recurring donation
  • Signup - Signup
  • Survey - Survey
  • Unsubscribe - Unsubscribe
  • UserUpdate - Update contact info

We've documented how to create the simplest Page Types below.

Page

All Pages inherit from Page and share the following fields:

  • name - Used in the page URL unless you self-host. Only letters, numbers, dashes, and underscores.
  • title
  • canonical_url - Set automatically for ActionKit hosted pages, set directly to redirect users to an external url.
  • type - Set based on the subclass, e.g. petition for a PetitionPage
  • lang - Language
  • goal - a numeric goal
  • goal_type - actions, dollars
  • status - active, draft, expired, deleted, sample
  • tags - list of Tags
  • list - a List
  • required_fields - list of FormFields

Only the fields name and title are required. Don't create Page instances directly, call create on one of the subclasses.

SignupPage

Signup pages are the simplest type of Page. All you need to create a signup page is a name for the page. Names must be unique.

Use SignupPages for your homepage, splash pages, anywhere you want to let members signup with a minimum of information.

By default, Users who take an action using this type of Page must provide email and zip. You can set the list of required fields for a page in the admin on the Edit Content screen.

>>> actionkit = Server('https://%s:%s@%s/api/', (user,password,hostname))
>>> page = actionkit.SignupPage.create({'title' : 'My New Signup Page',
                                        'name'  : 'mynewsignuppage',
                                        'goal'  : 1000 })
{'created_at': '2011-05-24T10:21:15',
 'custom_fields': {},
 'goal': 1000,
 'goal_type': 'actions',
 'hidden': 0,
 'hosted_with': 1,
 'id': 31,
 'lang': None,
 'list': 1,
 'multilingual_campaign': None,
 'name': 'mynewsignuppage',
 'required_fields': [],
 'status': 'active',
 'tags': [],
 'title': 'My New Signup Page',
 'type': 'Signup',
 'updated_at': '2011-05-24T12:21:30',
 'url': ''}

ImportPage

An ImportPage lets you import users, creating an easy to find record of which Users were imported.

Please read Importing User Data before using an ImportPage directly.

If you are importing Users from a single partner action, you probably want to create a PetitionPage with the appropriate text to be able to use the petition tools.

If you are importing Users from another system, where the Users have taken many actions but you don't have time to import the full action history, an ImportPage is just right.

import xmlrpclib
import sys

actionkit = xmlrpclib.Server('https://%s:%s@%s/api/' % (user,password,host))

import_page = actionkit.ImportPage.save_or_create(
                { 'name': 'from_my_previous_system_import' })

actionkit.PageFollowup.create({ 'page': import_page['id'],
                  'send_email': False })

field_names = [ 'email', 'zip', 'first_name', 'last_name' ]

imported = 0
new = 0

for line in sys.stdin:

    line = line.strip()
    flds = line.split(';')

    action = {}
    for i in range(len(flds)):
       action[field_names[i]] = flds[i]

    action['page'] = 'from_my_previous_system_import'

    response = actionkit.act(action)

    if response['success']:
        imported += 1
        if response['action']['created_user']:
            new += 1
    else:
        print >>sys.stderr, 'Unable to import line: %s' % line

print "Imported %s" % imported
print "Created  %s" % new

Custom Page Fields

A custom page field is a custom attribute for a page. It could be something like "background_color" which your editors could use during page setup to affect the look of the page. A custom page field has a single value.

Custom page fields are included in all Pages returned by the API.

You can set custom fields via the API using the method set_custom_fields. Any type of Page can have custom fields.

You can only set a custom field that has been added as an AllowedPageField. You can create AllowedPageFields via the API or in the Custom Page Fields section of the admin.

You can remove custom fields by calling clear_custom_fields. Calling clear_custom_fields with only a Page id, will remove all the custom fields for that page. Any additional parameters given to clear_custom_fields are used to search for fields to delete.

actionkit.AllowedPageField.create({ 'name': 'background', })
actionkit.AllowedPageField.create({ 'name': 'foreground', })

signup = actionkit.SignupPage.create(dict(name='test_api_subscription'))

actionkit.SignupPage.set_custom_fields(dict(
    id=signup['id'], background='white', foreground='black'))

signup = actionkit.SignupPage.get(id=signup['id'])
custom_fields = signup['custom_fields']

print custom_fields['background'] # 'white'
print custom_fields['foreground'] # 'black'

custom_fields = \
        actionkit.SignupPage.get_custom_fields(dict(id=signup['id']))

print custom_fields['background'] # 'white'
print custom_fields['foreground'] # 'black'

actionkit.SignupPage.clear_custom_fields(dict(id=signup['id'],
                                              name='background'))

actionkit.SignupPage.clear_custom_fields(dict(id=signup['id'],))

CMS Forms

If your Pages are being hosted on ActionKit, each Page will have related Form object with a few additional fields that control how it is rendered. You can create and update these Forms via the API. There is a one-to-one relationship between Forms and Pages. You cannot create more than one Form per Page.

The Form classes are named <PageType>Form, e.g. SignupPages have SignupForms. Each Form class has slightly different fields, refer to the :doc:`full reference <reference>`_ for the details of each Form.

All Forms share the following fields. Page is the only field you must provide.

  • page - The ActionKit page associated with this Form. This is a unique key, one Form per Page. Required.
  • client_hosted - True or False, defaults to False.
  • client_url - If client_hosted is True, this is where the page lives
  • templateset - The TemplateSet used to display this Form, assigned the default TemplateSet automatically.
  • thank_you_text - Thank you text to be displayed on the thank you page.

Here's an example of creating a SurveyPage, a SurveyForm and a few SurveyQuestions:

>>> survey = actionkit.SurveyPage.create(dict(name='mysurveypage',
...                                           title='My Survey Page'))
>>> form = actionkit.SurveyForm.create(dict(page=survey['id'],
...                                         client_hosted=False,
...                                         introduction_text='Answer!'))
>>> one = actionkit.SurveyQuestion.create(dict(
...     survey_form=form['id'],
...     question_label='label one',
...     question_html='<input type="text" name="action_question_one" />'
... ))
>>> two = actionkit.SurveyQuestion.create(dict(
...     survey_form=form['id'],
...     question_label='label two',
...     question_html='<input type="text" name="action_question_two" />'
... ))

PageFollowup

All pages allow you to assign a PageFollowup page with details for a confirmation email and a redirect.

Example:

>>> signup = actionkit.Page.get({id=2})
>>> followup = actionkit.PageFollowup.create({
...                 'page_id': signup['id'],
...                 'email_body': """Dear {{ user.first_name }},\n\nThanks for signing up!  You won't regret it.  \n\nThanks for all you do.  \n--\nThe Robotic Dogs Team """,
...                 'email_custom_from': 'Marmaduke <marmaduke@example.com>',
...                 'email_subject': 'Thanks!',
...                 'url': 'http://act.roboticdogs.me/thanks/%s' % signup['name'],
...                 'send_email':True
...             })

You can disable the sending of a confirmation email on an existing PageFollowup by saving it with send_email set to False.

Example:

>>> actionkit.PageFollowup.save({'id':followup['id'],'send_email':False})