Workflow: Handling of Room Keys on Room Move

OPERA Cloud supports two ways of informing the connected Door Lock system about guests moving to another room and the change of room keys.

  1. Room move for an "offline" Door Lock System
  2. Room move for an "online" Door Lock System

When the Door lock system is an offline system:

An "offline" Door Lock system typically handles room keys based on the room numbers. Room key data is written on the physical key.

For a room move of a checked in reservation, OPERA Cloud sends out a request with keyType "Remove" for the old room followed by a request with keyType "New" for the new room containing the new Room number as well as new "additionalRooms" and/or new "KeyOptions."

Additional key requests for the new room are sent after receiving a successful response for a New key.

Sequence Diagram

This image shows the process for handling room keys on a room move.

Description of Steps:

  Description Sample Call
1

Request to "Remove" room key(s) for the old room is sent to the door lock system from OPERA Cloud.

The door lock system must respond within 20 seconds with a "201" status message that the room key(s) have been set to inactive, or if an unsuccessful request, a "201" response containing message information on why the request could not be processed.

As the room move is processing in OPERA Cloud PMS, the guest moves to another room, and the old room key becomes invalid and should no longer work.

The guest might or might not hand the room key back to the hotel staff even if the guest receives a new room key.

Offline - Room Move Remove Room Key Request

POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysOutbound

{
  "keyType": "Remove",
  "encoderTerminal": "TERM1",
  "encoderId": "1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyRequestTime": "2024-02-26T16:16:10.295Z",
  "roomId": "101",
  "oldRoomId": "",
  "noOfKeys": 1,
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "guestShareFlag": "false",
  "OldGuestShareFlag": "",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyTrack": {
    "keyTrack1": "",
    "keyTrack2": "",
    "keyTrack3": ""
  },
  "additionalRooms": [
    "",
    ""
  ],
  "oldAdditionalRooms": [
    "",
    ""
  ],
  "userId": "PMSUser1",
  "keyOptions": [
    {
      "keyOptionsCode": "SAU",
      "keyOptionDescription": "Sauna"
    },
    {
      "keyOptionsCode": "GAR",
      "keyOptionDescription": "Garage"
    }
  ],
  "cardSerialNumber": "",
  "printData": {
    "printText": "",
    "printFile": "",
    "printPicture": ""
  }
}

Offline - Room Move Remove Room Key Response


{
  "roomId": "101",
  "responseCode": "OK",
  "encoderTerminal": "TERM1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyCreationTime": "2024-02-26T11:16:16.138Z",
  "noOfKeys": "1",
  "encoderId": "1",
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "responseText": "Key successfully deleted/removed",
  "userId": "PMSUser1"
}
2

Now a request for a "New" room key or Pincode for the new room is sent to the Door Lock system from OPERA Cloud.

The door lock system must respond within 20 seconds with a "201" status message that the room key(s) have been set to inactive, or if an unsuccessful request, a "201" response containing message information on why the request could not be processed.

With the move to another Room, the guest receives a room key with the new room data.

This can either be a new room key or Pincode, or the "old" room key can be used.

However, the room key must be encoded with the new data (roomId, Additional rooms, Key Options).

Optional: Additional room keys can also be requested.

Offline - Room Move New Room Key Request

POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysOutbound

{
  "keyType": "New",
  "encoderTerminal": "TERM1",
  "encoderId": "1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyRequestTime": "2024-02-26T16:16:10.295Z",
  "roomId": "201",
  "oldRoomId": "",
  "noOfKeys": 1,
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "guestShareFlag": "false",
  "OldGuestShareFlag": "",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyTrack": {
    "keyTrack1": "",
    "keyTrack2": "",
    "keyTrack3": ""
  },
  "additionalRooms": [
    "202",
    "203"
  ],
  "oldAdditionalRooms": [
    "",
    ""
  ],
  "userId": "PMSUser1",
  "keyOptions": [
    {
      "keyOptionsCode": "SAU",
      "keyOptionDescription": "Sauna"
    },
    {
      "keyOptionsCode": "GAR",
      "keyOptionDescription": "Garage"
    }
  ],
  "cardSerialNumber": "",
  "printData": {
    "printText": "",
    "printFile": "",
    "printPicture": ""
  }
}

Offline - Room Move New Room Key Response 

{
  "roomId": "201",
  "responseCode": "OK",
  "encoderTerminal": "TERM1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyCreationTime": "2024-02-26T11:16:16.138Z",
  "noOfKeys": "1",
  "encoderId": "1",
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "keyTrack": [
    {
      "keyTrack2": "98765A43B21C",
    }
  ],
  "additionalRooms": [
    "202",
    "203"
  ],
  "responseText": "Key successfully created",
  "keyOptions": [
    {
      "keyOptionsCode": "SAU",
      "keyOptionDescription": "Sauna",
      "isEnabled": "true",
      "default": "false"
    },
    {
      "keyOptionsCode": "GAR",
      "keyOptionDescription": "Garage",
      "isEnabled": "true",
      "default": "false"
    },
    {
      "keyOptionsCode": "MAIN",
      "keyOptionDescription": "MainEntrance",
      "isEnabled": "true",
      "default": "true"
    }
  ],
  "userId": "PMSUser1"
}

When the Door lock system is an online system:

The room keys can be handled based on the room and reservationId. Key data is not written on the physical key but stored in the Door Lock System database.

In this case, OPERA Cloud sends out a request with keyType "RoomMove" for the existing reservationId and sends the old and the new room number as well as the new "additionalRooms and/or new "keyOptions."

It is expected that the Door Lock system will update the existing room key data with the new roomId plus optionally update it with "additionalRooms" and "keyOptions."

Sequence Diagram

This image shows the process for requesting a room move of existing active room key(s) when the door lock system is an "Online System."

Description of Steps:

  Description Sample Call
1

Request for a "RoomMove" of existing active room key(s) or Pin code is sent to the door lock system from the OPERA Cloud PMS UI.

The door lock system must respond within 20 seconds with a "201" status message that the room key(s) have been set to inactive, or if an unsuccessful request, a "201" response containing message information on why the request could not be processed.

As the existing room Key information is not stored on the room key(s) itself but stored on Door Lock Systems database, the new room data (new roomId, new additional rooms, and new KeyOptions) must be updated on the database only. The new room data does not need to be encoded on the room key(s).

The hotel guest does not need a new room key(s) or Pincode, but the guest can use the existing one for the old room.

The old room must no longer be accessible with the room key(s) or Pin code after successful processing of the "RoomMove" request.

Online - Room Move Room Key Request

POST {{HostName}}/fof/v1/hotels/{{HotelId}}/roomKeysOutbound

{
  "keyType": "RoomMove",
  "encoderTerminal": "TERM1",
  "encoderId": "1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyRequestTime": "2024-02-26T16:16:10.295Z",
  "roomId": "201",
  "oldRoomId": "101",
  "noOfKeys": 1,
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "guestShareFlag": "false",
  "OldGuestShareFlag": "",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyTrack": {
    "keyTrack1": "",
    "keyTrack2": "",
    "keyTrack3": ""
  },
  "additionalRooms": [
    "202",
    "203"
  ],
  "oldAdditionalRooms": [
    "102",
    "103"
  ],
  "userId": "PMSUser1",
  "keyOptions": [
    {
      "keyOptionsCode": "SAU",
      "keyOptionDescription": "Sauna"
    },
    {
      "keyOptionsCode": "GAR",
      "keyOptionDescription": "Garage"
    }
  ],
  "cardSerialNumber": "",
  "printData": {
    "printText": "",
    "printFile": "",
    "printPicture": ""
  }
}

Online - Room Move Room Key Response 


{
  "roomId": "201",
  "responseCode": "OK",
  "encoderTerminal": "TERM1",
  "roomKeyType": "HardKey",
  "keyUserType": "Guest",
  "keyValidityStart": "2024-02-26T11:16:16.000Z",
  "keyValidityEnd": "2024-02-27T12:00:00.000Z",
  "keyCreationTime": "2024-02-26T11:16:16.138Z",
  "noOfKeys": "1",
  "encoderId": "1",
  "reservationIdList": [
    {
      "id": "{{ReservationId}}",
      "type": "Reservation"
    },
    {
      "id": "2468024",
      "type": "Confirmation"
    }
  ],
  "keyTrack": [
    {
      "keyTrack1": "",
      "keyTrack2": "98765A43B21C",
      "keyTrack3": ""
    }
  ],
  "responseText": "Key successfully changed",
  "additionalRooms": [
    "202",
    "203"
  ],
  "keyOptions": [
    {
      "keyOptionsCode": "SAU",
      "keyOptionDescription": "Sauna",
      "isEnabled": "true",
      "default": "false"
    },
    {
      "keyOptionsCode": "GAR",
      "keyOptionDescription": "Garage",
      "isEnabled": "true",
      "default": "false"
    },
    {
      "keyOptionsCode": "MAIN",
      "keyOptionDescription": "MainEntrance",
      "isEnabled": "true",
      "default": "true"
    }
  ],
  "userId": "PMSUser1"
}

Parent topic: Workflows