Skip to main content
All CollectionsSetting up Yapster 🛠KPI Games
KPI Gamification - Business Data/EPOS Data Specification
KPI Gamification - Business Data/EPOS Data Specification

Data Requirement for the Yapster's KPI Gamification Module

M
Written by Meg Payne
Updated over 2 years ago

The KPI Gamification Module is supported by live business data so we've compiled the requirements and guidance on this below. This is classified into:

  • Business data requirements

  • Data-file transport

  • Data-file format

  • Data-file requirements

  • Data-file schema

Having reviewed the article, if you are unsure if your existing systems can incorporate the details outlined below, please send an example file to support@yapster.info where the team will be happy to review and verify this for you.

Customer Business Data Requirements

The customer MUST provide us with data-files from which we can extract the following values for each participant, for each day:

  • participant-id

    • if you are running site/store-level competition then this should be site/location-id (which matches those already in Yapster via your HR feed), if you are running inter-area competition then area-id etc. There is no harm in having store-id, area-id, region-id, all in the file as this will give you the flexibility to run games at the various levels.

  • timestamp (ideally ISO8601)

    • we can work with: daily rollups, finer-grained rollups, or even unaggregated data.

  • KPI measure

    • this is what participants will compete on, so should be some number or numbers you want to drive. There is no harm in having multiple competitive measures in a feed, indeed this will make it easier to run new games on different measures since we won't then have to set up another data feed.

  • scaling-factor measure

    • this allows larger locations to compete fairly against smaller locations and should be something that can be used to scale the competitive measure. In a restaurant setting, it could be total sales, number of orders, or something similar.

Data-file Transport

There are several options to get data to us, listed below in a rough order of preference:

  1. CSV files put to our SFTP

  2. Get CSV files from your SFTP

  3. CSV files stored on one of our S3 buckets shared with you

  4. CSV files stored on one of your S3 buckets shared with us

Data-file Format

We can accept data-files formatted as:

  • CSV

  • TSV

  • excel

Data-file Requirements

The customer can provide data in a variety of files, schema, and aggregations (or not), but there are some general requirements:

  • There MUST be data for every participant for every day in a season. missing data will cause a game to be paused until it is provided (this can be overridden with configuration, with the obvious caveats about possible incorrect or unfair outcomes)

  • Measures in data-files MUST aggregate sensibly - i.e. it MUST be possible to get to a 7-days figure for a measure by a simple sum of 7 daily values for the measure. this means that e.g. a % ratio of 100 * desserts/covers is not a suitable measure. instead, we need the desserts and covers measures separately

  • There MUST NOT be any duplicate data, either within a single file or across all files

  • Temporal aggregations MUST NOT be coarser than 1 day. Ideally, temporal aggregations should fit cleanly within day buckets, but if not each aggregation period will be assigned to one particular day.

  • Data files SHOULD be named so that they will not overwrite any already provided files (if this can’t be done then we will have some remedial work to do to avoid data gaps after service issues)

  • All data files relating to the previous-day’s trading SHOULD be delivered to us well before the daily-update messaging time (which is configurable). If this is not possible then we can still run a game, but we will have to inject “waiting for data” messages on some days, and data updates will refer to two days previously, so the game experience is impaired.

Data-file Schema

We are flexible about the schema of the data in the files we accept from the customers.

There are 2 predefined types of schema we can process with minimal configuration:

  • pre-aggregated data with columns (no specific column names need to be used, as long as they are consistent - see data-mapping below) for (participant-id, timestamp, kpi-measure, and scaling-factor-measure). If the customer wants to provide a range of KPI and scaling factor measures in each record they can add as many columns as they wish, which will offer more flexibility with future games.

  • itemised data, which may be raw transactions or may be aggregated. Itemised data will generally include columns (again, we don’t require specific column names, as long as they are consistent) for (participant-id, timestamp, line-item-code, value)

If needed, we can also accept customer-data in any arbitrary schema (over any number of separate files) which can be processed with a SQL query to extract the values we require, although the additional work associated with the data-mapping, if significant, may incur an additional cost.

For any further questions, please contact our Support Team at support@yapster.info!

Did this answer your question?