Skip to content

Customizing Kiosk User Flow

The sequence and inclusion of screens seen in the Kiosk can be changed. This may be needed to alter the screen order or remove screens that do not apply to a site.

The application page sequence is defined in the flowconf.xml file that is located in the Kiosk Client installation folder. Do not update the flowconf.xml in the install folder as it will get removed during an upgrade or uninstall.

To change the Kiosk flow, copy theflowconf.xml file in C:\ProgramData\NEC\kiosk\Custom folder and modify this file to achieve the desired behavior. The file must have the same name as in the installation directory - flowconf.xml.

  • To remove a certain screen, remove its related entry from flowconf.xml. (This can also be done by adding XML comment indicators around the line to be removed. See examples in the file.)
  • To add a certain screen, just add a corresponding entry in the desired place in flowconf.xml
  • The order of the application screens can be changed with some restrictions. The order of the pages can be changed by simply changing the order of the corresponding entries in flowconf.xml.

Credit Card Pre-Authorization Options

Options that are available for the <in> and <out> flow:

  • allow-cc-replace Add this option to the <in> or <out> flow if you would like the guest to be given the opportunity to swipe a different credit card other than the one that is already on the reservation.

    • During check-in, the guest will see a link on the Booking Details page. Clicking on that link will take the guest to the Add Credit Card page where a guest can swipe to take pre-auth on the new card and have it stored for use on check-out.
    • During check-out, Kiosk will display a dialog box asking the guest if they would like to continue checking out using the existing CC. If they choose to replace the credit card, Kiosk will display the Add Credit Card page where a card can be swiped to be added to the folio prior to check-out. Note, this will cause the card to be charged an additional pre-auth amount. On check-out, all pre-auth and final balance due amounts will be handled.

  • enforce-cc-swipe Add this option to the <in> or <out> flow to force the Kiosk to always require an on-premises credit card swipe even if there is a card on the reservation. Swiping a credit card will authorize the card and charge a pre-authorization amount to the card.

    • enforce-cc-swipe takes precedence over allow-cc-replace
    • Check-in: It is common to have enforce-cc-swipe option set in the <in> flow. Typically, this is when a guest needs to swipe a credit card and have it pre-authorized. A swiped credit card during check-in will replace the virtual credit card that may already be on the reservation. The newly swiped card’s token will be used to process the balance on check-out.
    • Check-out: It is recommended to have enforce-cc-swipeoption set on the <out> flow to prevent the case of a guest having a balance but no credit card on the reservation and the property management system allows check-out to succeed with the unpaid balance. Some scenarios such as check-in with cash settlement but incidentals are incurred during the stay may cause this situation to occur.

Options set on the add-credit-card page:

  • ensure-guarantee This option should only be used when there is not a payment device connected to the Kiosk. The Kiosk will skip prompting to swipe a credit card for pre-auth. The Kiosk will check the reservation and only allow the guest to move forward if there is already a credit card on the folio. If there is not a credit card on the folio, the guest will be told to go to the front desk.

  • skip-on-settlement This option should only be used when a Settlement Type is set for a reservation (meaning that the initial bill has been paid up-front) and a credit card is not necessary to be on file for incidentals. If set and the settlement type matches the value configured for this option, the user will move forward without swiping a credit card during check in. If the settlement type does not match or this option is not set, the guest is prompted to swipe the pin pad.

  • show-cc-type-list This option is available to show the list of accepted credit card types that are defined in the Kiosk and supported by the payment provider.  The list of supported credit card types is not required to be seen. If this option is not enabled, the payment animation will be seen instead, and the guest is prompted to swipe the pin pad.

Options set on the folio-details page:

  • ensure-zero-balance This option should only be used when there is not a payment device connected to the Kiosk. The Kiosk will check the invoice balance from the PMS and if the balance is not $0, the guest will be sent to the front desk and will not be able to check-out using the Kiosk.
  • on-zero-balance This option can be used to override the enforce-cc-swipe option set on the <out> flow when the balance is $0. If the balance is $0, then the guest is not asked to swipe a card. The add-credit-card page is skipped and the next page in the flow is seen.

Flow Definition XML Format

  1. Everything inside this XML file must be enclosed between the <flows> and </flows> tags. Any other valid XML content that is found outside of these tags is ignored.

  2. Between the <flows> and </flows> tags we must have at least one <flow> node.

    • There is no upper limit. Any number of <flow> nodes can be defined.

    • The Kiosk Client will only use the one marked as the default. If multiple flow nodes are marked as default, Kiosk Client will use the first one marked as default in flowconf.xml.

      <flow name="Hotel" isDefault="true">

    • The name attribute of the <flow> node is purely descriptive, currently not being used by the app.

  3. Each flow consists of

    • three mandatory sub flows: one <common> sub flow, one <in> subflow and one <out> subflow
    • up to 10 additional subflows, denoted as <extra>, <extra1> ... <extra9>
      • There is no constraint on the presence or absence of the additional subflows.
      • Any additional subflow may be present or not. For example, we can only have <extra2> and <extra9> and this is perfectly valid.
    • The <common> subflow defines the sequence of pages that in the end leads to selecting the active subflow
      • The common definition must be enclosed between the <common> and </common> tags.
      • The common flow should always end with a selector page, such as select-options.

    • The <in> subflow defines the sequence of pages for registering a person in the system (i.e. check-in)

      • The <in> subflow definition must be enclosed between the <in> and </in> tags
      • It should always end with a completion page (i.e. the page that concludes the flow).

      • The <in> node accepts options allow-cc-replace and enforce-cc-swipe. See Credit Card Pre-Authorization Options for option details.

        <in options="allow-cc-replace">

<in options="enforce-cc-swipe">

        Note

        If both options are defined, the enforce-cc-swipe flag takes precedence over allow-cc-replace flag.

        <in options="allow-cc-replace; enforce-cc-swipe">

        It is not mandatory to specify either of these flags. They should be used as dictated by the particular business case of the customer. By default, the options attribute is not present for the <in> node in flowconf.xml file, after a fresh installation.

    • The <out> subflow defines the sequence of pages for check-out.

      • The <out> subflow definition must be enclosed between the <out>and </out> tags
      • It should always end with a completion page

      • The <out> node accepts options allow-cc-replace and enforce-cc-swipe. See Credit Card Pre-Authorization Options for option details

        <out options="allow-cc-replace">

<out options="enforce-cc-swipe">

        Note

        If both options are defined, the enforce-cc-swipe flag takes precedence over allow-cc-replace flag.

        <out options="allow-cc-replace; enforce-cc-swipe">

    • Any <extra...> subflow defines the sequence of pages that should be followed by the app to achieve a goal, other than register/unregister a person

      • By <extra...> we understand any node from this list: <extra>, <extra1> ... <extra9>
      • For example, an <extra...> subflow may be used to program additional hotel room access keys
      • The <extra...> subflow, if present, must be enclosed between the <extra...> and </extra...> tags
      • Any <extra...> subflow, if present, should always end with a completion page.

    • An<extra...> subflow can also be used to register / unregister persons in an alternative way than via the <in> or <out> subflows

      • For example, if in certain conditions we should only make use of some pages from the register sequence, then we may use an <extra...> subflow
      • In this case, we should also specify that the "intent" of the subflow is "In" (register), such as:
        <extra1 intent="In">

    • The "intent" for an <extra...> subflow may be set to:

      • "In" - resulting an extra subflow that behaves like an alternative register subflow. Such as:

        <extra1 intent="In">

      • "Out" - resulting an extra subflow that behaves like an alternative unregister subflow. Such as:

        <extra2 intent="Out">

    • "Extra" - resulting an extra subflow that neither registers nor unregisters persons - but it is doing something else. Such as:

      <extra intent="Extra">

    • Entirely omitted - it has same effect as when specifying "Extra", therefore you can simply write just: <extra>,without the intent part, and it is equivalent.

    • You do not need to specify an "intent" for <common>, <in> or <out>. Even if you do it, it will be ignored.

  4. In these sub flows, we can have multiple <page> nodes. The structure of such a <page> node is depicted below.

    <page name="prev-page-name" />
<page name="page-name" prev="other-prev-page" next="other-next-page" error="error-page" />
<page name="next-page-name" />

  5. The 'retrieve-booking' page is used when a reservation can be fetched using an internal reservation number only. It accepts an "options" attribute which can be used to display different filtering options as described below.

    • Page configuration for <in> flow

      <... options="search-by-booking-number" />       => displays only the Booking Reference Number field
<... options="search-by-booking-lastname" />     => displays only the Last Name field
<... options="search-by-number-and-lastname" />  => displays Booking Reference Number and the Last Name fields

    • Page configuration for <out> flow

      <... options="search-by-room" />                 => displays only the Room Number field
<... options="search-by-room-lastname" />        => displays only Room Number and LastName fields
<... options="search-by-room-documentnumber" />  => displays only Room Number and Document Number fields
<... options="search-by-number-and-lastname" />  => displays Booking Reference Number and the Last Name fields

    When no options are specified, or an invalid option is specified, the default page is loaded instead:

    • For the check-in flow, the default page is the one that presents "Booking Reference Number OR Name" as lookup options
    • For the check-out flow, the default page is the one that presents "Room Number AND Check-In Date" as lookup options

  6. You can specify key-value pairs in the options attribute for both subflows and pages. The format should be similar to this:

    <... options="key1; key2:val2;key3: val3; key4; key5; key6: val6" />
    • When the key is specified w/o a value (like key1, key4 or key5 in the example above), that option acts like a flagthat is set when the option is present. Such as enforce-cc-swipe or search-by-room etc...
    • When the key is specified with a value (likekey2, key3 or key6in the example), that option acts like a setting that gets the respective value for the corresponding subflow or page.

    Info

    This mechanism is applicable to all subflows and pages; however, each subflow or page is responsible for implementing their own custom behavior. If the subflow or page does not understand the option, it will just ignore it. For example, specifying the search-by-room option in the passport page will not raise any errors, but the passport page will totally ignore it.

  7. The options attribute for the 'folio-details' page includes enforce-cc-swipe and ensure-zero-balance.  See Credit Card Pre-Authorization Options for option details.

    <page name="folio-details" options="on-zero-balance" />

<page name="folio-details" options="ensure-zero-balance" />

    Note

    If you are using ensure-zero-balance this option for the folio-details page, then you need to enforce swiping the credit card for the checkout flow. That is, you need to use the enforce-cc-swipe option on the <out> node:

    <out options="enforce-cc-swipe">

  8. The reservation-lookup page accepts "options" attribute that can be used to display any combination of the lookup methods such as below.

    <page name="reservation-lookup" options="hotelbooking;qrcode;scandocument;externalbooking;membership;roomnumber_lastname;roomnumber_docnumber" />

    The table below shows which button titles are applied for each possible option:

    Option Usage Button title (English) Translation key OBS
    hotelbooking Look up using reservation number OR last name Name / Reservation Number Pages.ReservationLookup.NameResvNumber
    roomnumber_lastname Look up using room number AND last name Room Number & Last Name Pages.ReservationLookup.RoomAndLastName Applicable for additional keys and check-out flows, since typically we do not have a room before effective check-in.
    roomnumber_docnumber Look up using room number AND document number. Room Number & ID Document Number Pages.ReservationLookup.RoomAndDocNumber Applicable for check-out flow only, because typically we do not have a room before effective check-in.
    qrcode Look up reservation using a QR code QR Code Pages.ReservationLookup.QRCode Applicable only for reservations for which a QR code was generated, as part of an early arrival pre-check in.
    scandocument Look up reservation using first name & last names from a scanned ID document. Identity Document Pages.ReservationLookup.Scan This is the so-called "smart name lookup"
    externalbooking Look up using reservation number AND last name Name & Reservation Number Pages.ReservationLookup.ExternalNumber The reservation number can be either internal (i.e. Opera confirmation number) or external (.e. OTA confirmation number, CRS number, online booking system confirmation number, etc...)
    membership Lookup using a membership number Membership Number Pages.ReservationLookup.MembershipNumber
    name-checkout-date Lookup by name and checkout date. Name & CheckOut Date Pages.ReservationLookup.NameAndCheckoutDate
    reservationnumber_and_fullname Look up using reservation number AND full name. Full Name & Phone Number Pages.ReservationLookup.ReservationNumberAndFullName

  9. Certain pages can be skipped when the Early Arrival (Room Not Ready) feature is enabled:

    • The pages that have the skip-on-preregister option defined are skipped during the pre-check in flow. Example:

      <page name="keycard" error="booking-details" options="skip-on-preregister;">

    • The pages that have the skip-when-preregistered option defined are skipped during the regular check-in flow, if the guest has already gone once through the pre check-in flow. Example:

      <page name="additional-guests" options="skip-when-preregistered;" />

  10. By default, the credit card type list is hidden in all situations where the CC page is shown:

    <page name="add-credit-card" options="skip-on-preregister;" />

    To show the credit card type list before the CC operation, a new option in the credit cards page element in flowconf.xml can be added, such as below:

    <page name="add-credit-card" options="skip-when-preregistered;show-cc-type-list;">

    For making the application move on ONLY when the PMS reservation is using a credit card as guarantee, add the ensure-guarantee option to the add-credit-card page element in flowconf.xml, such as below:

    <page name="add-credit-card" options="skip-when-preregistered;ensure-guarantee;"/>

    For making the application move on when the PMS reservation has a matching Settlement Type, add the skip-on-settlement option to the add-credit-card page element in the “in” flow of flowconf.xml, as below:

    <page name="add-credit-card" options="skip-when-preregistered;skip-on-settlement:1001;"/>

  11. The signature page "options" attribute also accepts the confirm-reservation option, which must be present in order for the Confirmation Requests feature to be enabled in the flow.

    The Confirmation Requests feature is only released in the Japan market.

Arranging Pages

The sequence of pages displayed by the application is controlled by the prev / next / error attributes which can be added to a page node, like in the example below.

<page name="prev-page-name" />
<page name="page-name" prev="other-prev-page" next="other-next-page" error="error-page" />
<page name="next-page-name" />

The person that defines the flow should be aware that the app behavior is modified by the sequence of the page nodes, as depicted by these simple rules:

  • How does the app move to the previous page:
    • If "prev" attribute is specified, the app will move to that page - i.e. to "other-prev-page"
    • otherwise, it will move to the page that comes BEFORE the current page in the flow definition - i.e. to "prev-page-name"
  • How does the app move to the next page:
    • If "next" attribute is specified, the app will move to that page - i.e. to "other-next-page"
    • otherwise, it will move to the page that comes AFTER the current page in the flow definition - i.e. to "next-page-name"
  • How does the app behave when it encounters an error that cannot be corrected in the current page:
    • If "error" attribute is specified, then after the error popup is dismissed, the app will move to that page - i.e. to "error-page"
    • Otherwise, if "prev" attribute is specified, the app will move to that page - i.e. to "other-prev-page"
    • Otherwise, it will move to the page that comes BEFORE the current page in the flow definition - i.e. to "prev-page-name"

Dedicated application flows

In addition to the default "external" flow, Kiosk is shipped with other three dedicated flows, as described below.

  • Hotel-RecognizeMe => To be used when the Kiosk is configured to use the "Recognize me" features
    • The reservation lookup uses the primary guest's photo taken with Kiosk and matches it with an existing photo stored and configured in the face match system that contains te guest's name.
    • This functionality requires face match capabilities provided by systems such as NeoFace Watch or SFA
  • AccompanyGuestFlow => This flow is similar to the External Flow with the difference that when scanning documents and reviewing guest details, the accompanying guest’s details for the guest that just scanned are seen immediately instead of after all guests have completed scanning the documents.

To activate any of these flows, proceed like below:

  1. Copy theflowconf.xml file from the install folder (typically C:\Program Files (x86)\Kiosk Client) into C:\ProgramData\NEC\kiosk\Custom folder. The file must have the same name as in the installation directory - flowconf.xml.

  2. Open the flow config file from C:\ProgramData\NEC\kiosk\Custom folder in a text editor

  3. Find the default "external" flow node and set its isDefault attribute to false

  4. Find the flow node corresponding to the flow that you want to activate and set its isDefault attribute to true

    Warning

    Make sure that you have one and only one flow having its isDefault attribute set to true. If there are multiple flows having this attribute set to true, the application will use the first one of them, considering their order in the flow config file.

  5. Save flowconf.xml. To reload the file, it is enough to start any flow kind (check-in, check-out etc. ...) then use the Home page to return to the initial screen. The application reloads the flow config file each time when it returns to the initial screen.

Page Order Rules

When defining the page order in the flow definition, one must pay attention to the fact that the functionality of some pages depends on the data generated by other pages. If "page B" depends on the data models generated by "page A", then the "page B" must not come before "page A" in the flow definition file. If there is not a data dependency, then the pages can have any order that fits the best for the business case. The following table explains the page order constraints based on the data that is required, generated and validated by various pages.

Page Name Purpose Special Attribute Required Data Models Generated Data Models Behavior Conditions for Moving Next Remarks
select-options Use to select check-in or check-out flow selector page - - - - Common flow only.
dataprotection-note Shows the GDPR agreement - - - - User pressed "I agree" Can appear in any sub flow, but not after select-options in the common flow or after the completed page.
reservation-lookup Allows to choose the reservation look up method. - - - User makes a selection
retrieve-booking Retrieves a reservation based on guest name or room number - Reservation - A valid reservation is generated. This page can be used when the reservation can be fetched using an internal reservation number.
qr-code-verification Retrieves a reservation based on a QR code - - Reservation - A valid Reservation is generated.
external-number Retrieves a reservation based on an external booking number - - Reservation A valid Reservation is generated. This page can be used when the reservation can be fetched using an internal reservation number or an external reservation number.
membership-number Retrieves a reservation based on a membership number and membership type - - Reservation A valid Reservation is generated.
passport Scans the person's ID document - - DocumentData - A valid DocumentData is generated. The passport page can be removed from the flow definition if the business case does not require an actual document scanner.
verification Validates person identity -
  • Reservation
  • DocumentData
 - After a successful face match, it validates names and document number from Reservation against DocumentData Successful face match + successful validation
accompanying-guests Prompts the guest to specify a number of additional guests (sharer guests) to be added to the reservation, beside the amount originally configured in the reservation - Reservation - - Documents are scanned for all additional guests
additional-services Prompts the end user to choose the upsell packages to be added to the reservation - Reservation - - - -
guest-details Allows each guest to enter additional information, in addition to the information scanned from the ID documents, fetched from the PMS or from the external guest data source (if this option is active) -
  • Reservation
  • DocumentData
 - Iterates through all guests, primary and accompanying and allows reviewing collected information and entering additional required details. All mandatory data (with red highlights) was entered.
booking-details Shows reservation details - Reservation - - -
add-credit-card Associates a credit card with a reservation - Reservation - When the reservation does not have a credit card associated, the end user is prompted to swipe a credit card in the credit card reader device. The credit card is pre-authorized (via the payment system associated with the PMS) and its information is read and stored in the PMS. Credit card successfully pre-authorized information and it's successfully read and stored in the PMS. The Kiosk App displays the last 4 digits of the credit card for informative purposes only. Our application never does any operation directly on the credit card. Any transactions (including pre-authorization) are done either by the PMS itself or by an external payment system integrated with Kiosk.
health-declaration Health related questions - Reservation DocumentData QuestionAnswers After all questions were answered the answers are saved into the Kiosk Database. Also the answers are available in PDF format. All questions had been answered.
signature Captures guest's signature. - Reservation GuestSignatureData The application captures guest's signature as an image. This image is saved in Kiosk Database and it can be viewed in Kiosk admin reports. If the system is configured to use guest registration cards, the guest signature is appended to the registration card, and saved in the Kiosk database. The signed reg card can be downloaded from Kiosk Admin reports too. If the system is configured for confirmation requests, notification is sent to Kiosk Admin for hotel staff review. Guest signature successfully captured and saved in Kiosk database + staff confirmation, if required.
keycard Programs guest room key card(s) - Reservation - - -
keycard-return Return guest room key card(s) - Reservation - - - -
folio-details Shows folio (billing) details and allows the end user to enter and optional email address to send a copy of the billing details. - Reservation CheckOutData - - Outflow only.
completed Displays completion message completion page
  • Reservation
  • CheckOutData (out subflow only)
 - Performs actual person registration (check in or check out) Successful check-in or check-out To be used in any subflow except 'extra', 'extra1' etc ...
additional-keys-completed Displays completion message after successfully requesting additional keys. completion page Reservation - Just shows the completion message - Extra subflow only

Data Models for Pages

Data model Structure
Reservation 
{
  featureCode: string;
  reservationNumber: string;
  guestLastName: string;
  guestFirstName: string;
  passportNumber: string;
  country: string;
  checkInDate: string;
  checkOutDate: string;
  adults: string;
  children: string;
  beds: string;
  rooms: Room[];
  reservationStatus: string;
  hasCreditCard: string;
  lastFourDigits: string;
  guestFullName: string;
  emails: Email[];
  phones: Phone[];
  memberships: Membership[];
  preCheckIn: string;
}
DocumentData 
{
  // Scanned image of the document
  scannedimage: string;
  // Photo of the person that is in front of the Kiosk app
  cameraimage: string;
  age: string;
  firstname: string;
  lastname: string;
  middlename: string;
  license: string;
  street: string;
  city: string;
  state: string;
  zip: string;
  country: string;
  address: string;
  dob: string;
  dobday: string;
  dobmonth: string;
  dobyear: string;
  expiry: Date;
  issuedate: string;
  authenticationresult: string;

  // more fields will go here.. IR and UV images etc.
  frontwhite: string;
  frontir: string;
  frontuv: string;
  backwhite: string;
  backir: string;
  backuv: string;
}
Room 
{
  roomNumber: string;
  roomType: string;
  roomTypeCode: string;
  roomRate: string;
  roomRateCurrency: string;
}

Customizing the language bar

The languages visible in the Kiosk Client can be selected and re-ordered. The languages seen in the application can be customized.

<!-- These are the available languages for this flow. The ordering will apply to the user interface. The first one will be the default language  -->
<!-- Code format: "<ISO 639 Language Code>-<ISO 3166 Country Code>" -->
<languages>
    <language code="en-US" pmsCode="E" />
    <language code="es-MX" />
    <language code="ja-JP" />
    <!--<language code="de-DE" />
        <language code="fr-FR" />
        <language code="it-IT" />
        <language code="pt-BR" />
        <language code="ms-MY" pmsCode="MS"/>
        <language code="zh-CN" />
        <language code="ar-SA" />
        <language code="vi-VN" />
        <language code="id-ID" />
        <language code="ru-RU" />
        <language code="th-TH" />
        <language code="zh-TW" />
        <language code="ko-KR" />-->
</languages>

For each <language> under the <languages> node, the application will display a button in the language bar. The first language in the XML file is the default language (the language that the application will start with). After a guest completes using the Kiosk and if they had changed the language, the language will return to the default language when the Kiosk starts over.

Each language node must contain the language code formatted as "-". For convenience, below we give a list of the supported languages along with their codes.

Language ISO-639 language code ISO-3166 country code Code to use in application
English en us en-US
Malay ms my ms-MY
Chinese (Simplified) zh cn zh-CN
Chinese (Traditional) zh tw zh-TW
Japanese ja jp ja-JP
Spanish es es es-MX
Italian it it it-IT
German de de de-DE
French fr fr fr-FR
Portuguese (Brazilian) pt br pt-BR
Arabic ar sa ar-SA
Russian ru ru ru-RU
Vietnamese vi vn vi-VN
Indonesian id id id-ID
Thai th th th-TH
Korean ko kr ko-KR