Table of Contents
Mews PMS
Terminology
There are a few terms that Mews PMS and the Mews Connector API use that should be noted:
- Customer – account associated with an individual
- Reservation – primary data record that contains, among other things, the account ID of the company or individual who booked it and the resource ID of the assigned room
- Resource – a room or any other bookable space
Supported Features
The DV2000 PMS Link interface to the Mews Cloud PMS provides support for a limited set of hospitality features using both the Mews Connector API (over HTTPS) and a websocket connection to receive real-time events.
Supported
- Check In – From PMS to DV2000
- Check Out – From PMS to DV2000
- Room Move – Detected by DV2000 by interpreting check-in data received from PMS
- Room State (maid status) – Either direction
- Database Sync – From PMS to DV2000 (DV2000 must request the information it needs; there is no sync command as such)
Not Supported
Not Supported by the Mews API
- DND
- Phone COS
- Text message count
- MWI and/or voice message count
- VIP status
- Name change – there does not appear to any event that signals a change in a customer account record, which is where the name information is stored.
Not Supported by the DV2000
- Groups – Mews does have groups of some sort but the group IDs, like all IDs in the Mews PMS, are GUIDs which are not suitable for use as mailbox numbers.
Configuration
These instructions apply to DV2000 version 8.1.42 and above.
Guest Mailbox Configuration
Mews Cloud PMS uses unique, 36-character IDs (in the GUID format) to identify all records of any type (customer, reservation, resource, etc.). In the case of resources, there is also a Name field that is user-configurable and may be set to the room number or some other meaningful identifier; this field can contain letters and symbols as well as numbers.
| Mews Field | Description |
|---|---|
| Id | Used by Mews to identify a specific resource (room). Example: 5ee074b1-6c86-48e8-915f-c7aa4702086f |
| Name | User-configurable string in the resource record. May contain letters and symbols as well as numbers. Example: FD-01 |
To make setup easier, the DV2000 expects the Room ID field in the mailbox to be set to the same value as the Name field in the resource record on the Mew PMS for the desired room.
The Room ID can be found on the General page when configuring a mailbox of type Room, as shown below.
Mailbox Import
The room ID can also be included in the CSV file used for mailbox import; the column heading for this is RoomID.
Configure PMS Settings
The following settings are those used in the development of this link and, except for the access token, can be used for testing as well. Once the certification form has been submitted and reviewed, Mews will provide an access token that can be entered here for use in the certification process.
General
| Setting | Value |
|---|---|
| PMS or Protocol | Mews Hospitality Cloud PMS |
| Connection Type | HTTPS Rest + Websocket Automatically set when Mews PMS is selected. |
| Room lookup method | Match room ID Automatically set when Mews PMS is selected and cannot be changed. |
Network
| Setting | Value |
|---|---|
| API base URL | https://api.mews.com This is the API URL to use for the Mews Hospitality Cloud PMS. |
| API retry interval | The time to wait before checking if access to the API is no longer blocked. Value is in seconds. Default: 5 seconds. |
| Websocket URL | wss://ws.mews.com/ws/connector This is the websocket URL to use for production environment. |
| Websocket connect retry count | The maximum number of times to attempt to open a websocket connection with the Mews Cloud PMS. First 3 attempts will occur 10 seconds apart; the next 5 will occur 5 minutes apart. After that, an attempt will occur every 15 minutes until either the websocket is successfully opened or the maximum attempts has been reached, at which point the PMS link will shut down. Default: 30 |
| Access Token | Set this to the value provided by the customer. It is used to authorize access to the customer’s PMS instance. |
Configure Maid Status Settings
DV Manager has been updated so you can select Mews as an option when resetting the PMS maid codes to their default values.
They should be configured as shown below.
The room state (maid status) codes are defined within the Mew Connector API and appear to be fixed values. Currently, the values shown above are the only options and should not be changed.
The Display Text can be changed, and which digit each is assigned to can also be changed, but if a given PMS Code must be moved to a different VMS Digit assignment, be sure to copy the string exactly as shown (in particular, note that there are no spaces between words for the OutOfService and OutOfOrder codes).
Testing
The basic recommended order for testing is:
- Configure the DV2000 (as described in the previous section)
- Perform a database sync
- Test changing the room state (maid status)
- Test check in and check out
Perform Database Sync
Once the DV2000 has successfully established the websocket connection with Mews, it is recommended that a database sync be initiated before any other tests. This will allow the DV2000 to match each resource (room) to a mailbox, based on matching the resource’s Name to the mailbox’s Room ID. Each time a match is found, the sync process will write the resource ID into the mailbox (as custom data) so that it can be used in the future, especially when sending room state (maid status) changes to the PMS.
The database sync can be initiated using the steps below:
- Open the PMS Monitor application
- Select Tools | Send message,,,
- Select Request database swap
- Click OK
How it Works
The database sync process for Mews differs from that we have typically seen with PMS systems that use a serial or TCP connections. There is no sync command as such. Instead, the DV2000 uses the following process:
- Requests all resources (rooms)
- Requests all reservations with a State of
Started(checked in) - Requests the customer account record for each reservation
- Collates all data and processes it
Request Resources
Resources are requested in batches (pages) of 25 at a time until Mews indicates all resource records have been sent to us.
Each resource is matched to a mailbox, if possible, based on matching its Id field to the one stored in the mailbox’s custom data area. If no match is found, it will attempt to find the mailbox based on matching the resource’s Name field to the mailbox’s RoomID field. If a match is found, the ResourceId is then written to the mailbox’s custom data section for future use.
Request Reservations
Reservations are requested in batches (pages) of 25 at a time until Mews indicates all reservation records that fit the specified criteria have been sent to us.
Technically, Mews does not actually send the reservation records themselves, but rather all past updates to reservations that are still in the system and that meet the request criteria. In practice, this can mean that multiple reservation records can be sent for the same reservation ID, especially those with a State of Processed (which equates to checked out).
It appears, however, that there can only be one update record with a State of Started (i.e., checked in) and, I think, only one reservation can be attached to a given room at a time (multiple guests appear to be handled using count fields within the reservation). Therefor, the DV2000 only requests the reservations that are in the Started state.
Request Customer Accounts
As each ‘page’ of reservation records is received, the account ID and type (e.g, customer) is pulled out and used to build a list of customer IDs. Once all reservation records have been received, the DV2000 will request all customer records it needs (again, asking for a max of 25 at a time until all have been received).
Customer records can provide the full name (first, last and title) and will be assigned to the appropriate fields in the mailbox. They may also contain the guest’s language preference which will be set in the mailbox if that language is supported and installed.
Processing the Data
Once all the data is received, the DV2000 will collate it all and update the mailbox database according to the current state of the mailbox and the presence or absence of a Started reservation with a AssginedResourceId field set to the ID for the room that is matched to the given mailbox.
| Mailbox State | Received Check-in Record? | Action |
|---|---|---|
| Vacant | No | Mailbox will be checked out, but message archiving will be skipped since the mailbox was already in the vacant state. |
| Vacant | Yes | Mailbox will be checked in using the data from the reservation record and the customer account record associated with that reservation. The reservation ID will also be stored in the mailbox. |
| Occupied | No | Mailbox is checked out so that its state matches the PMS. |
| Occupied | Yes | If the reservation ID received matches the one stored in the mailbox, this is considered a ‘duplicate’ check-in and is essentially treated as a guest update. If the reservation ID received does not match the one stored in the mailbox but does match the one stored in a different mailbox, then it is processed as a room move. If the reservation ID received does not match the one stored in the mailbox (or any other), it is assumed there was a missed check-out and so the mailbox will be checked out, then checked in with the new data. |
What Data is Received and Saved
| Source record | Data | Notes |
|---|---|---|
| Reservation | ID, Arrival date, Departure date | Reservation ID is kept so we can tell if a check in received is new or a duplicate. |
| Customer | Name, Language | Customer records may contain the full name in separate fields for first, last and title. Language is only saved if it matches a supported, installed language on the DV2000. |
Websocket Events
The websocket connection is used to receive real-time updates from the PMS. The DV2000 processes two types of events (all others are ignored).
| Event | Processing |
|---|---|
| Reservation | If State is Started and Id matches the one stored in the mailbox, this is treated as a check-in. If State is Started and Id does not match the one stored in the mailbox but does match the one stored in a different mailbox, this is treated as a room move.If State is set to Processed, this is treated as a check-out. Events with any other state are ignored. |
| Resource | If the resource can be matched to a mailbox AND if the State field does not match the maid status field in the mailbox, then the mailbox will be updated with the value from the PMS. Otherwise, no action is taken. |
Changing the Maid Status
The PMS Tester application can be used to generate a maid status change to verify that the DV2000 is communicating the update to Mews correctly and that Mews is accepting the value.
In addition to checking the Mews admin web interface to verify the change, you should be able to see in the HOSTEL log not only that the update was sent, but may also send a resource event from Mews over the websocket connection indicating there was a change in state for that resource (room).