Multitariff 2

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. Official specification

1.1. Appearance and setup

Currently this described function is requested for the usage of owners of hybrid and electric vehicles but in the future, it could be used in completely different contexts.

1.2. Functionality

Customer basically needs Multitariff based on LPN. Additionally, following conditions and parameters in excel are necessary:

Start date subscription
Expiry date subscription
Tariff name

Customer will have to buy subscription in office of parking management.

Parking manager will upload the excel list with valid subscriptions.

Additionally, it is necessary to have an export function for this excel files in order to compare lists in excel format.

If customer wants to add / change subscriptions he has to upload an excel file which includes only added and/or changed lines. These lines will be merged in database during upload.

1.2.1. Payment procedure

Conditions:

The subscription was paid in an office and was uploaded in an excel list to PDM.control.

Actions on PDM and PDM.control:

User selects tariff "Subscription" and confirms the selection with green button.
User dials the LPN on PDM and confirms with green button.
PDM sends LPN with request for Multitariff to PDM.control.
PDM.control checks for LPN, start date and expiry date on subscription list and responses following information to PDM:
- Validation check answer
- Used tariff
If these responses are negative PDM shows the information on display and interrupts the operation.
If the response is positive user will get a bonus ticket or pay by coins/cards and PDM proceeds the payment.

1.2.2. Subscription renewal

Conditions:

1 The subscription was paid in an office and was uploaded in an excel list to PDM.control.

Actions on PDM and PDM.control:

User pushes TT button and chooses the tariff "Subscription renewal" and confirms the selection with green button.
User dials his LPN and confirms with green button.
PDM sends subscription renewal request to PDM.control.
PDM.control responses following information to PDM:
- Validation check answer LPN
- Start and expiry date of current/previous subscription
If these responses are negative PDM shows the information on display and interrupts the operation.
If the response is positive previous expiry date will be new start date for subscription
PDM.control has to renew expiry date to new expiry date on database.
The ticket includes the expiry of subscription.

2. Clarifications

2.1. Tariff validation

2.1.1. PM request

Should PDM.control validate tariff name provided in excel? There are two possibilities.

YES

Tariff which should be used will be stored as reference to existing tariff in a Zone.

Advantages:

User can not specify tariff which does not exist. It will eliminate errors in run-time caused by typos or incorrect expectations. Errors will be recognized very early (if all PDMs within one Zone use exactly same configuration and tariffs).

Disadvantages:

Issue 1: Tariff must exist at least on one PDM. If it is hidden and nobody can use it will be not possible to upload excel. It may create dead lock:

Tariff was not used on PDM; it cannot be defined in excel.
Tariff is not defined in excel; it cannot be used on PDM.

Solution 1: In such a case it necessary to be inserted tariff artificially. One payment with this tariff name has to be done at least at one PDM to let PDM.control know that such a tariff exists.

Issue 2: If tariff stop exist on PDMs within the zone reference is lost and bonus definitions which required such a non-existing tariff will be deleted. This is correct behavior, because PDM cannot use tariff which does not exist anyway. But user may be confused that some of his definitions will suddenly disappear without "any obvious reason".

Tariff in excel is completely independent on situation in town. They will be stored as text in the database. All errors and typos will be accepted during import. All errors will manifest at run-time on the street.

Please discuss with management or customer, which behavior is preferred.

2.1.2. Decision

It is clear that we have to focus on option "No". I think it is a better option and I’m sure Input would say the same. Especially Issue 2 would be really bad.

2.2. Subscription scope

2.2.1. PM request

It is written in specification:

The subscription was paid in an office and was uploaded in an excel list to PDM.control.

— Specification by RTB

If I remember correctly we have originally talked about uploading the excel to zone. Therefore the sentence should be "The subscription was paid in an office and was uploaded in an excel list to appropriate Zone in PDM.control".

It also mean, that subscription works independently for every enforcement zone. Is it correct?

Decision

Correct.

3. Implementation

This feature is composed from several functions. Each described in its own chapter.

Bonus definition depends on Zone. Be aware that if the zone is deleted, all bonus definitions will be deleted as well.

3.1. Excel upload

Following column structure is expected.

According to specification, the bonus is Zone specific. If you want to use it in multiple zones, you have to upload excel multiple times. Extension of subscription on PDM will extend it only in PDM’s Zone. Other zones will stay untouched.

Should excel contain header row which is ignored with fixed column order?

Should excel contain column name, therefore columns order do not matter?

Table 1. Excel structure
Name	LPN	Start date	Expiry date	Tariff Name	Days after expiry date to renewal
Type	String	Date	Date	String	Number

Only rows which should be put to database must be uploaded. Database is not deleted before upload. All previously uploaded rows stays unchanged unless conflict.

In case of data conflict, row from excel always overwrites row in database. LPN is considered to be unique and treated as primary key. If there is multiple definitions for the same LPN then last definition is taken. Be careful about not overwriting of subscription extended from PDM during processing excel outside PDM.control.

If you want to deactivate subscription for some LPN, upload new record which expiry date, which is in the past more then "number of days after expiry to renewal".

Expired rows will be from time to time automatically deleted from database. Do not be surprised that expired LPNs are missing in downloaded excel.

Processing of dates: Time provided is excel is ignored. It is always assumed to be 00:00:00. It is not clear how to process it if it would not be.

Start date - Subscription starts at 00:00:00 in uploader’s time zone, inclusive.
Expiry data - Subscription ends at 00:00:00 in uploader’s time zone + 1 days, exclusive.

Table 2. Example of date processing
—	Start date	Expiry date
Excel definition	2021-01-01	2021-12-31
Real time stamp	2021-01-01T00:00:00	2022-01-01T00:00:00

3.2. Remote functions for PDM

3.2.1. Subscription offer

PDM can ask about subscription availability by request 25. Time stamps are provided in PDM time zone. It may be different then uploader’s time zone. Please note that end time stamp to is exclusive.

Examples below shows only content of MRQ mnemonic related to current request. Keys can be unquoted unless they contains spaces or special characters. MRQ it self is array[]. The rest of message is standard.

Standard PDM message

PSA10027;GAC00011;DTM2021-05-12T17:08:00;VER7.5.5.54;PID1C38FC9346;MRQ[...];...;CRC1234

Request

Offer subscription (request)

{
    "REQ":25,
    "LCN":"PBAA111"
};

Response

If subscription exist, its parameters are send to PDM in all cases in subscription object. Meaning of its element is following.

from- Time stamp when subscription becomes valid,
to - Time stamp when subscription becomes invalid,
renew- until when it is possible to renew subscription on PDM.
tariff - tariff to be used with this subscription. If tariff is empty subscription cannot be used.

Subscription is valid and can be used

PDM.control will provide subscription details for requested LPN. It also provides information if it is possible to get bonus tariff to user in filed TID. There are three possible cases:

1 - 12

PDM must use tariff with provided index.

Bonus is not available. Use standard tariff.

-1

Configuration error. Either the PDM is not a part of any zone or PDM does not have required tariff.

Subscription exists and can be used (response)

{
    "REQ":25,
    "LCN":"PBAA111",
    "TID":5,
    "subscription":{
        "from":"2021-01-01T00:00:00",
        "to":"2022-01-01T00:00:00",
        "renew":"2022-01-05T00:00:00",
        "tariff":"Electric & Hybrid cars"
    }
}

Subscription exist but can not be used

Subscription for this LPN exists but cannot be used. It may be already used within defined parameters. It may be available again in future.

Such a subscription can be still extended until renew value.

Subscription exists and can not be used (response)

{
    "REQ":25,
    "LCN":"PBAA111",
    "TID":0,
    "subscription":{
        "from":"2021-01-01T00:00:00",
        "to":"2022-01-01T00:00:00",
        "renew":"2022-01-05T00:00:00",
        "tariff":"Electric & Hybrid cars"
    }
}

Subscription does not exist

If subscription is not found on server, element subscription does not exist.

Subscription does not exist (response)

{
    "REQ":25,
    "TID": 0,
    "LCN":"PBAA111",
    "available": false
}

3.2.2. Consumption of subscription

Request

If PDM uses subscription bonus, it has to inform PDM.control about it by following request.

Consumption of subscription bonus (request)

{
    "REQ":26,
    "LCN":"PBAA111"
}

Response

There is no response data. Therefore content of the response is empty. PDM is only notified that that request was processed.

Consumption of subscription bonus (response)

{
    "REQ":26
}

3.2.3. Renewal of subscription

Subscription can be extended by real time request 27. It is also necessary to send payment to payment log using standard mechanism.

Request

PDM has to indicate license plate and new end of subscription (exclusive) inside request 27.

Subscription extension (request)

{
    "REQ":27,
    "LCN":"PBAA111",
    "to":"2023-01-01T00:00:00"
}

Response

PDM.control indicates back whether the subscription was extended successfully by repeating subscription object. It may happen that:

somebody canceled subscription between initial request and this one
subscription expires
some server error prevents extension

In case of success the response may look like this.

Successful subscription extension (response)

{
    "REQ":27,
    "LCN":"PBAA111",
    "subscription":{
        "from":"2021-01-01T00:00:00",
        "to":"2023-01-01T00:00:00",
        "renew":"2023-01-05T00:00:00",
        "tariff":"Electric & Hybrid cars"
    }
}

In case that subscription to extend was not extended, null subscription will be returned.

Failed subscription extension (response)

{
    "REQ":27,
    "LCN":"PBAA111"
}

3.3. Automatic cleanup

Automatic cleanup of old data runs weekly every Saturday about 3 o’clock. Please be aware that exact time may be changed in future.

Data to be cleaned:

Subscriptions after expiration and extension period.
Used bonuses older then 30 days.