Subscribe to this blog to receive periodic product release announcements for developers and tips and tricks for using API.

Developer Blog Series: Volunteer API Preview

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

Property 

Type 

Description 

constituent_id 

string 

The constituent identifier for the volunteer. 

first_year_volunteered 

integer 

The first year the constituent volunteered.

total_hours 

decimal 

This computed field calculates the total number of hours the volunteer has contributed.

total_value 

currency 

This computed field calculates the total value of the time contributed by the volunteer.

total_years_volunteered 

integer 

This computed field calculates the total number of years the constituent has volunteered.

first_assignment 

volunteer assignment 

The first assignment the volunteer had at the organization.

last_assignment 

volunteer assignment 

The most recent assignment the volunteer had at the organization.

 

 

Assignment

Property 

Type 

Description 

id

sting

The assignment identifier.

job_id 

string 

The identifier of the job the assignment is for.

location 

string 

The location of the assignment. Available values are the entries in the Locations table, found in the Constituent API.

department 

string 

The department associated with the assignment. Available values are the entries in the Departments table, found in the Constituent API.

start 

dateTime 

The date and time when the assignment starts. Uses ISO-8601 format: 1969-11-21T10:29:43.

end 

dateTime 

The date and time when the assignment ends. Uses ISO-8601 format: 1969-11-21T10:29:43.

 

 

Availability

Property 

Type 

Description 

id

string

The availability identifier.

days 

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.

from 

fuzzy date 

The time of year the availability begins.

to 

fuzzy date 

The time of year the availability ceases to be applicable.

start_time 

string

The start time of the availability. Uses 24-hour time in the HH:mm format. For example, 17:30 represents 5:30 pm.

end_time 

string

The start time of the availability. Uses 24-hour time in the HH:mm format. For example, 17:30 represents 5:30 pm.

 

 

Emergency Contact

Property 

Type 

Description 

name 

string 

The name of the volunteer's emergency contact.

relationship_type

string 

The type of the relation to the volunteer. Availabile values are the entries in the Relationships table, found in the Constituent API. 

phone 

string 

The phone number of the volunteer's emergency contact.

 

 

Job

Property 

Type 

Description 

id

string

The job identifier.

job_name 

string 

The name of the job.

job_position 

string 

The name of the position associated with the job.

category 

string 

The job category. Available values are the entries in the Job Category table.

volunteer_type 

string 

The volunteer type appropriate for the job. Available values are the entries in the Volunteer Types table.

start 

dateTime 

The date and time when the job begins. Uses ISO-8601 format: 1969-11-21T10:29:43.

end 

dateTime 

The date and time when the job ends. Uses ISO-8601 format: 1969-11-21T10:29:43.

minimum_age

integer

The minimum age required to volunteer.

completed 

boolean 

Indicates whether the job is complete. This property defaults to false if no value is provided.

description

string

Longer description of the job.

allow_mandated

boolean

Indicates whether the job qualifies for mandatory volunteer work hours.

 

Timesheet

Property 

Type 

Notes 

id

string

The timesheet identifier.

date 

dateTime 

The date the task was completed.

job_id 

string 

The job associated with the timesheet.

department 

string 

The department associated with the assignment. Available values are the entries in the Departments table, found in the Constituent API.

location 

string 

The location associated with the timesheet. Available values are the entries in the Locations table, found in the Constituent API.

category 

string 

The job category associated with the timesheet. Available values are the entries in the Job Category table.

position  

string 

The position associated with the timesheet.

task 

string 

The task completed during the specified timesheet. Available values are the entries in the Job Task table.

volunteer type 

string 

The volunteer type associated with the job completed. Available values are the entries in the Volunteer Type table.

notes  

string

Notes about the completed timesheet.

apply_to_mandate 

boolean 

Indicates whether the timesheet can apply to mandated volunteer hours  for the constituent.

hours 

decimal 

Hours the volunteer contributed to the task.

hourly_wage 

currency 

Approximate hourly value of the task performed.

value 

currency 

Calculated field based on hours and hourly_wage.

 

 

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!

Posted by Halley Coplin on Sep 6, 2017 5:28 PM America/New_York

Leave a Comment

Log in to post a comment.