Action Builder

Overview

Action Builder is an online tool for field organizing, with an original use-case designed for the Labor context. While it has essentially no built-in outreach capabilities, it does provide robust record and relationship storage, including the ability to create custom record types. For more information, see Action Builder developer docs

Note

Custom Fields/Tags

Action Builder custom fields are treated as tags in both the SQL Mirror, and the API. This means that, with a couple exceptions such as date, values must be created ahead of time to be applied to a record. Each tag has two layers of taxonomy above it as well, that appear slightly differently in the SQL Mirror and in the API. In the SQL Mirror, each tag has a tag_category, and each category has a tag_group. In the API, the equivalents are called tag_field and tag_section, respectively (closer to the naming in the UI). Tags can be applied on Connections as well as on Entities.

Quick Start

To instantiate a class, you can either pass in the API token as an argument or set the ACTION_BUILDER_API_TOKEN environmental variable. The subdomain at which you access the UI must also be provided. If all calls from this object will be to the same Campaign in Action Builder, an optional campaign argument may also be supplied. If not supplied when instantiating, campaign may be passed to individual methods, instead.

from parsons import ActionBuilder

# First approach: Use API credentials via environmental variables
bldr = ActionBuilder(subdomain='yourorgsubdomain')

# Second approach: Pass API credentials as arguments
bldr = ActionBuilder(api_token='MY_API_TOKEN', subdomain='yourorgsubdomain')

# Third approach: Include campaign argument
     bldr = ActionBuilder(
             api_token = 'MY_API_TOKEN',
             subdomain = 'yourorgsubdomain',
             campaign = 'your-desired-campaign-id'
     )

You can then call various endpoints:

API

class parsons.ActionBuilder(api_token=None, subdomain=None, campaign=None)

Args:

api_token: str

The OSDI API token

subdomain: str

The part of the web app URL preceding ‘.actionbuilder.org’

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Can also be supplied in individual methods in case multiple campaigns need to be referenced.

get_campaign_tags(campaign=None, limit=None, per_page=25, filter=None)

Retrieve all tags (i.e. custom field values) within provided limit and filters Args:

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

limit: int

The number of entries to return. When None, returns all entries.

per_page: int

The number of entries per page to return. 25 maximum and default.

filter

The OData query for filtering results. E.g. “modified_date gt ‘2014-03-25’”. When None, no filter is applied.

Returns:

Parsons Table of full set of tags available in Action Builder.

get_tag_by_name(tag_name, campaign=None)

Convenience method to retrieve data on a single tag by its name/value Args:

tag_name: str

The value of the tag to search for.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Parsons Table of data found on tag in Action Builder from searching by name.

insert_new_tag(tag_name, tag_field, tag_section, campaign=None)

Load a new tag value into Action Builder. Required before applying the value to any entity records. Args:

tag_name: str

The name of the new tag, i.e. the custom field value.

tag_field: str

The name of the tag category, i.e. the custom field name.

tag_section: str

The name of the tag section, i.e. the custom field group name.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Dict containing Action Builder tag data.

insert_entity_record(entity_type, data=None, campaign=None)

Load a new entity record in Action Builder of the type provided. Args:

entity_type: str

The name of the record type being inserted. Required if identifiers are not provided.

data: dict

The details to include on the record being upserted, to be included as the value of the person key. See [documentation for the Person Signup Helper](https://www.actionbuilder.org/docs/v1/person_signup_helper.html#post) for examples, and [the Person endpoint](https://www.actionbuilder.org/docs/v1/people.html#field-names) for full entity object composition.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Dict containing Action Builder entity data.

update_entity_record(identifier, data, campaign=None)

Update an entity record in Action Builder based on the identifier passed. Args:

identifier: str

The unique identifier for a record being updated. ID strings will need to begin with the origin system, followed by a colon, e.g. action_builder:abc123-….

data: dict

The details to include on the record being upserted, to be included as the value of the person key. See [documentation for the Person Signup Helper](https://www.actionbuilder.org/docs/v1/person_signup_helper.html#post) for examples, and [the Person endpoint](https://www.actionbuilder.org/docs/v1/people.html#field-names) for full entity object composition.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Dict containing Action Builder entity data.

add_section_field_values_to_record(identifier, section, field_values, campaign=None)

Add one or more tags (i.e. custom field value) to an existing entity record in Action Builder. The tags, along with their field and section, must already exist (except for date fields). Args:

identifier: str

The unique identifier for a record being updated. ID strings will need to begin with the origin system, followed by a colon, e.g. action_builder:abc123-….

section: str

The name of the tag section, i.e. the custom field group name.

field_values: dict

A collection of field names and tags stored as keys and values.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Dict containing Action Builder entity data of the entity being tagged.

remove_tagging(identifier=None, tag_id=None, tag_name=None, tagging_id=None, campaign=None)

Remove one or more tags (i.e. custom field value) from an existing entity or connection record in Action Builder. The basis for this end point is the combination of the tag’s interact ID and that of the specific tagging. The tag ID can usually be determined from the tag’s name, and the tagging ID can be derived if the identifier of the entity or connection record is supplied instead. Args:

identifier: str

Optional. The unique identifier for an entity or connection record being updated. If omitted, tagging_id must be provided.

tag_id: str

Optional. The unique identifier for the tag being removed. If omitted, tag_name must be provided.

tag_name: str

Optional. The exact name of the tag being removed. May result in an error if multiple tags (in different fields/sections) have the same name. If omitted, tag_id must be provided.

tagging_id: str

Optional. The unique identifier for the specific application of the tag to an individual entity or connection record. If omitted, identifier must be provided.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

API response JSON which contains {‘message’: ‘Tag has been removed from Taggable Logbook’} if successful.

upsert_connection(identifiers, tag_data=None, campaign=None, reactivate=True)

Load or update a connection record in Action Builder between two existing entity records. Only one connection record is allowed per pair of entities, so if the connection already exists, this method will update, but will otherwise create a new connection record. Args:

identifiers: list

A list of two unique identifier strings for records being connected. ID strings will need to begin with the origin system, followed by a colon, e.g. action_builder:abc123-…. Requires exactly two identifiers.

tag_data: list

List of dicts of tags to be added to the connection record (i.e. Connection Info). See [documentation on Connection Helper](https://www.actionbuilder.org/docs/v1/connection_helper.html#post) for examples.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

reactivate: bool

Optional. Whether or not to set the inactive flag on a given Connection to False if the Connection exists and has inactive set to True. True by default.

Returns:

Dict containing Action Builder connection data.

deactivate_connection(from_identifier, connection_identifier=None, to_identifier=None, campaign=None)

Deactivate an existing connection record in Action Builder between two existing entity records. Only one connection record is allowed per pair of entities, so this can be done by supplying the ID for the connection record, or for the two connected entity records. Args:

from_identifier: str

Unique identifier for one of the two entities with a connection.

connection_identifier: str

Optional. The unique identifier for an entity or connection record being updated. If omitted, to_identifier must be provided.

to_identifier: str

Optional. The second entity with a connection to from_entity. If omitted, connection_identifier must be provided.

campaign: str

Optional. The 36-character “interact ID” of the campaign whose data is to be retrieved or edited. Not necessary if supplied when instantiating the class.

Returns:

Dict containing Action Builder connection data.