AHENS Tutorial

Introduction

Welcome to the Amadeus Hospitality Event Notification Services (AHENS) API guide! AHENS is a platform to enable exchanging messages between different Amadeus Hospitality and vendor applications. The asynchronous nature of AHENS enables interacting partners to send and receive messages at their own pace. Various applications that can benefit from this platform can include Delphi.fdc orgs, PMS, RMS, HotSOS, iPlan, etc.

Built as a micro-service, AHENS easily scales to usage demands in order to provide an even better experience with Amadeus-Hospitality products to the partners and internal applications.

It is expected that the reader of this guide has basic familiarity with REST.

How it all works!

Different hospitality applications need to exchange information with each other by nature. During initial set up with Amadeus Hospitality Web Services (AHWS), applications get registered on AHENS as publishers, subscribers or both indicating a desire to send and/or receive relevant messages. The type and criteria of the messages to be exchanged is configured initially but can be updated later as needed.

On AHENS, a one-on-one mapping associates each Event publisher to a subscriber of its Notifications. The mapping is called a PubSubMap and is available to the client by PubSubMap APIs listed Here.

Sample work flow

To demonstrate how applications can leverage the functionality provided by AHENS let’s review an example use case.

Consider a Property Management System (PMS) is configured to work with a Delphi.fdc organization and is set up to use AHENS for message exchange. Whenever an update to the Delphi.fdc org of the mentioned property is made, Delphi.fdc would make an attempt to inform the PMS accordingly. Let’s consider a Booking update at the moment. The Delphi.fdc org will publish an Event to AHENS informing the Booking update. AHENS will look for a possible list of subscribing parties to be informed of updates to the mentioned Delphi.fdc org. Once it finds the registered PMS in this case, it will create a Notification for the subscribing PMS to retrieve the updated changes to their Delphi.fdc org. The Notification will either be sent to the subscriber or remain in AHENS to be picked up depending on the initial set up request of the partner PMS.

The diagram below depicts the above mentioned process.

Figure 1 - Sample Message Exchange Through AHENS

Publishing Events

Publishing Events to AHENS is simple and straightforward. The only thing the client application has to do is to call the Event API with a list of available updates. The process is depicted in figure 2.

EntityType

Endpoint

Summary

Event ahens/event

Returns a multi-status response (Http Code 207) which consists of individual responses to each Event sent in the request.

Figure 2 – publishing Events to AHENS
Figure 2 - Publish Event Process.

To access any API on AHENS, a prior authentication with AHWS and logging in with provided credentials as described below is required.

Authenticate with AHWS

Once you have your API credentials (supplied by Amadeus Hospitality), you will be able to use all of the APIs outlined in this document.

When using the developer console in this documentation, you can simply input your AHWS credentials into "Authentication type" field as "Resource Owner Password". For a deeper dive on our authentication, check out the authentication guide.

Logging in and Accessing the APIs

Once you have your API credentials (supplied by Amadeus Hospitality), you will be able to use the APIs outlined in this document.

Publishing Events

Event API enables users to publish multiple Events to AHENS simultaneously. Details of the API are as follows:

 API: Event

 TYPE: HTTP POST

Request URL

https://<<HostEnvironment>>/ahens/event

Request body

The body of the request must be in a valid format acceptable by AHENS. A sample request body containing one Event is given below.

[
  {
     "eventDetail": {
       "resourceId": "xxxxxx",
       "resourceType": "Booking",
       "locationId": "yyyy",
       "subject": "Booking event for xxxxxxx",
       "eventDataLink": "https://www.amadeus-hospitality.com/zzzzzzz"
     },
     "correlationId": "11111111-2222-3333-4444-555555555555
  }
]

Request Parameters Definition

As depicted in the previous sample Event post request body, the API requires several parameters. Here is a list of the required parameters along with their definitions and correct values.

  • eventDetail
  • Any detail to be included for the subscriber

  • resourceId
  • ID of the resource about which the Event is published

  • resourceType
  • The type of the resource for which the Event is generated.

  • locationId
  • ID of the location to which the Event is associated.

  • publisher
  • ID of the publisher of the Event.

Response:

Event Post API returns a multi-status response (Http Code 207) which consists of individual responses to each Event sent in the request. Here is a sample response to an Event Post API call. For each Event included in the Post call, you will receive an Http OK (200) response if AHENS has successfully received and stored it; otherwise, a custom failure response will be sent. A more detailed description of response codes and formats leveraged by AHENS is provided at Here.

[
  {
     "statusCode": 200,
     "message": "OK",
     "resourceId": "xxxxxx",
  },
  {
     "statusCode": 200,
     "message": "OK",
     "resourceId": "yyyyyy",
  }
]
			

There is no more you need to do once you have successfully published your Event(s). AHENS will generate Notifications and make them available to the applications that have subscribed to receive updates from you.

Receiving and Processing Notifications from AHENS

Subscriber Engagement Level

During initial set up phase, your application is set up to receive updates from certain publishers. At the same time, you choose if your application will actively poll AHENS to receive the latest updates or you would like to be informed by AHENS directly.

Active Subscription Workflow

A typical workflow for receiving Notifications actively from AHENS is given below:

  • Actively call Notification Receive API to retrieve any available updates waiting for your application.
    • Once you have successfully received and processed your updates, make a call to Notification/Commit API to inform AHENS that the received Notifications have been processed.
    • In case you are not interested in processing the Notifications you just received, simply call the Notification/Cancel API so that AHENS does not re-stage the Notification for you.
    • See Notification Restaging below for details on Notification restaging.

Passive Subscription Workflow

  • AHENS will send you Notifications containing updates of interest once they are made
    • If the notification send call receives a success response from your side, AHENS will mark the notification as committed which means no further processing will be required on the mentioned notification.
    • In case AHENS receives a failure response while pushing the notification, it will be marked as failed. Such notifications will be picked up and retried later for a configurable number of times.
    • See Notification Restaging below for details on Notification restaging.

Authentication with AHWS

The authentication stage is the same as the one for publishing Events and can be found here. Once authenticated, you may call any of the APIs provided in this document. See the authentication guide for details.

EntityType

Endpoint

Summary

Notification ahens/notification/receive

A call to the Notification Receive API returns a list of available Notifications to the caller. The result will return empty if there are no updates available.

Notification ahens/notification/commit

The Commit method is called with a collection of NotificationIds. These are Notification identifiers present in Notifications received by the subscriber system.

Notification ahens/notification/cancel

Similar to Commit, the Cancel method is called with a collection of Notification IDs.

Receiving Notifications

To receive updates, simply call Notification Receive API and you will be given a list of Notifications available for you.

Here are the details on this API:

 API: Notification Receive

 TYPE: HTTP POST

Request URL

https://<<HostEnvironment>>/ahens/notification/receive

Request body

Request body:

The body of the request must be in a valid format acceptable by AHENS. A sample request body containing one Event is given below. It should be mentioned that none of the fields included below are required; i.e. the API may be called with an empty request body. While tenancyId and channelId fields are specific to the calling party and must match the exact value provided by to the caller at the time of customer registration, the remaining fields enable the user to restrict the Notifications to be retrieved based on their will.

While it doesn’t frequently happen, in case there are more than 5000 Notifications available to the caller, 5000 Notifications will be returned at each call. A continuation token will be made available in the response header for retrieval of the remaining Notification batches. The mentioned token can be provided in the request body as a field.

[ 
  {
    "tenancyId": "ten123",
    "channelId": "chan456",
    "locationId": "loc789",
    "resourceType": "Booking",
    "limit": 100,
    "correlationId": "11111111-2222-3333-4444-555555555555"
  }
]

Response

A call to the Notification Receive API returns a list of available Notifications to the caller. The result will return empty if there are no updates available. Below you may find a sample response to the mentioned API.

[
  {
    "id": "string",
    "eventId": "string",
    "pubSubMapId": "string",
    "eventDetail": {
      "resourceId": "string",
      "resourceType": "string",
      "locationId": "string",
      "subject": "string",
      "eventDataLink": "string",
      "eventData": {},
      "publishedOn": "2019-08-02T14:56:27.954Z"
    },
    "correlationId": "string",
    "status": "New",
    "lastStatusChangeOn": "2019-08-02T14:56:27.954Z",
    "lastSubscribedOn": "2019-08-02T14:56:27.954Z",
    "receivedCount": 0,
    "trackingId": "string",
    "createdOn": "2019-08-02T14:56:27.954Z",
    "modifiedOn": "2019-08-02T14:56:27.954Z",
    "updateId": "string",
    "recordStatus": "Active"
  }
]
Notification Receive Diagram

Confirm That Updates Have Been Received and Processed

When you have finished processing the updated resources, you’ll need to confirm this with AHENS, so that those notifications won’t be delivered to you a second time. To do this you will need to “commit” the Notifications you received earlier. Simply post the Notifications you received back to the Notification/Commit API to commit them, indicating that all processing is complete.

The Commit request is treated as an explicit acknowledgment by the subscriber system that Notifications has been received successfully.

Commit Processed Notifications

 API: Notification Commit

 TYPE: HTTP POST

Request URL

https://<<HostEnvironment>>/ahens/notification/commit

Request body

The Commit method is called with a collection of NotificationIds. These are Notification identifiers present in Notifications received by the subscriber system. Collection of Notification identifiers (List required): Notification subscriber must supply a collection of Notifications identifiers.

Canceling a Notification

If you did not successfully process a notification, or have no interest in processing one, you can choose to cancel it.

If you don't commit or cancel a notification, you can receive it again after it has been restaged. See Active Subscriber Notification Restaging below.

 API: Notification Cancel

 TYPE: HTTP POST

Request URL

https://<<HostEnvironment>>/ahens/notification/cancel

Request body

Similar to Commit, the Cancel method is called with a collection of Notification IDs.

Notification Restaging

Active Subscriber Notification Restaging

Notification Stage Diagram

For Active Notification Subscribers, the Amadeus Hospitality Event Notification Service utilizes an internal workflow to manage Notifications to ensure that partners are processing all of their Notifications. The workflow has configurable timers and counters to tailor it to our partners' needs. These configuration options can be set by your Amadeus Partner Success representative.

For Active Subscribers, when the Recieve API method is called, the Notifications are put in the Received state. If after a period of time (defaults to 1 hour) these Notifications have not been Commited or Canceled, these Notifications will be restaged to the New state, allowing them to be Received again. Only Notifications in the New state can be Received.

Each time a Notification is Received, the Notification ReceivedCount is incremented. If you Receive a Notification with a ReceivedCount greater than one, that Notification has gone through the restage workflow due to not being Committed or Cancelled before the Restage Check timer has expired.

If the ReceivedCount is incremented more than the maximum allowed (defaults to five), the Notification will be put in a Failed state. These Notifications can no longer be Received, and will no longer be processed in the Notification workflow. If you would like Receive your Failed Notifications, contact your Amadeus Partner Success representative and they will restage them for you.

Passive Subscriber Notification Restaging

Passive Subscribers will receive their Notifications via HTTP Post to a url supplied by the subscriber. If the subscriber responds with a HTTP 200 level response code, the Notifications will be commited. If the subscriber responds with an error code (400 - 599), AHENS will retry the HTTP Post after waiting a period of time. If the HTTP Post continues to fail, the Notification will be changed to the Failed state, and will not be resent. If you would like Receive your Failed Notifications, contact your Amadeus Partner Success representative and they will restage them for you.

Retrieve data associated with the Notification

Once Notifications are received into the subscriber system, the subscriber can retrieve the data associated with the Notification. The data associated with the Notification typically is a JSON document representing the resource about which the Notification was issued to the subscriber system.

The sequence diagram shows the steps to retrieve the data associated with the Notification.

The steps involved in retrieval of Notification data are:

1. Authenticate with AHWS (as described Here ).

2. Retrieve data associated with the Notification using the URL provided in the Notification.

Note: The eventDataLink attribute in the Notification represents the URL to fetch the resource.

Publisher-Subscriber Mappings

Publisher-Subscriber Registration

As a subscriber of Notifications from AHENS, the subscriber system is required to be registered with AHWS. The registration process creates a ‘channel’ for data flow between integrating systems and provisions credentials to be used for data exchange. The same process is applied to applications requiring to publish Events to AHENS.

PubSubMap in AHENS

AHENS saves one-to-one records of publishers of Events and subscribers of Notifications in entities called PubSubMaps. Each application may be the publisher for many different subscribers and inverse. Publishers and subscribers will have access to their associated mappings on AHENS for retrieval and patch purposes mainly. The customers are not allowed by APIs to modify the records in any other way other than described in the Patch API section below.

EntityType

Endpoint

Summary

PubSubMap ahens/pubsubmap

Retrieves all subscriber mappings for the logged in user's channel

PubSubMap ahens/pubsubmap/{id}

Retrieves the Publisher-Subscriber mapping for the given ID and patches it to either put the subscriber's Notifications on hold for the specified period or to resume receiving Notifications.

PubSubMap ahens/pubsubmap

Retrieves all Publisher-Subscriber mappings for the caller and patches all their PubSubMaps to either put the subscriber's Notifications on hold for the specified period or to resume receiving Notifications.

Retrieving Your PubSubMaps

To retrieve PubSubMaps belonging to your channel(s), you can call the PubSubMap Get API which retrieves all your active publisher-subscriber mappings. Details of the API are as follows:

 API: PubSubMap

 TYPE: HTTP GET

Request URL

https://<<HostEnvironment>>/ahens/pubsubmap

Request Parameters Definition

There are no parameters required to call this API.

Response:

[
  {
     "id": "TheId",
     "tenancyId": "bbbb",
     "channelId": "cccc",
     "resourceType": "BookingSynchronization",
     "action": "POST",
     "receiverEndpoint": "https://www.amadeus-hospitality.com/yyyyyyy",
     "receiverAction": "POST",
     "locationId": "eeee",
     "channelType": "RoomBlock",
     "endPoint": "https://www.amadeus-hospitality.com/xxxxxxx",
     "hold": false,
     "holdDuration": 7,
     "retentionPeriod": 30,
     "allowDuplicate": true,
     "rules":[
        {
            "fact": "string",
            "operator": "In",
            "contains": [
              "string"
            ],
            "dateRange": {
              "daysInPast": 0,
              "daysInFuture": 0
            },
            "value": 0
	    }
	 ],
     "subscriberType": "Passive"
  }
]

Temporarily Pausing Notifications From AHENS or Resuming Them

AHENS enables you to stop receiving Notifications from all or some of the channels you have subscribed to. This allows our partners to attend to required maintenance on their side too. Once there is no more reason you would need to have Notifications on hold, you can easily resume receiving updates from your registered publishers. APIs below provide the mentioned functionality. When a certain channel's Notifications are put on hold, AHENS will continue receiving their related updates from Publishers. However, the related Notifications will not be made available to the subscriber but saved for later retrieval. Receiving Notifications can be resumed by either customer disabling the Notifications hold on their desired channels or when the hold duration specified by them is over.

The API given below is meant to operate on all channels which belong to you. Therefore, you may pause Notifications from AHENS for all your channels or resume them after a hold is in place.

Holding or Resuming Notifications for All Channels

 API: PubSubMap

 TYPE: HTTP PATCH

Request URL

https://<<HostEnvironment>>/ahens/pubsubmap

Request Parameters Definition

"Hold" and "HoldDuration" fields should be input when calling this API, the former representing holdState with a boolean value while the latter specifies the duration requested for the hold operation. "HoldDuration" takes integer values of intended minutes of hold and should not exceed 41,760 minutes. If you would like to temporarily stop receiving Notifications you have subscribed to, you need to set "Hold" to true and specify the duration intended to pause Notification for with "HoldDuration". On the other hand, to resume receiving updates from AHENS, simply set "Hold" to false and "HoldDuration" to "0".

Response:

The API will return an HTTP OK (Code 200) response if the transaction is successfully completed.

Holding or Resuming Notifications for A Specific Channel

 API: PubSubMap

 TYPE: HTTP PATCH

Request URL

https://<<HostEnvironment>>/ahens/pubsubmap/{PubSubMap_id}

Request Parameters Definition

The request body for this API should include a patch document. The only fields allowed to be updated include "Hold" and "HoldDuration". Any other updates will be rejected and return an HTTP Bad Request response.

Response:

The API will return an HTTP OK (Code 200) response if the transaction is successfully completed.

Troubleshooting and Errors

Error Scenarios

Most APIs discussed in this document will return a response with an Http 200 (OK) status code if the call has been successfully gone through. In a few cases, a multi-status response with an Http 207 code will be returned. Such a response addresses more than one Http Post requests and contains individual responses to each resource with a status code of either success (Http 200) or failure.

A list of HTTP status codes provided by AHENS responses is provided in the table below.

HTTP Status Code

Reason

200

The server has successfully processed the request.

204

The server successfully processed the request but is returning no content.

207

MultiStatus, conveys multiple statuses. Collection of AHENS responses.

400

BadRequest, if all identifiers in the NotificationCommitRequest parameters are invalid. Collection of AHENS responses.

401

Unauthorized, if the caller is not authorized.

403

Forbidden, if the caller does not have valid permissions.

500

InternalServerError, for other server-side errors.

503

ServiceUnavailable, if the service is under maintenance or a transient failure, client may retry with exponential backoff

Calling OAuth

The most common error status code you will get from the OAuth service is a 403 - Forbidden. The error property in the response body will tell you what was not accepted.

  • Access_denied means you have an incorrect Username and Password pair. The user might not exist or the password provided was wrong.
  • Unauthorized_client means there is incorrect information in the client_id and client_secret fields. Ensure you are using the correct values that you received from Amadeus Hospitality when you acquired your credentials.
  • You may also get a 405 - Method Not Allowed if you call OAuth endpoints with the GET verb instead of POST.

400 – Bad Request

If you receive this response code, it means AHENS has received your request, but is unable to process it due to missing or invalid inputs. You need to review your request based on the criteria specified for each API and make corrections as applicable.

401 - Unauthorized

If there is no ChannelLocation relationship between the calling user and the Location you will receive an Unauthorized.

403 - Forbidden

If the caller of the API lacks permission to receive some resource, they will receive this response code.

500 - Internal Server Error

If the server experiences some unexpected error, this response code will be returned.

503 - Service Unavailable

You will get this response code if the service is under maintenance or a transient failure. You may retry the call later.

Rate Limits

Sample Requests and Responses

The sample shown below is a JSON document containing Notifications. The document will contain a collection of Notifications that are available in AHENS at any given instant for the subscriber system.


Description of Notification attributes

{

 eventId (string): The AHENS Event identifier.

 pubSubMapId (string): The AHENS PubSubMap identifier.

 eventDetail (EventDetail): Details of the Event about which Notification is issued.

{

  resourceId (string): Identifier of the resource for which Event is raised.

  resourceType (string): Type of resource for which Event is raised.

  locationId (string): Property (Hotel/Location) identifier.

  subject (string, optional): Additional description of the Event.

  eventDataLink (string, optional): Specifies the Url where data associated with the Event can be retrieved. Either EventDataLink or EventData is needed to process the Event.

  eventData (object, optional): Represents data associated with the Event. If publishing systems sends the data associated with the Event, this attribute will contain the data. Either EventDataLink or EventData is needed to process the Event.

  publishedOn (string, optional): Date and time when the Event was published. If the publisher does not specify the date and time, AHENS will assign the current date and time in UTC.

}

 correlationId (string): A CorrelationId, is a unique identifier that is attached to an Event that is published to AHENS and are referenced in the Notifications subscribed by the subscribers. If CorrelationId is not provided by the publisher, AHENS will assign a unique identifier to the Event.

 status (string, optional): Represents Notification status = ['New', 'Received', 'Committed', 'Cancelled'],

 lastStatusChangeOn (string, optional): Date and time in UTC when the Notification's status was last changed.

 lastSubscribedOn (string, optional): Date and time in UTC when the subscriber last received the Notification. When a Notification is retried, this time stamp will be updated. LastSubscribedOn is relevant to Notifications that are not 'New'.

 receivedCount (integer, optional): The number of attempts made by the subscriber to receive Notification.

 trackingId (string, optional): A TrackingId is a unique identifier that associated with a message to/from AHENS. If TrackingId is not provided by the publisher, AHENS will assign a unique identifier to the Event.

 recordStatus (string, optional): Indicates the status of Notification record. = ['Active', 'Retired', 'Deleted']

}