Kinesis Configuration Setup

Article author
Cory LeFevre
  • Updated

Description:
This article outlines how SkyTab Venue integrates with client-hosted AWS environments using Amazon Kinesis to stream real-time order state changes. Learn how to configure the necessary infrastructure, manage permissions, and interpret payload structures to enable secure and scalable data consumption.


Table of Contents


Kinesis Feed Overview

  1. SkyTab Venue's ordering app publishes to a Kinesis stream in SkyTab Venue's AWS account.
  2. An SkyTab Venue-managed Lambda publishes those messages to a stream in your account (that you set up).
  3. You would write a Lambda and connect it to your own Kinesis stream—and you can define any business logic inside your own Lambda.

SkyTab Venue supports this setup because it gives you full control over your Lambda's business logic, hosted in your own AWS account. You can also control scale by adjusting the appropriate Kinesis shard count.


Controlling Access

There is some IAM configuration needed to give the SkyTab Venue Lambda permission to publish to the stream in your AWS account. This has been implemented before. Without going deep into technical detail:

  • Create a “Kinesis Writer” IAM role.
  • The role’s trust policy must trust the ARN of the SkyTab Venue Lambda role.

Example pseudocode:

credentials = Aws::AssumeRoleCredentials.new(role_arn: "THE-ARN-OF-THE-WRITER-ROLE-YOU-CREATED")
kinesis_client = Aws::Kinesis::Client.new(credentials)

kinesis_client.put_record(stream_name: "your-stream-name", data: <JSON PAYLOAD HERE>)

Our Lambda assumes the role you prepare in your AWS account before publishing. Because that role trusts SkyTab Venue, our Lambda is able to publish to your stream.


Implementation Order

You could:

  1. Create a Kinesis stream in your AWS account.
  2. Create a “Kinesis Writer” role (do not add the trust policy yet).
  3. Provide SkyTab Venue with:
    • The ARN of the Kinesis Writer role
    • The region of the stream

Then SkyTab Venue will:

  1. Provision the Lambda that publishes to your stream.
  2. Provide you with the ARN of the Lambda’s role so you can update the trust policy on your “Kinesis Writer” role.


SkyTab Venue Integration

SkyTab Venue’s ordering system (known as “Stadium”) publishes messages when order states change. These messages can be integrated into your systems.

How it works:
A SkyTab Venue-hosted Lambda consumes messages and publishes them to a Kinesis stream in your AWS account. You may connect any number of client-hosted Lambdas to this stream.


Requirements

SkyTab Venue

  • A Kinesis stream for each environment (e.g., mars-dev, levis-prd)
  • A dedicated Lambda to publish to your Kinesis stream

Client

  • A client-hosted Lambda to consume from your Kinesis stream


Identity Management / Permissions

To complete the setup, create the following in your AWS environment:

  • A Kinesis stream
  • A consumer Lambda with any business logic required
  • An IAM role or user for that Lambda, with permissions to read from the stream and access other AWS resources
  • A “Writer Role” that SkyTab Venue’s Lambda can assume. This role must grant sts:AssumeRole to the SkyTab Venue Lambda’s ARN


Sample Payload

{
    "_id": "01egndytjh3xmmt154hxa6dz4m",
    "_v": 1,
    "o": "cubs",
    "u": "1d1c41ee-a875-43dd-ad9c-4375256190de",
    "s": "stadium",
    "e": "order.state.change",
    "p": {
        "uuid": "b120fdbf-9b4e-44a8-99fd-4e21e3709c1f",
        "venue_uuid": "e13b6c22-fdcf-4446-ba25-c240bc9bc40b",
				"confirmation_number": "1234",
        "state": "completion_pending",
        "created_at": "2020-08-26T01:02:46Z",
        "total": 7500,
        "tax": 250,
        "discount": "0",
        "tip": 1250,
        "device_uuid": "817c505d-d620-467b-b8a7-77ba9cd2fd30",
        "revenue_center_name": "Suite 101",
        "revenue_center_external_ref_id": "external-suite-101",
        "revenue_center_uuid": "c30550a3-4f87-4a7d-8fd9-22afc2bdbbdb",
        "menu_name": "Day of Event",         "menu_external_ref_id": "external-day-of-event",
        "service_type": "POS",
        "employee_name": null,
        "employee_id": null,
        "transaction_history": [{
            "state": "authorized",
            "time": "2020-08-26T01:02:47Z"
        }],
        "state_history": [{
            "state": "tabbed",
            "time": "2020-08-26T01:02:46Z"
        }, {
            "state": "processing",
            "time": "2020-08-26T02:28:12Z"
        }, {
            "state": "completion_pending",
            "time": "2020-08-26T02:28:13Z"
        }],
        "line_items": [{
            "uuid": "6d268953-85c8-4db4-8091-33676e890c6f",
            "name": "Sausage Sampler",
            "price": 1000,
            "sku": "5001",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": [{"discount_amount_in_cents": 0, "uuid": "8e8c197e-9b2b-4f40-a528-ce28f51404d7"}]
        }, {
            "uuid": "8aed311c-3c2d-46d8-9d63-c6d218491c1d",
            "name": "Sausage Sampler",
            "price": 1000,
            "sku": "5001",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": []
        }, {
            "uuid": "038418fc-59b8-4b91-b8f7-b5d71ef2bbe1",
            "name": "Sausage Sampler",
            "price": 1000,
            "sku": "5001",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": []
        }, {
            "uuid": "a4b862dc-bb73-4ae0-a805-5ddd25e6d7a7",
            "name": "Sausage Sampler",
            "price": 1000,
            "sku": "5001",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": []
        }, {
            "uuid": "d888d272-2260-4761-8809-5a7ab92a1ec1",
            "name": "Sausage Sampler",
            "price": 1000,
            "sku": "5001",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": []
        }, {
            "uuid": "887c26fd-0669-4d78-9319-ab46dbf3b86d",
            "name": "Service Charge",
            "price": 1000,
            "sku": "8374626",
            "created_at": "2020-08-26T01:02:46Z",
            "refunded_at": null,
            "removed_at": null,
            "modified_line_item_uuid": null,
            "promotions": []
        }]
    }
}

 


Data Types

{
    "_id": standard ULID string
    "_v": short integer
    "o": 256 character string
    "u": 36 character UUID
    "s": short string, currently always “stadium”
    "e": 256 character string
    "p": {
        "uuid": 36 character UUID string
        "state": 256 character string
        "created_at": 256 character date string
        "total": 16-bit integer total in cents
        "tax": 16-bit integer tax in cents
        "discount": 256 character string discount amount
        "tip": 16-bit integer tax in cents
        "device_uuid": 36 character UUID string
        "revenue_center_name": 256 character string
        "revenue_center_external_ref_id": 256 character string
        "menu_name": 256 character string
        "menu_external_ref_id": 256 character string
        "service_type": short string
        "employee_name": 256 character string
        "employee_id": 256 character string
        "transaction_history": [{
            "state": 256 character string
            "time": 256 character date string
        }],
        "state_history": [{
            "state": 256 character string
            "time": 256 character date string
        }],
        "line_items": [{
            "uuid": 36 character UUID string
            "name": 256 character string
            "price": 16-bit integer price in cents
            "sku": 256 character string
            "created_at": 256 character date string
            "refunded_at": 256 character date string
            "removed_at": 256 character date string
            "modified_line_item_uuid": 36 character UUID string
        }]
    }
}

 


Payload Deduplication Tip

Each payload includes a state_history array with timestamps. If two payloads have the same values and the latest timestamps match, the order state has not changed.

To quickly detect duplicates, hash a sorted (by date) version of the array. A repeated hash indicates a duplicate message.


Kinesis Feed Field Reference

General Fields

  • _id: Unique identifier of the Kinesis payload
  • _v: Version of the service (always 1)
  • o: Organization identifier
  • u: User identifier
  • uuid: State listener identifier
  • s: Source service (always "stadium")
  • e: Event type (always "order.state.change")

p (Order Object)

  • uuid: Order identifier
  • venue_uuid: Venue identifier
  • state: Current order state
  • client_created_at: Timestamp when order was started
  • created_at: Timestamp when order was created
  • device_subtype: Device type
  • total: Total in cents
  • tax: Tax in cents
  • discount: Discount in cents
  • tip: Tip in cents
  • device_uuid: Device identifier
  • revenue_center_name: Location name
  • revenue_center_uuid: Location identifier
  • menu_name: Menu name
  • menu_external_ref_id: Menu external reference ID
  • service_type: Service type (e.g., Concessions, Delivery, POS)
  • employee_name: Employee name (if applicable)
  • employee_id: Employee ID (if applicable)

Payment Transactions

  • authorization_amount: Authorized amount in dollars
  • payment_type: Payment source
  • settlement_amount: Settled amount in dollars
  • created_at: Payment timestamp
  • last_four: Last four digits of credit card (if available)
  • transaction_history: State and timestamp of payment changes

Order State History

  • state: State of the order
  • time: Timestamp of the state

Line Items

  • uuid: Line item identifier
  • name: Item name
  • price: Price in cents
  • sku: SKU of the item
  • created_at_date: When the item was created
  • refunded_at_date: Refund timestamp
  • removed_at_date: Void timestamp
  • updated_at: When the item was added to the cart
  • modified_line_item_uuid: Modified item reference (if applicable)
  • tax_amount_in_cents: Tax per item
  • tax_inclusive: Indicates if tax is included in the price
  • item_uuid: Menu item ID

Promotions

  • discount_amount_in_cents: Discount per line item in cents
  • uuid: Promotion identifier

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Related articles

Comments

0 comments

Please sign in to leave a comment.