Skip to content

API - Events

Published Events

Sequoia publishes 'events' in order to notify its clients of changes. These events are triggered when certain things happen within the system - such as a job file being modified or a declaration response being received from CHIEF - and are published by the Sequoia Publication Service.

In turn, the Sequoia API can subscribe to these events and convert them to a predefined message payload for publication to the connected application.

Collecting events

The Sequoia API has 3 connection methods:

  • WCF Duplex HTTP (For .NET applications)
  • WCF HTTP Single (For .NET applications)
  • SOAP HTTP Single (Interoperable)

Collecting events using WCF Duplex

To connect to the API via the WCF duplex channel, you will need to register a callback object. A callback object is an object which is kept in scope for the duration of the connection and allows the API to publish events as they are received directly to that object via the duplex WCF channel. The application connecting to the API needs to monitor this object for changes as the 'PublishMessage' method will get called for each event passed from the API to the callback object.

An example (in c#) of such a callback could be as simple as the following:

using System;  
using System.Collections.Generic;  
public class SequoiaApiServiceCallback : ISequoiaApiDualChannelServiceCallback  
  public void PublishMessage(ASM.Sequoia.Api.Contracts.DataContracts.CallBacks.PublishedMessage message)  
    if (MessageReceived != null)  
    MessageReceived(new KeyValuePair<string, string>(message.EventName, message.Content));  
  public event Action<KeyValuePair<string, string>> MessageReceived;  

Collecting events using WCF HTTP or SOAP HTTP

When connecting to the API using single channel modes, there is no way for the API to push data to an external application. it is expected that the application that connects to the API will invoke the 'GetEvents' method periodically to collect a list of events.

The resulting list will conform to EventsResponse.xsd

Event Configuration

The sequoia API will subscribe to a (configurable) set of events with the Sequoia Publication Service when a user logs on (via single or duplex channels) for the authenticated API user. If a user invokes a method call on the API via the SOAP channel, the API will subscribe to events for a predefined 'API user'.

When an event is received by the API from the Publication Service, it will look for code associated to the event identifier and if found it will attempt to convert the Sequoia event to a predefined message payload which is published to the connected application. If there is no code available to convert a Sequoia event to a predefined format for onward publication (to an application connected to the API), or the API fails to convert the message to the predefined format for onward publication (to an application connected to the API), then the event is ignored.

Configuring the API to ignore events

The Sequoia API's configuration file contains a section which looks like this (Rel 1.89.x)

<!-- Publication Subscriptions configuration section -->  
    <add eventName="jobUpdated"/>  
    <add eventName="shipmentModified"/>  
    <add eventName="declarationResponse"/>  
    <add eventName="declarationReportResponse"/>  
    <add eventName="declarationErrorResponse"/>  
    <add eventName="publishETSFStatusChange"/>  
    <add eventName="publishAgentStatusChange"/>  
    <add eventName="worksheetFinalised"/>  
    <add eventName="mucrClosure"/>  
    <add eventName="associationResponse"/>  

Each event name listed corresponds to the name of an event that is raised by the publication service when 'things occur' in Sequoia. To prevent the API from responding to any event, either remove or comment out the appropriate <add eventname="eventToIgnore" /> element in this section.

The API must be restarted for changes to take effect.

Configuring the API to handle new events

While it is possible to add new entries into the configuration file to make the API aware of events, development work must occur to define how the Sequoia publication event is to be transformed to match a defined event payload schema. Therefore, until such work is completed, any entries into the file for events that occur will not produce any more events being propagated to the connected application, they will just cause an unnecessary overhead in processing requests for events which are destined to silently fail and be ignored.

Typically, when any new events are added to the API, the new version of the API itself will have a configuration file where the event is configured to be propagated to any connected client.

Event Content

The data made available to a connecting application consists of an event name and an event payload.

The name is used to identify the type of event being sent, and will therefore allow the connecting application to determine what to do with the payload. The name also provides a clue as to the nature of the event, and why it has been raised.

The event payload is a string which will typically be an XML document with some information that relates to the nature of the event, for example providing a record pointer to identify a record which has been modified and can be queried for further information using one of the other API methods.

List of Published Events

The following is a list of events currently published through the Sequoia API.

Event Name Event Description Raised: Payload Version
jobUpdated A job has been updated Whenever a job is saved Returns Job reference as a string (no xsd constraint) <1.89.x
shipmentModified A shipment has been modified Whenever a shipment is saved Returns Shipment reference as a string (no xsd constraint) <1.89.x
declarationResponse A response message to a declaration has been received When a CUSRES is received in response to a CUSDEC with no errors DeclarationGbResponseNotification.xsd <1.89.x
declarationReportResponse A response message to a declaration has been received containing report information When a CUSRES RPA is received in response to a CUSDEC DeclarationGbResponseNotification.xsd <1.89.x
declarationErrorResponse A response message to a declaration has been received which indicates that there are errors with the declaration When a CUSRES is received in response to a CUSDEC with errors DeclarationGbResponseNotification.xsd <1.89.x
publishETSFStatusChange An ETSF (ERTS) record has been updated with a new customs status. Whenever an ETSF record is saved, or when an FSN is received from the CCS-UK inventory system. EtsfFreightStatusNotification.xsd <1.89.x
publishAgentStatusChange An Agent Inventory (CCS-UK) record has been updated with a new customs status Whenever an FSN is received from the CCS-UK inventory system. FreightStatusNotification.xsd <1.89.x
worksheetFinalised A worksheet has been marked as 'finalised' When the user finalises a worksheet WorksheetIdentifier.xsd 1.83.111
mucrClosure A MUCR closure message has been received which may or may not indicate failure (and if so, will have error messages saying why the closure request was rejected) On receipt of a UKCTRL (ACK or NAK) in response to UKCINV CST MucrClosureNotification.xsd 1.89.x
associationResponse An association or disassociation message has been received which may or may not indicate failure (and if so, will have error messages saying why the request was rejected) On receipt of UKCTRL (ACK or NAK) in response to UKCINV EAC (A/D) AssociationNotification.xsd
airCarrierResponse A response has been received to an FWB (air waybill) or FHL (air manifest message sent to a carrier. On receipt of CIMFMA (acknowledgement) or CIMFNA (rejection) from an air carrier. AirTransportResponse.xsd 1.131.x
airWaybillFSUStatusUpdate A status update has been received for an air waybill. On receipt of a CIMFSU message from an air carrier. AirWaybillFSUStatusUpdate.xsd 1.131.x
agentInventoryStatus1Set Notification when Status 1 (NPR=NPX) is set on an agent inventory consignment. This event will only be raised where the consignment is not located in your own ETSF facility. On receipt of a CUSCAR FRC message from CCS-UK in which Status 1 (NPR=NPX) is set. AgentInventoryStatus1Notification.xsd 1.131.x
etsfInventoryStatus1Set Notification when Status 1 (NPR=NPX) is set on an ETSF inventory consignment. Following user input (goods in) EtsfStatus1Notification.xsd 1.131.x
agentInventoryModified Notification when an agent inventory record is modified (including created) On receipt of a CUSCAR message from CCS-UK AgentInventoryUpdatedEvent.xsd 1.131.x
DeclarationAcceptanceNotification Notification of acceptance of a declaration. This event payload includes significant data from the declaration itself as well as response data, job and external job references. It is intended to summarise, in one event payload, all information needed, to save having to call the API to retrieve further data. On receipt of a CUSRES response (1st and any subsequent) to an accepted declaration. DeclarationAcceptanceNotification.xsd 1.144x
movementStatusNotification Notification when an NCTS Movement's status is updated. This occurs whenever an associated NCTS Declaration or Arrival receive a status update. On receipt of the following NCTS messages:
NctsStatus.xsd 2.6x