VAN

Overview

The VAN module leverages the VAN API and generally follows the naming convention of their API endpoints. It is recommended that you reference their API documentation to additional details and information.

Note

API Keys

• API Keys are specific to each committee and state, so you might need many.

• Not all API Keys are provisioned for all end points. When requesting API keys, you should specify the endpoints that you need access to.

Warning

VANIDs

VANIDs are unique to each state and instance of the VAN. VANIDs used for the AV VAN will not match those of the SmartVAN or VoteBuilder.

QuickStart

To call the VAN class you can either store the api key as an environmental variable VAN_API_KEY or pass it in as an argument..

from parsons import VAN

 van = VAN(db='MyVoters') # Initiate class via environmental variable api key

 van = VAN(api_key='asdfa-sdfadsf-adsfasdf',db='MyVoters') # Pass api key directly

You can then call various endpoints:

from parsons import VAN

 van = VAN()

 # List events with a date filter
 events = van.get_events(starting_before='2018-02-01')

 # List all folders shared with API Key User
 folders = van.get_folders()

 # Return a dataframe rather than a list of dicts
 saved_lists = van.get_saved_lists().to_dataframe()

This a is just a small sampling of all of the VAN endpoints that you can leverage. We recommend reviewing the documentation for all functions.

Common Workflows

Score: Loading and Updating

Loading a score a multi-step process. Once a score is set to approved, loading takes place overnight.

from parsons import VAN

#Instatiate Class
van = VAN(db="MyVoters")

#List all of the scores / slots
print json.dumps(van.get_scores(), indent=4)

#Input the score slot id
score_slot_id = 34115

#Load the file via the file to VAN
r = van.file_load('score.csv',
              'https://box.com/scores.zip',
              ['vanid','myscore'],
              'vanid',
              'VANID',
               score_slot_id,
               'myscore',
               email='anemailaddress@gmail.com')


# Update Status - The email that you get when it is loaded will include a score update
# id. Pass this to approve the score to be loaded.
#   - Might take a few minutes to get the email
#   - Email will also include some nice stats to QC, included matched rows

van.score_update_status(47187,'approved') # Pass the score update id and set to approved

People: Add Survey Response

The following workflow can be used to apply survey questions, activist codes and canvass reponses.

from parsons import VAN

# Instatiate Class
van = VAN(db="MyVoters")

sq_id = 311838 # Valid survey question id
sr = 1288926 # Valid survey response id
ct = 36 # Valid contact type id
it_id = 4 # Valid input type id

# Create a valid survey question response
sq_response = van.people_sq_response(sq_id,sr_id)
van.people_canvass_response(dwid,
                            key_type='dwid',
                            contact_type_id=ct_id,
                            input_type_id=it_id,
                            responses=sq_response)

Event: Creating and Modifying

Events are made up of sub objects that need to exist to create an event

• Event Object - The event itself

• Event Type - The type of event, such as a Canvass or Phone Bank. These are created in the VAN UI and can be reused for multiple events.

• Locations - An event can have multiple locations. While not required to initially create an event, these are required to add signups to an event.

• Roles - The various roles that a person can have at an event, such as Lead or Canvasser. These are set as part of the event type.

• Shifts - Each event can have multiple shits in which a person can be assigned. These are specified in the event creation.

from parsons import VAN

# Instatiate class
van = VAN(db="EveryAction")

# Create A Location
loc_id = van.location(name='Big `Ol Canvass', address='100 W Washington', city='Chicago', state='IL')

# Create Event
name = 'GOTV Canvass' # Name of event
short_name = 'GOTVCan' # Short name of event, 12 chars or less
start_time = '2018-11-01T15:00:00' # ISO formatted date
end_time = '2018-11-01T18:00:00' # ISO formatted date after start time
event_type_id = 296199 # A valid event type id
roles = [259236] # A list of valid role ids
location_ids = [loc_id] # An optional list of locations ids for the event
description = 'CPD Super Volunteers Canvass' # Optional description of 200 chars or less
shifts = [{'name': 'Shift 1',
           'start_time': '2018-11-01T15:00:00',
           'end_time': '2018-11-11T17:00:00'}] # Shifts must fall within event start/end time.

new_event = van.event_create(name, short_name, start_time, end_time, event_type_id, roles,
                             location_ids=location_ids, shifts=shifts, description=description)

Signup: Adding and Modifying

from parsons import VAN

# Instatiate class
van = VAN(db="EveryAction")

# Create a new signup

vanid = 100349920
event_id = 750001004
shift_id = 19076
role_id = 263920
location_id = 3
role_id = 263920
status_id = 11

# Create the signup. Will return a signup id
signup_id  = van.signup_create(vanid, event_id, shift_id, role_id, status_id, location_id

# Modify a status of the signup
new_status_id = 6
van.signup_update(signup_id, status_id=new_status_id)

People

class parsons.ngpvan.van.People(van_connection)

find_person(first_name=None, last_name=None, date_of_birth=None, email=None, phone=None, street_number=None, street_name=None, zip=None, match_map=None)

Find a person record.

Note

Person find must include the following minimum combinations to conduct a search.

• first_name, last_name, email

• first_name, last_name, phone

• first_name, last_name, zip5, date_of_birth

• first_name, last_name, street_number, street_name, zip5

• email_address

Note

The arguments that can be passed are a selection of the possible values that can be used in a search. A full list of possible values can be found here. To use these values, pass in a dictionary using the match_map argument.

Args:

first_name: str

The person’s first name

last_name: str

The person’s last name

dob: str

ISO 8601 formatted date of birth (e.g. 1981-02-01)

email: str

The person’s email address

phone: str

Phone number of any type (Work, Cell, Home)

street_number: str

Street Number

street_name: str

Street Name

zip: str

5 digit zip code

match_map: dict

A dictionary of values to match against. Will override all other arguments if provided.

fields: The fields to return. Leave as default for all available fields

Returns:

A person dict

upsert_person(first_name=None, last_name=None, date_of_birth=None, email=None, phone=None, street_number=None, street_name=None, zip=None, match_map=None)

Create or update a person record.

Note

Person find must include the following minimum combinations.

• first_name, last_name, email

• first_name, last_name, phone

• first_name, last_name, zip5, date_of_birth

• first_name, last_name, street_number, street_name, zip5

• email_address

Note

The arguments that can be passed are a selection of the possible values that can be used in a search. A full list of possible values can be found here. To use these values, pass in a dictionary using the match_map argument.

Warning

This method can only be run on MyMembers, EveryAction, MyCampaign databases.

Args:

first_name: str

The person’s first name

last_name: str

The person’s last name

dob: str

ISO 8601 formatted date of birth (e.g. 1981-02-01)

email: str

The person’s email address

phone: str

Phone number of any type (Work, Cell, Home)

street_number: str

Street Number

street_name: str

Street Name

zip: str

5 digit zip code

match_map: dict

A dictionary of values to match against. Will override all other arguments if provided.

Returns:

A person dict

get_person(id, id_type='vanid', fields=['emails', 'phones', 'custom_fields', 'external_ids', 'addresses', 'recorded_addresses', 'preferences', 'suppressions', 'reported_demographics', 'disclosure_field_values'])

Returns a single person record using their VANID or external id.

Args:

id: str

A valid id

id_type: str

A known person identifier type available on this VAN instance such as dwid

fields: The fields to return. Leave as default for all available fields

Returns:

A person dict

apply_canvass_result(id, result_code_id, id_type='vanid', contact_type_id=None, input_type_id=None, date_canvassed=None)

Apply a canvass result to a person. Use this end point for attempts that do not result in a survey response or an activist code (e.g. Not Home).

Args:

id: str

A valid person id

result_code_idint

Specifies the result code of the attempt. Valid ids can be found by using the get_canvass_responses_result_codes()

id_type: str

A known person identifier type available on this VAN instance such as dwid

contact_type_idint

Optional; A valid contact type id

input_type_idint

Optional; Defaults to 11 (API Input)

date_canvassedstr

Optional; ISO 8601 formatted date. Defaults to todays date

apply_survey_response(id, survey_question_id, survey_response_id, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)

Apply a single survey response to a person.

Args:

id: str

A valid person id

survey_question_id: int

A valid survey question id

survey_response_id: int

A valid survey response id

id_type: str

A known person identifier type available on this VAN instance such as dwid

result_code_idint

Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()

contact_type_idint

Optional; A valid contact type id

input_type_idint

Optional; Defaults to 11 (API Input)

date_canvassedstr

Optional; ISO 8601 formatted date. Defaults to todays date

toggle_activist_code(id, activist_code_id, action, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)

Apply or remove an activist code to or from a person.

Args:

id: str

A valid person id

activist_code_id: int

A valid activist code id

action: str

Either ‘apply’ or ‘remove’

id_type: str

A known person identifier type available on this VAN instance such as dwid

result_code_idint

Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()

contact_type_idint

Optional; A valid contact type id

input_type_idint

Optional; Defaults to 11 (API Input)

date_canvassedstr

Optional; ISO 8601 formatted date. Defaults to todays date

toggle_volunteer_action(id, volunteer_activity_id, action, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)

Apply or remove a volunteer action to or from a person.

Args:

id: str

A valid person id

id_type: str

A known person identifier type available on this VAN instance such as dwid

volunteer_activity_id: int

A valid volunteer activity id

action: str

Either ‘apply’ or ‘remove’

result_code_idint

Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()

contact_type_id: int

Optional; A valid contact type id

input_type_id: int

Optional; Defaults to 11 (API Input)

date_canvassed: str

Optional; ISO 8601 formatted date. Defaults to todays date

** NOT IMPLEMENTED **

apply_response(id, response, id_type='vanid', contact_type_id=None, input_type_id=None, date_canvassed=None, result_code_id=None)

Apply responses such as survey questions, activist codes, and volunteer actions to a person record. This method allows you apply multiple responses (e.g. two survey questions) at the same time. It is a low level method that requires that you conform to the VAN API response object format.

Args:

id: str

A valid person id

response: dict

A list of dicts with each dict containing a valid action.

id_type: str

A known person identifier type available on this VAN instance such as dwid

result_code_idint

Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()

contact_type_idint

Optional; A valid contact type id

input_type_idint

Optional; Defaults to 11 (API Input)

date_canvassedstr

Optional; ISO 8601 formatted date. Defaults to todays date

responses : list or dict

Returns:

True if successful

response = [{"activistCodeId": 18917,
             "action": "Apply",
             "type": "ActivistCode"},
            {"surveyQuestionId": 109149,
             "surveyResponseId": 465468,
             "action": "SurveyResponse"}
            ]
van.apply_response(5222, response)

create_relationship(vanid_1, vanid_2, relationship_id)

Create a relationship between two individuals

Args:

vanid_1int

The vanid of the primary individual; aka the node

vanid_2int

The vanid of the secondary individual; the spoke

relationship_idint

The relationship id indicating the type of relationship

Returns:

Tuple of (204, No Content) if successful, (404, Not Found).

Activist Codes

class parsons.ngpvan.van.ActivistCodes(van_connection)

Note

To apply or remove activist codes, use the toggle_activist_code() method.

get_activist_codes()

Get activist codes.

Returns:

Parsons Table

See Parsons Table for output options.

get_activist_code(activist_code_id)

Get an activist code.

Args:

activist_code_idint

The activist code id.

Returns:

Parsons Table

See Parsons Table for output options.

Survey Questions

class parsons.ngpvan.van.SurveyQuestions(van_connection)

get_survey_questions(statuses=None, name=None, sq_type=None, question=None, cycle=None, page_size=200)

Get survey questions.

Args:

statuses: str

Comma delimited list of statuses of Survey Questions. One or more of Active (default), Archived, and Inactive.

name: str

Filter to survey questions with names begin with the input

sq_type: str

Filter to survey questions of the given type

question: str

Filter to survey questions with script questions that contain the given input

cycle: str

A year in the format YYYY; filters to Survey Questions with the given cycle

Returns:

Parsons Table

See Parsons Table for output options.

get_survey_question(survey_question_id)

Get a survey question

Returns:

Parsons Table

See Parsons Table for output options.

Events

class parsons.ngpvan.van.Events(van_connection)

get_events(code_ids=None, event_type_ids=None, rep_event_id=None, starting_after=None, starting_before=None, district_field=None, expand=['locations', 'codes', 'shifts', 'roles', 'notes', 'onlineForms'])

Get events.

Args:

code_ids: str

Filter by code id

event_type_ids: str

Filter by event_type_ids

rep_event_id: str

Filters to recurring events that are recurrences the passed event id.

starting_after: str

Events beginning after iso8601 formatted date.

starting_before: str

Events beginning before iso8601 formatted date.

district_field: str

Filter by district field

page_size: str

Not Implemented

expandlist

A list of nested jsons to include in returned event object. Can be locations, codes, shifts, roles, notes, onlineForms.

Returns:

Parsons Table

See Parsons Table for output options.

get_event(event_id, expand=['locations', 'codes', 'shifts', 'roles', 'notes', 'onlineForms'])

Get an event.

Args:

event_id: int

The event id.

expand: list

A list of nested jsons to include in returned event object. Can be locations, codes, shifts, roles, notes, onlineForms.

Returns:

Parsons Table

See Parsons Table for output options.

create_event(name, short_name, start_date, end_date, event_type_id, roles, shifts=None, description=None, editable=False, publicly_viewable=False, location_ids=None, code_ids=None, notes=None, district_field_value=None, voter_registration_batches=None)

Create an event

Args:

name: str

A name for this event, no longer than 500 characters.

short_name: str

A shorter name for this event, no longer than 12 characters.

start_date: str

The start date and time for this event.

end_date: str

The end date and time for this event that is after start_date

event_type_id: int

A valid event type id.

roles: list

A list of valid role ids that correspond the with the event type.

shifts:

A list of dicts with shifts formatted as:

[
    {
     'name': 'Shift 1',
     'start_time': '12-31-2018T12:00:00',
     'end_time': '12-31-2018T13:00:00'
    }
    {
     'name': 'Shift 2',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

description: str

An optional description for this Event, no longer than 500 characters.

editable: boolean

If True, prevents modification of this event by any users other than the user associated the API key. Setting this to true effectively makes the event read-only in the VAN interface.

publicly_viewable: boolean

Used by NGP VAN’s website platform to indicate whether this event can be viewed publicly.

location_ids: list

A list of location_ids where the event is taking place

code_ids: list

A list of codes that are applied to this event for organizational purposes. Note that at most one source code and any number of tags, may be applied to an event.

notes: list

A list of notes

Returns:

The event code

delete_event(event_id)

Delete an event.

Args:

event_id: int

The event id.

Returns:

None

add_event_shift(event_id, shift_name, start_time, end_time)

Add shifts to an event

Args:

event_id: int

The event id.

shift_name: str

The name of the shift

start_time: str

The start time for the shift.

end_time: str

The end time of the shift.

Returns:

None

get_event_types()

Get event types.

Returns:

Parsons Table

See Parsons Table for output options.

Locations

class parsons.ngpvan.van.Locations(van_connection)

get_locations(name=None)

Get locations.

Args:

name: str

Filter locations by name.

Returns:

Parsons Table

See Parsons Table for output options.

get_location(location_id)

Get a location.

Args:

location_id: int

The location id.

Returns:

Parsons Table

See Parsons Table for output options.

create_location(name, address_line1=None, address_line2=None, city=None, state=None, zip_code=None)

Find or create a location. If location already exists, will return location id.

Args:

name: str

A name for this location, no longer than 50 characters.

address_line1: str

First line of a street address.

address_line2: str

Second line of a street address.

city: str

City or town name.

state: str

Two or three character state or province code (e.g., MN, ON, NSW, etc.).

zip_code: str

ZIP, ZIP+4, Postal Code, Post code, etc.

Returns:

A location id

delete_location(location_id)

Delete a location.

Args:

location_id: int

The location id

Returns:

200: OK if successful and 404 Not Found if location not found

Signups

class parsons.ngpvan.van.Signups(van_connection)

Class for ‘/signups’ end points.

get_signups_statuses(event_id=None, event_type_id=None)

Get a list of valid signup statuses for a given event type or event. You may pass either and event_id or an event_type_id but not both.

Args:

event_id: int

A valid event id

event_type_id: int

A valid event type id

Returns:

Parsons Table

See Parsons Table for output options.

get_person_signups(vanid)

Get the signup history of a person.

Args:

vanid: int

A valid vanid associated with a person

Returns:

Parsons Table

See Parsons Table for output options.

get_event_signups(event_id)

Get the signup history of an event.

Args:

event_id: int

A valid event_id associated with an event

Returns:

Parsons Table

See Parsons Table for output options.

get_signup(event_signup_id)

Get a single signup object.

Args:

event_id: int

A valid event_signup_id associated with a signup.

Returns:

Parsons Table

See Parsons Table for output options.

create_signup(vanid, event_id, shift_id, role_id, status_id, location_id)

Create a new signup for an event.

Args:

vanid: int

A valid vanid of the person to signup for the event.

event_id: int

A valid event_id to associate the person with the event

shift_id:

A shift_id, associated with the event to assign the person

role_id:

A role_id, associated with the event to assign the person

status_id:

A status_id of the person

location_id:

A location_id for the event

Returns:

Int

The event signup id

update_signup(event_signup_id, shift_id=None, role_id=None, status_id=None, location_id=None)

Update a signup object. All of the kwargs will update the values associated with them.

Args:

event_signup_id: int

A valid event signup id

shift_id: int

The shift_id to update

role_id: int

The role_id to update

status_id: int

The status_id to update

location_id: int

The location_id to update

Returns:

tuple

If successful (204, No Content)

delete_signup(event_signup_id)

Delete a signup object

Args:

event_signup_id: int

A valid event signup id

Returns:

tuple

If successful (204, No Content)

Codes

class parsons.ngpvan.van.Codes(van_connection)

get_codes(name=None, supported_entities=None, parent_code_id=None, code_type=None)

Get codes.

Args:

namestr

Filter by name of code.

supported_entitiesstr

Filter by supported entities.

parent_code_idstr

Filter by parent code id.

code_typestr

Filter by code type.

Returns:

Parsons Table

See Parsons Table for output options.

get_code(code_id)

Get a code.

Args:

code_idint

The code id.

Returns:

Parsons Table

See Parsons Table for output options.

get_code_types()

Get code types.

Returns:

Parsons Table

See Parsons Table for output options.

create_code(name=None, parent_code_id=None, description=None, code_type='SourceCode', supported_entities=None)

Create a code.

Args:

name: str

The name of the code.

parent_code_id: int

A unique identifier for this code’s parent.

description: str

A description for this code, no longer than 200 characters.

code_type: str

The code type. Tag and SourceCode are valid values.

supported_entities: list

A list of dicts that enumerate the searchability and applicability rules of the code. You can find supported entities with the code_supported_entities()

[
    {
     'name': 'Event',
     'is_searchable': True,
     'is_applicable': True
    }
    {
     'name': 'Locations',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

update_code(code_id, name=None, parent_code_id=None, description=None, code_type='SourceCode', supported_entities=None)

Update a code.

Args:

code_id: int

The code id.

name: str

The name of the code.

parent_code_id: int

A unique identifier for this code’s parent.

description: str

A description for this code, no longer than 200 characters.

code_type: str

The code type. Tag and SourceCode are valid values.

supported_entities: list

A list of dicts that enumerate the searchability and applicability rules of the code. You can find supported entities with the code_supported_entities()

[
    {
     'name': 'Event',
     'is_searchable': True,
     'is_applicable': True
    }
    {
     'name': 'Locations',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

delete_code(code_id)

Delete a code.

Args:

code_id: int

The code id.

Returns:

(204, 'No Content') if successful

get_code_supported_entities()

Get code supported entities.

Returns:

Parsons Table

See Parsons Table for output options.

Canvass Responses

class parsons.ngpvan.van.CanvassResponses(van_connection)

get_canvass_responses_contact_types()

Get canvass response contact types.

Returns:

Parsons Table

See Parsons Table for output options.

get_canvass_responses_input_types()

Get canvass response input types.

Returns:

Parsons Table

See Parsons Table for output options.

get_canvass_responses_result_codes()

Get canvass response result code ids.

Returns:

Parsons Table

See Parsons Table for output options.

Supporter Groups

class parsons.ngpvan.van.SupporterGroups(van_connection)

Class for ‘/activistCodes’ end points.

get_supporter_groups()

Get supporter group objects

Returns:

Parsons Table

See Parsons Table for output options.

get_supporter_group(supporter_group_id)

Get a single supporter group object

Args:

supporter_group_idint

The activist code id associated with the activist code.

Returns:

Parsons Table

See Parsons Table for output options.

create_supporter_group(name, description)

Create a new supporter group

Args:

name: str

The name of the supporter group. 100 character limit

description: str

Optional; A description of the supporter group. 200 character limit.

Returns

Parsons Table with the newly createed supporter group id, name and description

add_person_supporter_group(supporter_group_id, vanid)

Add a person to a supporter group

Args:

supporter_group_id: int

The supporter group id

vanid: int

The vanid of the person to apply

delete_person_supporter_group(supporter_group_id, vanid)

Remove a person from a supporter group

Args:

supporter_group_id: int

The supporter group id

vanid: int

The vanid of the person to remove

Saved Lists

Note

A saved list must be shared with the user associated with your API key to be listed.

class parsons.ngpvan.van.SavedLists(van_connection)

get_saved_lists(folder_id=None)

Get all saved lists

Args:

folder_idint

Optional; the id for a VAN folder. If included returns only the saved lists in the folder

Returns:

Parsons Table

See Parsons Table for output options.

get_saved_list(saved_list_id)

Returns a single saved list object

Args:

saved_list_idint

The saved list id associated with the saved list.

Returns:

Parsons Table

See Parsons Table for output options.

download_saved_list(saved_list_id)

Download a saved list

Args:

saved_list_id

The saved list id associated with the saved list.

Returns:

Parsons Table

See Parsons Table for output options.

Folders

Note

A folder must be shared with the user associated with your API key to be listed.

class parsons.ngpvan.van.Folders(van_connection)

folders()

List all folders

Returns:

Parsons Table

See Parsons Table for output options.

folder(folder_id)

Get a single folder

Args:

folder_id: int

The folder id associated with the folder.

Returns:

Parsons Table

See Parsons Table for output options.

Export Jobs

class parsons.ngpvan.van.ExportJobs(van_connection)

export_job_types()

Lists export job types

Returns:

Parsons Table

See Parsons Table for output options.

export_job_create(list_id, export_type=4, webhookUrl='https://www.nothing.com')

Creates an export job

Currently, this is only used for exporting saved lists. It is recommended that you use the saved_list_download() method instead.

Args:

list_id: int

This is where you should input the list id

export_type: int

The export type id, which defines the columns to export

webhookUrl:

A webhook to include to notify as to the status of the export

Returns:

Parsons Table

See Parsons Table for output options. Includes a download link for the file.

export_job(export_job_id)

Returns a single export job

Args:

export_job_id: int

Export job id

Returns:

Parsons Table

See Parsons Table for output options.

Scores

Prior to loading a score for the first time, you must contact VAN support to request a score slot.

Note

Score Auto Approval

Scores can be automatically set to approved through the file_load function allowing you to skip calling the file_load() function. To automatically approve scores, if the average of the scores is within the fault tolerance specified by the user.It is only available to API keys with permission to automatically approve scores.

class parsons.ngpvan.van.Scores(van_connection)

get_scores()

Get all scores

Returns:

Parsons Table

See Parsons Table for output options.

get_score(score_id)

Get an individual score

Args:

score_id: int

The score id

Returns:

Parsons Table

See Parsons Table for output options.

Score Updates

class parsons.ngpvan.van.ScoreUpdates(van_connection)

get_score_updates(created_before=None, created_after=None, score_id=None)

Get all score updates

Args:

created_before: str

Optional; Filter score updates to those created before date. Use “YYYY-MM-DD” format.

created_after: str

Optional; Filter score updates to those created after date. Use “YYYY-MM-DD” format.

Returns:

Parsons Table

See Parsons Table for output options.

get_score_update(score_update_id)

Get a score update object

Args:

score_update_idint

The score update id

Returns:

Parsons Table

See Parsons Table for output options.

update_score_status(score_update_id, status)

Change the status of a score update object. This end point is used to approve a score loading job.

Args:

score_update_id: str

The score update id

status: str

One of ‘pending approval’, ‘approved’, ‘disapproved’

Returns:

boolean

True if the status update is accepted

File Loading Jobs

class parsons.ngpvan.van.FileLoadingJobs(van_connection)

create_file_load(file_name, file_url, columns, id_column, id_type, score_id, score_column, delimiter='csv', header=True, description=None, email=None, auto_average=None, auto_tolerance=None)

Loads a file. Only used for loading scores at this time. Scores must be compressed using zip.

Args:

file_name: str

The name of the file contained in the zip file.

file_url: str

The url path to directly download the file. Can also be a path to an FTP site.

columns: list

A list of column names contained in the file.

id_column: str

The column name of the id column in the file.

id_type: str

A valid primary key, such as VANID or DWID. Varies by VAN instance.

score_id: int

The score slot id

score_column: str

The column holding the score

delimiter: str

The file delimiter used.

email: str

A valid email address in which file loading status will be sent.

auto_average: float

The average of scores to be loaded.

auto_tolerance: float

The fault tolerance of the VAN calculated average compared to the auto_average. The tolerance must be less than 10% of the difference between the maximum and minimum possible acceptable values of the score.

Returns:

dict

The file load id

create_file_load_multi(file_name, file_url, columns, id_column, id_type, score_map, delimiter='csv', header=True, description=None, email=None)

An iteration of the file_load() method that allows you to load multiple scores at the same time.

Args:

file_namestr

The name of the file contained in the zip file.

file_urlstr

The url path to directly download the file. Can also be a path to an FTP site.

columns: list

A list of column names contained in the file.

id_columnstr

The column name of the id column in the file.

id_typestr

A valid primary key, such as VANID or DWID. Varies by VAN instance.

score_maplist

A list of dicts that adheres to the following syntax

[{'score_id' : int,
  'score_column': str,
  'auto_average': float,
  'auto_tolerance': float }]

email: str

A valid email address in which file loading status will be sent.

Returns:

The file load job id