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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.

remove_entity_record_from_campaign(identifier, campaign=None)[source]

Remove an entity record from a campaign. Records cannot be permanently deleted, but a record that has been removed from a campaign will not appear in the UI. Args:

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

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 with HTTP response.

add_section_field_values_to_record(identifier, section, field_values, campaign=None)[source]

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)[source]

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)[source]

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)[source]

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.