Operator Integrations with BOSS

To enable a seamless integration to POS with the staff of JSM we need to have three integrations with BOSS.

1. Staff Importing to Operators
2. Clock In Status for Allowing to Sign In
3. Check Transaction on clock out of BOSS

Staff Importing

To enable POS to know who is to use POS and then what permissions they have we need to have a new field in BOSS, and a way to pull that information.

The new field ideally would be a nullable value, where null means they cannot use POS, but if a value it's their operator level.

The outcome would be a list with the following fields:

Field Name	Purpose
Staff ID	Unique GUID from BOSS for each staff member
Pin Code	Pin Code unique to a member of staff
First Name	First Name
Last Name	Last Name
Operator Level	A value of ADMIN, MANAGER, SUPERVISOR or OPERATOR

To provide clarity, an operator level means:

Level	Purpose
Admin	Global POS User who can do any operation
Manager	Venue Manager who can do cashing up operations
Supervisor	Ability to override sign ins and sales reviews
Operator	Can just use a till to process transactions

The API will only return active staff who have a POS Operator level.

The list of operators needs to be unique per site. For clarity, if the staff member works in two venues we need to know that.

Due to the above I suggest a schema such as

{
    "id": "GUID",
    "pinCode": 123456,
    "firstName": "Test",
    "lastName": "Test",
    "operatorLevel": "OPERATOR",
    "venues": [
        "EINSTEIN",
        "SOHO"
    ]
}

POS will call the API hourly to get a current list of staff registered for that venue, and will merge this into it's database and disable any it no longer finds.

Transaction Check

To enable POS to not become in a locked state for an operator. BOSS will Check POS when clocking out if there are any open transactions.

You will need to have a Client ID and secret issued from the ID system.

Authenticating

You will need to acquire a bearer token from the IdP before sending a request to POS Engine.

This can be acquired by calling the following endpoint, with the method HTTP POST and a form body and content type of application/x-www-form-urlencoded

QA Endpoint = https://id.jsm.systems/realms/pos-qa/protocol/openid-connect/token

PROD Endpoint = https://id.jsm.systems/realms/pos-prod/protocol/openid-connect/token

Body

Name	Value
grant_type	client_credentials
client_id	stock
client_secret	TO BE PROVIDED
audience	api-pos-engine
scope	roles

Web Hook Endpoint

To get the information you will need to do a GET to

QA End Point = https://api.qa.pos.jsm.systems/boss/check-operator/{bossId}

PROD End Point = https://api.pos.pubinvest.co.uk/boss/check-operator/{bossId}

Authorization header as Bearer and then your token.

The result will be

{
  "bossId": 0,
  "hasOpenTransactions": true,
  "transactions": [
    {
      "transactionId": 0,
      "operatorId": 0,
      "transactionNumber": 0,
      "workstationTerminalNumber": 0,
      "siteName": "string"
    }
  ]
}

Field	Description
bossId	BOSS ID of OPERATOR
hasOpenTransactions	Whether there is any open transactions on the till
transactions	List of transactions to resolve before clocking out

Transaction Details

Field	Description
transactionId	Internal ID of Transaction
operatorId	Internal ID of Operator
transactionNumber	Transaction Number the person knows to use
workstationTerminalNumber	The Till Number the issue is still on
siteName	Name of POS Site

Till Sign On Process

When a staff member starts their shift on a till they will go through a process to get a fob assigned.

The flow for this is:

1. Start "Sign On" on till
2. Search for their name on the operator list, which is a list from POS of operators not currently assigned on POS
3. Enter their BOSS Pin Code for security
4. Call BOSS API to check if that staff member is clocked in to the relevant venue.
5. If clocked in, allow till session
6. If not clock in, they cannot work on a till.

If BOSS is down they will automatically allow sign in

I think there is an API already built for this but can we get a refresh of it? :)

We may need an API to search for a person too who is in a different venue for the scenario where a member of staff works at one bar, say Black Rabbit, but goes and works in SOHO. THey would not be on the system as SOHO but will clock in.

This means we need to be able to on demand on the till ask BOSS to get a person who's clocked in, it may be ideal to have an API to get all users clocked in for a venue, with a filter on where we can pass BOSS ID in to restrict to one result.