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. .. toctree:: :maxdepth: 1 ********** 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.. .. code-block:: python 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: .. code-block:: python 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. .. code-block:: python 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. .. code-block:: python 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. .. code-block:: python 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 ============================ .. code-block:: python 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 ****** .. autoclass:: parsons.ngpvan.van.People :inherited-members: ************** Activist Codes ************** .. autoclass:: parsons.ngpvan.van.ActivistCodes :inherited-members: ***************** Survey Questions ***************** .. autoclass:: parsons.ngpvan.van.SurveyQuestions :inherited-members: ****** Events ****** .. autoclass:: parsons.ngpvan.van.Events :inherited-members: ********* Locations ********* .. autoclass:: parsons.ngpvan.van.Locations :inherited-members: ******* Signups ******* .. autoclass:: parsons.ngpvan.van.Signups :inherited-members: ***** Codes ***** .. autoclass:: parsons.ngpvan.van.Codes :inherited-members: ***************** Canvass Responses ***************** .. autoclass:: parsons.ngpvan.van.CanvassResponses :inherited-members: **************** Supporter Groups **************** .. autoclass:: parsons.ngpvan.van.SupporterGroups :inherited-members: *********** Saved Lists *********** .. note:: A saved list must be shared with the user associated with your API key to be listed. .. autoclass:: parsons.ngpvan.van.SavedLists :inherited-members: ******* Folders ******* .. note:: A folder must be shared with the user associated with your API key to be listed. .. autoclass:: parsons.ngpvan.van.Folders :inherited-members: *********** Export Jobs *********** .. autoclass:: parsons.ngpvan.van.ExportJobs :inherited-members: ****** 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 :meth:`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. .. autoclass:: parsons.ngpvan.van.Scores :inherited-members: ************* Score Updates ************* .. autoclass:: parsons.ngpvan.van.ScoreUpdates :inherited-members: ***************** File Loading Jobs ***************** .. autoclass:: parsons.ngpvan.van.FileLoadingJobs :inherited-members: