Record Canvass Helper

This document defines the Record Canvass Helper resource.

The Record Attendance Helper is a helper endpoint to aid in the creation of Canvass, Answer, Tagging, and Item (list membership) resources via POST. It provides a quick and easy way to create a canvass as well as all the data collected during that canvass, eliminating the need for multiple POST operations to store that information.

In addition, you can indicate to the server whether to trigger additional actions, such as an autoresponse email sent back to the person who took action.

The Record Canvass Helper assumes that the person who was canvassed (the “target”) already exists in the system.

Typically, the response to a successful Record Canvass Helper POST is the full representation of the Canvass. However, the Record Canvass Helper can be used without authentication, allowing for use in frontend javascript-based applications without giving away API key secrets, for example. If no authentication is passed, the response on success will simply be the server response code (ex: 200) and an empty JSON object. On error, the server response code (ex: 404, 500) plus an error message may be returned.

Some initial implementations may only support helpers – direct RESTful access may not be supported. In those cases, the _links section may be omitted in responses.

Sections:

Endpoints and URL structures

OSDI does not specify specific endpoints and link structures for compliant systems to use. Rather, because OSDI is a HAL+JSON API, endpoints and structures are defined in the links section of each returned resource, starting with the API Entry Point link.

HAL’s link structure lets an API consumer move through API levels, resources, and collections by parsing and following links. While most systems will not change the value of their links often and obey RESTful design principles, the value of each link when that resource is retrieved is the only canonical value, and it can change at any time.

The link relation label for the Record Canvass Helper is osdi:record_canvass_helper.

Back to top…

Fields

The field names for this resource, with standard names, punctuation and capitalization, and values where appropriate.

Note: As with the entire OSDI specification, the specific fields a compliant system implements will vary between each system, as will the fields each system requires when creating or updating resources, which fields are writeable, and the operations you are allowed to perform on each resource.

Common Fields

A set of common fields that appear on all resources is included first, for reference.

Name Type Description
identifiers strings[] A unique string array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.

Control Headers

An “osdi:control” JSON object may contain common OSDI control headers which can be used on an OSDI POST, PUT, PATCH, Helper or other function calls to modify server behavior. Read More

Name Type Description
return_response boolean Defaults to true, if specified as false, the operation does not need to return the resource representation in the response

Back to top…

Record Canvass Helper Fields

A list of fields specific for POSTing via the Record Canvass Helper. Please note that the target of a canvass (the person who has been canvassed) is indicated by the Person identifier in the route.

Name Type Description
origin_system string A human readable identifier of the system where this attendance was created. (ex: “OSDI System”)
action_date string The date and time the canvass was attempted.
contact_type string A code indicating the method by which the person was contacted. For example: “in-person”
input_type string A code indicating the method by which the canvass is being input into the system. For example: “mobile”
success boolean True if the target was successfully contacted, False otherwise.
status_code string A code indicating the status of the contact attempt. For example: “not-home” indicates that the contact failed because the target was not home, while “success” indicates that the target was contacted successfully. An empty or missing value for status_code should be assumed to mean that the contact was successful.
canvasser Person* A link to a single Person resource representing the person who made the contact.
question_response Question Response An object hash of key/value pairs associated with the person created by a user rather than a service or vendor.

Back to top…

Helper Action Functions

Helper Action Functions are additional actions that the OSDI server will perform along with inserting or updating the associated person.

Name Type Description
add_tags strings[] An array of tag names corresponding to previously created tags to add to this person when it is created.
add_tags_uri strings[] An array of tag URIs corresponding to previously created tags to add to this person when it is created.
add_lists strings[] An array of list names corresponding to previously created lists to add to this person when it is created.
add_lists_uri strings[] An array of list URIs corresponding to previously created lists to add to this person when it is created.
add_questions_responses_uri QuestionResponseObject An array of Question Response Objects, indicating answers which should be applied to the person.
triggers Triggers An object hash representing responses a user would like to trigger from the server as part of the POST, such as sending an autoresponse email back to the person who took action with this helper.

Question Response Object Fields

Name Type Description
question string The identifier for the Question which is being answered
responses string[] One or more responses to the Question, if the corresponding question_type is SingleChoice or MultiChoice; should be a subset of the responses available for the question
value string A free-text response to the question, if the corresponding question_type is Paragraph.

Triggers

Here autoresponse identifiers are handled independent of the OSDI specification’s identifier schema. The autoresponse sent is determined by the server that is being interacted with, the system, and the id. Three types of autoresponse triggers are defined below and those types should follow this specification and format.

Name Type Description
autoresponse object An object hash representing the autoresponse email trigger type.
autoresponse.enabled boolean A boolean indicating whether the autoresponse email should be sent or not.
autoresponse.identifiers strings[] A unique string array of identifiers in the format [system name]:[id].
Name Type Description
sms_response object An object hash representing the autoresponse sms trigger type.
sms_response.enabled boolean A boolean indicating whether the autoresponse sms should be sent or not.
sms_response.identifiers strings[] A unique string array of identifiers in the format [system name]:[id].
Name Type Description
call_response object An object hash representing the autoresponse call trigger type.
call_response.enabled boolean A boolean indicating whether the autoresponse call should be sent or not.
call_response.identifiers strings[] A unique string array of identifiers in the format [system name]:[id].

Back to top…

These JSON hashes included in the table above are broken out into their own tables for readability, rather than independent resources with their own endpoints.

Question Response

Name Type Description
question Question* A question to which an Answer is being added
value string The response the person gave, if the question type is “Paragraph” or if otherwise appropriate (e.g., if the question response was “Other”).
responses string[] An array of strings corresponding to the question response key(s) chosen by the Person who answered the Question.

Back to top…

Back to top…

Scenarios

The scenarios below show common create (POST) operations that can be performed on this helper. While the canonical definitions of fields are above, these examples should be complete as well.

Scenario: Creating a new canvass (POST)

Posting to the record canvass helper endpoint will allow you to create a new canvass and the associated answers and/or taggings in one operation. The response is the attendance that was created. While each implementing system will require different fields, any optional fields not included in a post operation should not be set at all by the receiving system, or should be set to default values.

Request

POST https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/record_canvass_helper

Header:
OSDI-API-Token:[your api key here]

{
    "canvass": {
      "origin_system": "OSDI Sample System",
      "action_date": "2014-03-18T11:02:15Z",
      "contact_type": "in-person",
      "input_type": "mobile",
      "success": true,
      "status_code": "",
    },
    "triggers": {
        "autoresponse": {
            "identifiers": [
                "system_1:eb84f0d01dec3b1ffb9e4dca406fa45e", 
                "system_2:15117b282328146ac6afebaa8acd80e7"
            ],
            "enabled": true
        },
        "sms_response": {
            "identifiers": [
                "system_1:efe398db3439be6bbf00d90e693ec3a3"
            ],
            "enabled": true
        },
        "call_response": {
            "identifiers": [
                "system_1:83069490-8a17-4131-b13e-f9a44d2b7646"
            ],
            "enabled": true
        }
    },
    "add_tags": [
        "volunteer",
        "donor"
    ],
    "add_tags_uri": [
        "https://osdi-sample-system.org/api/v1/tags/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
    ],
    "add_lists": [
        "supporters"
    ],
    "add_lists_uri": [
        "https://osdi-sample-system.org/api/v1/lists/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
    ],
    "add_questions_responses_uri": [
      {
        "question": "https://osdi-sample-system.org/api/v1/questions/c945d6fe-929e-11e3-a2e9-12313d316c29",
        "responses": [ "r1", "r2", "r2"]
      },
      {
        "question": "https://osdi-sample-system.org/api/v1/questions/c945d6fe-929e-11e3-a2e9-12313d316c2a",
        "value": "Heard about the candidate at the Labor Day Picnic"
      }
    ]
}

Response

200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{
    "identifiers": [
        "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
        "foreign_system:1"
    ],
    "origin_system": "OSDI Sample System",
    "created_date": "2014-03-20T21:04:31Z",
    "modified_date": "2014-03-20T21:04:31Z",
    "action_date": "2014-03-18T11:02:15Z",
    "contact_type": "in-person",
    "input_type": "mobile",
    "success": true,
    "status_code": "",
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/canvasses/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
        },
        "osdi:canvasser": {
            "href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316444"
        },
        "osdi:target": {
            "href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
        },
        "osdi:answers": {
            "href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/canvasses/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/answers"
        },
        "osdi:taggings": {
            "href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/canvasses/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/taggings"
        }
    }
}

Back to top…

Scenario: Creating a new canvass without authentication (POST)

Posting to the record canvass helper endpoint without authentication will allow you to create a new canvass and the associated answers and/or taggings in one operation, but without giving away API key secrets or leaking data, so this method is appropriate for frontend javascript applications. The response on success will simply be the server response code (ex: 200) and an empty JSON object. On error, the server response code (ex: 404, 500) plus an error message may be returned. While each implementing system will require different fields, any optional fields not included in a POST operation should not be set at all by the receiving system, or should be set to default values.

Request

POST https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/record_canvass_helper

{
    "canvass": {
      "origin_system": "OSDI Sample System",
      "action_date": "2014-03-18T11:02:15Z",
      "contact_type": "in-person",
      "input_type": "mobile",
      "success": true,
      "status_code": "",
    },
    "triggers": {
        "autoresponse": {
            "identifiers": [
                "system_1:eb84f0d01dec3b1ffb9e4dca406fa45e", 
                "system_2:15117b282328146ac6afebaa8acd80e7"
            ],
            "enabled": true
        },
        "sms_response": {
            "identifiers": [
                "system_1:efe398db3439be6bbf00d90e693ec3a3"
            ],
            "enabled": true
        },
        "call_response": {
            "identifiers": [
                "system_1:83069490-8a17-4131-b13e-f9a44d2b7646"
            ],
            "enabled": true
        }
    },
    "add_tags": [
        "volunteer",
        "donor"
    ],
    "add_tags_uri": [
        "https://osdi-sample-system.org/api/v1/tags/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
    ],
    "add_lists": [
        "supporters"
    ],
    "add_lists_uri": [
        "https://osdi-sample-system.org/api/v1/lists/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
    ],
    "add_questions_responses_uri": [
      {
        "question": "https://osdi-sample-system.org/api/v1/questions/c945d6fe-929e-11e3-a2e9-12313d316c29",
        "responses": [ "r1", "r2", "r2"]
      },
      {
        "question": "https://osdi-sample-system.org/api/v1/questions/c945d6fe-929e-11e3-a2e9-12313d316c2a",
        "value": "Heard about the candidate at the Labor Day Picnic"
      }
    ]
}

Response

200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{}

Back to top…