Validating a Ticket

The aim of the Validation API is to help Operators perform various actions on the queue and tickets of an endpoint, and get information on the endpoint.

info

See Concept and Terms to read the definitions of endpoint, operator, time slot and other terms.

Step (1) Login

The first step consists in connecting to an endpoint (see Authentication and Pre-Login).

caution

Steps 1.a and 1.b are contradictory. The method is either to log with ID and password or to log with SSO.

Then, the logical progression until logout has three steps, as illustrated below.

Step (2) Open an Endpoint

To be able to perform actions on an endpoint the Operator must open this endpoint once s/he is connected to it.

PUT /endpoints/{endpointId}

⇾ Go to the route

Hidden Mode

By default, no action on tickets can be performed if the endpoint is closed. However, it is possible in some cases to log to the endpoint without opening it, which allows to perform actions on a closed endpoint.

This must be authorized at the queue level:

queue.config.hiddenModeAllowed === true

And for the Operator as well:

role.hiddenModeAllowed === true

Step (3) Get the Roles

Then, s/he must get the list of operator roles to know which actions s/he is allowed to do.

GET /operator/roles

⇾ Go to the route

The route returns all the roles that are possible for the Operator.

All the operator roles are associated to a queue.

{
  "companyId1": {
    "placeId1": {
      "queueId1": {
        "authorizedSetState": {},
        "extendedAttributes": {},
        "recallAllowed": true,
        "showIndicators": true,
        "hiddenModeAllowed": false,
        "bookingClosedForTodayAllowed": false,
        "pauseAllowed": false
      }
    }
  }
}

Main Roles

Below are the main attributes corresponding to the Operator roles.

Attribute	Description
authorizedSetState	An array listing all the state changes that the Operator is allowed to do. For example, any ticket with the status 0 - Booked can be changed to 200 - Called.
recallAllowed	A boolean. If true, the Operator is allowed to recall a ticket.
showIndicators	A boolean. If true, the Operator is allowed to consult the indicators.
hiddenModeAllowed	A boolean. If true, the Operator is allowed to perform actions on a closed endpoint.
pauseAllowed	A boolean. If true, the Operator is allowed to suspend a queue.

Extended Attributes Roles

The roles defined in the extended attributes are queue-specific, and vary from queue to queue.

Extended attributes are defined on a queue tickets. The list of the extended attributes is endless and match the specific needs of the Company. They are defined upstream with Lineberty.

info

Most of queues do not have any extended attributes, they are not required but implemented to enlarge the possibilities.

The extended attributes can be:

• More about the ticket user: Name, first name, age, does the user have priority, etc.
• More about the object of the ticket: A file number, a flight number, etc.

In the API, the field extendedAttributes will describe every action allowed for every attribute of the queue.

"extendedAttributes": {
          "civility": {
            "create": false,
            "read": true,
            "update": true,
            "delete": false
          },
}

In this example, the queue has only one extended attribute which ID is civility.
This attribute defines a role for the Operator who is allowed to read and update the civility field in the application but not to create nor remove it, even if the field has no value.

info

All the attributes of the queue are available in the queue object directly. See the route to GET THE QUEUE.

Time Slots

| Optional step |

Defining (and then deleting) time slots is a step that only concerns queues of a certain type, when the Operator must specify her/his attendance hours when arriving.
All the operators' attendance hours for a day will define the available time slots for the day.

info

Whether this step is optional or not will be defined when developing the interface of the Validation application.

One of the possible actions (see hereinafter) for the Operator will be to change the time slots. Such a modification must be allowed on the endpoint:

if ( endpoint.config.editTimeslotsAllowed === true ) {
  // The time slots can be modified, the action is allowed
} else {
  // The time slots cannot be modified, the action is not allowed
}

Step (4) Perform an Action

Once connected, the Operator can perform one or many actions among all the possible actions that have been defined for this place.

caution

This must be defined prior to the development of the Validation application, between Lineberty and the Company, since many actions require specific rights that Lineberty must grant to each user in particular.

There is no hierarchy between these actions and no predefined order: the Operator can perform any action before or after any other action.

Get the Suspended Tickets

The Operator can get the list of all the tickets that remain 'on hold' in the queue for the current day, in other words all the tickets that are not at the final state (either Done or Canceled).

GET /queues/{queueId}/tickets/currents

⇾ Go to the route

tip

You can use SSE requests to get the state changes made on all the tickets in real time. The list of tickets that is returned is paginated to reduce the volume.

GET /queues/{queueId}/tickets/currents/SSE

Get the Ticket History

The Operator can get the list of all tickets that ended during the day, that is to say all the tickets which state is either 'Done' or 'Canceled'. The list of tickets that is returned is paginated to reduce the volume.

GET /queues/{queueId}/tickets/history

⇾ Go to the route

Get the Tickets for the Coming Days

The Operator can get the list of all the tickets that are booked for the coming days, whatever their state is. It is possible to define a start and an end date to limit a time period. The list of tickets that is returned is paginated to reduce the volume.

GET /queues/{queueId}/tickets/nextDays

⇾ Go to the route

Search for Tickets

The Operator can make a search on tickets using various attributes as search criteria, such as the ticket ID. However, the number of returned tickets is limited to avoid saturation. It is better to use precise search criteria.

POST /queues/{queueId}/tickets/search

⇾ Go to the route

Change the Ticket State

The main role of the Operator is to move people (i.e. tickets) through the queue by changing the state of the tickets.

PUT /tickets/{ticketId}/states

⇾ Go to the route

caution

A change of state is possible only if it is authorized both at queue level and at operator role level.

Limitation at Queue Level

Not all state changes are allowed. There is a limitation to the possible state changes at queue level.

queue.config.authorizedSetState

Example of values 
{
  "100": [
    200
  ],
  "200": [
    300,
    500
  ],
  "500": [
    700
  ]
}

These arrays mean that:

• If the ticket state is 100 - Alerted it can only change to 200 - Called.
• A ticket which state is 200 - Called can change either to 300 - On hold or to 500 - In progress.
• However, if the ticket state is 0 - Booked or 400 - No show, no action is possible on the queue because these values are not listed.

Limitation at Operator Role Level

There is also a limitation at the operator role level, for every queue to which s/he has access.

role.authorizedSetState

Change the Attributes of a Ticket

On some queues, it is possible to modify ticket attributes, which are queue-specific fields.

PUT /tickets/{ticketId}/extendedAttributes

⇾ Go to the route

Modifying these attributes is submitted to rights that are allocated at queue level:

if ( queue.config.extendedAttributes[ ATTRIBUT_NAME ].editAllowed === true ) {
  // The edition of the attribute is allowed
} else {
  // The edition of the attribute is not allowed
}

Or that are allocated at operator level:

if ( queue.config.extendedAttributes[ ATTRIBUT_NAME ].update === true ) {
  // The modification of the attribute is allowed
} else {
  //  The modification of the attribute is not allowed
}

Recall a User

A User who has not shown up after being called, can be recalled by the Operator and notified on her/his phone, and/or by receiving an email and/or an SMS.

GET /tickets/{ticketId}/recall

⇾ Go to the route

This notification can be sent only if the action is allowed on the queue:

if ( queue.config.recall.allowed === true ) {
  // The queue allows to recall a user
} else {
  // The queue does not allow to recall a user
}

And only if one of the Operator's role is allowed to recall a user:

if ( role.recallAllowed === true ) {
  // The Operator is allowed to recall a User
} else {
  // The Operator is not allowed to recall a User
}

Anti-Spam Rules

To prevent abuse there are anti-spam rules:

Key	Rule
queue.config.recall.firstDelay	A minimum delay between the moment when the ticket is called and the first time it is recalled.
queue.config.recall.delayBetweenRecall	A minimum delay between two recalls sent to the User.
queue.config.recall.maximumRecall	The maximum number of possible recalls sent to a same User.

Display Indicators

Indicators are available to track the state of the queue and get various information on the traffic such as the number of booked tickets, the number of validated tickets, etc.

GET /queues/{queueId}/indicators

⇾ Go to the route

Displaying the indicators must be allowed on the queue:

if ( queue.config.showIndicators === true ) {
  // The queue allows to display the indicators
} else {
  // The list of indicators cannot be displayed for this queue
}

In addition, the Operator must be allowed to display the indicators:

if ( role.showIndicators === true ) {
  // The Operator is allowed to display the indicators
} else {
  // The Operator is not allowed to access the indicators
}

Change the Time Slots

For many reasons, such as close arlier, open later, suspend the queue to take a break, etc. the operator may want to change the time slots (see above) of the endpoint.

PUT /endpoints/{endpointId}/timeslots

⇾ Go to the route to define the time slots.

DELETE /endpoints/{endpointId}/timeslots

⇾ Go to the route to delete time slots.

This is possible only if the action is allowed on the endpoint:

if ( endpoint.config.editTimeslotsAllowed === true ) {
  // Editing the time slots is allowed on the endpoint
} else {
  // The time slots cannot be edited on the endpoint 
}

Suspend the Queue

The Operator may want to suspend (pause) the queue and block any movement on it in the event of a problem preventing the normal functioning of the queue. For example, a checkout or an attraction breaks down.

PUT /queues/{queueId}/pause

⇾ Go to the route

This action is possible only if it is allowed on the queue:

if ( queue.config.pause.editAllowed === true ) {
  // The queue can be suspended
} else {
  // The queue cannot be suspended
}

And only if the Operator is allowed to do it:

if ( role.pauseAllowed === true ) {
  // The Operator is allowed to suspend the queue
} else {
  // The Operator is not allowed to suspend the queue
}

Get the Counter Value

A counting system is implemented to count the number of people entering or leaving the place.

GET /counters

⇾ Go to the route

A SSE route allows you to get values in real time and receive an event each time a counter is incremented/decremented.

GET /counters/SSE

⇾ Go to the route

Change a Counter Value

It is possible to change the value of a counter to increase or decrease it.

PUT /counters/{counterId}

⇾ Go to the route to increment a counter.

DELETE /counters/{counterId}

⇾ Go to the route to decrement a counter.

There is no specific permission to edit a counter value.

Step (5) Logout

When the operator has finished her/his day, s/he must disconnect from the endpoint and then, logout (if s/he connected in SSO).

caution

If the operator wishes to close the endpoint earlier, s/he must delete any time slots remaining between the current time and the original scheduled end time, otherwise the queue will still be considered open.