The Gnosis Calendar API (JSON Request) - Adding your Calendar to your Main Website

Introduction

The Gnosis system maintains a calendar of events, which are displayed on the inbuilt calendar controls (grid and list) that are embedded in the Gnosis Portal web pages. If desired, your web developer can design additional event/calendar widgets on pages within your main website using the Event List Handler and search endpoints provided for such use cases. 

This document describes

• The Calendar event listing API
• The Calendar event search API

Calendar Event Listing API

Below is a list of possible calendar widgets you might consider adding to your main website. 

• All events scheduled that day
• All events in a designated category
• Events based on promotion settings
• Mini calendar identifying days with scheduled events

The Event List Handler will return either a JSON or JSONP response based on your request parameters. The following information should be provided to your web developer to add the desired calendar widgets to your current website.

Calendar Listing EndPoint

Gnosis will provide a list of events in response to a properly formatted JSON request to the Event List Handler API. This endpoint is open and anonymous so no authentication or API key is required. The API endpoint for the Gnosis system in question is:

http://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/EventListHandler.ashx

NOTE: replace “YourOrganizationID” with the OganizationID for the desired system

Calendar Listing Parameters

The parameters provided to the request define the type and date range of events that are returned in the list.  The following describes each parameter:

1.      Date Range Selection Options
There are two types of date range filters that can be specified - Absolute Date Parameters and Relative Date parameters.

●       StartsDaysIntoFuture (int). Filters events to those starting after the number of days specified from the current date.

●       StartDate (datetime). Filters events to only those starting on or after the specified date and time

●       ForNumberOfDays (int) Filters events to only include those that start within ForNumberOfDays days after the StartsDaysIntoFuture.  For example, if today is the first of the month, a StartsDaysIntoFuture of 5 and ForNumberOfDays of 15 will show an event from the 5th to the 20th of the month.

●       EndDate (datetime). Filters events to only those starting on or before specified date and time.
 

2.      Event Marketing Priority Filters
These filters - if specified - will limit returned entries to the marketing priority(s) specified (High, Medium, and Low). 
If a priority is not specified, it will not apply as a filter.  If one or more priorities are specified, Events without those priorities set will not be included.(see priority specification in the event form shown at below)

Note: If High, Medium or Low priority are set, events will only be included if their promotion settings include “web” and they specify a number of days pre-event that the event should be promoted.

●       IncludeHighPri (bool 1 or 0). If set, filters the list to only include those events with a pre-event promotion level set to High Priority.

●       IncludeMedPri (bool 1 or 0). If set, filters the list to only include those events with a pre-event promotion level set to Medium Priority.

●       IncludeLowPri (bool 1 or 0). If set, filters the list to only include those events with a pre-event promotion level set to Low Priority.

●       WebPromo (bool 1 or 0; defaults to 1). If set (or omitted), filters the list to only include those events with Include On Website set.

●       EmailPromo (bool 1 or 0; defaults to 0). If set, filters the list to only include those events with Include In Email Blasts set.

●       AllPromo (bool 1 or 0; defaults to 0). If set, does not limit by web or email promotion (if set to 1, overrides WebPromo and EmailPromo options)
 

3.      Event Category & City/Location Limit Filters

●       LimitToCategoryIDs (string: comma separated list of int)  If the parameter is not empty, the list will only include those events with Category IDs included in this CSV list. 

●       LimitToCityIDs (string: comma separated list of int)  If the parameter is not empty, the list will only include those events with City/Location IDs included in this CSV list. 
 
To obtain the ID number of your specified event categories and cities, in Gnosis Pro, go to “Settings | Administration Reference Data, right-click on the Event Categories or Location/City group, and select “Copy Category as Lookup Table”.  This will give you a list of your Event Categories or Location/Cities with the corresponding ID numbers for each one.

4.      JSONP

●       jsonpcallback(string)  The function name to use for JSONP callbacks. Adding this parameter will cause a JSONP response, omitting the callback parameter will just return a standard JSON response.

5.      QueryString Parameters

●       An alternate method of specifying parameters on the QueryString is also available. Parameters may be added in the normal manner:
?ParamName1=Value1&ParamName2=Value2 etc.

Some examples of JSON requests to retrieve event information are shown below:

To get the next 30 days worth of specific event categories as two specific City/Locations:

{
   "StartsDaysIntoFuture": 1,
   "ForNumberOfDays": 30,
   "LimitToCategoryIDs": “1109,1124,1201”,
   "LimitToCityIDs": "1302,1309"
}

Or for all events in an exact date/time range:

{
   "StartDate": "2014-05-01T00:00:00",

    "EndDate": "2014-05-31T23:59:59",
}

Or for all High priority events in a specific category with an exact start date/time and a ForNumberOfDays parameter:

{
   "StartDate": "2014-05-01T00:00:00",

    "ForNumberOfDays": 30,
   "IncludeHighPri": 1,
   "LimitToCategoryIDs": “1109”
}

Or for a simple get all events in the date range, all that is required is:

{
   "StartDate": "2014-05-01T00:00:00",

    "EndDate": "2014-05-31T23:59:59"
}

Calendar Listing Response

The following is an example of a typical JSON response with multiple events listed:

[
   {
       "EventID": 1149,
       "EventName": "Annual Gathering",
       "EventCategory": "Social Events",
       "EventDate": "2014-05-01T00:00:00",
       "EventTime": "17:00:00",
       "EventDuration": "02:00:00",
       "EventLocation": "Main Meeting Area",
       "EventPageURL": "http://YourOrganizationID.gnosishosting.net/Site/Events/Info/Annual_Gathering",
       "EventDescription": "Join us for fun, fellowship, and food, games, and more."
   },
   {
       "EventID": 1031,
       "EventName": "A Community Meeting",
       "EventCategory": "Community",
       "EventDate": "2014-05-03T00:00:00",
       "EventTime": "17:30:00",
       "EventDuration": "02:30:00",
       "EventLocation": "The Main Hall",
       "EventPageURL": "http://YourOrganizationID.gnosishosting.net/Site/Events/Info/Community_Mtg",
       "EventDescription": "A gathering of all community members to celebrate the day..."
   }
]

Note: The event description is the short description field in Gnosis.  It is formatted as HTML and may be up to 1000 characters long.

Calendar Event Images

An image for each event is also available as a URL for constructing an image tag source.  If a specific event does not have an image specified, the default event image specified in Gnosis preferences will be displayed instead.

The Event Image URL uses the “EventID” returned in the JSON response and is formatted as follows:

https://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/ImageHandler.ashx?mode=4&EVID=EventID

An HTTP Response of 200 will be returned on a successful query.

Link to Calendar Description & Registration Link

When displaying event names on the page, we recommend also linking the event name to the relevant event information popup on the calendar page or on the full event information page.

To do this, formulate the link as follows:

• Link to Calendar Page Popup (the normally preferred option)
  https://YourOrganizationID.GnosisHosting.net/Calendar?EVID=EventID
   
• Link to Full Event Information Page
  Use the full URL specified in the {EventPageURL} JSON return field for the event.

Calendar Event Search API

To facilitate adding calendar event searches to your main website search function, we provide an API endpoint that you can call as part of your website search that returns a list of matching calendar events in a JSON array, allowing you to format and present the matching search data, complete with a link to the event/program on the calendar.

Calling the Search API Endpoint

The following API endpoint can be called to initiate an event/program search.  At least two non-whitespace characters must be supplied in the search text

POST: https://YourOrganizationID.GnosisHosting.net/gnosis-api/v1/events/calendar/search
{ "searchText" : "Your Search Text"}

Search Data Returned

An array of JSON objects of Events will be returned as described below.  Each event contains the following information:

• ID: The Event ID
• EventName: The name of the event
• LocationName: The location of the event within the designated "City"
• City: The Calendar City/Location/Office as defined in Calendar cities.
• Description: The short description of the event
  • Dates: An array of:
    • ID: Event Instance ID's
    • Start: the date/time of the events in the local time zone of the system.

[
    {
        "ID": 1033,
        "EventName": "Laughter Therapy 101",
        "LocationName": "1st Floor Yoga Room",
        "City": "Main Clubhouse",
        "Description": "Combine breathing/laughter/relaxation to improve your breathing, mood, 

and your spirit.  Facilitator: Jane Smith, Certified Laughter Yoga 

Leader and Licensed Respiratory Therapist.",
        "Dates": [
            {
                "ID": 5416,
                "Start": "2023-11-03T12:00:00"
            }
        ]
    }
]

When displaying this data, you can implement any of the following options
Note: If your Gnosis website uses a custom domain instead of Gnosis Hosting, you can use the custom domain in place of the server name specified in the examples. 
Also note - if your Calendar URL is different from the URL shown below, use your calendar URL instead:

• To link to The specific event instance on a specific date on the calendar:
  https://YourOrganizationID.gnosishosting.net/Events/Calendar?EVIID=Dates.ID
• To link to the next instance of the selected event on the calendar:
  https://YourOrganizationID.gnosishosting.net/Events/Calendar?EVID=ID
• To get an event image for the event:
  https://YourOrganizationID.GnosisHosting.net/Connect4/Handlers/ImageHandler.ashx?mode=4&EVID=ID