Group IT Template Business Requirement Identifier ... D - DEM-02737... · formal documentation, the...
Transcript of Group IT Template Business Requirement Identifier ... D - DEM-02737... · formal documentation, the...
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
1
SERVICE REQUEST DETAILS
Business Division Customer Services
Business Requestor(s) Brian Mokgele
Business Senior Manager Lloyd Mokgotho
Demand Name Online Vending System Replacement
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
2
Contents
CONTROL TABLE ................................................................................................................................... 4 1.
CUSTOMER AND STAKEHOLDER DETAILS .............................................................................................. 5 2.
2.1 Customer Information ................................................................................................................ 5
2.2 Group IT Information .................................................................................................................. 5
GLOSSARY OF TERMS / DEFINITIONS .................................................................................................... 6 3.
BUSINESS REQUIREMENTS SPECIFICATION FOCUS ............................................................................... 16 4.
REASON FOR THE REQUIREMENT........................................................................................................ 16 5.
5.1 Define the current business challenges / issues that need to be addressed ........................................... 16
5.2 Define the high level gaps between the “As-Is” and “To-Be” state ....................................................... 17
5.2.1 Current “As-Is” situation i.e. how is the situation currently been managed (diagrams to depict the platform) ........................................................................................................................................... 17
5.2.2 “To-Be” situation i.e. how would the business prefer to work/operate to address the business challenges. ........................................................................................................................................ 25
5.2.2.1. New additional OVS high level functionality: ................................................................................... 25 5.2.2.2. New Additional PSG high level functionality: ................................................................................... 26
AS IS AND TO BE BUSINESS PROCESS ACTIVITY MAPPING .................................................................... 27 6.
6.1 As-is business process ............................................................................................................... 27
6.1.2 The PCM activities that support Online Vending can be seen below: .................................................... 28
6.2 To-be business process ............................................................................................................. 28
BUSINESS REQUIREMENTS ................................................................................................................. 28 7.
7.1 High level Requirements ........................................................................................................... 28
7.2 Detailed requirements and Business rules ................................................................................. 30
7.2.1 OVS Replacement Requirements......................................................................................................... 30
7.2.2 Prepayment Support Gateway (PSG) Requirements ............................................................................ 36
7.2.3 KRN Requirements ............................................................................................................................. 39
C. Prepare Eskom IT systems to manage the Token ID rollover: ....................................................................... 39
7.2.4 Bulk Key Change Token Requirements ................................................................................................ 39
7.2.5 OVS Business Continuity – DR Requirements ....................................................................................... 40
E. Provide a remote (off-site) BC solution for vending ...................................................................................... 40
7.3 Information/data requirements ................................................................................................ 41
7.4 Data flow diagram OR Context diagram .................................................................................... 42
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
3
7.5 Use Case Diagram ..................................................................................................................... 43
7.6 Define the legal requirements. .................................................................................................. 55
No Legal requirements ....................................................................................................................... 55
7.7 Intellectual Property ................................................................................................................. 55
REPORTING REQUIREMENTS .............................................................................................................. 56 8.
8.1 High level reporting requirements ............................................................................................ 56
8.2 Detailed reporting requirements ............................................................................................... 58
NON FUNCTIONAL REQUIREMENTS .................................................................................................... 85 9.
9.1 User interface requirements ..................................................................................................... 85
9.2 System Integration requirements .............................................................................................. 90
9.3 Access requirements ................................................................................................................ 92
9.4 Archiving requirements ............................................................................................................ 92
9.5 Disaster recovery requirements ................................................................................................ 93
9.6 Business continuity requirements ............................................................................................. 94
OUT OF SCOPE AND PRECONDITIONS ................................................................................................. 94 10.
10.1 Define what is out of scope in terms of business requirement elicitation. .................................. 94
10.2 Define any preconditions and dependencies that impact the business requirement ................... 95
TRAINING .......................................................................................................................................... 96 11.
11.1 Define the high level training requirements: ............................................................................. 96
CORPORATE, DIVISIONAL AND DEPARTMENTAL PLAN ALIGNMENT ..................................................... 96 12.
12.1 Strategic alignment .................................................................................................................. 96
CHANGE REQUEST COSTING ONLY (not for any other BRS types).......................................................... 97 13.
POSSIBLE OPTIONS ............................................................................................................................. 97 14.
REFERENCES....................................................................................................................................... 99 15.
DOCUMENT ACKNOWLEDGEMENT ................................................................................................... 100 16.
DOCUMENT APPROVAL .................................................................................................................... 101 17.
ABBREVIATIONS ............................................................................................................................... 102 18.
CONTROL TABLE ............................................................................................................................... 105 19.
Appendix A – OVS High Level DR Design ........................................................................................... 108 20.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
4
CONTROL TABLE 1.
The table that defines what sections of the document need to be completed for the different types of BRS’s is available at the end of the document.
DOCUMENT TRACKER Date Version Author Name Changes (section changed, page
number, from what to what)
10/10/2018
0.1
Janeen Vergotine
Populated first draft of BRS with Jimmy Kennedy’s input
12/10/2018
0.2
Janeen Vergotine
Updated first draft of BRS with Jimmy Kennedy’s and Kervan Naicker’s input
23/10/2018
0.3
Janeen Vergotine
Populated relevant sections with stakeholders inputs
25/10/2018
0.4
Janeen Vergotine
Updated BRS with feedback received during workshop
30/10/2018 0.5 Janeen Vergotine
Populated relevant sections with stakeholders inputs
Reporting info
Use Case Info
Access Roles
01/11/2018 0.6 Janeen Vergotine
Updated the BRS with feedback from the workshop and with the detailed reporting requirements
06/11/2018 0.7 Janeen Vergotine
Populated all outstanding sections with stakeholders input Rename project document from Prepaid Vending solution to Online Vending System Replacement
07/11/2018 0.7 (2) Janeen Vergotine
Updated the BRS with feedback from the workshop
09/11/2018 0.8 Janeen Vergotine
Populate document with final feedback from stakeholders
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
5
CUSTOMER AND STAKEHOLDER DETAILS 2.
2.1 Customer Information
Name Department & Division
Role / Expertise Contact Info Participation
Brian Mokgele Customer Services
Business Requestor/ Business Process Owner/ Business Subject Matter Expert
011 6552402 Requested SME to form part of analysis. To participate in all workshops and review draft BRS
Lloyd Mokgotho Customer Services
Business Senior Manager
015 230 4433 Only wants to participate after BRS is finalised
Martin Masoleng Group Technology Business Subject Matter Expert
011 655 2038 Requested SME to form part of analysis. To participate in all workshops and review draft BRS
Jimmy O'Kennedy
Group Technology Business Subject Matter Expert
011 655 2510 Requested SME to form part of analysis. To participate in all workshops and review draft BRS
Bokkie Verwey Customer Services
Business Subject Matter Expert
021 915 2120 Requested SME to form part of analysis. To participate in all workshops and review draft BRS
2.2 Group IT Information
Name Department & Division
Role / Expertise Contact Info Participation
Janeen Vergotine
Group IT - BPM Group IT Business Analyst +27 21 915 2599
Elma Mmakola Group IT - BRM Group IT Business Relationship Manager
+27 11 690 4016
Shareen Lombard
Group IT Group IT Portfolio Manager +27 31 204 5900
Nwabisa Sijadu Group IT - SEAR Group IT Architect +27 11 690 4098
Kervan Naicker Group IT - ITSO Group IT ITSO Advisor +27 11 655 2493
Zamile Gantana Group IT - ITSO Group IT ITSO Advisor +27 11 690 4004
Willie Olivier Group IT - ITSO Group IT Application Support Manager
+27 11 655 2555
Riaan van Wyk Group IT - BPM Group IT Business Process Middle Manager
+27 21 915 2142
Maureen Mokone
Group IT - BPM Group IT Senior Business Process Manager
+27 11 800 5766
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
6
GLOSSARY OF TERMS / DEFINITIONS 3.
Term Definition
Analytics Refers to the business intelligence capability.
Business Continuity Business continuity encompasses planning and preparation to ensure that an organization can continue to operate in case of serious incidents or disasters and is able to recover to an operational state within a reasonably short period.
Business Intelligence The term Business Intelligence (BI) refers to technologies, applications and practices for the collection, integration, analysis, and presentation of business information. The purpose of Business Intelligence is to support better business decision making. It can also be described as a broad set of data analysis applications, including ad hoc analysis and querying, enterprise reporting, online analytical processing (OLAP), mobile BI, real-time BI, operational BI, cloud and software as a service BI, open source BI, collaborative BI and location intelligence.
Business Requirements Specification
Business requirements specification is the eliciting, analysing and documenting of business requirements early in the development cycle to guide the design of the solution.
Business Rule A business rule is a rule that defines or constrains some aspect of business and always resolves to either true or false. Business rules are intended to assert business structure or to control or influence the behaviour of the business. Business rules describe the operations, definitions and constraints that apply to an organization. Business rules can apply to people, processes, corporate behaviour and computing systems in an organization, and are put in place to help the organization achieve its goals.
Change Request A change request is when an enhancement is made to an existing system that meets specific criteria.
Disaster Recovery / Disaster Recovery Plan
A disaster recovery plan (DRP) is a documented process or set of procedures to recover and protect a business IT infrastructure in the event of a disaster. Such a plan, ordinarily documented in written form, specifies procedures an organization is to follow in the event of a disaster. It is "a comprehensive statement of consistent actions to be taken before, during and after a disaster".
External Agents Sends information to and receive information from analysis area of study/focus area.
Innovation Innovation generally refers to changing processes or creating more effective processes, products and ideas. For businesses, this could mean implementing new ideas, creating dynamic products or improving your existing services. Predominantly focuses on digitisation type projects.
Process Set of activities that describe how an activity is executed.
Project A project consists of a concrete and organized effort motivated by a perceived opportunity when facing a problem, a need, a desire or a source of. It seeks the realization of a unique and innovative deliverable, such as a product, a
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
7
Term Definition
service, a process, or in some cases, a scientific research. Each project has a beginning and an end, and as such is considered a closed dynamic system. It is developed along the 4 Ps of project management: Plan, Processes, People, and Power. It is bound by the triple constraints that are calendar, costs and norms of quality, each of which can be determined and measured objectively along the project lifecycle. Each project produces some level of formal documentation, the deliverable(s), of course, and some impacts, which can be positive and/or negative.
Software License Purchase A software license is a legal instrument (usually by way of contract law, with or without printed material) governing the use or redistribution of software. All software is copyright protected, in source code as also object code form. The only exception is software in the public domain. A typical software license grants the licensee, typically an end-user, permission to use one or more copies of software in ways where such a use would otherwise potentially constitute copyright infringement of the software owner's exclusive rights under copyright law.
System An organized, purposeful structure that consists of interrelated and interdependent elements (components, entities, factors, members, parts etc.). These elements continually influence one another (directly or indirectly) to maintain their activity and the existence of the system, in order to achieve the goal of the system
Account Balance Account Balance is a running total of the money in the account. (Usually for the Vending Agent). The Account Balance is the accounting total and may be positive or negative, depending on the Credit Limit and Emergency Credit Limit. The Account balance is often not the same as the Available Credit for the same reasons. Account Balance = Total deposits (i.e. additions) to date – Total sales (i.e. deductions) to date
Algorithm Type (AT) A two-digit code defined by STS. There are codes for the algorithm to make an STS token as well as for the various algorithms to make tokens for proprietary meters. The combination of Token Technology and Algorithm Type, define the Meter Type
Benefit Indicator Vending
Blind Vend Blind Vend is where the Vend transaction is performed for a meter that does not exist on the Meter Database. In such a scenario, the Meter information is provided from a Meter Card or alternatively via manual entry by the Operator at the Client, (often from an old token). It is recommended that if the Meter information does not exist on the Meter Database, the Server shall capture this information only as an exception record to allow maintenance personnel to correct the data. However, the Meter information is never updated/captured on the actual Meter Database
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
8
Term Definition
since the Vending Server must never become a master source of the Meter Data. The Vending Server will always only be updated from the Customer Information System, i.e. CC&B
CDU ID A unique number given by CC&B which identifies the Vending Client but the Online Vending Server uses the EAN Number to identify the Vending Client uniquely.
ClientID This identifier is defined in the XMLVend specification and used to uniquely identify a Vending Agent in an Online Vending System. Note that more than one ClientID may be assigned to a Vending Agent. If the Online vending system uses the TLS protocol, then the Vending Agent certificate or client certificate contains the ClientID. The ClientID must then only be read from the certificate and populated in the XMLVend request messages. It is recommended that identifier be of an EAN type as this ensures uniqueness across all online vending systems worldwide. The ClientID may also be mapped to a CDUID by the Online Vending Server to ensure legacy compatibility.
Credit (available) Available Credit is the amount of credit that the Vending Agent has available to him. The Available Credit may be higher or lower than the actual Account Balance in his account, depending on the Credit Limit and Emergency Credit Limit. Available Credit may be positive or negative but vending processes shall only be allowed when Available Credit is positive. Available Credit = Account Balance – Credit Limit – Emergency Credit Limit (if exists) Because Emergency Credit is temporary and automatically disappears after a pre-determined time, the Available Credit may suddenly change to a further negative value when the Emergency Credit duration expires.
Credit (emergency limit) Emergency Credit is actually only a limit (not any real credit) and should strictly be called Emergency Credit Limit. It is the temporary additional (lower) limit that may be applied for a specific Vending Agent to allow him to continue vending in an emergency situation. (The Emergency Credit Limit is always a debit amount) Only one Emergency Credit Limit can exist for a Vending Agent at any time. Emergency Credit Limits are not cumulative if applied multiple times which means the latest applied Emergency Credit Limit always overwrites any possible previous Emergency Credit Limit. However the validity period is reset to its full available duration every time a change it made to this limit. Note that the Emergency Credit Limit does not replace the normal Credit Limit or add any temporary credit, but instead exists in addition to the normal credit limit for the valid duration.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
9
Term Definition
Credit (limit) The Credit Limit is the bottom limit down to where a Vending Agent account can be decremented when no Emergency Credit Limit exists for the Vending Agent. The Credit Limit is usually only configured once when the Vending Agent is registered and this limit may be positive, zero or negative. A negative Credit Limit may be used for a trustworthy Vending Agent like a Bank that will always operate in credit mode. A positive Credit Limit may be used for a high risk Vending Agent where additional financial security is required.
Credit (Token) or Energy Token / Vend / Transaction
Typically Tokens or Transactions for Energy as defined in STS. This includes Normal Sale, FBE, Meter Credit Transfer Token and Free Issue (if allowed). It specifically excludes Key Change and any Engineering Tokens (like Clear Credit)
Engineering Key Change The Engineering Key Change function will allow the operator to specify both the “From” and also the “To” information for a Key Change request. Only selected Vending Agent Roles will be configured on the Server to perform this function since there is some risk attached to this operation. However, the operation will only be allowed if the meter information is not found on the Server, otherwise the Database information will in any case be used as the “To” information. These rules ensure that meters do not deviate from configuration information as specified on the Database. A typical example where this function will be required is in a meter laboratory environment where a technician may change new meters from the Default codes to the correct field codes, before they are installed and loaded on the Meter Database.
Engineering Token/ Transaction Typically Tokens or Transactions for the specific Engineering Functions as defined in STS. This includes “Set Power Limit”, “Clear Tamper”, “Clear Credit” etc.
FBE (Token/ Vend/ Transaction) Mostly known as Free Basic Electricity or FBE A specific kind of Credit Token as defined by STS. A meter will only accept one FBE Token per month so there is no risk in Vending Agents producing multiple FBE Tokens for a meter. Typically an FBE Token does not have a Credit (monetary) value (i.e. it is free) but it does have an Energy value which is used for energy balancing purposes.
Gateway Vending Agent Gateway Vending Agent is one of the defined Vending Agent Types and describes how the Vending Agent equipment looks The Gateway Vending Agent must set up his own Gateway to communicate to the Eskom Server via a permanent communication line. The Gateway Vending Agent will have only one Vending Agent Account and all Vend requests will be handled via this Gateway and account. Behind the Gateway, the Vending Agent may have many proprietary Vending Terminals of different capabilities but all of that is transparent to Eskom since the Terminals never communicate directly with the Eskom Server.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
10
Term Definition
This configuration is typically the way that the Banks would operate but note that it is also possible for a Regional Vending Agent or even an Area Vending Agent to be configured on the Server as a Gateway Vending Agent. Note that the terms National Vending Agent, Regional Vending Agent and Small Vending Agent is now only a description of the size and footprint of the Vending Agent operation.
GL Owner GL Owner is the owner of a Supply Group. In Eskom such an owner is typically an Eskom Region. A GL Owner may have many Supply Groups but every Supply Group can have only one GL Owner. This owner of the Supply Group determines who owns the transaction and also supplies the electricity for this customer.
Key Change Token Two Tokens make up the generation of a Key Change Token. They are created to change the meter configuration namely the Tariff Index, Supply Group Code and Key Revision Number
Key Management Centre (KMC) The KMC is a secure trust centre that has been setup with Eskom to secure the STS master keys. The KMC also securely codes and distributes STS encoding modules.
Key Revision Number (KRN) The Key Revision Number is a single-digit number and if forms an integral component that points to the secure Vending Key for a specific Supply Group Code. Currently most Supply Group Codes still only exist for Key Revision 1 but if a key is compromised, a new Vending Key will be created and while the Supply Group Code will remain the same, the Key Revision would change. This change will also require Key Changes for all the meters in that Supply Group.
Mag Card (Magnetic Card/Token) Not the same as Meter Card. Magnetic Card is a specific type of a Token This is usually a paper (disposable) Card that carries the credit or other data to the meter. There currently exist STS as well as Proprietary Magnetic Cards
Meter Card A plastic card with magnetic strip according to ISO 7812 series specification. Meter Card is not the same as Token or Magnetic Card. Every new meter is supplied with a Meter Card. The data on the Meter Card defines all the information that is required to make a valid token for the meter. The following information is encoded on track two of the Meter Card: • Meter Serial Number • Algorithm Type • Token Technology • Supply Group Code • Key Revision Number • Tariff Index It is very important to ensure that the Information on the Meter Card remains always in sync with the information configured in the meter. The Meter Card must therefore always be re-coded whenever Key Change Tokens are created for a meter.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
11
Term Definition
Meter Credit Transfer Token / Vend / Transaction Originally defined in the NRS transaction types as Replacement Transaction. However, the term “replacement” caused many misunderstandings and conflicting interpretations. It has therefore been renamed to “Meter Credit Transfer Token” or “Credit Transfer Token” for short. This transaction still creates a standard credit token to use in the meter. The only differences are that it is specifically reserved for when a faulty meter has been changed out and the customer provides the Operator with a voucher for change-out. Also the Credit Transfer Token is typically for a kWh amount instead of for a monetary value.
Meter Type The Meter Type is a combination of Token Technology and Algorithm Type. The Meter Type uniquely defines how a token should be created to work in the meter.
Multi Vending Agent / Multi Client Vending Agent
Multi Vending Agent is one of the defined Vending Agency Types and describes how the Vending Agent equipment is configured. It used to be known as a Super Vending Agent but that term is not encouraged due to the confusion is causes. A Multi Vending Agent is a special case of a Client Vending Agent. If a Vending Agent owns multiple Clients, it is possible to link them all to a single Vending Agent Account on the Server. All bank deposits and vend requests will then be handled via this single account and the Multi Vending Agent will have only one contract with Eskom. The result is that every individual Client still communicates directly to the Vending Server but the Vending, Credit and Commission are linked to the same Vending Agent Account. A typical example of a Client Vending Agent might be an owner with several small shops or prepaid cell phone kiosks.
National Vending Agent / National Agent
National Vending Agent is a term to describe the footprint or size that the Vending Agent covers. It does not describe any vending technology or configuration. A National Vending Agent is an agent that provides vending for several or all Eskom Regions; typically like the banks do today. This means there must be a dedicated Eskom party to contract and manage a National Vending Agent on behalf of multiple Eskom Regions. A National Vending Agent will have only one entry on the Server and all Vend Requests will be handled via that single Vending Agent account
Operator A generic term for any person that operates a Vending Client or a Vending Server.
Regional Vending Agent Regional Vending Agent is a term to describe the footprint or size that the Vending Agent covers. It does not describe any vending technology or configuration.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
12
Term Definition
A Regional Vending Agent is an agent that provides Vending for one Eskom Region or only a part of a Region. The Regional Vending Agent will be managed by the Region that contracted him. A Regional Vending Agent will have only one entry on the Server and all Vend Requests will be handled via that single Vending Agent account. It is possible for a Regional Vending Agent to establish independent contracts with different Regions but then they would be managed as separate Regional Vending Agents.
Small Vending Agent (Area Vending Agent) Small Vending Agent is a term to describe the footprint or size that the Vending Agent covers. It does not describe any vending technology or configuration. A Small Vending Agent is someone that provides Vending for only a small area ranging typically from only one Client up to the size of a few towns
STS (Meters / Vending) STS defines how (what format) the Client communicates with the Meter. An STS Client can create tokens that will work in STS meters from any manufacturer.
Supply Group Code (SGC) A geographical group of meters. The Supply Group Code also defines the owner of the meters in a specific geographical area. (Typically the supplier of the electricity). Often a Vending Agent is only configured to vend to a specific selection of Supply Groups. The Supply Group Code is a six-digit code and together with the Key Revision Number, points to the secure Vending Key that is used to create the Meter Key.
Tariff Index (TI) A two-digit code that defines what tariff the meter is on. The Tariff Index typically points to the specific tariff price(s) as stored in the Vending Server for Online mode, or in the CDU for Offline Vending mode.
Token Various kinds of data packages that are created by the Vending system and subsequently inserted into the meter to transfer information to the meter. Most tokens are encrypted for security but some risk-free tokens are not encrypted. The STS algorithm currently defines numeric Tokens and Magnetic Tokens. In addition to STS, there are a number of proprietary tokens but the majority are also numeric or magnetic cards, albeit incompatible with each other and with STS. Currently all tokens are stored on physical media, (i.e. numeric printed string, or disposable magnetic card). In this respect the reference to “Token” often refers to the physical media that carries the Token data, which is actually incorrect. The Correct term for the physical device is actually “Token Carrier”. Virtual tokens are under consideration as well but have not been implemented in meters yet.
Token Carrier A Token is only the data package that is created by the Vending system and
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
13
Term Definition
subsequently inserted into the meter to transfer information to the meter. It does not necessarily define the physical media of the token. The physical media of the Token is defined by the Token Carrier. This is specifically relevant for STS since the Vending Server may create the same STS token for any STS meter and send it to the Client. The Client may then be locally configurable to support some or all Token Carriers without having to communicate this with the Vending Server. Currently all tokens are stored on physical media, (i.e. numeric printed string, or disposable magnetic card). These are therefore defined as the Token Carrier. Virtual Tokens are under consideration as well but have not been implemented in meters yet. Virtual Tokens will not have a physical Token Carrier as they may be transferred via radio, power line communication or other means.
Token Technology/Type (TT) A two-digit code defined by STS. There are codes for the various tokens used by STS as well as for the tokens used by proprietary meters. The combination of Token Technology and Algorithm Type, define the Meter Type
Transaction The term Transaction usually refers to actions where credit for the meter is affected, like a Vend, FBE, Cancel or Replacement (i.e. Credit Transfer) Transaction. (i.e. this usually does not include thins like Power Limit Tokens or Key Changes) The Transactions are defined in detail in NRS 009-3. Below is list of the most common Transaction Types as defined by NRS009-3
Definition Typical use kWh effect
Amount effect
Credit limit
Prepayment sale Token vend Credit Credit Deduct
Prepayment refund Refund cash to customer Debit Debit Deduct
Reprint Reprinted token/account payment receipt
No Action No Action No Action
Replacement token (renamed to Credit Transfer token)
Refund of credit left in faulty meter
No Action No Action Deduct
Fixed charge Repayment collection No Action Credit Deduct
Free Issue token Marketing Credit No Action Deduct
Cancel token Operator made mistake with amount
Debit Debit None
Account payment Account sale Credit Credit None
Account cancellation Account cancellation Debit Debit None
Transaction pending (Pending flag in the Tx record marks the Tx type as pending)
Error No Action No Action Deduct
FBE token FBE token vend (support token)
Credit No Action No Action
Recovery charge Monthly right of use No Action Credit Deduct
Update Meter Key Update Meter Key is a new and simplified Key Change process. The Update Meter Key action is initiated by the Operator e.g. by selecting the appropriate button on the Client. The operator must then provide the “From” information
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
14
Term Definition
from the Meter Card or sometimes via manual entry from an old token. This will create the normal Key Change tokens and encode the Meter Card. The only difference being that the meter information is always changed to become the same as the data in the Meter Database. This function therefore does not introduce any data risk and may be enabled for any operators. The operator may also retry this function multiple times with different “From” information until successful and the end result will always be the same as the data on the Meter Database.
Vend (Vending Operation/Transaction) A Vending operation or Vending transaction may be any one where a credit token is generated for a meter. This includes a normal sale, FBE token issue, Free token (if supported), and Credit Transfer token. This specifically excludes Engineering tokens and Key Change tokens.
Vending Client The Online Vending Machine that issues the Token to the Operator. The Vending Client does not have the capability to create a prepaid Token; it must request tokens from the Vending Server via XMLVend protocol.
Vending Gateway The Vending Gateway is an intermediary device for a Gateway Vending Agent. For such a Vending Agent all the Vend requests will be passed to the Server via this Gateway and similarly the Server will return all the responses to the Gateway. Behind the Gateway, the Vending Agent may have many proprietary Vending Terminals of different capabilities but all of that is transparent to Eskom since the Terminals never communicate directly with the Eskom Server.
Vending Server The Vending Server is the Eskom Server in a protected environment that talks to all the Clients and create all the tokens. It contains the security hardware to create the prepaid Tokens, record Transactions and manage Vending Agent Accounts. The Meter Database and several other components are often also incorporated into the Vending Server. Communication with all Vending Clients and Vending Gateways is via the XMLVend protocol.
Vending Terminal A Vending Terminal is vending device that usually has a proprietary design and communication. It operates similar to a Vending Client but may also have other dedicated functions that would be transparent to Eskom. A Vending Terminal does not communicate directly to the Server but all communication is instead routed via the Vending Gateway.
Vending Agent The term Vending Agent may also refer to the vending entity in general, the owner of a Spaza shop, and may all be referred to as Vending Agents.
Vending Agent Account Every Vending Agent will get an Account on the Utility financial system and the same Account number will be registered on the Vending Server. The Vending Agent must deposit credit into this Vending Agent Account with Utility. The Vending Agent Certificate will also be linked to this Account number to identify the Vending Agent and the credit will be deducted for the Vending Agent with every Vending operation.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
15
Term Definition
Vending Agent Certificate (Client Certificate) This certificate is generated on the Online Vending CA for every Vending Agent once the contract has been agreed between the Vending Agent and the Utility. The certificate identifies the specific Vending Agent by the Utility issued EAN number (ClientID) and ensures that all communication with the Vending Server is secured via TLS and this certificate. The Certificate does not directly identify the Vending Client although the Vending Agent (that will get the Vending Commission) is registered against all his Vending Clients on the Vending Server. Since the Vending Agent Certificate is stored on separate hardware, the Vending Agent may remove it and carry it with him. It is theoretically possible that the Vending Agent can insert the Certificate into another Vending Client and Vend from that Client. In that Case the Vending Server will still identify the Vending Agent correctly and deduct the credit from the correct Vending Agent Account. Similarly, the commission will also be calculated for this same Vending Agent Account.
Vending Agent Credit Every Vending Agent has its own Vending Agent Account. All money deposited into this account will be added to his Credit level. The monetary value of all vending transactions is then deducted from the available Vending Agent Credit at the time of the transaction. The minimum credit limit for every Vending Agent is configurable on the Vending Server.
Vending Agent Footprint Vending Agent Footprint has nothing to do with the vending technology or configuration. It only describes the geographical size that the Vending Agent covers. However, this size and Regional overlap does have implications of how Vending Agents are contracted and managed. The following Vending Agent Footprints have been defined. • National Vending Agent • Regional Vending Agent • Small Vending Agent (or Area Vending Agent)
Vending Agency Types Vending Agent Type caused a lot of confusion. Please also review the definitions of the following items to understand this better. Vending Agency Type defines the Vending configuration used and how the Vending Agent is configured to the Vending Server. The following are the defined Vending Agency Types:
Client Vending (also called Normal Vending for a generic name). The Client Vending will usually have only one Vending Client.
Multi Vending (or Multi Client Vending) is a special case of Client Vending. The only difference being that many Clients are linked to a single Vending Agent account for a Multi Vending. This is related to the Super Vending Agent scenario.
Gateway Vending has an intermediary Gateway that sends and receives all communication between the Server and the Vending Terminals of the
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
16
Term Definition
Vending Agent. A Gateway Vending is typical for a Vending that has many Vending outlets.
X509 Standard for definition of electronic certificates. These are used by SSL authentication and encryption
XMLVend The SANS 1524-6-10:2010 specification specifies an XML communication mechanism named XMLVend. The Vending Server will communicate to all Vending Clients and Vending Gateways through XMLVend. This specification is obtainable from, http://www.prepayment.eskom.co.za/xmlvend.asp
Eskom Specialised XMLVend The 240-72275656 specifies Eskom Online Vending XMLVend extensions
and restrictions. It also specifies the interpretation of optional fields that may be required for Eskom implementations. This specification is obtainable from, http://www.prepayment.eskom.co.za/xmlvend.asp
BUSINESS REQUIREMENTS SPECIFICATION FOCUS 4.
The purpose of this document is thus to record and confirm the business requirements for: Total or partial system replacement of existing Online Vending System.
REASON FOR THE REQUIREMENT 5.
5.1 Define the current business challenges / issues that need to be addressed
Online Vending System (OVS) is a revenue collection platform for almost 6 million prepaid electricity customers and need to be replaced urgently due to the National Treasury’s instruction which was communicated to Customer Service on 14 August 2018. The online vending system replacement had already been included in the Customer Service portfolio plan and the project was still going through the normal priority ranking. The average revenue collected via this platform is R9billion per annum. This system supports the Government policy of dispensing Free Basic Electricity to the indigent customers or Municipality communities. The current challenges experiences can be described as per the following: The maintenance and support contract has expired (31 August 2018) and can't be extended further
as per National Treasury instruction. This means that the current production platform and DR site cannot be maintained and supported by
the Vending Agent. There is no remote off-site business continuity solution in place There is a code freeze on the current platform and as a result the following critical projects cannot be
completed:-
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
17
1. The Bulk Key Change token tool that has been developed and capex portion of approximately R2.5m already spent on the solution.
2. The mandatory Standard Transfer Specification (STS) Key Revision changes on OVS cannot be done (needed to support recoding of approximately 6 million prepaid meters)
3. The functional development of prepaid electricity Virtual Tokens to be used in conjunction with smart meters cannot be done.
4. The enhancement and integration of the My-Eskom App to include Eskom direct vending solution cannot be done.
5. Current high speed security modules in OVS cannot be replaced with STS6 modules, a special enabling patch has to be applied on OVS.
The new OVS should thus cater or support the following (in addition to the current) functionality as well: Future prepaid smart metering rollout which is in line with the Eskom smart grid programme. The mandatory STS Key Revision rollover requirement (i.e. recoding of all STS compliant prepaid
meters from key revision 1 to 2, which should be done before the cut-off baseline of November 2024, otherwise issued prepaid electricity tokens from then onwards will not work)
PSG to produce bulk key change tokens, when bulk supply group code, tariff index, or key revision number is changed
Provide a remote (off-site) BC solution for online vending
5.2 Define the high level gaps between the “As-Is” and “To-Be” state
5.2.1 Current “As-Is” situation i.e. how is the situation currently been managed (diagrams to depict the platform)
Eskom is currently providing electricity to 6 338 556 customers of which 5 955 878 (as at end September 2018) are using prepaid electricity. Since 2006 Eskom has developed and implemented an Online Vending System (OVS) for dispensing prepaid electricity tokens to its customers. This is a system that allows customers to purchase prepaid electricity via virtual or remote terminals located in retail outlets or in the existing vending stations. Online Vending allows the Vending Agents to purchase tokens from the main system in real-time; communicating with the Eskom server via the XMLVend protocol, creates the encrypted tokens using the Standard Transfer Specification (STS) secure protocol and sends the tokens to the vending agent. The Online Vending System is made up of a single central server known as the Online Vending Server (OVS) that is linked to Online Vending Clients (OVC), which are located throughout the country. When a customer wishes to purchase a prepaid token from an online vending client, the Vending Agent client sends a request to the OVS; which then creates and sends the token data back to the requesting Vending Agent client. The Vending Agent client is then able to issue the token to the customer. The customer returns to their premises and enters the token number into an electricity meter to utilise the amount of electricity purchased. The diagram below shows the end to end vending platform from the Vending Agents (service provider) to the customer.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
18
Figure 1: End to end Vending Platform
The Online Vending System is based on Client / Server system architecture. All data is stored centrally on the OVS, with no data being stored on the OVC. This approach reduces the risk of transactional errors and improves customer service, sales management and credit management control throughout. The OVC requests tokens from the OVS, which in turn creates and issues the tokens back to the requesting OVC, thus improving the customer service delivery. As the Online Vending System operates in real-time, tokens and management and financial reports are obtained with minimal delay. Vending Agent payment data is concurrently processed into the OVS and SAP utilising the SWIFT interface. Hence all transactional reports reflect current data as the changes occur providing management with an accurate assessment of the current status of the prepaid electricity environment.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
19
Figure 2: Online Vending Transactions Process
The Online Vending System includes the following key components: The “Integration layer” allows information to flow between the Vending platform and various other
systems. “Prepaid Support Gateway” is used by Eskom for administrative functions such as re-issuing tokens. The “Vending application” is where the electricity token is generated. The “Database” is where all customer data and transaction data is stored The “Administration” component is used to access the vending application and set-up vending
configurations.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
20
Figure 3: OVS overview
The other complimenting systems include the following: “Distribution Data Warehouse (DDW)” – Transactional data is loaded onto the DDW for reporting
purposes. “CC&I” – Meter faults and Queries that are recorded at the vending outlets or via Contact Centres are
forwarded to CC&I The diagram below also depicts the transaction process flow from when the customer goes to any merchant that has a relationship with an Eskom approved National Vending Agent that can access the system. The approved vending agent collects prepaid electricity sales monies from the merchant, deposits it at the Eskom approved bank, and the monies get to be reflected on SAP system that integrates with the ESKOM platform.
Figure 4: OVS and other Eskom systems
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
21
The three main interfaces between CC&B and OVS include: Customer data download from CC&B to OVS; any changes in CC&B have to be replicated to the
Online Vending server. Transaction upload from OVS to CC&B Tariff downloads from CC&B to OVS (The tariff data is configured within CC&B).
Figure 5: OVS and Integration systems
Eskom’s Online Vending System utilises three different Online Vending Models which are: Client Vending Multi-Client Vending Gateway Vending
Client Vending Model The Client Vending model refers to a Vending Agent, such as a corner shop, who operates a single vending unit (which is similar to a CDU), and sells prepaid electricity tokens to his customers Multi-Client Vending Model The Multi-Client Vending model refers to a Vending Agent who has multiple shops. Each shop has a vending unit (Client) which is used to sell prepaid electricity tokens to their customers. Gateway Vending Model The Gateway Vending model refers to a Vending Agent who utilises a dedicated Vending Gateway. Terminals which are used to sell prepaid electricity tokens to their customers are linked to a Vending Agent’s Gateway and are not visible to the OVS. The various Vending options and how they communicate with Eskom’ OVS can be viewed in the figure below. Client Vending Agents have only one point of entry with the OVS, in contrast the multi-client
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
22
gateway that has multiple points of sale but have only one server and one vending ID linked to SAP account number. Gateway Vending Agents have different Vending terminals in all the different regions, but have one Vending Client Server that communicates directly with the Eskom Online Vending Server.
Figure 6: Online Vending Models
The existing “As Is” high level functionality of OVS, PSG and OVS Admin can be described as follows: 5.2.2.1. OVS Current Functionality
Currently supports the following STS meter Types:
Meter Type Encryption Algorithm Type
(EA was AT)
Token Carrier Type
(TCT was TT)
PRSTSMAG 07 (STS) 01 (magnetic card)
PRSTSKEY 07 (STS) 02 (numeric)
Register and manage multiple online Vending Agents with secure X509 certificates and secure
communication via the Eskom specialized version of XMLVend
Vend credit tokens for kWh and currency tokens for registered meters as well as un-registered
meters with 11 or 13 digit meter numbers. With support for: Automatic debt % recovery, Straight line
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
23
credit tokens (for kWh), Incline Block rate tokens (for kWh), and daily fixed charges (for kWh or
currency credit tokens).
Issue Free Basic Electricity (FBE) tokens and Municipal funded FBE tokens, either automatically
with first purchase per month or also on demand
Pay account against an Eskom Account number
Pay Debt, if the customer is configured for debt recovery
Over recovery (automatically generates a credit token where debt was over recovered)
Reprint transactions (re-prints 1 to 3 of the last transactions for meter)
Update meter key (key change) for registered meters
Confirm Customer details for registered customers
Produce a meter card for a meter (via Confirm Meter Use Case)
Capture Customer Fault (Customer Fault Report)
Trial Vend (test token with no credit impact)
Advice Request (Issue Advice Last Response)
Vending Agent Statement (displays last 10 credit actions on account, excluding vending)
Interfaces:
o Customer fault report request handling – XML based- (customer meter fault logged at POS routed via system to middleware)
o Use both real-time XML based message processing via MSMQ and the Eskom defined Customer Download flat file to register or update customers and meters on the system’s database
o Real time transport of XML based vendor deposit and adjustment messages through Middleware, via MSMQ to database
o Supports XML based real time transaction message export from the database, via Middleware, and ensure MSMQ routing and processing
o Facilitates XML based real time customer fault reporting where customer meter faults logged at a POS are routed via the system to the end receiver
5.2.2.2. PSG Current Functionality
Register and manage multiple PSG instances that operate from the same database as OVS with
secure X509 certificates and secure communication via the Eskom specialized version of XMLVend,
(without impacting OVS performance), (for numeric tokens and mag card tokens)
Collect FBE Token on demand
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
24
Create, store and track Meter Credit Transfer (Change-out) Token (create replacement credit token
for original invalid token)
Reprint Transaction (re-prints 1 to 3 of the last transactions for meter)
Verify Token (decrypt token and display receipt with token ID (TID), (but without monetary value for
kWh due to step tariff)
Update Meter Key for registered meter (key change from database data) and also program meter
card
Create Engineering Key Change (for registered and un-registered meters.) and also program meter
card
Set Power Limit
Set Phase Unbalance Limit
Clear Credit
Confirm Customer Details
Produce a meter card for a meter (via the Confirm Meter Details Use Case)
Create non-meter Specific Tokens (free display tokens for 11 and 13 digit meters)
Generate Vending Agent information, Customer information, Exception, System Information and Engineering reports
PSG Vending Agent Management
1. Vending Agent Credit
2. Vending Agent Management
Generate Reports
1. Vendor Information Reports
2. Vendor Exception Reports
3. Customer Information Reports
4. Exception Reports
5. System Information Reports
5.2.2.3. OVS Admin Current Functionality
Security Management
1. Manage System Roles
2. Manage Role-Process
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
25
3. Manage Users
4. Manage User Roles
5. Manage Role Functions
System Configuration
1. Interface Configuration
2. Configure Utility Details
3. Manage Vendor Categories
4. Manage Banks
5. Manage Meter Types
6. Manage GL Owners
7. Manage Supply Group Codes
8. Manage Client ID's
9. Manage Eskom Bank Accounts
10. Manage Month End Dates
5.2.2 “To-Be” situation i.e. how would the business prefer to work/operate to address the business challenges.
The Online Vending Solution must meet all the current functionalities/requirements and provide the additional functionalities as described below:
5.2.2.1. New additional OVS high level functionality:
Must fully support the new STS ver. 6 requirements with KRN roll-over and multiple base date
capabilities.
Must support STS and Misty algorithm meters.
Implement both; KRN effective date trigger mechanism, as well as new KRN meter download trigger
mechanism, for KRN related key changes.
Provision for multiple fixed charges
Provision for multiple consumption based charges
Must additionally also support the following meter Types:
Meter Type Encryption Algorithm Type (EA was AT)
Token Carrier Type (TCT was TT)
PRSTSVIR 07 (STS) 07 (Virtual Token Carrier)
PRSTSDLM 07 (STS) 08 (DLMS/COSEM)
PRMISKEY 11 (Misty) 02 (numeric)
PRMISVIR 11 (Misty) 07 (Virtual Token Carrier)
PRMISDLM 11 (Misty) 08 (DLMS/COSEM)
Note: It should be made easier for the authorized person to add more meter types in future
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
26
Transfer virtual prepaid electricity tokens automatically to the designated Eskom system (smart
meters), in addition to the normal printing of numeric token receipts.
Must have the capability to clear keys in the designated registers from the security module before
new keys are installed from the Key Load File import
Web based or other database archiving solution required
Separate Reporting Server required without impacting OVS performance
VAT and Tax number registration should be configurable and must align to the SARS legal
requirements and linked per Supply Group Code.
VAT and Tax number should be included on the receipt per supply group code for prepaid purchases
Send automatic credit depletion notification to vending agents
Dashboard for live transaction traffic monitoring per vending agent
Provision for emergency or advance credit token issuing
Functionality for the issuing of bulk FBE or direct remote virtual token, using the applicable
messaging platforms (sms, email, WhatsApp, etc.) via the Eskom approved middleware.
The solution must be flexible to support other Eskom Approved like business tariffs and Landrate
tariffs
Provision to accept non-electricity utility payments such as water, gas, rates and taxes
A new remote (off-site) business continuity solution
5.2.2.2. New Additional PSG high level functionality:
Bulk Update Meter Key Change (Only allowed for specific individuals by configuration)
Bulk Engineering Key Change (Only allowed for specific individuals by configuration)
Provide a built-in functionality to identify multiple transactions per meter or per PSG agent
Provide additional Engineering reports
The high level gap must reflect the high level business requirement which will be used to create the executive summary.
As Is Statement To Be Statement Therefore the high level gap is:
Only support STS meter Support STS and Misty algorithm meters
New solution to cater for both types of meters
Allows for single key change tokens only
Produce Key Change Tokens for multiple meters at a time
Bulk Key Change Functionality in to be built into Prepayment
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
27
As Is Statement To Be Statement Therefore the high level gap is:
Support Gateway (PSG)
KRN has not been changed and the system is not ready to use multiple base dates
OVS to be able to manage multiple base dates and transition meters from one base date and KRN to the next
Support KRN roll-over and multiple base date capabilities
Offline BC solution is not available i.e. Eskom has no fall-back should both OVS production and DR fail at the same time.
New BC solution to be employed if OVS production and OVS DR fail at the same time.
New BC solution to replace Offline BC solution to provide additional assurance for vending BC.
AS IS AND TO BE BUSINESS PROCESS ACTIVITY MAPPING 6.
6.1 As-is business process
6.1.1 Identify the PCM and list the PCM activities that are impacted: PCM Number PCM Name EHPUM link
240-56302025 Manage Revenue PCM Manage Online Vending
https://hyperwave.eskom.co.za/240-56302025
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
28
6.1.2 The PCM activities that support Online Vending can be seen below:
6.2 To-be business process
6.2.1 Define any new business processes that will be a result of this requirement, if applicable. If no change in business process, state that. N/A – No changes to the current business processes are foreseen at this stage.
BUSINESS REQUIREMENTS 7.
7.1 High level Requirements
The following requirements must be met by the solution:
A. Full replacement of the current Online Vending System with additional
enhancements/requirements
A.1 Implement the required OVS requirements to support vending to customers
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
29
A.2 Comply with the relevant requirements of STS release 6
A.3 Implement the required security modules as prescribed by Eskom for XMLVend
A.4 Support all the required Use Cases
A.5 Interface with other Eskom systems, using Eskom approved middleware
A.6 Key Management (loading the supply groups and keys into OVS security modules)
A.7 Implement separate Reporting Server without impacting OVS performance
B. Provide a customer support system (PSG) for Eskom Support Staff
B.1 Implement the required security modules as prescribed by Eskom
B.2 Implement the required PSG requirements to provide customer support
B.3 Support all the required Use Cases
B.4 Implement the required reports
B.5 New report for tracing user activity
C. Prepare Eskom IT systems to manage the Token ID rollover
D. Provide a Bulk Key Change Token solution that will automate the process of entering the bulk
meter number required to produce tokens, following this, the solution shall produce bulk key
change tokens for the valid registered meters
E. Provide a remote (off-site) BC solution
F. Provide a data archiving solution - web application or other suitable solution
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
30
7.2 Detailed requirements and Business rules
7.2.1 OVS Replacement Requirements
A. Full replacement of the current Online Vending System with additional enhancements /requirements
Functionality grouping
BRS Number
Functionality Business Rule No and Description
A1: Vending to customers
A1.1. The system must be designed to support at least 20 million customers and should be scalable to support additional customers.
The number is based on the following projections:
The system lifespan to be at least 10 years. Growth is expected to be (+250k per year).
Consider Municipal customer takeovers and conversions from conventional to prepaid as well.
Current capacity is 15 million customers.
A1.2. The system must be designed for a peak vending transaction rate of 250 transactions/second and a continuous average transaction rate of at least 100 transactions/second
A1.3. The server must be able to handle large bursts of vending transaction requests that may come through so as to prevent extended locking of records thereby causing delays in response times
A1.4. Server must provide for a suitable data archiving solution to maintain database table sizes
A1.5. Support both kWh and Currency vending for 11 digit as well as 13 digit based STS and Misty meters, and be able to produce tokens for: 1. Numeric tokens, (keypad meters) 2. Disposable magnetic cards, (magcard meters) 3. Virtual STS tokens, (smart meters and other
systems via electronic communication) Virtual tokens must be transmitted to the designated receiving stations by the Vending Server.
4. The system must also be able to encode plastic meter cards with the respective meter details both from manual request as well as whenever Key Change Tokens are created for the meter
Meter types that must be supported: The above differentiations are designed as specific Meter Types, and are constructed from a combination
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
31
Functionality grouping
BRS Number
Functionality Business Rule No and Description
of the Token Technology and Encryption Algorithm as defined by the STS standard:
Meter Type
Encryption Algorithm Type (EA was AT)
Token Carrier Type (TCT was TT)
PRSTSMAG
07 (STS) 01 (magnetic card)
PRSTSKEY
07 (STS) 02 (numeric)
PRSTSVIR
07 (STS) 07 (Virtual Token Carrier)
PRSTSDLM
07 (STS) 08 (DLMS/COSEM)
PRMISKEY
11 (Misty) 02 (numeric)
PRMISVIR
11 (Misty) 07 (Virtual Token Carrier)
PRMISDLM
11 (Misty) 08 (DLMS/COSEM)
The table above covers currently supported meters. There must be flexibility to add support for new meter types other than those listed in the table above. Note: This table will make reference to encryption algorithm and token technology support and the encryption algorithm does not currently exist.
A1.6. The server must always create and send a response numeric token receipt for every vend transaction, even if the meter type indicates it must create a magnetic card token or virtual token
A1.7. The customer or operator must be able to identify a meter and start a credit vend (or other STS transaction) by either: 1. Enter the meter number and obtain the other
information from the database 2. Enter the meter number, Tariff Index (TI), Supply
Group Code (SGC), Key Revision Number (KRN), Encryption Algorithm (EA), Token Carrier Type (TT). Typically known as “Blind Vending” as vending can then be done for meters that are not registered on the database but the same operation must also be allowed for other STS based tokens.
3. Swipe a plastic meter card and read the meter information from track 2 of the meter card.
NOTE 1: If the meter is registered on the system database, the information from the database must always be used for the transaction instead of the information manually supplied or read from a meter card. NOTE 2: If the vending configuration data entered for the meter is different from the data stored on the database, a key change must first be created before any other tokens are created with the new data after the
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
32
Functionality grouping
BRS Number
Functionality Business Rule No and Description
key change. The relevant vending configuration data to verify are: SGC, KRN, TI
A1.8. Allow for the issuing of FBE tokens either upon manual request and also automatically include a FBE token with the first vend of the month if the Benefit Indicator Vending (BIV) setting for the customer allows FBE token allocation. FBE transactions are only possible for registered meters
A1.9. Allow for the issuing of bulk FBE or direct remote virtual tokens, using the applicable messaging platforms (sms, email, WhatsApp, etc.) via the Eskom approved middleware
A2: STS Support –
A2.1. Fully comply with the requirements of STS release 6 (also marketed as STS Edition 2). Specification IEC 62055-41 Edition 3
All future changes and STS requirements should be adhered to
A3: XML Vend Support
A3.1. Support the full Eskom specialized version of XMLVend protocol. All Use Cases must be supported. No other interface shall be allowed for creating STS based transactions
A3.2. Register, configure and support multiple Vending Agents on the system. All communication with the Vending Agents must be via the XMLVend protocol and be protected via certificate based security, (with X509 certificates).
A3.3. Simultaneously support multiple independent Vending Agents via the XMLVend protocol.
A3.4. The following security measures must be used to identify and control the following items for every Vending Agent on the Vending server: 1. Vending Agent configuration (including the specific
Use Cases available) 2. Supply Group Codes available for Vending by the
Vending Agent 3. Available credit 4. Emergency credit 5. All XMLVend transactions by the Vending Agent
A4: Use Case support
A3.1 The following Use Cases must be supported for Vending Agents, however it is preferred that this configuration be configurable on the system per individual vending Agent: 1. Purchase Credit Token (meter serial number
only) 2. Purchase Credit Token (all data) 3. Meter Credit Transfer (meter serial number only) 4. Meter Credit Transfer (all data) 5. Collect FBE (meter serial number only)
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
33
Functionality grouping
BRS Number
Functionality Business Rule No and Description
6. Collect FBE (all data) – customer not registered on CC&B for FBE
7. Update Meter Key 8. Meter Specific Engineering Token (meter serial
number only) 9. Meter Specific Engineering Token (all data) 10. Non-meter Specific Engineering Token 11. Verify Token (meter serial number only) 12. Verify Token (all data) 13. Vend Trial Token 14. Pay Debt (meter serial number only) 15. Pay Debt (all data) 16. Pay Account 17. Reprint Transaction 18. Confirm Meter Details 19. Confirm Customer Details 20. Customer Fault Report 21. Vending Agent Statement 22. Issue Advice (last response. Issued automatically)
Provide an end-to-end track and trace transaction reconciliation functionality 1. Provide the ability to track and trace a transaction
request from the time it enters the Eskom environment until the response leaves the OVS environment.
NOTE 3: Track and trace using the unique identifier of every transaction
A4: System interfaces
A4.1. Import and use the Eskom defined tariff file to decide in real time, from the tariff Index, what tariff configuration must be applied when creating STS credit tokens. The following options must be supported as defined by the specific tariff index for the transaction: 1. Straight line kWh credit token, (for registered and
unregistered meters) 2. Incline Block Tariff (IBT) credit token, (for
registered and unregistered meters) 3. Fixed charge credit transaction, (for registered and
unregistered meters). Daily fix charge is deducted from the date of the previous vend until today and remainder of money is for kWh or currency credit. For unregistered meter, only one day’s fixed charge is deducted (Additional rules apply)
4. Currency credit token (for registered and unregistered meters)
5. Cater for multiple fixed charges and mutable variable charges (c/kWh based). Please see below:
NOTE 4: The “Blind Vend” number of allowances, is also set in the same tariff file (per tariff and supply group) and must be allowed when doing a vend request for an unregistered meter. NOTE 5: “Blind Vend” count flag set in the tariff file must be interpreted and applied on the server
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
34
Functionality grouping
BRS Number
Functionality Business Rule No and Description
6. The receipts should also show the different
charges
7. The proposal is for OVS to have 4 fixed charges
and 4 c/kWh charges.
8. The above tariffs are serviced by single and 3 phase whole current meters.
A4.2. Import and use the Eskom defined Benefit Indicator Vending (BIV) file to decide in real time, from the BIV field for the customer, what benefits to apply for the meter, namely: 1. Free Basic Electricity (FBE), or Municipal Funded
FBE (i.e. additional amount per township allowed but the same rules apply for either one)
2. Percentage of payment must be automatically deducted for debt payment from the vend transaction amount before token created.
The debt recovery rate is part of the BIV file
A4.3. Import and use both real time XML based message processing via MSMQ or any other Messaging Queue and the Eskom defined Customer Download flat file to register or update customers and meters on the system’s database. 1. If a new meter is downloaded, its status is changed
from unregistered (or missing) to registered on the particular Service Point in the field.
2. If a different meter is downloaded with the same service point, this meter becomes unregistered (also called uninstalled) but the same rules apply as for an unregistered meter.
3. If the meter is downloaded with different vending configuration dates (i.e. SGC, KRN, TI), the meter remains installed but a new flag is set for the meter: “key change required”. If this flag is set, the system must first perform a key change of the meter to the new downloaded data before any other tokens are created for the meter. The key
NOTE 6: If a customer is required to update a meter key, the customer is prevented from vending, until the meter key token is issued.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
35
Functionality grouping
BRS Number
Functionality Business Rule No and Description
change operation must automatically clear that key change required flag.
4. If other data for the meter has changed, that data is simply updated on the system.
5. It must not be possible to add, modify or delete any customer or meter data directly on the system. All changes must be made in CC&B and downloaded to the vending system.
6. Blocking and unblocking of customers from vending, is controlled by a flag set in the file or XML message and must be interpreted and applied correctly to block all vending to such a meter
A4.4. The server must, in real time, be able to import XML based vendor deposit and adjustment messages from SAP through the Middleware, via MSMQ or any other Messaging Queue, for insertion and updating on the database. The following are applicable: 1. Vending Agent credit deposits 2. Credit adjustments
A4.5. The server must support XML based real time transaction message export from the database, sent via the middleware and ensure MSMQ or any other Messaging Queue routing and processing for the following transaction types: 1. Account payment 2. Debt recovery 3. Over recovery 4. FBE (free basic electricity) 5. Meter credit transfer 6. Normal resource (transaction) 7. Fixed Charge
A4.6. Facilitate XML based real time customer fault reporting where customer meter faults logged at a vending terminal must be transported from the server to the database to then be exported and sent via the Middleware interface to the receiving system.
A5: OVS Key Management
A5.1 Key Management: Server must be able to import key load files into the database as supplied according to the approved STS specifications provided by Eskom’s Key Management Centre 1. During the key file loading process, the server must
be able to interrogate and wipe clean/delete all existing keys from the security module into which the security keys are loaded from the key load file
2. The Key Load program must also update the server configuration data with the Supply Group, Key Revision Number and register number when
NOTE 7: Additional fields associated with every supply group code, must be populated manually by the administrator, e.g. the owner and VAT number for every Supply Group – include this note in the system configuration section…
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
36
Functionality grouping
BRS Number
Functionality Business Rule No and Description
the file is imported
A6: OVS Admin Reports
A6.1. Vendor Information Reports 1. First Issued FBE per Vendor and Meter 2. Client Details Report 3. Vendor Details Report 4. Transaction Listing Per Vendor Report 5. Transaction Summary Report 6. National Transaction Summary Report 7. Account Payment Summary Report 8. Vendor Account Statement Report 9. Reconciliation Sales Summary Report 10. Reconciliation Vendor Account Balance Report 11. Vendor Credit Report
A6.2. Customer Information Reports 1. Customer Details Report 2. Customer Transaction Details Report 3. Customer Transaction Details Per Account Report 4. Unallocated Pending Blocked Customers Report 5. Customer Step Details Report 6. Blocked CC&B Unallocated Pending Report 7. Corrected Unallocated Meters Report 8. Customer Fault Report
A6.3. Vendor Exception Reports 1. Vending Agent Low Credit Exception Report 2. Last Response Requests Report
A6.4. Exception Reports 1. Meter Not Registered Exception Report 2. Customer Meter Data Exception Report 3. Meter Import Exception Report
A6.5. System Information Reports 1. Current Tariff Status Report 2. Historic Tariff Status Report 3. BIV File Configuration Report 4. Functions To User Mapping Report
7.2.2 Prepayment Support Gateway (PSG) Requirements
B. Provide a customer support system (PSG) for Eskom Support Staff
Functionality grouping
BRS # Functionality Business Rule No and Description
B1: System Security
B1.1. The Prepayment Support System (PSG) must be registered and protected in the same manner as the Vending Agents with certificate based security
B1.2. The same security must be used to isolate and control
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
37
Functionality grouping
BRS # Functionality Business Rule No and Description
the following items for the support functionality: 1. Support system configuration (including specific Use
Cases available per user role on the system) 2. Must operate from the same database as the
vending system 3. Use Case functionality must be available per user
role 4. Manage the available credit for Meter Credit
Transfer tokens for PSG owners. 5. All XMLVend transactions by the support user
B1.3. Ability to select from a list of options (dropdown button), the reasons why certain functions were performed by the user for example why a meter credit token was created.
Option to be defined at a later stage
B2: Customer Support
B2.1. 1. Create numeric, magnetic and virtual tokens 2. The Verify Token Use Case must also be able to
read magnetic card tokens for verification
B2.2. Read and encode plastic meter cards with the respective meter details both from manual request as well as whenever Key Change Tokens are created for the meter
B2.3. Bulk Key Change Token functionality required. (Detailed in a separate document.)
B3: Use Case support
B3.1. The following Use Cases must be supported for support staff, this configuration must be configurable on the system per user role: 1. Collect FBE Token 2. Create Meter Credit Transfer (Change-out) Token
(create replacement credit token for original invalid token)
3. Reprint Transaction (re-prints 1 to 3 of the last transactions for meter)
4. Verify Token (decrypt token and display receipt with token ID (TID), (but without monetary value for kWh due to step tariff)
5. Update Meter Key (key change but can only enter data for the “From” field, the “To” field data must exist in the database. It can also be used to change the SGC, TI & KRN.
6. Create Engineering key change (Can enter “From” and “To” data but database data is used for the “To” data if meter registered with different data.). It can also be used to change the SGC, TI & KRN.
7. Set Power Limit 8. Set Phase Unbalance Limit 9. Clear Credit 10. Confirm Customer Details 11. Make Meter Card (Confirm Meter Details Use Case) 12. Vending Agent Statement (displays last 10 credit
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
38
Functionality grouping
BRS # Functionality Business Rule No and Description
actions on account, excluding vend) 13. Non-meter Specific Tokens (free display tokens for
11 and 13 digit meters) 14. Bulk Update Meter Key (Only allowed for specific
individuals by configuration) 15. Bulk Engineering Key Change Key (Only allowed
for specific individuals by configuration) 16. Change Post Paid to Prepaid – Out of scope 17. Change Prepaid to Post Paid - Out of scope
B4: PSG Reports
B4.1. Vendor Information Reports 1. Client Details Report 2. Vendor Details Report 3. Transaction Listing Per Vendor Report 4. Transaction Summary Report Vending 5. National Transaction Summary Report 6. Vendor Account Statement Report 7. Reconciliation Sales Summary Report 8. Reconciliation Vendor Account Balance Report 9. Vendor Credit Report View Vendor Credit Run
B4.2. Customer Information Reports 1. Customer Details Report 2. Customer Transaction Details Report 3. Customer Transaction Details Per Account Report 4. Unallocated Pending Blocked Customers Report 5. Customer Step Details Report View Customer 6. Blocked CCB Unallocated Pending Report 7. Corrected Unallocated Meters Report 8. Customer Fault Report
B4.3. Exception Reports 1. Meter Not Registered Exception Report 2. Customer Meter Data Exception Report 3. Meter Import Exception Report
B4.4. System Information Reports 1. Functions To User Mapping Report
B4.5. Engineering Reports 1. Engineering Transactions Per GL Owner and Agent 2. Engineering Transactions Per GL Owner and MSNO
B5: New Report
B5.1. PSG Agent Activity Log Report 1. New report for tracing user activity
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
39
7.2.3 KRN Requirements
C. Prepare Eskom IT systems to manage the Token ID rollover:
*Note: The detailed requirements are captured in the KRN User Requirements Specification document, KRN URS Link
Functionality grouping
BRS #
Functionality Business Rule No and Description
C1: System configuration
C1.1. Sourcing and storage of the KRN:
1. Changes to CC&B to capture and store the KRN and base date during meter registration
2. Ensure that the KRN is transferred from CC&B to OVS along with other meter information
3. Store the KRN per meter in OVS
C1.2. Ensure that OVS/PSG can handle multiple base dates
1. Ensure that meters can be transitioned from the current base date and KRN to the next base date and KRN
C2: Security Modules
C2.1. Security Modules:
1. Firmware updates to security modules to manage multiple base dates and more keys
2. Security modules to handle the new KLF format
C3: Reports C3.1. Ensure that the progress of the TID rollover can be tracked (per meter or SGC) using relevant reports
7.2.4 Bulk Key Change Token Requirements
A. Enhancement of the existing PSG solution to produce bulk key change tokens *Note: The detailed requirements are captured in the BKCT User Requirements Specification document, BKCT URS Link
Functionality grouping
BRS #
Functionality Business Rule No and Description
D1: System configuration
D1.1. Enhancement of the existing PSG solution 1. Produce bulk key change tokens, when bulk supply group
code, tariff index, or key revision number is changed
Build-in or incorporate the requested additional functionality into the ‘old’ PSG design
D1.2. Automate the process of entering the bulk meter number required to produce tokens, following this, the solution shall produce bulk key change tokens for the valid registered meters
D1.3. A bulk PSG configuration must be created on the PSG system with some additional functionality for the Bulk PSG. This Bulk PSG configuration will not be available or accessible to the
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
40
Functionality grouping
BRS #
Functionality Business Rule No and Description
general PSG users.
D1.4. The creation of the Bulk PSG and the user rights assigned must operate in the same manner as the current PSG design setup.
Because of the risks associated with unauthorised access to the Bulk PSG, strict controls will be exercised when granting access to the users of PSG, users will be granted access typically created under the new profile, “AgentBulk” to separate the roles of PSG users, granting “AgentBulk” privilege only to the newly designed Bulk functionality.
7.2.5 OVS Business Continuity – DR Requirements
E. Provide a remote (off-site) BC solution for vending
*Note: The detailed requirements are captured in the OVS BC/DR Business Requirements Specification document, OVS BC BRS Link
Functionality grouping
BRS #
Functionality Business Rule No and Description
E1: New solution
E1.1. Replace the Offline BC solution, which was provided by two NVAs with a new BC solution
E1.2. The new BC solution will supplement the existing OVS DR solution
E1.3. The new BC solution will provide additional assurance for vending business continuity
E1.4. The new BC solution will be used if OVS production and DR are both unavailable (out of service, failed etc.)
Group IT Business Requirement Specification (BRS)
Online Vending System (OVS) Replacement Project DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised
version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 41 of 108
7.3 Information/data requirements
7.3.1 Define the following information:
BRS Number
Functionality Data Source(s) Availability of data
Migration of data
DI1 Transactional Data: Prepaid transactional sales information
Vending Client OVS database Only if data structure on database and/or infrastructure is being changed
DI2 National Vending Agent bank deposits and adjustments SAP OVS database Only if data structure on database and/or infrastructure is being changed
DI3 Customer and Meter data CC&B OVS database and CC&B
Only if data structure on database and/or infrastructure is being changed
DI4 Tariff information CC&B OVS and CC&B Only if data structure on database and/or infrastructure is being changed
DI5 Benefit Indicator Vending (BIV) information CC&B OVS and CC&B Only if data structure on database and/or infrastructure is being changed
DI6 Customer fault reporting Vending Client OVS and CC&I Only if data structure on database and/or infrastructure is being changed
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 42 of 108
7.4 Data flow diagram OR Context diagram
The diagram below indicates the data flow between OVS and the integrating Eskom systems. Additional diagrams can be found under the “As Is” 5.2.1 section of the document.
Figure 7: OVS Information/Data Flow
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 43 of 108
7.5 Use Case Diagram
7.5.1 Insert the use case diagram based on the business requirements that have been defined. Each request will be determined on its own merits in terms of whether a use case diagram needs to be provided or not.
Name Purchase Credit Token (meter serial number only)
Scenario Description This scenario covers the customer’s request for one or more Credit Tokens using only the meter’s serial number. The Purchase Credit Token Use Case will automatically also investigate whether the meter number is eligible for FBE token issue, Fixed charges and for Debt Recovery and include them automatically where applicable. The FBE, Fixed charges and Debt Recovery are therefore optional returns in the response from the Server.
Desired Outcome A new Purchase Credit token is created for the customer’s meter.
If the customer/meter is so configured, the Server will also issue an FBE token and/or will recover outstanding fixed charges and/or debt.
Credit transaction, Debt Recovery transaction, Fixed Charges transaction and FBE transaction are all recorded as separate entries on the Server database.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Purchase Credit Token (all data)
Scenario Description This scenario covers the customer’s request for one or more Credit Tokens for his or her prepayment meter. The customer provides all meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or manually entered from an old token. The Purchase Credit Token Use Case will automatically also investigate whether the meter number is eligible for FBE token issue, Fixed charges and for Debt Recovery and include them automatically where applicable. The FBE, Fixed charges and Debt Recovery are therefore optional returns in the response from the Server.
Desired Outcome A new Purchase Credit token is created for the customer’s meter.
If the customer/meter is so configured, the Server will also issue an FBE token and/or will recover outstanding fixed charges and/or debt.
Credit transaction, Debt Recovery transaction, Fixed Charges transaction and FBE transaction are all recorded as separate entries on the Server database.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Meter Credit Transfer (meter serial number only)
Scenario Description This scenario covers the customer’s request for a Meter Credit Transfer Token for his or
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 44 of 108
her prepayment meter. The customer provides only the meter serial number. The meter credit transfer Use Case refers to the replacement transaction. A meter credit transfer token is only vended when a faulty meter has been replaced in the field and the customer now requires a token for the credit that remained on his old meter, to enter it into the new meter. This Use Case will still decrement the Vending Agent’s credit (PSG) and the original meter change-out slip must be retained so that a manual reconciliation and refund of this credit to the Vending Agent can be done at a later stage. The meter change-out slip must contain the new meter serial number, the old meter serial number, the kWh or currency to transfer, a reference number for the slip and a valid signature from the field service representative.
Desired Outcome A new Meter Credit Transfer token is created which replace the amount of electricity on the customer’s meter before the meter was replaced.
The Vending Agent retains the original meter change-out slip for manual credit reconciliation.
Participants Customer
Vending Client
Vending Agent Vending Server
Name Meter Credit Transfer (all data)
Scenario Description This scenario covers the customer’s request for a Meter Credit Transfer Token for his or her prepayment meter. The customer provides meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or an old token The meter credit transfer Use Case refers to the replacement transaction. A meter credit transfer token is only vended when a faulty meter has been replaced in the field and the customer now requires a token for the credit that remained on his old meter, to enter it into the new meter. This Use Case will still decrement the Vending Agent’s credit (PSG) and the original meter change-out slip must be retained so that a manual reconciliation and refund of this credit to the Vending Agent can be done at a later stage. The meter change-out slip must contain the new meter serial number, the old meter serial number, the kWh or currency to transfer, a reference number for the slip and a valid signature from the field service representative. The only difference between this Use Case and the previous Use Case is that here the Vending Agent provides all the necessary configuration information for the meter. This information may be manually entered from an old token or may be entered via the meter swipe card. The Vending Agent will often need to use this option if the meter does not yet exist on the Server database.
Desired Outcome A new meter credit transfer token is created which replace the amount of electricity on the customers meter before the meter was replaced.
The Vending Agent retains the original meter change-out slip for manual credit reconciliation.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 45 of 108
Participants Customer
Vending Client
Vending Agent Vending Server
Name Collect FBE (meter serial number only)
Scenario Description This scenario covers the customer’s request for a separate FBE issue that is not necessarily tied to any other transaction. The customer provides only the meter serial number.
Desired Outcome An FBE token is generated for the requested meter number
The FBE – transaction is recorded on the Server.
No credit deductions are made
Participants Customer
Vending Client
Vending Agent Vending Server
Name Collect FBE (all data)
Scenario Description This scenario covers the customer’s request for a separate FBE issue that is not necessarily tied to any other transaction. The customer provides meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or an old token
Desired Outcome An FBE token is generated for the requested meter number
The FBE – transaction is recorded on the Server.
No credit deductions are made
Participants Customer
Vending Client
Vending Agent Vending Server
Name Update Meter Key
Scenario Description This scenario covers the request for Update Meter Key tokens. (This is a specialised implementation of a meter key change request) The Update Meter Key Data Use Case is used request a set of key change tokens, which are used to update one or more key data items (i.e. SGC, TI and KRN) for a specific meter. This Use Case is manually triggered from the client. The "From" meter key data is obtained from a meter card or an old token. The "To" meter key data is always obtained from the Server database which implies that this request will only work for a meter that exists in the Server database. The Vending Agent will not be allowed to enter his own "To" meter data, as this will always be obtained from Server database. The fact that the result will always be in line with the Server configuration for the meter, removes the risks normally associated with doing key changes. The Vending Agent may
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 46 of 108
therefore re-try this transaction as many times as required and provide different parameters for the “From” information until the tokens are successfully accepted by the meter. Every Update Meter Key transaction must also trigger the encoding of the meter card on the Client. In addition, Eskom is following a strategy to issue a matching “Power Limit” token. A successful “Update Meter Key” response must therefore also include a matching “Set Max Power Limit” token.
Desired Outcome Two Key Change tokens are created to change his meter configuration to be the same as the Server database.
A matching Set Max Power Limit token is. for this meter and included in the response
The meter card is encoded by the Client to match the new meter configuration
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Meter Specific Engineering Token (meter serial number only)
Scenario Description With this Use Case, the operator can request meter specific STS engineering tokens, which are defined in IEC 62055-41. These tokens are used to update the meter configuration information. For this Use Case the operator provides the meter serial number to identify the meter as well as configuration parameters for certain engineering tokens. The following meter specific engineering tokens must be supported
Notes: 1 The Default Credit is a single value configured on the Server in kWh and in Rand)
No Token Name Token Specific Parameters 1 Set Power Limit Power Limit [nnn.nn kW] 2 Set Phase Unbalance Power Limit [nnn.nn kW]
3 Add Default Credit1 None
4 Clear Credit None
5 Clear Tamper None 6 Engineering Key Change
2 From
SGC [nnnnnn] KRN [n] TI [nn] To SGC [nnnnnn] KRN [n] TI [nn]
7 Set Water Factor Water Factor [nnnnnn]
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 47 of 108
2 The “Engineering Key Change” function provides more flexibility for selected operators
than the regular “Update Meter Key” function. The “Update Meter Key” function shall always use the data on the Server database for the “To” information while the “Engineering Key Change” function shall allow the operator to provide the “To” information if the meter does not exist on the Server database. (If the meter already exists on the Server database, The Server shall return with message that data is changed to database [SGC, KRN, TI] and not “To” data)
Desired Outcome The requested Engineering token(s) are generated for the required meter number
The transaction is recorded on the Server.
No credit deductions are made
Participants Vending Client
Technician Vending Server
Name Meter Specific Engineering Token (all data)
Scenario Description With this Use Case, the operator can request meter specific STS engineering tokens, which are defined in IEC 62055-41. These tokens are used to update the meter configuration information. For this scenario the operator provides all the meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or an old token. The following meter specific engineering tokens must be supported
No Token Name Token Specific Parameters 1 Set Power Limit Power Limit [nnn.nn kW] 2 Set Phase Unbalance Power Limit [nnn.nn kW] 3 Add Default Credit
1 None
4 Clear Credit None 5 Clear Tamper None 6 Engineering Key Change
2 From
SGC [nnnnnn] KRN [n] TI [nn] To SGC [nnnnnn] KRN [n] TI [nn]
7 Set Water Factor Water Factor [nnnnnn] Notes: 1 The Default Credit Value is a single value configured on the Server in kWh and in Rand)
2 The “Engineering Key Change” function provides more flexibility for selected operators
than the regular “Update Meter Key” function. The “Update Meter Key” function shall always use the data on the Server database for the “To” information while the “Engineering Key Change” function shall allow the operator to provide the “To” information if the meter does not exist on the Server database. (If the meter already exists on the
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 48 of 108
Server database, The Server shall return with message that data is instead changed to database [SGC, KRN, TI] and not “To” data) 3 The business logic for an Engineering token is somewhat different than for another
transaction. For normal transactions, the philosophy is to always use the data that is on the Server if the meter is registered on the database. For Engineering tokens (except Engineering Key Change) the data that is supplied by the Client must always be used, irrespective of whether the meter exists on the database. This relaxation is required since it is often required to code meters to different parameters in a meter laboratory, even when the meter data has not yet been updated on the Server database. Only the “to” data for an “Engineering Key Change” is still limited in the normal manner if the meter exists on the database.
Desired Outcome The requested Engineering token(s) is generated for the required meter number
The transaction is recorded on the Server.
No credit deductions are made
Participants Vending Client
Technician Vending Server
Name Non-meter Specific Engineering Token
Scenario Description With this Use Case, the operator can request non-meter specific STS engineering tokens, which are defined in IEC 62055-41. No meter details are required. These are no-risk operations and also do not affect the Vending Agent credit. Must be done for 11 and 13 digit meters. The following non-meter specific engineering tokens must be supported
No Token Name 1. Test All 2. Test Disconnection 3. Test Display 4. Test Input device 5. Display Total Energy consumed 6. Display Key Revision (KRN) - (also includes key type) 7. Display Tariff Index (TI) 8. Display Maximum Power Limit 9. Display Phase Unbalance Limit 10. Display Tamper status 11. Display Credit available 12. Display Instantaneous Power 13. Display Version 14. Display Water Factor 15. Display Tariff Rate
Display Supply Group Code (SGC)
Desired Outcome The requested Engineering token is generated and will work in any STS meter
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 49 of 108
No transactions are recorded on the Server.
No credit deductions are made
Participants Technician
Vending Client Vending Server
Name Verify Token (meter serial number only)
Scenario Description This scenario covers the customer’s request to verify that a token should work in his meter and also to verify the value imbedded in an STS token. The customer provides only the meter serial number.
Desired Outcome The system should produce a response stating that the token is valid for a particular tariff index and supply group code along with the extracted value.
Participants Customer
Vending Client
Vending Agent Vending Server
Name Verify Token (all data)
Scenario Description This scenario covers the customer’s request to verify that a token should work in his meter and also to verify the value imbedded in an STS token. The customer provides meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or an old token
Desired Outcome The system should produce a response stating that the token is valid for a particular tariff index and supply group code along with the extracted value.
Participants Customer
Vending Client
Vending Agent Vending Server
Name Vend Trial Token
Scenario Description Vend Trial Token operates exactly like the two scenarios of the real Vending Use Case (i.e. with meter serial number only and with all data), but no actual token is created or transaction recorded.
Desired Outcome The Vending Agent wants to confirm whether a token can be created successfully for a particular meter and what the applicable credit and deductions will be.
The Server performs all required validations for a real transaction but does not create a token or record the transaction
The Server returns a Trial token receipt with twenty zeros in place of the STS numbers.
Participants Vending Client
Vending Agent Vending Server
Name Pay Debt (meter serial number only)
Scenario Description While debt recovery is automatically processed whenever a customer purchases electricity, this Use Case allows the customer to pay debt for a selected amount whenever
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 50 of 108
so desired. For this scenario the customer provides only the meter’s serial number as identification.
Desired Outcome The customer pays the selected amount against his outstanding debt and receives a receipt as proof of payment.
The Debt transaction is recorded on the Server.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Pay Debt (all data)
Scenario Description While debt recovery is automatically processed whenever a customer purchases electricity, this Use Case allows the customer to pay debt for a selected amount whenever so desired. For this scenario the customer provides all the meter configuration information (MSNO, SGC, KRN, TI, TT, AT) from a meter card or an old token
Desired Outcome The customer pays the selected amount against his outstanding debt and receives a receipt as proof of payment.
The Debt transaction is recorded on the Server.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Pay Account
Scenario Description The Pay Account Use Case allows the customer to pay a selected amount against any valid account number. While Pay Debt and the automatic Debt Recovery require an existing account number for that customer on the Server database, Pay Account will accept payment against any valid account number which is provided by the customer.
Desired Outcome The customer pays the selected amount against a valid account number and receives a receipt as proof of payment.
The Account payment transaction is recorded on the Server.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Reprint Transaction
Scenario Description A reprint Use Case allows a customer to print previously generated transaction(s). The input data must be Meter Serial Number, Account Number or the complete track 2 meter data. The Server returns a server configured number of credit related transactions. The Vending Agent then selects the required transactions to print from the returned list on the Client.
Desired Outcome A reprint of the last set of transactions, including any FBE tokens and Debt recovery transactions which are auto-vended
Participants Customer
Vending Client
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 51 of 108
Vending Agent
Vending Server
Name Confirm Meter Details
Scenario Description The Confirm Meter Details Use Case allows the Vending Agent to obtain the configuration information for a specific meter or to create a Meter Card for a meter. The Vending Agent only requires the meter serial number for this request.
Desired Outcome The Server returns all the meter configuration information for the Client to display. The Client may also allow the Vending Agent to create a meter card from the returned information. Only the Token Technology information, may be changed by the Client when making a Meter Card, all other information must be used as supplied by the Server.
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Confirm Customer Details
Scenario Description The Confirm Customer Details Use Case allows the Vending Agent to obtain the information for a customer regarding the meter configuration, debt recovery tariff etc. Various fields may be used for the search criteria
Desired Outcome The Server returns all the customer's information for the Client
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Customer Fault Report
Scenario Description The Customer Fault Report Use Case allows the Vending Agent to report a meter (or other) fault to the utility, if the Vending Agent could not solve it. The Online vending system provides the unique facility at the vending point where such an error can be reported and it can be reported very quickly to the Vending Server. The Vending Server must have the capability to produce regular fault reports which can be forwarded to Field Services for formal registration on the Eskom system and subsequent correction. To address the fault effectively, the specific meter serial number and other configuration information will be required, as well as contact details for the customer. The Server must also create a unique fault reference number for the customer to aid in later fault identification.
No Fault (Only choose first correct fault description found)
Fault type*
1. Display, lights or buttons faulty Physical meter
2. Fire / water damage Physical meter
3. Keeps tripping or erratic trip Physical meter
4. Meter dead Physical meter
5. No trip or disconnection Physical meter
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 52 of 108
6. Serious Box or physical damage Physical meter
7. Network fault report (not meter related) Network
8. Tokens not working - Incorrect TI Non meter
9. Tokens not working - Incorrect SGC Non meter
10. Record Missing – Converted From Conventional
Non meter
11. Record Missing - Meter Changed Out Non meter
12. Record Missing – New Installation Non meter
Note:
Future fault recording may include data or customer fault types
Cater for free format field, but limit the characters to make the message as short as possible to allow the customer to give a clear description of the actual problem.
Desired Outcome The Server logs the customer fault for later export to external systems. A unique fault reference number is created by the Server and included in the fault notification response to the Client
Participants Customer
Vending Client
Vending Agent
Vending Server
Name Create Deposit Slip
Scenario Description Due to the upfront nature of online vending, it is not required anymore to tie banking deposits to any specific batches or transaction ranges. The Vending Agent may now request a deposit slip at any time from the server when he wishes to make a deposit into his credit account. The Server must save the deposit slip created for possible future verification but no system functionality is tied to a specific deposit slip. The Vending Agent may even discard the deposit slip without using it and request another. The same upfront functionality eliminates the requirement for the server to be aware of the specific amount deposited for a specific deposit slip. The server must only return a recommended deposit amount in the response. The recommended amount is the value to deposit to return the Vending Agent credit to the Optimum Credit Value: The recommended value is calculated as: Deposit amount recommended = Optimum Credit Value + Credit Limit – Account Balance *Note that any Emergency Credit that may exist is ignored The Client may still allow the Vending Agent to manually change the actual amount to be deposited before the deposit slip is printed.
Desired Outcome The Server generates a correctly formatted bank deposit slip for the Vending Agent with a recommended deposit amount.
It is suggested that the Client machines allow the Vending Agent to adjust the recommended amount before the deposit slip is printed.
Participants Vending Client
Vending Agent
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 53 of 108
Vending Server
Name Reprint Deposit Slip
Scenario Description Due to the upfront nature of online vending, it is not required anymore to tie banking deposits to any specific batches or transaction ranges. The Vending Agent may now request a deposit slip at any time from the server when he wishes to make a deposit into his credit account. This Use Case allows the Vending Agent to reprint a previously created deposit slip (if it still exists on the Server). This will allow the Vending Agent to use the same deposit slip reference number if the earlier deposit slip has been lost or damaged. Re-using the same deposit slip for multiple deposits is not recommended but will not affect the operations on the server.
Desired Outcome The Vending Agent submits the request and the Server returns a pre-configured number of earlier deposit slips.
It is suggested that the Client machines allow the Vending Agent to select the specific deposit slip to be printed.
Participants Vending Client
Vending Agent
Vending Server
Name Vending Agent Statement
Scenario Description This Use Case allows the Vending Agent to verify the Available Credit, the Credit Limit, and the last X number of Credit Updates for the specific Client account. (X is configured on the Server). This Use Case is manually triggered from the client. Refer to the Vending Agent Statement receipt format in document “Online Vending Receipt Formats” and XMLVend specification for detailed information about all the fields in the statement. Notice that the “Bank date” is the field when the action was initiated e.g. the transaction date of banking. The “Applied date” is the date that the actual change was applied on the Client account on the server (i.e. when the Vending Agent would see the effect).
Desired Outcome The Vending Agent is able to reconcile his bank deposits with the credit updates on the Server and to be able to see the remaining credit available The Vending Agent Statement is shown and/or printed on the Client. It is recommended that the statement is only displayed on the screen (if feasible) and the Vending Agent can optionally choose to print as well
Participants Vending Client
Vending Agent
Vending Server
Name Issue Advice (last response)
Scenario Description This Use Case is automatically generated by the Client if a valid response has not been received from the Server for the Client Configured duration. The specific duration is dependent on the unique Client circumstances as well as the reliability and bandwidth of
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 54 of 108
the communications infrastructure. This Use Case is only applicable for requests where permanent changes may result from the request namely; Credit Purchase, Meter Credit Transfer and Pay Account (all types). This is specifically noted in every Use Case workflow where relevant. Use Cases where permanent changes do not result from the request, shall not use this Use Case, the Client must instead simply inform the Vending Agent that the request has timed out and must be retried.
Desired Outcome If the referenced Advice Request Message ID exists on the Server, the Server will return an auto-reprint transaction
If the referenced Advice Request Message ID does not exist, (or if the requested message is of an invalid type for this response) the Server will return an exception message to indicate that the referenced request does not exist. The Client can then continue to vend normally.
If the referenced Advice Request Message ID does exist, the Server must return the relevant auto-reprint transaction for that Message ID
The Client must print the auto-reprint transaction so that the Vending Agent can give it to the customer or otherwise retain the receipt to claim the value of the token back from Eskom if the customer has already left.
Participants Vending Client
Vending Server
Name Bulk Update Meter Key Change
Scenario Description Use the Update Meter Key Use Case for every meter in the file. This Use Case caters for the entering of bulk meter numbers to produce bulk key change tokens for valid registered numbers, when the bulk supply group code, tariff index, or key revision number is changed. The Update Meter Key Data Use Case is used request a set of key change tokens, which are used to update one or more key data items (i.e. SGC, TI and KRN) for a specific meter. This Use Case is manually triggered from the PSG using a flat file that is imported.
Desired Outcome An output file with all the key change token(s) requested for the input file.
Participants Customer
Vending Client
Vending Server
AgentBulk
Name Bulk Engineering Key Change
Scenario Description Use the Meter Specific Engineering Token (all data) Use Case for every meter in the input file. The input file is created by the PSG user for the import into PSG. Provide a tool to assist with the creation of the input file.
Desired Outcome An output file with all the Engineering key change token(s) requested for the input file
Participants Customer
Vending Client
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 55 of 108
Vending Server
AgentBulk
7.6 Define the legal requirements.
No Legal requirements
7.7 Intellectual Property
All intellectual property belongs to Eskom.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised
version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 56 of 108
REPORTING REQUIREMENTS 8.
8.1 High level reporting requirements
8.1.1 Define the high level reporting requirements in number form. Report Number
Report Name Report Types Functionality
R1. Vendor Information Reports
1. Vendor Details Report 2. Client Details Report 3. Transaction Listing Per Vendor Report 4. Transaction Summary Report 5. National Transaction Summary Report 6. Account Payment Summary Report 7. Vendor Account Statement Report 8. Reconciliation Sales Summary Report 9. Reconciliation Vendor Account Balance Report 10. Vendor Credit Report
The Vending Agent information reports provides all the relevant details for the Vending Agent, such as:
Vending Agent details Vending Agent transactions Vending Agent balances Vending Agent payments Vending Agent sales Vending Agent credit
R2. Vendor Exception Reports
1. Vendor Low Credit Exception Report 2. Last Response Requests Report
The exception reports provide you with a view of all the Vending Agents with a low credit and is intended to show all advice last response requests transactions that were sent from a specific Vending Agent
R3. Customer Information Reports
1. Customer Details Report 2. Customer Transaction Details Report 3. Customer Transaction Details Per Account Report 4. Unallocated Pending Blocked Customers Report 5. Customer Step Details Report 6. Blocked CC&B Unallocated Pending Report
The customer information reports provides all the relevant details for the Vending Agent, such as:
Customer details Customer transactions Blocked customers Unallocated meters
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised
version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 57 of 108
7. Corrected Unallocated Meters Report 8. Customer Fault Report
Customer faults
R4. Exception Reports 1. Meter Not Registered Exception Report 2. Customer Meter Data Exception Report 3. Meter Import Exception Report
The exception reports display all the meters that are not registered, any discrepancies in the customers’ meter details and discrepancies in the meters being imported.
R5. System Information Reports
1. Current Tariff Status Report 2. Historic Tariff Status Report 3. BIV File Configuration Report 4. Functions To User Mapping Report
The system information reports provides you with the current as well as the historical tariffs, the benefits configured per customer and a list of all the Admin Functions users have access to.
R6. Meter Credit Transfer Reports
1. Meter Credit Transfer Per GL Owner and Agent 2. Meter Credit Transfer Per GL Owner and MSNO
R7. New Reports 1. First Issued FBE Reconciliation Report 2. PSG Agent Activity Log Report 3. Vendor Average Sales Report 4. Vendor Credit Movement Report 5. Credit Audit Trail Report 6. Key Rollover Key Changes Reports 7. Vend Transaction Dashboard for a period
The reports will provide a list of all valid FBE transactions per Vending Agent, log and trace all user activity performed on the system, provides a trend of the average sales peak per Vending Agent and tracks the movement of each Vending Agent’s credit on a daily basis.
Note: PSG Agents should not have access to the Vending Agent Information Reports
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 58 of 108
8.2 Detailed reporting requirements
8.2.1 Vendor Details Report Report name: View Vendor Details
Group: Vendor Information
Description: This Report will display all details of Vendor.
Input Parameters: Dropdown menu with all GLs Dropdown menu with all CDU Ids
Return Structure: Report Title: VIEW VENDOR DETAILS Report Header: CDU ID & Status : [CDU ID] & [STATUS : {Active/Disabled}] Vendor Name SAP Account No: {SAP AR Account} Address: {Registered address of the Vendor} Contacts : {Phone Contacts of Vendor} Report Columns: Client ID: [SORTED]{ Each CDU ID can have multiple Client IDs, if the Vendor is a Multi-
Client Vendor } Certificate Valid from: [from date] to [to date] Status : {Active or Disabled} Client Interface Mode: { “Swipe Card & Manual” or “Swipe Card”
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.2. Client Details Report Report name: View Client Details Report
Group: Vendor Information
Description: This Report will display all details of Vendor to which the selected Client ID is linked. It will also retrieve all other Client IDs linked to this particular Vendor.
Input Parameters: Dropdown menu with all Client Ids
Return Structure: Report Title: VIEW CLIENT DETAILS Report Header: Client ID selected: Status : {Active/Disabled} Certificate Valid from: [from date] to [to date] CDU ID lined to this Client ID: Vendor Name: SAP Account No: {SAP AR Account} Address: {Registered address of the Vendor}
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 59 of 108
Contacts : {Phone Contacts of Vendor} Report Columns: Client ID: [SORTED] { All Client IDs linked to this same CDU ID. Each CDU ID can have
multiple Client IDs, if the Vendor is a Multi-Client Vendor } Status : {Active/Disabled} Certificate Valid from: [from date] to [to date] Client Interface Mode: { “Swipe Card & Manual” or “Swipe Card”
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.3. Transaction Listing Per Vendor Report Report name: Detailed Transaction Listing per Vendor (UC009)
Group: Vendor Information
Description: This Report is intended to show all transactions that were processed from a specific vendor. This includes FBE, debt etc. and must be ordered by Client ID and Transaction Timestamp (TS)
Input Parameters: Dropdown menu with all GLs Dropdown menu with all vendor’s CDU_ID’s. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Header: CDU_ID Vendor Name Selected start date Selected end date Report Columns: Trn Timestamp [SORTABLE] XMLVend Msg_ID Client_ID Terminal ID Trn Description MSNO SGC {This value will be blank for Account Payment, excl Debt} Trf Ind {This value will be blank for Account Payment, excl Debt} KRN {This value will be blank for Account Payment, excl Debt} Alg Type {This value will be blank for Account Payment, excl Debt} Tok Tech {This value will be blank for Account Payment, excl Debt} BIV Code {This value will be blank for Account Payment, excl Debt} Account # {This is the Customer’s Conventional Account No. This value may not be
populated for all Customers.} Trn Amount (R) {Format: 2 Decimal places} kWh Units {Format: 2 Decimal places} {This value will be blank for Account Payment} Token {This value will be blank for Account Payment} Receipt # Group Trn # Transaction #
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 60 of 108
Credit Before (R) {Format: 2 Decimal places} : [UNSORTABLE] Credit After (R) {Format: 2 Decimal places} : [UNSORTABLE]
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.4. Transaction Summary Report Report name: Transaction Summary per SGC and Transaction Type by Date
Group: Vendor Information
Description: This Report will be used to view transactions done per SGC and Transaction Type.
Input Parameters: Dropdown menus for GLs {Regions}, CDU_IDs and SGCs. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Heading: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } SGC : { selected SGC or “All SGCs” } Start date selected End date selected Report Created on Default Report Sorting: Sorting must be done on the CDU_ID and SG_Code Report Columns: Date (Optional) GL : { as a header for each group or as a column } CDU_ID [SORTABLE] SGC [SORTABLE] {Format: 6 Numerics, prefixed with Zeroes} Normal Sale Count Normal Sale Value (R) {Format: 2 decimal places} Normal Sale Units (kWh) {Format: 2 decimal places} FBE Count FBE Value (R) {Format: 2 decimal places} FBE Units (kWh) {Format: 2 decimal places} Meter Cred Trnsfr Count Meter Cred Trnsfr Value (R) {Format: 2 decimal places} Meter Cred Trnsfr Units (kWh) {Format: 2 decimal places} Over Recovery Count Over Recovery Value (R) {Format: 2 decimal places} Over Recovery Units (kWh) {Format: 2 decimal places}
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 61 of 108
Debt Recovery Count Debt Recovery Value (R) {Format: 2 decimal places} Total (R) per SGC: {Format: 2 decimal places} Total kWh per SGC: {Format: 2 decimal places}
Report Footer: Display totals of all the Columns.
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
Note: Report to be configured per vendor per month Report cannot handle changes in sales type, make provision for sales type column 8.2.5. National Transaction Summary Report Report name: Vending Transaction Summary per Client ID and Transaction Type by Date
Group: Vendor Information
Description: This Report will be used to view transactions done per Client ID and Transaction Type.
Input Parameters: Dropdown menus for GLs {Regions}, CDU_IDs and Client IDs. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Heading: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } Client ID : { selected Client ID or “All Client IDs” } Start date selected End date selected Report Created on Default Report Sorting: CDU ID, SGC Report Columns: CDU_ID [SORTABLE] Client ID [SORTABLE] : {This is 13 Digit EAN Number} Normal Sale Count Normal Sale Value (R) {Format: 2 decimal places} Normal Sale Units (kWh) {Format: 2 decimal places} FBE Count FBE Value (R) {Format: 2 decimal places} FBE Units (kWh) {Format: 2 decimal places} Meter Cred Trnsfr Count Meter Cred Trnsfr Value (R) {Format: 2 decimal places} Meter Cred Trnsfr Units (kWh) {Format: 2 decimal places} Over Recovery Count
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 62 of 108
Over Recovery Value (R) {Format: 2 decimal places} Over Recovery Units (kWh) {Format: 2 decimal places} Debt Recovery Count Debt Recovery Value (R) {Format: 2 decimal places} Total (R) per Client ID: {Format: 2 decimal places} Total kWh per Client ID: {Format: 2 decimal places}
Report Footer: Display totals of all the Columns from Normal Sale Count
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.6. Account Payment Summary Report Report name: Account Payment Summary per Transaction Type by Date
Group: Vendor Information
Description: This Report will be used to view Account Payment transactions done per CDU_ID.
Input Parameters: Dropdown menu with all GL’s {Regions} vendor’s CDU_ID’s. Sorting must be done on the CDU_ID. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Processing Logic A Count must be done on the Rand Values per Account Payment Type for the Vendor(s) selected in the input parameters
Return Structure: Report Heading: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } Start date selected End date selected Report Created on Default Report Sorting: Sorting must be done on the CDU_ID and SGC Report Columns: CDU_ID Client ID Generic Transaction Count Generic Transaction Value (R) {Format: 2 decimal places} Upgrade Transaction Count Upgrade Transaction Value (R) {Format: 2 decimal places} Conversion Transaction Count Conversion Transaction Value (R) {Format: 2 decimal places}
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 63 of 108
Connection Transaction Count Connection Transaction Value (R) {Format: 2 decimal places} Tamper Transaction Count Tamper Transaction Value (R) {Format: 2 decimal places} Total (R) per Client ID Report Footer: Display totals of all the Columns from Generic Transaction Count
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.7. Vendor Account Statement Report Report name: Vendor Account Statement Report
Group: Vendor Information
Description: This Report will display all effects on the Vendor’s Account Balance and Available Credit. Emergency Credits have no effect on Vendor’s Account Balance. Emergency Credits will only have an effect on Vendor’s Available Credits, whether ISSUED, CANCELLED or EXPIRED.
Input Parameters: Dropdown menu with all GL Dropdown menu with all CDU_ID’s. Start Date of Report (default will be current day’s date) End Date of Report (default will be current day’s date)
Return Structure: Report Title: VENDOR ACCOUNT STATEMENT REPORT Report Header: GL: { Region Name } CDU ID Vendor Name Date From: {From Date Chosen} Date To: {End Date chosen} Report Created on: {Date} Default Report Sorting: Applied Date Report Columns: Applied Date [SORTABLE] Action: { Following values will apply:
o Deposit o Adjustment from SAP o Emer Cred ISSUED o Emer Cred CANCELLED o Emer Cred EXPIRED o Credit Limit Change }
Amount (R)
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 64 of 108
Reference : {Deposit Reference or SAP Adjustment reference or user comments when Emergency Credits issued or cancelled}
Available Credit Limit (R) Account Balance (R)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
Note: The report doesn’t always show the limit changes 8.2.8. Reconciliation Sales Summary Report Report name: Reconciliation Sales Summary Report Group: Vendor Information
Description: This Report will display a list of transactions performed against a Vendors account (this will include any debits or credits made to the account) but will exclude FBE transactions.
Input Parameters: Dropdown menu with all vendor’s CDU_ID’s. Disabled vendors must also be displayed. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Title: RECONCILIATION SALES SUMMARY REPORT Report Header: CDU ID Vendor Name Date From: Date To: Opening Account Balance (R): {Opening Balance on From Date} Closing Account Balance (R) : {Closing Balnce on To Date} Report Created on: Default Report Sorting: All Vendor Credit Adjustments will be sorted by Transaction Date. Report Columns: Transaction Type: {To include all the transactions which affect Vendors Account Balance.
Typical Transactions will be all types of transactions Vended, Vendor Deposits, Adjustments done to Vendors’ AR Account in SAP}
Transaction Date: No. of Transactions: Total kWh Units: Vendor Debits (R): Vendor Credits (R): FBE Count FBE kWh Fixed Charges Count Fixed Charges Value Report Footer:
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 65 of 108
{ Totals for the columns: No. of Transactions, Total kWh Units, Vendor Debits, Vendor Credits }
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
Note: The report does not show fixed charges and does not include FBE KWH 8.2.9. Reconciliation Vendor Account Balance Report Report name: Reconciliation Vendor Account Balance Report
Group: Vendor Information
Description: This Report will display Account Balance of all selected Vendors on the selected date (the balance is taken from the last transaction timestamp done on the date selected). The calculation for the Vendor Account Balance includes all Transactions/Adjustments, which affects the Vendors Credit Level upto date specified.
Input Parameters: Dropdown menu with all GL’s {Regions}, CDU_ID’s. End date of report (default will be current day’s date)
Return Structure: Report Title: RECONCILIATION VENDOR ACCOUNT BALANCE REPORT Report Header: End date of Report: {Date chosen} Report Created on: {Date} Default Report Sorting: By CDU ID Report Columns: CDU_ID : {Make this a link, to be clicked for complete details. Probably can show the
“View Vendor Credit Report”} Vendor Name Credit Limit (R) Emergency Credit (R) : { Should display [0], if no Emergency Credits issued or if
Emergency Credits issued previously expires } Emergency Credit Expiry Date: {Date on which emer cred expires} Available Credit (R) Account Balance (R)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
Note: The report times out because of the big data volume 8.2.10. Vendor Credit Report Report name: View Vendor Credit
Group: Vendor Information
Description: This Report will display all the details of Vendor’s Credit status.
Input Parameters: Dropdown menu with all GL’s {Regions}, CDU_ID’s. End date of report (default will be current day’s date)
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 66 of 108
Return Structure: Report Title: VIEW VENDOR CREDIT Report Header: Report Created on: {Date} CDU_ID Vendor Name Credit Limit (R) Credit Limit Reason: { Reason given while setting this Value } Emergency Credit (R) : { Should display [0], if no Emergency Credits issued or if
Emergency Credits issued previously expires } Emergency Credit Expiry Date: {Date on which emer cred expires} Emergency Credit Reason : {Reason for giving Emer Cred } Available Credit(R) Account Balance (R) Recommended Deposit Amount (R) Optimum Credit (R)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.11. Vendor Low Credit Exception Report
Report name: Low Credit Exception Report
Group: Exception Reports
Description: This Report displayes all the CDU IDs with No Credit/Low Credits.
Input Parameters: Dropdown menus for GLs Dropdown menus for CDU IDs Text box to fillin a Rand value [A] to see all the Vendors whose Available Credit is below
value [A] during the date range selected. Start Date End Date
Return Structure: Report Title: LOW CREDIT EXCEPTION REPORT Report Header: GL (Region) : { selected GL or “All GLs”. If All GLs are selected, each group should have a
header displaying the GL. If this is not possible, remove GL from this section and add a new Report Column: “GL (Region)” }
Date From: {Date chosen} Date To: {Date chosen} Report Created on: {Date} Default Report Sorting: By CDU ID and Date Logged Report Columns: Date Logged [SORTABLE] : {Timestamp} CDU ID [SORTABLE]
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 67 of 108
Available Credit (R): {This is available credit of the Vendor at the time it was identified that
he has low credits. To verify his current Available Credits go to Vendor Credit Report } Credit Limit (R) Emer Credit (R) : {This is the value of Emergency Credits issued to the Vendor at the time
it was identified that he has low credits }
Security: Admin
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.12. Last Response Requests Report
Report name: View Last Response Requests per Vendor
Group: Vendor Information
Description: This Report is intended to show all advice last response requests transactions that were sent from a specific vendor. The query will also indicate in a header format the number of advice last response requests sent to the server as well as a count on the number of valid responses sent back to the vendor by the server and the XML Message content of the response will be included in the returned data.
Input Parameters: Dropdown menu with all GL Names. Dropdown menu with all Vendor’s CDU_ID’s and Vendor names. Sorting must be done on
the CDU_ID, and the Name must be displayed in ()’s. Disabled Vendors must also be displayed.
Dropdown with all Client IDs for selected CDU_ID Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Title: LAST RESPONSE REQUESTS PER VENDOR Report Heading: Report Created on: {Date} Vendor CDU_ID Status: { Active / Disabled } Selected start date Selected end date No. of Requests Received (this is the messages.request count) No. of Responses Sent (this is the messages.response count) Default Report Sorting: Sorting must be done per Client ID and then on Transaction Date Report Columns: Transaction Date : { Server time when the response was sent ] Client_ID: {13 digit EAN Number } Server_ID: {13 digit EAN Number } Date timestamp of request : { This is the time OVS received the request } MSG ID {Date Timestamp and 6 Digit Msg_ID} Advice MSG ID : { Message ID of the original request } Response Type : { to display valid response or fault response }
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 68 of 108
Message Content (XML Format) : { If displaying the full XMLVend Response makes the cell too big, only the response message can be displayed }
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.13. Customer Details Report
Report name: View Customer Transaction Details per Account
Group: Customer Information
Description: This Report displays detailed Customer info based on MSNO and Account information provided. This Report retrieves data from main database as well as from error bucket (List of customer records, whose information fails validation rules when downloaded from CC&B).
Input Parameters: A text box where the user will be able to enter a MSNO. {To input either MSNO or Account Number}
A text box where the user will be able to enter a Account Number. {To input either MSNO or Account Number}
Return Structure: Report Header: Customer Name: { show “NOT REGISTERED” if customer not registered.} Address1 (Stand No): { show “NOT REGISTERED” if customer not registered.} Address2 (Townshop): { show “NOT REGISTERED” if customer not registered.} Meter Serial Number (MSNO): Account No : {Account number against which Debt is recovered from PDR Customer} Tariff Index Supply Group Code (SGC) Algorithm Type: { 2 digit code + Description. Blank if not provided} Token Technology: {2 digit code + Description: (Key pad or Magnetic). Blank if not
provided} Key Rev Number (KRN): BIV Code: FBE : { kWh units if Customer qualifies or N/A if none} Debt % : {This is % to be recovered if the customer is a PDR Customer or N/A} Grace Purchases used : {Show number of Grace Purchases used if customer not
registered or N/A if registered } Customer Information Updated on: [ Date ] { Date Customer information last updated
from import from CC&B } Blocked: {It will have any of the following values:
YES. CC&B Block YES. OVS Unallocated Block NO }
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.14. Customer Transaction Details Report
Report name: View Customer Transaction Details per MSNO
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 69 of 108
Group: Customer Information
Description: This Report displays detailed transactions for a specific MSNO from a given start and end date
Input Parameters: A text box where the user will be able to enter a Meter Serial Number. Start date of report (default date will be current date) End date of report (default date will be current date)
Return Structure: Report Header: Meter Serial Number Customer Name Date From Date To Default Report Sorting: Sorting must be done on the Trn Timestamp Receipt No Report Columns: Trn_Timestamp CDU ID CLIENT ID MSNO Trn Type SGC Trf Ind BIV Code KRN
Alg Type
Token Tech Receipt No Transaction No Group Trans. No Trn Amount ® kWh Units Token
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.15. Customer Transaction Details Per Account Report
Report name: View Customer Transaction Details per Account
Group: Customer Information
Description: This Report displays detailed transactions for a specific Account, from a given start and end date
Input Parameters: A text box where the user will be able to enter a Account Number. Start date of report (default date will be current date) End date of report (default date will be current date)
Return Structure: Report Header: Account Number Customer Name
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 70 of 108
Date From Date To Default Report Sorting: Sorting must be done on the Trn Timestamp Receipt No Report Columns: Trn_Timestamp CDU ID CLIENT ID Trn Type Receipt No Group Trans. No Trn Amount (R)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.16. Unallocated Pending Blocked Customers Report
Report name: View Customer Transaction Details per Account
Group: Customer Information
Description: This Report displays detailed transactions for a specific Account, from a given start and end date
Input Parameters: A text box where the user will be able to enter a Account Number. Start date of report (default date will be current date) End date of report (default date will be current date)
Return Structure: Report Header: Account Number Customer Name Date From Date To Default Report Sorting: Sorting must be done on the Trn Timestamp Receipt No Report Columns: Trn_Timestamp CDU ID CLIENT ID Trn Type Receipt No Group Trans. No Trn Amount (R)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 71 of 108
8.2.17. Customer Step Details Report
Report name: Customer Step Details Report
Group: Customer Information Reports
Description: This Report is intended to show all transactions that were processed for a specific meter. This Report displays the tariff step details per transaction.
Input Parameters:
MSNO Start Date End Date
Return Structure: Report Title: CUSTOMER STEP DETAILS REPORT
Report Header:
Report Created on MSNO selected Selected start date Selected end date
Default Report Sorting:
Trn Timestamp Desc Receipt No
Report Columns:
Trn Timestamp [SORTABLE] CDUID [SORTABLE] ClientID [SORTABLE] MSNO Trn Type Receipt No [SORTABLE] Step 1 kWh Step1 Rand Value Step2 kWh Step 2 Rand Value Step 3 kWh Step3 Rand Value Step4 kWh Step 4 Rand Value Period Total kWh Period Total Rand Value Grand Total kWh Grand Total Rand Value
Security: Admin
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Note the Rand amount for all the FBE transactions must be zero and their kWh
contribution dependent on the inclusion/exclusion setting.
Transactions will be order by Trn Timestamp and Receipt No
Export To Excel Yes
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 72 of 108
8.2.18. Blocked CC&B Unallocated Pending Report
Report name: Blocked Customers Group: Customer Information
Description: This Report is to view details of meters that have been blocked by CC&B and meters blocked by OVS as a result of unallocation. The report will also show unallocated pending blocked meters.
Input Parameters: Text box for the user to enter a Meter Serial Number. If the Meter Serial Number is blank, all blocked and pending blocked meters should appear.
Return Structure: OPTION1: When a MSNO is entered Page 1: Report Title: DETAILS FOR UNALLOCATED BLOCKED METERS Report Heading: Report Created on: {Date} Report Columns: CDU ID MSNO SGC TI No of Grace Purchases used: { Value } No of Grace Purchases left: { Value } Page 2: Report Title: DETAILS OF BLOCKED METERS FROM CC&B Report Heading: Report Created on: {Date} Report Columns: MSNO SGC TI Page 3: Report Title: DETAILS FOR UNALLOCATED BLOCKED METERS Report Heading: Report Created on: {Date} Report Columns: CDU ID MSNO SGC TI No of Grace Purchases used: { Value }
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 73 of 108
OPTION 2: When a (MSNO text box is left blank; Page 1: Report Title: VIEW BLOCKED/UNALLOCATED PENDING BLOCKED CUSTOMERS Report Heading: Report Created on: {Date} No. of BLOCKED Customers from CC & B: { Value } : {link to view details. This should
display Option2:Page2} No. of BLOCKED Customers as a result of Unallocation: { Value } : {link to view details.
This should display Option2:Page3} No. of PENDING BLOCKED customer as a result of unallocation: {Value } : {link to view
details. This should display Main page of the Report; Unallocated Pending Blocked Customers }
Total: {Total of the above 3 values } Page 2: Report Title: DETAILS OF BLOCKED METERS FROM CC&B Report Heading: Report Created on: {Date} Total No. of BLOCKED Customers from CC & B: { Value } Default Report Sorting: Sorting must be done on the SGC, TI. Report Columns: SGC TI MSNo Addr1 {?} Addr2 {?} Page 3: Report Title: DETAILS FOR UNALLOCATED BLOCKED METERS Report Heading: Report Created on: {Date} Total No. of UNALLOCATED BLOCKED Customers on OVS: { Value } Default Report Sorting: Sorting must be done on the CDU ID, SGC, TI. Report Columns: CDU ID SGC
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 74 of 108
TI MSNo
Security: All
Export To Excel Yes
8.2.19. Corrected Unallocated Meters Report
Report name: Corrected Unallocated Meter Report (Imported from CC & B)
Group: Customer Information
Description: This Report will show all meters that was previously unregistered and which have subsequently been registered and imported from CC & B
Input Parameters: Dropdown menu with all vendor’s CDU_ID’s. An ‘All’ option must also be available and if the All function is selected, the page will display all meters that was previously unallocated which has subsequently been registered.
Return Structure: Report Title: CORRECTED UNALLOCATED METER REPORT Report Heading: Report Created on: {Date} Total No. of UNALLOCATED Customers Corrected: { Value } Default Report Sorting: Sorting must be done on the CDU ID, CLIENT ID, SGC, TI. Report Columns: CDU_ID Client ID (EAN) Meter Serial Number Trf Ind : {Tariff Index} SGC BIV Code
Security: All
Export To Excel Yes
8.2.20. Customer Fault Report
Report name: Customer Fault Report
Group: Customer Information
Description: To view customers faults logged on the Online Vending System.
Input Parameters: Drop Down for GL (Region), CDU ID Text box to enter a MSNO, as a search criteria. Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Title: CUSTOMER FAULT REPORT Report Header: CDU ID : {Displayed only when Text Box field is blank} Vendor Name: {Displayed only when Text Box field is blank}
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 75 of 108
Date From: Date To: {Date chosen} Report Created on: {Date} Default Report Sorting: By Log Date Report Columns: Log Date: {Date fault was logged} MSNO SGC : {Blank if not provided} Trf Ind : {Blank if not provided} Customer Name: {Prepaid Customer’s Name} Cust Address : { Customer’s Address. Blank if not provided} Cust Contacts:{Customer’s Contact number. Blank if not provided} Fault Type: {Will have any of the following values:
Correction of Tariff Code Correction of SGC Update Unregistered Meter Meter Burnt Out Meter Reversing No Supply Faulty Meter-No Supply MCB Tripped at Meter Box Broken Meter box – still working }
Fault Message: Fault Reference: {Generated by OVS}
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.21. Meter Not Registered Exception Report
Report name: Meter not Registered Exception Report
Group: Exception Reports
Description: This Report lists all the MSNO which are not registered in CC&B and which are vending by “Grace Purchase” option [Impulse Vending].
Input Parameters: Start date of report (default will be current day’s date) End date of report (default will be current day’s date)
Return Structure: Report Title: METER NOT REGISTERED EXCEPTION REPORT Report Header: Date From: {Date chosen} Date To: {Date chosen} Report Created on: {Date} Default Report Sorting: By Date Logged
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 76 of 108
Report Columns: Date Logged: {Date Exception was logged} MSNO CDU ID: {Where last the Unallocated Customer purchased} SGC : {Blank if not provided} Trf Ind : {Blank if not provided} Alg Type: { 2 digit code + Description. Blank if not provided} Token Tech: {2 digit code + Description: (Key pad or Magnetic). Blank if not provided}
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.22. Customer Meter Data Exception Report
Report name: Customer/Meter Data Exception Report
Group: Exception Reports
Description: This Report lists all the entries logged when CC&B data (AT & TT) mismatches with the data supplied by the Customer by Meter Card. Only, in this case, data provided by Customer should be considered as accurate and CC&B data must be rectified accordingly. Also to be noted that OVS will only vend to STS Meters.
Input Parameters: Dropdowns to “Select One or all CDU IDs, One or all SGCs. Text box to verify a MSNO. {It its blank, must retrieve all the exceptions.} Start date of report (default will be current day’s date) End date of report (default will be current day’s date) {If Start Date/End Date is blank, it must retrive all the exception logs}
Return Structure: Report Title: CUSTOMER/METER DATA EXCEPTION REPORT Report Header: Date From: Date To: {Date chosen} Report Created on: {Date} Default Report Sorting: By Log Date Report Columns: Date Logged: {Date Exception was logged} CDU ID : {If this is BLANK, the exception happened at Vending Process, otherwise, it
happened during a customer/meter import process MSNO SGC : {Blank if not provided} Trf Ind : {Blank if not provided} BIV Code Alg Type: { 2 digit code + Description. Blank if not provided} Token Tech: {2 digit code + Description: (Key pad or Magnetic). Blank if not provided} Account No : {Account number against which Debt is recovered from Prepayment
Customer} Exception Type: { It will have the following values:
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 77 of 108
No/Invalid Account Number Invalid AT/TT Invalid SGC Invalid TI Invalid TI-SGC combination Invalid BIV Code }
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.23. Current Tariff Status Report
Report name: Current Tariff Status Report
Group: System Information
Description: This Report displays the current tariff configuration for the OVS.
Input Parameters: GL SGC
Return Structure: Report Title: CURRENT TARIFF STATUS REPORT Report Header: Report Created on: {Date} Total Count of Tariffs : { Count of Tariff+SGC combinations} Default Report Sorting: By SGC, Tariff Index, Effective Date. Report Columns: SGC [SORTABLE] Trf Ind [SORTABLE] Pwr Lmt [SORTABLE] Status [SORTABLE] Current Step 1 Trf Rate (cents) New Step 1 Trf Rate (cents) Current Step 1 FBE kWh value : { kWh Units } New Step 1 FBE kWh value : { kWh Units } Current Step 2 Trf Rate (cents) New Step 2 Trf Rate (cents) Current Step 2 FBE kWh value : { kWh Units } New Step 2 FBE kWh value : { kWh Units } Current Step 3 Trf Rate (cents) New Step 3 Trf Rate (cents) Current Step 3 FBE kWh value : { kWh Units } New Step 3 FBE kWh value : { kWh Units } Current Step 4 Trf Rate (cents) New Step 4 Trf Rate (cents) Current Step 4 FBE kWh value : { kWh Units } New Step 4 FBE kWh value : { kWh Units }
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 78 of 108
Effective Date [SORTABLE]
Security: Admin
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.24. Historic Tariff Status Report
Report name: Historic Tariff Status Report
Group: System Information
Description: This Report lists historic tariffs that applied at a certain dates.
Input Parameters: GL SGC Start Date (default will be current day’s date) End Date (default will be current day’s date)
Return Structure: Report Title: HISTORIC TARIFF STATUS REPORT Report Header: Date From: {Date chosen} Date To: {Date chosen} Report Created on: {Date} Total Count of Tariffs : { Count of Tariff+SGC combinations} Default Report Sorting: By GL, SGC, Tariff Index, Effective Date. Report Columns: GL [SORTABLE] SGC [SORTABLE] Trf Ind [SORTABLE] Effective Date [SORTABLE] Step 1 Trf Rate (cents) Step 1 FBE kWh value : { kWh Units } Step 2 Trf Rate (cents) Step 2 FBE kWh value : { kWh Units } Step 3 Trf Rate (cents) Step 3 FBE kWh value : { kWh Units } Step 4 Trf Rate (cents) Step 4 FBE kWh value : { kWh Units }
Security: Admin
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.25. BIV File Configuration Report
Report name: BIV File Configuration Report
Group: System Information
Description: This Report shows the configuration of benefit indicator on the system.
Input Parameters: GL
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 79 of 108
SGC
Return Structure: Report Title: BIV FILE CONFIGURATION REPORT Report Header: Report Created on: {Date} Total Count of BIV Codes Default Report Sorting: By TI, BIV Code Report Columns: Trf Ind [SORTABLE] BIV Code [SORTABLE] Package Code [SORTABLE] Munic Code [SORTABLE] FBE kWh: { kWh Units } Debt%: { Value } Effective Date [SORTABLE]
Security: Admin
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.26. Functions To User Mapping Report
Report name: Functions to User Mapping Report
Group: System Information
Description: This report lists all the Admin Functions users have access to.
Input Parameters: Dropdown of all Admin Functions. { Choose this to lists all the users linked to this function } Dropdown of Novell User IDs on OVS. { Choose this to list all the functions enabled for this
User }
Return Structure: Report Title: FUNCTIONS TO USER MAPPING REPORT Report Header: Report Created on: {Date} Default Report Sorting: Report Columns:
Security: Admin, Super User
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.27. Meter Credit Transfer Per GL Owner and Agent
Report name: Meter Credit Transfer Per GL Owner and Agent Report
Group: Vending Agent Information
Description: This Report will show the meter credit transfer token created by the Agent from that GL owner
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 80 of 108
Input Parameters: Dropdown menu with all GL owner {Regions}, Agents, Date Range End date of report (default will be current day’s date)
Return Structure: Report Title: METER CREDIT TRANSFER PER GL OWNER AND AGENT REPORT Report Header: Report Columns: Meter number SGC TI kWh or Currency Agent name
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.28. Meter Credit Transfer Per GL Owner and MSNO
Report name: Meter Credit Transfer Per GL Owner and MSNO
Group: Vending Agent Information
Description: This Report will show the meter credit transfer token created for the meter from that GL owner
Input Parameters: Dropdown menu with all GL owner {Regions}, Meter Number, Date Range End date of report (default will be current day’s date)
Return Structure: Report Title: METER CREDIT TRANSFER PER GL OWNER AND MSNO REPORT Report Header: Report Columns: Meter number SGC TI kWh or Currency Agent Name
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.29. First Issued FBE Reconciliation Report
Report name: First Issued FBE Reconciliation Report
Group: Vending Agent Information
Description: This Report will display all the valid FBE transactions per Vending Agent per month.
Input Parameters: Dropdown menu with all GL’s {Regions}, CDU_ID’s. End date of report (default will be current day’s date)
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 81 of 108
Return Structure: Report Title: FIRST ISSUED FBE RECONCILIATION REPORT Report Header: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } SGC : { selected SGC or “All SGCs” } Start date selected End date selected Report Created on Report Columns: TRN_TIMESTAMP SGC Name Response Time Stamp Response MSG_ID Client ID Terminal ID/Agent TRN Type MSNO TRN Amt(R) kWh Units TOKEN Group TRN No
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd. Only upload first token per month for each meter instead of alphabetical batch uploads
Export To Excel Yes
8.2.30. PSG Agent Activity Log Report
Report name: PSG Agent Activity Log Report
Group: Vending Agent Information
Description: This Report will log and trace all user activity performed on the system either per meter number or per Agent.
Input Parameters: The report can either be requested per Agent name or per meter number. Dropdown menu with all Date range, Agent’s Name or Meter Number, GL Owner End date of report (default will be current day’s date)
Return Structure: Report Title: PSG AGENT ACTIVITY LOG REPORT Report Header: CDU ID : { selected CDU ID or “All CDU IDs” } Start date selected End date selected Report Created on Report Columns: CDU ID
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 82 of 108
Agent Name Date Meter Number Action Performed Parameters for particular action (Parameters to be defined)
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.31. Vendor Average Sales Report
Report name: Vendor Average Sales Report
Group: Vending Agent Information
Description: This Report will provide a trend of the average sales peak per Vending Agent.
Input Parameters: Dropdown menu with all GL’s {Regions}, CDU_ID’s, SGC. End date of report (default will be current day’s date)
Return Structure: Report Title: VENDOR AVERAGE SALES REPORT Report Header: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } SGC : { selected SGC or “All SGCs” } Start date selected End date selected Report Created on Report Columns: Normal Sales kWh Normal sales Rand Normal sales Number(Count) FBE kwh FBE number Debt recovery Fixed Charge value Total Rand Total kWh Total Count
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.32. Vendor Credit Movement Report
Report name: Vendor Credit Movement Report
Group: Vending Agent Information
Description: This Report will track the movement of each Vending Agent’s credit on a daily basis.
Input Parameters: Dropdown menu with all GL’s {Regions}, CDU_ID’s. End date of report (default will be current day’s date)
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 83 of 108
Return Structure: Report Title: VENDOR CREDIT MOVEMENT REPORT Report Header: CDU ID Start date selected End date selected Report Created on Report Columns: Date Day Available credit Sales Debt recovery Fixed charges Deposits Refunds given Adjustments credit transfer Adjustments debit transfer Credit available Increase/decrease in guarantee Emergency credit given/cancelled Total credit available Total weekly outstanding sales Sales payable less deposits (-) indicates deposits less than sales Guarantee on server Amount owing to Eskom/(-) due to Vending Agent
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.33. Credit Audit Trail Report
Report name: Credit Audit Trail Report
Group: Vending Agent Information
Description: This Report will provide a view of all emergency credit loaded and limit changes done by a Vending Agent Controller. Report must also show when adjustments by the system are made.
Input Parameters: Dropdown menu with all Date range, Vending Agent Controller, CDU_ID’s End date of report (default will be current day’s date)
Return Structure: Report Title: CREDIT AUDIT TRAIL REPORT Report Header: GL (Region) : { selected GL or “All GLs” } CDU ID : { selected CDU ID or “All CDU IDs” } SGC : { selected SGC or “All SGCs” } Start date selected
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 84 of 108
End date selected Report Created on Report Columns: Date Timestamp PSG/Vendor ID, Agent Original Amount Amended Amount
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.34. SGC/KRN Detail Report
Report name: SGC/KRN Detail Report
Group: Vending Agent Information
Description: This Report will provide a view of all meters per Supply Group associated to each KRN and base date.
Input Parameters: Dropdown menu with all Meter serial number, SGC, KRN and Base date End date of report (default will be current day’s date)
Return Structure: Report Title: SGC/KRN DETAIL REPORT Report Columns: Meter number From SGC From KRN From Tariff Index To SGC To KRN To Tariff Index Date of Key Change
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.35. Meter Base Date Summary Report
Report name: Meter Base Date Summary Report
Group: Vending Agent Information
Description: This Report will provide all meters for a particular SGC.
Input Parameters: Dropdown menu with all Date Range, SGC End date of report (default will be current day’s date)
Return Structure: Report Title: METER BASE DATE SUMMARY REPORT Report Header: SGC : { selected SGC or “All SGCs” }
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 85 of 108
KRN : { KRN 1 and KRN2} Report Columns: Total number of Meters Per SGC Per KRN
Security: All
Comment All dates and times are in format YYYY-MM-DD HH:mm:dd.
Export To Excel Yes
8.2.36. Vend Transaction Dashboard for a period
Report name: Vend Transaction Dashboard
Group: Vending Agent Information
Description: A Dashboard showing a summary of the total transactions over a period in total and per Vending Agent
Input Parameters: Normal Sales and FBE transactions
Security: All
NON FUNCTIONAL REQUIREMENTS 9.
9.1 User interface requirements
The current user interfaces for OVS and PSG are both web based and the proposed solution’s layout should be similar or based on more updated technology.
The diagrams below provide an indication of the current Graphical User Interfaces (GUI) per role for the 2 systems:
9.1.1 OVS Admin Administrator
Services/Applications Description
Administrator Role Security Management
The Administrator can do all the configurations on OVS
1. Manage System Roles
1. This function is used to configure the system level of the Roles and the Role Type. The Role Type affects what rules apply for the specific role
2. Manage Role-Process
2. Can add or remove functionality for a specific Role. Changes will affect all users that are assigned to the modified Role.
3. Manage Users 3. Can add, enable or disable users.
4. Manage User Roles 4. Can add or remove user roles.
5. Manage Role Functions
5. Can add or remove specific program functions (Methods) for every role on OVS.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 86 of 108
Services/Applications Description
System Configuration
6. Interface Configuration
6. This function shows and allows configuration of all the interfaces
7. Configure Utility Details 7. Can add/edit utility details but currently there is one utility which is Eskom
8. Manage Vendor Categories 8. Can configure which use case a vendor or a PSG can perform
9. Manage Banks 9. Can configure various banks in use by Eskom
10. Manage Meter Types 10. Can add/edit meter types
11. Manage GL Owners 11. Can add/edit GL Owners which in Eskom terms are regions.
12. Manage Supply Group Codes
12. Can assign GL Owner to the SGC but the loading of SGC is done when a tariff file is imported to OVS using the tariff importer tool.
13. Manage Client ID’s 13. Can add new client IDs by uploading a client id file that has new ids.
14. Manage Eskom Bank Accounts
14. This function allows the user to add or change Eskom bank accounts for the vendors’ deposits.
15. Manage Month End Dates 15. Can modify and set the Month End Dates for the system.
Vendor Management
16. Vendor Credit 16. Allows user to view/issue credit
17. Vendor Management 17. To edit/add the details of any vendor/PSG.
Reports
18. Reports 18. To run any of the reports on OVS
Super user
Services/Applications Description
Super User Security Management
1. Manage Users 1. Can add, enable or disable users.
2. Manage User Roles 2. Can add or remove user roles.
System Configuration
3. Manage Vendor Categories 3. Can configure which use case a vendor or a PSG can perform
4. Manage Banks 4. Can configure various banks in use by Eskom
5. Manage Meter Types 5. Can add/edit meter types
6. Manage Supply Group Codes
6. Can assign GL Owner to the SGC but the loading of SGC is done when a tariff file is imported to OVS using the tariff importer tool. Super User can only view
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 87 of 108
Services/Applications Description
7. Manage Client ID’s 7. Can add new client IDs by uploading a client id file that has new ids.
8. Manage Eskom Bank Accounts
8. This function allows the user to add or change Eskom bank accounts for the vendors’ deposits.
9. Manage Month End Dates 9. Can modify and set the Month End Dates for the system.
Vendor Management
10. Vendor Credit 10. Allows user to view/issue credit
11. Vendor Management 11. To edit/add the details of any vendor/PSG.
Reports
12. Reports 12. To run any of the reports on OVS
Vendor Controller and Operator
Services/Applications Description
Vendor Controller 1. Manage Users
1. Can enable or disable users within the region that is assigned to.
2. Manage User Roles
2. Can add or remove user roles within the region that user is assigned to.
3. Manage Eskom Bank Accounts
3. This function allows the user to add or change Eskom bank accounts for the vendors’ deposits. (These are Eskom bank accounts for vendors to deposit money into for vending.)
4. Vendor Credit
4. Allows user to issue credit but only to those vendors/PSG that are linked to that region.
5. Vendor Management
5. To edit the details of a vendor/PSG linked to the region and activate or de-activate any of these vendors.
6. Reports 6. To run any of the reports on OVS
Operator 7. Reports
7. To run any of the reports on OVS
8. Vendor Credit 8. Read only view
9.1.2. PSG Administrator
Services/Applications Description
Administrator Role Security Management
The Administrator can do all the configurations on PSG.
1. Manage Users
1. Can add, enable or disable users
2. Manage User Roles 2. Can add or remove user roles if its agents then roles are assigned per PSG and type of role
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 88 of 108
Services/Applications Description
3. Manage Role-Process
3. This function allows creation of new roles for Super Users and Agents, or modification of existing roles.
4. Manage Role Template Processes
4. This allows an Administrator to create or configure templates for the various Agent Roles.
System Configuration
5. Manage GL Owners 5. Can add/edit GL Owners which in Eskom terms are regions.
Gateway Functions
6. Show Meter Card Data
6. Allows user to swipe a meter card on the meter card reader and results displayed on the GUI.
Application Settings
7. Application Settings 7. This is the configuration screen for the PSG global parameters
8. MCP Driver Download 8. This function downloads the card encoder software and has instructions for IT support on how to install it.
Reports
9. Reports 9. To run any of the reports on OVS
Super User
Services/Applications Description
Super User Security Management
Please also note that the Super User role is PSG specific a Super User assigned for a role can’t see/view other regional stuff.
6. Manage Users
10. Can add, enable or disable users
7. Manage User Roles 11. Can add or remove user roles if its agents then roles are assigned per PSG and type of role
Gateway Functions
12. Show Meter Card Data
8. Allows user to swipe a meter card on the meter card reader and results displayed on the GUI.
Application Settings
13. MCP Driver Download 10. This function downloads the card encoder software and has instructions for IT support on how to install it.
Reports
14. Reports 11. To run any of the reports on OVS
AgentCred, AgentCust and AgentTech
Services/Applications Description
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 89 of 108
Services/Applications Description
Agents (AgentCred, AgentCust, AgentTech)
1. Issue FBE Tokens
All these functionalities are self-explanatory. 1. Free basic electricity tokens
2. Issue Meter Credit Transfer Token
2. Issue tokens that have been replaced and only for meters that are registered on OVS. (Limited to AgentCred)
3. Update Meter Key
3. If meter data has changed then a key change token is generated in order to punch on the meter.
4. Confirm Meter Details 4. This is to confirm whether meter is on OVS.
5. Verify Token
5. To verify any token that has been issued to the customer by a vendor.
6. Reprint Transaction 6. Reprints the last 3 tokens vended to the customer.
7. Non-meter Specific Test Tokens
7. Generates a token, this is just used to test PSG functionality.
8. Engineering Key Change 8. If meter data has changed then a key change token is generated in order to punch on the meter.
9. Set Power Limit 9. This is to issue a token that sets a power limit on the meter.
10. Set Phase Unbalance Limit
10. This issues a token that sets phase unbalanced limit.
11. Default Meter Credit
11. Issues a token of 5KwH for a new meter or a faulty meter that has recently been replaced. (Limited to AgentTech)
12. Clear Credit 12. Issues a token to clear credit in a particular meter.
13. Clear Tamper Status
13. Issues a token to clear a tamper status on the meter.
14. Vendor Statement
14. Creates a statement report for that particular vendor.
15. Convert Token to Magnetic Card
15. Converts normal token issued for magnetic meters.
16. MCP Driver Download
16. This function downloads the card encoder software and has instructions for IT support on how to install it.
17. Reports
17. To run any of the reports on OVS
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 90 of 108
9.2 System Integration requirements
9.2.1 The diagram below demonstrates the high level integration view between the various systems:
Figure 8: Integration diagram
The following system integration requirements must be met by the solution: The server must import and use the Eskom defined tariff file, to decide in real time from the tariff
Index, what tariff configuration must be applied when creating STS credit tokens The server must import and use the Eskom defined Benefit Indicator Vending (BIV) file to decide in
real time, from the BIV field for the customer, what FBE or debt recovery benefits to apply for the meter
The server must be able to import and use both real time XML based message processing via MSMQ, and also the Eskom defined Customer Download flat file, to register or update customers and meters on the system’s database
The server must, in real time, be able to transport XML based vendor deposit and adjustment messages from SAP through the Middleware, via MSMQ, for insertion and updating on the database
The server must support XML based real time transaction message export from the database, sent via the Middleware and ensure MSMQ routing and processing for vending transactions
The server must be able to facilitate XML based real time customer fault reporting where customer meter faults that are logged at a vending terminal, must be transported from the server to the database to then be exported and sent via the Middleware interface to the receiving system
The server must be able to send virtual tokens via the middleware to the integration bus and then to the Meter Data Management System (MDMS)
The OVS system must also be able to integrate with an independent XMLVend Test Suite
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 91 of 108
BRS Number
Functionality Impacted Systems
Sending System Owner
Receiving System Owner
What information needs to be integrated
SI1 CC&B passes customer (Address and Service Point), meter, tariff, FBE allocation and fixed charges data to OVS to ensure that customer and meter data in OVS is current and ready for vending.
CC&B, OVS CC&B
OVS
Customer (Address and Service Point), meter, tariff, FBE allocation and fixed charges data
SI2 CC&B passes PDR related information to OVS to ensure that PDR transactions can be effected in OVS.
CC&B, OVS CC&B
OVS
PDR configuration, PDR balances
SI3 SAP passes Vending Agent deposits and financial adjustment information to OVS.
SAP, OVS SAP OVS Financial adjustments and Vending Agent payments confirmations
SI4 OVS passes vending (meter sales) transaction information to CC&B to ensure that the record of prepaid sales in CC&B are current.
OVS, CC&B OVS CC&B Vending Transactions - Meter sales transaction information Fixed charges FBE
SI5 OVS passes customer fault information to CC&I.
OVS, CC&I OVS CC&I Customer faults with Meter number, Contact details of customer and OVS reference number
SI6 OVS to pass the virtual token information via the Eskom middleware to MDMS.
OVS, MDMS OVS MDMS STS Token information with meter number, Transaction ID, Date and time of transaction
SI7 OVS passes PDR transactions back to CC&B OVS, CC&B OVS CC&B PDR transactions
Note: All the interfaces must be fully automated interfaces between the various systems
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 92 of 108
9.3 Access requirements
9.3.1 Access roles for OVS Admin and PSG
System BRS Number
Role Define different types of access and what permissions that role has
OVS Admin AR1. Administrator The Administrator Role shall have unrestrictive access to all aspects of the system, except any of the XMLVend functions. For access to the XMLVend Functions the User must be registered on the XMLVend request system. An Administrator Role has access to all GL Owners and is able to define new Roles and customise existing Roles. Administrator to have a view of the Vend Transaction Dashboard.
AR2. Super User A Super User Role has wide access to the system, managing vending client ID’s, vending agents, vending agent’s bank accounts, users and their roles as well as the vending agents’ credit.
AR3. Vending Agent Controller
The vending agent controller manages the uses and their roles, manages the vending agent’s credit and bank accounts
AR4. Operator The operator will only be allowed to run reports on the system and to view the vendor credits
PSG AR5. Administrator The Administrator Role shall have unrestrictive access to all aspects of the system
AR6. Super User Super-User Role shall be allocated as the specific PSG owner. The Super-user is responsible for his PSG and must use their role to maintain operational characteristics and daily running of the PSG. The Super User Role shall have the ability to allocate Users to Agent Roles.
AR7. AgentCred AgentCred is the only one that can produce meter credit transfer tokens and all the normal support functions accept the specific technical meter functions in a store
AR8. AgentBulk AgentBulk is the only one that can produce bulk key change tokens
AR9. AgentTech AgentTech can produce the five units default credit for a meter in addition to the other support functions
AR10. AgentCust Can only perform the normal support functions
Note: PSG Agents should not have access to the Vending Agent Information Reports
9.4 Archiving requirements
9.4.1 State the retention / archiving period required for the data/information.
Retention Period
Archiving will be based on current archiving requirements for OVS:
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 93 of 108
Retention Period
Transactional Data must be kept on the system for 3 years; thereafter it can be archived every quarter/bi-annually and must be retrievable possibly on a separate system.
9.5 Disaster recovery requirements
9.5.1 High-level disaster recovery requirements
If OVS production fails, the OVS DR solution is used. OVS production failure, failover to OVS DR The OVS production site is located at Megawatt Park (MWP) from where the production database is replicated via Oracle Data Guard replication to the failover database at 141 Sivewright over the WAN. In the event of a disaster at MWP, the production system will be switched over to the DR environment located at 141 Sivewright. A management decision must be taken related to the amount of data that is lost due to the disaster before vending is started up in the DR environment.
See - OVS high-level DR design
Should a DR be invoked, transactional processing will be redirected manually from MWP to site 141
by changing the network routing to point to the DR firewall and F5 load balancer. No changes will be required from the online Vending Agent to connect to the DR site as the failover
will be done centrally on a network level. o Disable vending virtual server on the F5 load balancer at MWP in production if not already
disabled by disaster. o Change DNS record on MWP PROD GTM to point to DR virtual IP of F5
The DR design caters for: o RPO = 2 hours o RTO < 8 hours
SM table (in OVS) contains key information for security modules. These are different for the production and DR environments. The failover procedure must include updates to this table with the DR information.
All interfaces to other Eskom IT systems, e.g. CC&B, CC&I, SAP etc. are still operational in OVS DR. After an outage, information is synched from OVS DR back to OVS production to ensure that vending
operations can continue as normal.
Note: Adequate redundancy exists within OVS so that a minor disruption (i.e. disk drive failure, short-term power outage) that does not require relocation will not activate the plan.
Data loss Time to recover
RPO = 2 hours RTO < 8 hours.
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the
user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002
Page 94 of 108
9.6 Business continuity requirements
9.6.1 Confirm the business continuity information.
Business continuity plan exists Y
Name of BCP IT Service Continuity Plan
Name of BCP owner Willie Olivier
If BCP does not exist, what plans are in place from a customer view to define a BCP
N/A
If BCP needs to change, what plans are in place from a customer view to update the BCP
A remote off-site BC solution is required which are included in the scope of this project
OUT OF SCOPE AND PRECONDITIONS 10.
10.1 Define what is out of scope in terms of business requirement elicitation.
Unique identifier number
Out of scope
O1 Change Post Paid to Prepaid and Change Prepaid to Post Paid
Group IT Business Requirement Specification (BRS)
Online Vending System (OVS) Replacement Project DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
Controlled Disclosure
Page 95 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
10.2 Define any preconditions and dependencies that impact the business requirement
Unique identifier number
Business Activities Processes Projects (IT and Business)
Technology (if known)
D1 Interfaces from CC&B to OVS must be completed including PDR and currency tariffs
Manage Revenue PDR Project
D2 MDMS server must be available and configured to receive and distribute the Virtual tokens.
Manage Customer Services Master Data
Manage Revenue
Manage Customer Contact
Manage Customer Base
MDMS Project Smart Metering
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 96 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
TRAINING 11.
11.1 Define the high level training requirements:
BRS Number
Functionality
T1 Supply a training environment
T2 All users to be trained on the new solution
T3 Flexible training environment
CORPORATE, DIVISIONAL AND DEPARTMENTAL PLAN ALIGNMENT 12.
12.1 Strategic alignment
12.1.1 Select the Eskom Shareholder's Strategic Intent Statement (SIS) that are supported by this requirement:
SIS Supported
(Y/N) How
Provide reliable, predictable and affordable electricity in line with the approvals and regulatory model by NERSA.
Y OVS is a revenue collection platform for almost 6 million prepaid electricity customer and need to be urgently replaced due to the National Treasury instruction which was communicated to Customer Service on 14 August 2018
Ensure and maintain a financially viable and sustainable company.
Y Average revenue collected via this platform is R9billion per annum.
Consolidate socio-economic contribution to ensure alignment to national transformation imperatives.
Y This system supports the Government policy of dispensing Free Basic Electricity to the indigent customers or Municipality communities.
Reduce the impact on the environment. N
Ensure that company structure is responsive to changing energy landscape.
Y The new OVS should support future prepaid smart metering rollout which is in line with the Eskom smart grid programme.
Submit annual strategic documents and report on progress.
N
Conduct reporting in line with regulatory model, with profit and loss for each licensee.
N
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 97 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
12.1.2 Divisional Focus areas / mandates being supported Become a customer-centric organisation that stimulates demand and collect revenue. The online vending system was originally approved as strategic service and revenue collection enabler. The system supports customer-centric organisation in the sense that prepayment is seen as a means of direct budgeting, reducing the time between payment (purchase) and use (consumption) of electricity while improving access and convenience for the customer.
12.1.3 Departmental Focus areas / mandates being supported Online Vending is in line with the value chain objectives of sustainable processes, systems and data.
CHANGE REQUEST COSTING ONLY (not for any other BRS types) 13.
This must be completed for change requests ONLY.
POSSIBLE OPTIONS 14.
a) Option 1: Issue an RFP to implement an Online Vending Solution on a managed service
Description Implementation of a new solution on Eskom’s infrastructure. This is a full replacement of the current OVS software, hardware and infrastructure
Critical knowledge /skills /enabling factors required to provide a successful delivery
Security
Integration
Business knowledge
An appropriate vendor to do the implementation
Option Risks Availability of the internal resources to support the new solution
Advantages Allows open market scanning as different solutions will be provided
Disadvantages Procurement process could be longer
Capital Expenditure required
The percentage solution fit is unknown
The current OVS hardware will be redundant
No flexibility to customise to Eskom environment
Fit to need: Close to 100%
Estimated implementation duration:
To be determined probably from best practise 12-18
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 98 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
b) Option 2: Issue an RFP to implement an Online Vending Solution hosted on a cloud service
Description Implementation of a new solution to do prepaid vending in the cloud. The market and the cloud evaluation assessment will determine whether the solution is on premise or off premise and also whether (IaaS, PaaS, or SaaS). The solution must comply with Eskom’s cloud requirements.
Critical knowledge /skills /enabling factors required to provide a successful delivery
Cloud Implementation skills
Security
Integration to internal systems
Business knowledge
Protection of personal information
An appropriate vendor to do the implementation
Option Risks Availability of the internal resources to support the new solution for Iaas and Paas
Advantages Allows open market scanning as different solutions will be provided
Reduce IT operational cost by leveraging on new technologies and IT resources (skills & infrastructure)
Maintenance cost should be lower since it will be COTS
Disadvantages The percentage solution fit is unknown.
Procurement process could be longer
Operational Expenditure required
No flexibility to customise to Eskom environment
Fit to need: Close to 100%
Estimated implementation duration:
To be determined
c) Option 3: Do Nothing – Status Quo “As Is”
Description Continue to use the current solution and renew the contract with the current service provider
Critical knowledge /skills /enabling factors required to provide a successful delivery
Vendor supported and maintained solution
Renewal of the support and maintenance contract
Option Risks The OVS maintenance and support contract expired on 31 August 2018 and can't be extended further as per treasury instruction which was communicated to Customer Services on 14 August 2018.
The current production platform and DR site cannot be maintained and supported by the vendor.
There is no offline business continuity solution
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 99 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
There is a code freeze on the current platform and as a result the following critical projects cannot be completed
Advantages No Capital Expenditure
No learning effort
Disadvantages Vendor lock in
Non Adherence to National Treasury instruction for Eskom to advertise a competitive bid
Old technology is used
Highly customized solution and costly to maintain
Fit to need: 0%
Estimated implementation duration:
N/A
Recommended Option:
Option number 1
Can it be done under the current SLA: No – solution to be decided on
If YES, list the vendor and the contract reference #. N/A
Is software or licenses required? Provide details Unknown
Estimated Cost: To Be Determined
REFERENCES 15.
The following documents have been referenced or used to compile this Business Requirements Specification including Process Control Manuals.
Number Name Location
KRN - DEM-00812-J0L3 - GIT Project User Requirements Specification
KRN URS Link
Requirement for Bulk Key Change Functionality in Prepayment Support Gateway (PSG)
BKCT URS Link
Business Requirement Specification (BRS) OVS Business Continuity – DR (DEM-01730-P8M9) v0.8.4
OVC BC BRS Link
240-109236634 Online Vending System Glossary And Definition of Terms
https://hyperwave.eskom.co.za/240-109236634
DEM-02737-T6L7_DEM_OVS REPLACEMENT Demand Form
Online Vending Processes ver2.13
Online Vending Reporting Requirements ver2.2
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 102 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
ABBREVIATIONS 18.
Abbreviation Description
ACE Analytics Centre of Excellence Department
Alg Algorithm
ARIS Architecture of Integrated Information Systems
AT Algorithm Type
BC Business Continuity
BCP Business Continuity Plan
BI Business Intelligence (also known as Analytics)
BIV Benefit Indicator Vending
BKCT Bulk Key Change Token
BPM Business Process Manager
BRS Business Requirements Specification
CC&B Customer Care and Billing
CC&I Customer Care and Interaction
CDU Credit Dispensing Unit
COSEM Companion Specification for Energy Metering
CR Change Request
DDW Distribution Data Warehouse
DFD Data Flow Diagram
DLMS Device Language Message Specification
DR Disaster Recovery
EA Encryption Algorithm
FBE Free Basic Electricity
GIT Group Information Technology Division, also referred to as Group IT
GL General Ledger
GUI Graphical User Interface
Iaas Infrastructure as a Service
IBT Inclining Block Tariff
ID Identification
IEC International Electrotechnical Commission
IT Information Technology
ITSO Information Technology Service Operations
KLF Key Load File
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 103 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
Abbreviation Description
KPA Key Performance Area
KPI Key Performance Indicator
KRN Key Revision Number
kWh Kilowatt Hour
MDMS Meter Data Management System
MSMQ Microsoft Message Queuing
MSNO Meter Serial Number
MWP Megawatt Park
NERSA National Energy Regulator of South Africa
NT National Treasury
OS Operating System
OVC Online Vending Client
OVS Online Vending System
Paas Platform as a Service
PCM Process Control Manual
PDR Prepaid Debt Recovery
POS Point of Sale
PSG Prepayment Support Gateway
RFP Request for Proposal
RPO Recovery Point Objective - the maximum tolerable period in which data might be lost from an IT service due to a major incident
RTO Return Time Objective – the time it takes to recover the service
Saas Software as a Service
SAP Systems, Applications and Products (Eskom Financial System)
SARS South African Revenue Service
SEAR Strategy Execution Architecture and Risk
SGC Supply Group Code
SIS Strategic Intent Statement
SLA Service Level Agreement
SME Subject Matter Expert
SMS Short Message Service
SSL Secure Sockets Layer
STS Standard Transfer Specification
TCT Token Carrier Type
TI Tariff Index
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS)
Replacement Project DEM-02737-T6L7
Template Identifier
240-83570075 Rev 4
Authorisation Date
14 May 2018
Review Date December 2021
Controlled Disclosure
Page 104 of 108
When downloaded from the document management system, this document is uncontrolled and the responsibility rests with the user to ensure it is in line with the authorised version on the system.
No part of this document may be reproduced without the expressed consent of the copyright holder, Eskom Holdings SOC Limited, Reg No 2002/015527/30.
Abbreviation Description
TID Token Identifier
Trf Transformer
TT Token Technology (Token Type)
UI User Interface
URS User Requirements Specification
VAT Value Added Tax
XML eXtensible Markup Language
Group IT Business Requirement Specification (BRS) Online Vending System (OVS) Replacement
Project DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
105
CONTROL TABLE 19.
This table defines what sections of the document need to be completed for the different types of BRS’s.
Section Number
Section Description Change Request
BRS1 BRS2 BRS A
(Analytics) Innovation
Project
2.1 Customer information Y Y Y (Review) Y Y
2.2 Group IT information Y Y Y (Review) Y Y
3 Glossary of terms / definitions Y Y Y (Review) Y Y
4 Business requirements specification focus area Y Y Y (Review) Y Y
5 Reason for the requirement
5.1 Define the current business challenges / issues that need to be addressed
Y Y Y (Review) Y Y
5.2 Define the high level gaps between the “As-Is” and “To-be” business
Y Y Y (Review) Y Y
6 As-is and To-be business process mapping
6.1 As-is business process Y Y Y (Review) Y Y
6.2 To-be business process N N Y (Review) Y Y
7 Business requirements
7.1 High level requirements Y Y Y (Review) Y Y
7.2 Detailed requirements and business rules Y Y Y (Review) Y Y
7.3 Information/data requirements Y Y (Highlevel) Y (Detail) Y (Detail) Y (Highlevel)
7.4 Data flow diagram / Context diagram Y N Y Y N
Group IT Business Requirement Specification (BRS) Online Vending System (OVS) Replacement
Project DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
106
Section Number
Section Description Change Request
BRS1 BRS2 BRS A
(Analytics) Innovation
Project
7.5 Use case diagram N N Y N Y (Optional)
7.6 Legal requirements Y Y Y (Review) Y Y
7.7 Intellectual property Y Y Y (Review) Y Y
8 Reporting requirements
8.1 High level reporting requirements Y Y N Y Y
8.2 Detailed reporting requirements Y Y (Review) Y Y N
9 Non-functional requirements
9.1 User interface requirements N N Y Y N
9.2 System Integration requirements N N Y Y N
9.3 Access requirements Y (Depends) N Y Y Y
9.4 Archiving requirements N N Y N Y
9.5 Disaster recovery N Y Y (Review) Y N
9.6 Business continuity N N Y Y N
10 Out of scope and preconditions
10.1 Define what is out of scope in terms of business requirement elicitation
Y Y (Highlevel) Y (Review) Y Y (Highlevel)
10.2 Define any preconditions and dependencies that impact the business requirement
Y Y (Highlevel) Y (Review) Y Y (Highlevel)
11 Training
11.1 High level training requirements Y N Y Y N
11.2 Possible types of high level training that will be required Y N Y Y N
Group IT Business Requirement Specification (BRS) Online Vending System (OVS) Replacement
Project DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
107
Section Number
Section Description Change Request
BRS1 BRS2 BRS A
(Analytics) Innovation
Project
12 Corporate, divisional and departmental plan alignment
12.1 Business strategy supported Y Y Y (Review) Y Y
12.1.1 Eskom strategic pillar/s that are supported by this requirement
Y Y Y (Review) Y Y
12.1.2 Critical targets that are supported by this requirement Y Y Y (Review) Y Y
12.1.3 Divisional plans supported by this requirement Y Y Y (Review) Y Y
12.1.4 Departmental plans supported by this requirement Y Y Y (Review) Y Y
13 Change request costing Y N N N N
14 Possible options Y N N Y (Depends) N
15 References Y Y Y (Review) Y Y
16 Document acknowledgement Y PDF no
signatures Y Y Y
17 Document approval Y PDF no
signatures Y Y Y
18 Abbreviations Y Y Y (Review) Y Y
19 Control table
Group IT Business Requirement
Specification (BRS) Online Vending System (OVS) Replacement Project
DEM-02737-T6L7
Template Identifier 240-83570075 Rev 4
Authorisation Date 14 May 2018
Review Date December 2021
108
Appendix A – OVS High Level DR Design 20.