Developer Blog Series: Volunteer API Preview

Halley Coplin
Halley Coplin
Ninth Anniversary Kudos 1 Participant Facilitator 1
in SKY Developer Announcements


As I'm sure many of you know, the volunteer module for Raiser's Edge includes a set of robust and powerful entities to track volunteer efforts, and Blackbaud has relied on partners and clients to build great things on top of these entities. We want to continue that tradition by delivering the Volunteer API as our next big release under the SKY API umbrella.

 

However, before we go too far down that line, I want to solicit feedback to ensure that we deliver the best possible experience in the top priority order for developers like you. To that end, I want to walk through our tentative plans for the Volunteer API. Hopefully this will inspire creative app ideas and constructive feedback to help us determine if we are headed down the right path with this functionality. The opportunity to improve volunteer experiences for our users is a big part of why I work at Blackbaud, so this API is particularly near and dear to my heart.

 

First, I will outline the entities, and then I will enumerate the endpoints that we intend to surface in a rough priority order. I encourage you to provide feedback on both aspects of the total feature set by sharing your use cases and letting us know what entities and endpoints are most important to your applications' desired functionality.

 

Volunteer API Entities

Volunteer Summary

Type  Description  string  The constituent identifier for the volunteer.  integer  The first year the constituent volunteered. decimal  This computed field calculates the total number of hours the volunteer has contributed. currency  This computed field calculates the total value of the time contributed by the volunteer. integer  This computed field calculates the total number of years the constituent has volunteered. volunteer assignment  The first assignment the volunteer had at the organization. volunteer assignment  The most recent assignment the volunteer had at the organization.

Property 

constituent_id 

first_year_volunteered 

total_hours 

total_value 

total_years_volunteered 

first_assignment 

last_assignment 

 

 

Assignment

Type  Description  sting The assignment identifier. string  The identifier of the job the assignment is for. string  The location of the assignment. Available values are the entries in the Locations table, found in the Constituent API. string  The department associated with the assignment. Available values are the entries in the Departments table, found in the Constituent API. dateTime  The date and time when the assignment starts. Uses ISO-8601 format: 1969-11-21T10:29:43. dateTime  The date and time when the assignment ends. Uses ISO-8601 format: 1969-11-21T10:29:43.

Property 

id

job_id 

location 

department 

start 

end 

 

 

Availability

Type  Description  string The availability identifier. string  Days the volunteer is available to be scheduled for assignments. Available values include: Sundays, Mondays, Tuesdays, Wednesdays, Thursdays, Fridays, Saturdays, AllDays, Weekdays, Weekends, and NotSpecified. fuzzy date  The time of year the availability begins. fuzzy date  The time of year the availability ceases to be applicable. string The start time of the availability. Uses 24-hour time in the HH:mm format. For example, 17:30 represents 5:30 pm. string The start time of the availability. Uses 24-hour time in the HH:mm format. For example, 17:30 represents 5:30 pm.

Property 

id

days 

from 

to 

start_time 

end_time 

 

 

Emergency Contact

Type  Description  string  The name of the volunteer's emergency contact. string  The type of the relation to the volunteer. Availabile values are the entries in the Relationships table, found in the Constituent API.  string  The phone number of the volunteer's emergency contact.

Property 

name 

relationship_type

phone 

 

 

Job

Type  Description  string The job identifier. string  The name of the job. string  The name of the position associated with the job. string  The job category. Available values are the entries in the Job Category table. string  The volunteer type appropriate for the job. Available values are the entries in the Volunteer Types table. dateTime  The date and time when the job begins. Uses ISO-8601 format: 1969-11-21T10:29:43. dateTime  The date and time when the job ends. Uses ISO-8601 format: 1969-11-21T10:29:43. integer The minimum age required to volunteer. boolean  Indicates whether the job is complete. This property defaults to false if no value is provided. string Longer description of the job. boolean Indicates whether the job qualifies for mandatory volunteer work hours.

Property 

id

job_name 

job_position 

category 

volunteer_type 

start 

end 

minimum_age

completed 

description

allow_mandated

 

Timesheet

Type  Notes  string The timesheet identifier. dateTime  The date the task was completed. string  The job associated with the timesheet. string  The department associated with the assignment. Available values are the entries in the Departments table, found in the Constituent API. string  The location associated with the timesheet. Available values are the entries in the Locations table, found in the Constituent API. string  The job category associated with the timesheet. Available values are the entries in the Job Category table. string  The position associated with the timesheet. string  The task completed during the specified timesheet. Available values are the entries in the Job Task table. string  The volunteer type associated with the job completed. Available values are the entries in the Volunteer Type table. string Notes about the completed timesheet. boolean  Indicates whether the timesheet can apply to mandated volunteer hours  for the constituent. decimal  Hours the volunteer contributed to the task. currency  Approximate hourly value of the task performed. currency  Calculated field based on hours and hourly_wage.

Property 

id

date 

job_id 

department 

location 

category 

position  

task 

volunteer type 

notes  

apply_to_mandate 

hours 

hourly_wage 

value 

 

 

Volunteer API Endpoints

We intend to surface full CRUD operation endpoints (POST, PATCH, and DELETE) for each entity except the Volunteer Summary entity. In addition, we intend to surface list endpoints with the standard date_added and date_modified filtering options for the Job, Timesheet, Assignment, Availability, and Interest entities. We are also exploring the option of retiring single constituent endpoints as we move forward and replacing them with constituent_id filters on the child entity list endpoints. However, the initial beta release of the Volunteer API is likely to still include single volunteer endpoints while we continue to build out the child entity lists.

 

In terms of priority, we will first release GET endpoints for the volunteer entities. We will surface POST operations for timesheets, assignments, and emergency contacts at the same time or shortly thereafter. Before we release POST endpoints, we will include the required code table entry endpoints to support POST operations.

 

GET Single Volunteer Endpoints

GET /volunteers/v1/{volunteer_id}/assignments

GET /volunteers/v1/{volunteer_id}/availability

GET /volunteers/v1/{volunteer_id}/emergency

GET /volunteers/v1/{volunteer_id}/interests

GET /volunteers/v1/{volunteer_id}/summary

GET /volunteers/v1/{volunteer_id}/timesheets

 

Additional GET Endpoints Required to Enable POST Endpoints

GET /volunteers/v1/volunteertypes

GET /volunteers/v1/positions

GET /volunteers/v1/jobtasks

GET /volunteers/v1/jobcategories

 

Initial POST Endpoints

POST /volunteers/v1/assignments

POST /volunteers/v1/timesheets

POST /volunteers/v1/emergencycontact

 

Additional POST operations, PATCH operations, and list endpoints are a bit farther down the line. However, this is the primary area where I would like your feedback. Which volunteer entities are the most important to you? Do you agree with the planned order for releasing endpoints? Or did we miss something? Please let me know!

 

Additional Endpoints

GET /volunteers/v1/interests

 

POST /volunteers/v1/jobs

POST /volunteers/v1/availability

POST /volunteers/v1/interests

 

PATCH /volunteers/v1/assignments/{assignment_id}

PATCH /volunteers/v1/availability/{availability_id}

PATCH /volunteers/v1/timesheets/{timesheet_id}

PATCH /volunteers/v1/jobs/{job_id}

 

DELETE /volunteers/v1/assignments/{assignment_id}

DELETE /volunteers/v1/availability/{availability_id}

DELETE /volunteers/v1/timesheets/{timesheet_id}

DELETE /volunteers/v1/jobs/{job_id}

 

Finally, we will create lists for all relevant entity types within the Volunteer API, much like the list endpoints that we surface in existing APIs.

 

Volunteer List Endpoints

GET /volunteers/v1/assignments[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/availability[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/emergency[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/interests[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/jobs[?date_added][&last_modified][&sort_token]

GET /volunteers/v1/timesheets[?date_added][&last_modified][&sort_token]

 

That said, we are still evaluating what a volunteer list should look like. What is the most important information to you in a list of volunteers? Is the volunteer summary information the most relevant, or is it something else?

 

I look forward to hearing any and all feedback that you have, and I look forward to building something great together. Thanks, and as always, happy coding!




Comments

Categories