Publishing

Introduction

Do you have volunteer opportunities you'd like to see included in All for Good search results?

We want to make it easy to publish your volunteer opportunities - and for qualified volunteers to find them.

Your Options

There are several options you can choose from - depending upon how many volunteer opportunities you have - and your access to skilled technical folks.

One At A Time

If you have a few infrequently changing volunteer opportunites - or you don't have access to skilled technical folks - you can publish one at a time via All for Good.

  1. Sign Up or Sign In
  2. Register an Organization
  3. Publish your Project
  4. Search for your Project
  5. Your Project appears in search results! 🎊

Continuously

If you have lots of frequently changing volunteer opportunities - and access to skilled technical folks - you can publish continuously via WebSub.

How does it work?

  1. Points of Light acts as a Hub
  2. All for Good acts as a Subscriber
  3. You act as a Publisher
  4. All for Good subscribes to Your Publication
  5. Your Volunteer Opportunties appear in All for Good search results! 🎊

Why WebSub?

  • Open standard
  • Vendor and technology neutral
  • Allows for multiple hubs and avoids a Points of Light Hub dependency
  • Allows publishers to control content and access
  • Standardizes communication between publishers and subscribers, avoiding multiple costly proprietary integrations

Your Publication

Your publication is a URL you provide which allows the All for Good Subscriber to discover and read your volunteer opportunities in a standard format.

In addition to WebSub, your publication will embrace the [Link Header] and [Schema.org] standards.

RFC5988 defines standard links for your publication - enabling the All for Good Subscriber to discover your volunteer opportunities.

You'll need to include the following relations in the Link header returned with your publication's HTTP responses.

Hub

This relation indicates the URLs of the WebSub Hubs your publication is published at.

Your publication will include the following hub relation to indicate it's being published at the Points of Light hub.

<https://voyager.pointsoflight.org/api/websub/subscriptions>; rel="hub"

Multiple Hubs

WebSub allows for a publisher to publish via more than one hub by including multiple hub relations in the Link header.

This allows for the volunteering community to not be wholly dependent upon or locked into the Points of Light hub for critical operations.

Self

This relation indicates the URL of your publication itself.

<https://publisher.example.com/your-publication>; rel="self"

Next

This relation indicates the next URL for your publication.

  • If you have a large number of volunteer opportunities it's unlikely they can be returned via a single URL
  • The next relation enables the All for Good Subscriber to follow a sequence of next URLs and return all of your volunteer opportunities

<https://publisher.example.com/your-publication?page=2>; rel="next"

A Combined Example

This example shows:

  1. An All for Good Subscriber request to your publication
  2. Your publication response with the Link header including the required relations
GET /your-publication HTTP/1.1
Host: publisher.example.com

HTTP/1.1 200 Ok
Link: <https://voyager.pointsoflight.org/api/websub/subscriptions>; rel="hub",
      <https://publisher.example.com/your-publication>; rel="self",
      <https://publisher.example.com/your-publication?page=2>; rel="next"

Schema.org

Schema.org defines standard data structures for your publication - enabling the All for Good Subscriber to read your volunteer opportunities.

Why Schema.org?

Your publication will use many Schema.org structures.

## Event (object)
+ @type: Event (required) - A schema.org [Event](https://schema.org/Event)
+ description: Horizons for Homeless Childrenis seeking volunteers...
+ director (Person)
+ duration: PT3H
+ endDate: `2017-09-23T13:00:00-04:00`
+ identifier: `https://staging.changemaker.pointsoflight.org/api/websub/publications/events/M28gWV8R` (required)
+ location (Place)
+ maximumAttendeeCapacity: 100 (number)
+ name: Volunteer and Play with Children at Homeless Shelters in Northeast MA
+ organizer - A reference to the Organization
    + @type: Organization
    + identifier: `https://staging.changemaker.pointsoflight.org/api/websub/publications/organizations/baker-college-of-muskegon`
+ startDate: `2017-09-23T10:00:00-04:00`

## GeoCoordinates (object)
+ @type: GeoCoordinates (required) - A schema.org [GeoCoordinates](https://schema.org/GeoCoordinates)
+ latitude: 43.2443111 (number)
+ longitude: `-86.1965856` (number)

## Organization
+ @type: Organization (required) - A schema.org [Organization](https://schema.org/Organization)
+ description: The beginning of Baker College can be traced back to the turn of the 20th century.
+ identifier: `https://staging.changemaker.pointsoflight.org/api/websub/publications/organizations/baker-college-of-muskegon`
+ location (Place)
+ name: Baker College of Muskegon
+ telephone: 2317775200

## Person
+ @type: Person (required) - A schema.org [Person](https://schema.org/Person)
+ email: [email protected]
+ name: Leah Schenkel

## Place (object)
+ @type: Place (required) - A schema.org [Place](https://schema.org/Place)
+ address (PostalAddress)
+ geo (GeoCoordinates)

## PostalAddress (object)
+ @type: PostalAddress (required) - A schema.org [PostalAddress](https://schema.org/PostalAddress)
+ addressCountry: US
+ addressLocality: Muskegon
+ addressRegion: Michigan
+ postalCode: 49442
+ streetAddress: 1904 Marquette Ave

←