ID card bonus 1

Disclaimer

This document is only collection of author’s notes, experiences and point of views. It is not, in any meaning, either complete description of the topic nor official RTB documentation. It may be inaccurate, incomplete, obsolete, misleading or completely wrong. It may even cause loss of data or damage system integrity. It may not comply with company codex, values, presentation style or economic interests or may reveal company secrets.

As such, it is absolutely prohibited to distribute this document outside of RTB & Co. GmbH. Such an action may result into legal acts against both the sender and the company. It is only intended, after review of technical and presentational correctness and accuracy, to be used as an information source for official documentation.

Always contact documentation department for information about current presentation style and allowed formats before creating customer’s documentation.

1. Introduction

This bonus can verify whether a card number is contained in an uploaded list in a form of excel file. If card number is in the list then the PDM sells a parking ticket according a price defined by tariff specified in the list.

Oct 2016 was introduced first implementation which allows switching tariff by index The functionality above was introduced on Oct, 2016. See Description.
Aug 2021 added possibility to enter tariff name (instead of tariff index) to excel which will be given for specific card number. See Extension 1.
Aug 2023 added possibility to define expiration date, number of usages per period. See Extension 2.

Also known as: Italian social insurance card.

2. Description

Bonus was originally developed to verify Italian health cards. The requirement defined that operator will put all the health card numbers of people living in specific area to the excel sheet. It is uploaded to PDM.control. If such a person come it will get a special tariff defined in the excel table instead of standard one.

Three may be multiple bonuses of such a type defined in area. Each bonus is designated by its type which PDM needs to provide to define appropriate section in which is key (usually card number, license plate …) to be searched in.

2.1. UI

2.1.1. Bonus section

To configure such a bonus create new bonus type and define its name and optionally also a description. Value of name field should be kept short (only few characters) Value of description field is not used by PDM. It is only for for the operator to better remember for what purpose is this section used.

2.1.2. Excel file

After creation of bonus section its rules can be added.

If a new excel is uploaded all previous data for this card type are lost. Be sure that all relevant data are contained in the excel table.

Table 1. Structure of excel table
ID <text>	Tariff index <number>

Table 2. Example of excel table
16c3b7f4	5
2a05b41f	5
5f5e1000	7
1fbd1e20	5

2.2. Integration with PDM

Bonus can be request by real time command number 2.

Examples below shows content of MRQ mnemonic.

Sample request

[{
    "REQ": 2,
    "BID": { (1)
        "type": "health-1", (2)
        "key": "a" (3)
    }
}]

1	Object holding composite key of the requested bonus.
2	Bonus type as it is define above
3	An ID to lookup in database.

Response - bonus exist

[{
    "REQ": 2,
    "TID": 5 (1)
}]

1	Index of tariff which PDM must use.

Response - bonus does not exist

[{
    "REQ": 2,
}]

In this case information about tariff index is missing. PDM must use default tariff (or some of them which are freely available).

3. Extension 1

The first extension adds possibility to choose how the desired tariff defined in excel. Additionally to its index it is possible to define its name. In this case it does not matter on which exact position is the tariff stored in the tariff set in configuration.

3.1. UI

An option how is the tariff is define was added. Choose Index to keep original functionality or choose Name to consider content of second excel column as tariff name.

Table 3. Structure of excel table
Card ID <text>	Tariff name <text>

Table 4. Example of excel table
16c3b7f4	Resident 1
2a05b41f	Resident 1
5f5e1000	Disabled
1fbd1e20	Resident 1

3.2. PDM

Request to check if key is in the list. The procedure is the same as in previous version.

Sample request

[{
    "REQ": 2,
    "BID": {
        "type": "health-2",
        "key": "ABC"
    }
}]

After sending such a request 3 situation can happen.

Case 1: The key was found in specified type. At the same time tariff or required name exist on PDM. The such a case the tariff id is returned as result of this command.

Response - bonus exist

[{
    "REQ": 2,
    "TID": 5
}]

Case 2: The key was found in specified type. At the same time tariff or required name does not exist on PDM. The such a case the value -1 is returned as tariff id. It usually mean an error in configuration. In such a case PDM should send an information to operator to update configuration.

Response - bonus exist, tariff does not.

[{
    "REQ": 2,
    "TID": -1
}]

Case 3 The key was found in specified type. In such a case a TID filed is omitted to indicate to PDM that default tariff must be used.

Response - bonus does not exist.

[{
    "REQ": 2
}]

4. Extension 2

The second extension was requested by PM. It has to handle a case described by following specification.

ID
- Every ID defines expiration date. After this date it become invalid. It is still reported to the PDM that it exists but it cannot provide any bonus.
Bonus
Bonus limits usage of every individual ID per period. E.g. it can be used 6 times per week.
Bonus defines a clearing schedule. In such a moment usages of all IDs will be set to 0 and counter starts again.

Design decision

In order to make implementation easier the usage of each key is stored to the same table as it definition. It means that after excel upload usage of all keys (within the modified bonus) will set to 0.

4.1. UI

There is a new field in bonus definition which allows to define maximal number of issued bonuses and cron expression (see chapter Understanding CRON Expressions) to reset counters. Cron expressions can be created or validated by CronMaker or crontab guru.

Figure 1. Example bonus setting for a diver form club who can buy at most 4 tickets per week (reset at every Monday 00:00)

Table 5. Structure of excel table
ID <text>	Tariff index / name <number>	Expiration <Date>

Table 6. Example of excel table
7b5bcbec	Diver	2024-01-01
5a827999	Diver boss	2099-12-31

Note: Date format may be different based on Excel locale.

4.2. PDM

Additionally there are following real time request to support required functionality.

4.2.1. List bonus types

List bonus types which are available in Zone from the PDM sending request is.

Request list of bonus types.

[{
    "REQ": 50
}]

Response is array of available bonus types.

Sample response (there are bonuses defined)

[{
    "REQ": 50,
    "types": [
        {"type":"diver", "description":"Water World Sports (diving club)"},
        {"type": "fisher", "description": "Fishing club (regular member)"}
    ]
}]

It may be empty if there is no bonus defined.

Sample response (no bonuses)

[{
    "REQ": 50,
    "types": []
}]

4.2.2. Find ID within one bonus

If there a customer already selected a bonus and provided its ID, PDM may ask whether there is a bonus for such an ID. In order to achieve desired result real time requests 2 was extended to provide additional information in bonus key. PDM may use it to get additional information about bonus. Backward compatibility is kept.

Sample request

[{
    "REQ": 2,
    "BID": {
        "type": "diver",
        "key": "287D175A" (1)
    }
}]

1	A record key, usually card id or license plate number.

As a response PDM.control provides properties of selected ID.

Sample response, key exists

[{
    "REQ": 2,
    "TID":2, (1)
    "bonus": {
        "expiration":"2023-05-12T17:38", (2)
        "currentUsage":3, (3)
        "maxUsage": 6, (4)
        "expired":false, (5)
        "type":"diver", (6)
        "key": "287D175A" (7)
    }
}]

1	Tariff ID to switch to. Please note that tariff ID can be -1 in case that defined name (in excel) can not be converted to the index. If it does not exist on PDM a -1 is returned.
2	Key expiration in PDM local time.
3	How many times was the bonus already used since last reset.
4	How many times can be the bonus used within one period.
5	Key is already expired.
6	Bonus type (repeated from request).
7	Lookup key (repeated from request).

PDM has to verify whether the bonus is not expired and if total count will not be exceed by this sale.

If there is no record for specified key in the database, then the element bonus will be undefined (not present).

Sample response, key does not exist

[{
    "REQ": 2,
    "bonus": null
}]

4.2.3. Find bonus type for ID

This function can be used in case that a customer just present a card (or enters license plate) and PDM wants to find if such an ID is a part of some bonus type available in this zone.

Sample request

[{
    "REQ": 51,
    "BID": {
        "key": "287D175A"
    }
}]

Sample response for known key

[{
    "REQ": 51,
    "types": ["diver", "fisher"] (1)
}]

1	List of bonus types containing a key.

Sample response for unknown key

[{
    "REQ": 51,
    "types": []
}]

4.2.4. Use bonus

If PDM decides to use bonus in needs to indicate to PDM.control it to PDM.control. Additionally in must indicated how many bonuses was used. I may happen that a customer buys multiple tickets at once.

Sample request

[{
    "REQ": 52,
    "BID": {
        "type": "diver",
        "key": "287D175A"
    },
    "used": 1 (1)
}]

1	Number of time the bonus was used by PDM.

The answer shows new properties of the bonus after usage.

Sample response, key exists

[{
    "REQ": 52,
    "bonus": {
        "expiration":"2023-05-12T17:38",
        "currentUsage":3,
        "maxUsage": 6,
        "expired":false,
        "type":"diver",
        "key": "287D175A"
    }
}]

4.3. Typical use cases

4.3.1. Known bonus type

PDM knows bonus type in advance. Customer just provides bonus key to verify its availability.

4.3.2. Let a customer choose bonus first

In this use case a list of all available bonus types is first presented to customer. He chooses one of them and provides bonus key.

4.3.3. Let a customer provide ID first

This is a use case when a customer first provides a bonus key (card ID, LPN, …). Then PDM let him choose a bonus type and sell ticket.

4.4. Understanding CRON Expressions

A CRON expression is a string consisting of six or seven sub-expressions (fields), separated by white space, that describe individual details of the schedule.

A very useful tool that enables users to schedule tasks to run periodically at a specified date/time in the future, thus allowing the automation of a lot of tasks and processes that otherwise would require human intervention or another type of coordination.

4.4.1. Basics

The order of the six fields is:

{second} {minute} {hour} {day} {month} {day of the week} { year (optional)}

4.4.2. Examples

A CRON expression that can be used as a trigger that executes every three minutes looks like: 0 */3 * * * *`.

Or a CRON expression that executes "at minute 5 past every hour from 4 through 7 in February and March", looks like: 5 4-7 * 2,3 * (detils).

Special
character

Meaning

Example

Selects every value in a field

An asterisk "*" in the day of the week field means every day.

Separates items in a list

A comma "1,3" in the day of the week field means just Mondays (day 1) and Wednesdays (day 3).

Specifies a range

A hyphen "10-12" in the hour field means a range that includes the hours 10, 11, and 12.

Specifies an increment

A slash "*/10" in the minutes field means an increment of every 10 minutes.

Credit: Paris Polyzos, Source Understanding CRON Expressions.