Using the Gnosis Calendar API (JSON Request)

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 could design additional event/calendar widgets on pages within your main website using the Event List Handler endpoint provided for such use cases. 

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.

EndPoint

Gnosis will provide a list of events in response to a properly formatted JSON request to the Event List Handler API. 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

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 Limit Filters

●       LimitToCategoryIDs (string: comma separated list of int)  If the parameter is not empty, the list to only include those events with category numbers included in this CSV list. 
 
To obtain the ID number of your specified event categories, in Gnosis Pro, go to “Settings | Administration Reference Data | Event Categories”, right-click on the Event Categories group and select “Copy Category as Lookup Table”.  This will give you a list of your event categories 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:

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

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"
}

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.

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

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.