This document outlines the purpose, technology, use cases, methods, objects and examples for using the Event API.
This document focuses on the SOAP interface to this API.
The Event API provides programmatic access to retrieve messages from the Events system, to allow retrieval of historical messages.
The Event API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/Events.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Event API via SOAP uses the Permissions System to allow and deny access to users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Event) to be able to authenticate and perform the various actions available under this API.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Available methods are listed below.
Available objects are listed below.
Event API usage examples are available. These examples demonstrate the use of the API via a SOAP interface in C#.
See Authenticate.
Retrieve the messages that match the specified (SubscribedID, Sequence) pairs.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| subscriberSequenceMap | SubscriberSequenceMapping[] | Collection of (SubscriberID, Sequence) pairs identifying the messages to retrieve. |
Returns an EventMessageApiResponse indicating the outcome of the call.
Retrieve a list of all event types in the system
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
Returns an EventTypeApiResponse indicating the outcome of the call.
See ApiResponse.
Represents a (SubscriberID, Sequence) pair that uniquely identifies an EventMessage
| Field Name | Type | Description | Notes |
|---|---|---|---|
| SubscriberID | Int | The subscribers unique identifier. | This is included in all outgoing webhooks. |
| Sequence | Int | The unique identifier for the mesage to the specified Subscriber. | This is included in all outgoing webhooks. |
Represents an event within the Events System.
| Field Name | Type | Description |
|---|---|---|
| Type | String | Gives the human-readable name of the event. |
| SubscriberID | Int | Unique identifier for the subsciber that observed the event. |
| Sequence | Int | Unique identifier of the event for the subscriber. |
| Payload | XmlDocument | Structured data representing the event. |
Represents a type of event that can be triggered by the Events System.
| Field Name | Type | Description |
|---|---|---|
| Type | String | Gives the human-readable name of the event. |
| Trigger | String | Description of the actions that trigger this event type, for documentation purposes. |
| PayloadFormat | XmlDocument | Structured data representing the payload fields to expect for this type of event. |
Contains basic information about the result of a method call, along with an array of EventMessage objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | If this is populated with sequence IDs then it means that the sequences were unknown in the system and no EventMessages could be retrieved for these. |
| Data | EventMessage[] | Array of EventMessage objects returned from the method call. |
Contains basic information about the result of a method call, along with an array of EventType objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | EventType[] | Array of EventType objects returned from the method call. |
The Event API returns standard API response codes.