Group IT Template Business Requirement Identifier ... D - DEM-02737... · formal documentation, the deliverable(s), of course, and some impacts, which can be positive and/or negative

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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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


Updated the BRS with feedback from the workshop and with the detailed reporting requirements


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


Populate document with final feedback from stakeholders




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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


Bokkie Verwey Customer Services

Business Subject Matter Expert


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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:-

http://www.prepayment.eskom.co.za/xmlvend.asp

http://www.prepayment.eskom.co.za/xmlvend.asp




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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






Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


31


BRS Number


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


32


BRS Number


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)




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


33


BRS Number


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


34


BRS Number


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


35


BRS Number


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…




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


36


BRS Number


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


37



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


38



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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


BRS #


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


BRS #


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

https://hyperwave.eskom.co.za/Eskom/Group%20IT/BUSINESS%20PROCESS%20MANAGEMENT/BPM%20Sections/Customer%20Services/Operational%20records/Demands/Registered/DEM-00812-J0L3%20KRN%20Rollover/KRN%20-%20DEM-00812-J0L3%20-%20GIT%20Project%20User%20Requirements%20Specification%20-%20pre-planning%20-%20final%202%20-%20signed.pdf;internal&action=forcetemplates.action

https://hyperwave.eskom.co.za/Eskom/Group%20IT/PROJECT%20DELIVERY%20DEPARTMENT/Group%20IT%20Projects/Projects%20Operational%20Records/02%20-%20Small%20Projects%20%28Old%20BAU%29/IO100000009257%20-%20OVS%20bulk%20key%20tokens%20functionality%20project/ERA-Execution%20Phase/11-System%20Development%20Lifecycle/01%20-%20Analysis/URS/474-9429%20URS%20Bulk%20KCT%20Ver3_2017.pdf




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


40


BRS #


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


BRS #


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.)

https://hyperwave.eskom.co.za/Eskom/Group%20IT/BUSINESS%20PROCESS%20MANAGEMENT/BPM%20Sections/Customer%20Services/Operational%20records/Demands/Registered/DEM-01730-P8M9_BRS1_OVS%20Business%20Continuity%20%20DR/DEM-01730-P8M9_BRS1_OVS%20Business%20Continuity%20%20DR%20-%20v0.8.4.pdf

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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018


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.


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 45 of 108


Vending Client


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


Vending Client


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.



Vending Client


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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]




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 49 of 108

No transactions are recorded on the Server.


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.


Vending Client


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.


Vending Client


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.



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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.


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.


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


Vending Client




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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.


Vending Agent




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.


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.


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


Vending Client




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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}




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.3. Transaction Listing Per Vendor Report Report name: Detailed Transaction Listing per Vendor (UC009)


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 #




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 60 of 108

Credit Before (R) {Format: 2 Decimal places} : [UNSORTABLE] Credit After (R) {Format: 2 Decimal places} : [UNSORTABLE]

Security: All


Export To Excel Yes

8.2.4. Transaction Summary Report Report name: Transaction Summary per SGC and Transaction Type by Date


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}




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.6. Account Payment Summary Report Report name: Account Payment Summary per Transaction Type by Date


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}




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.7. Vendor Account Statement Report Report name: Vendor Account Statement Report


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)




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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:




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 65 of 108

{ Totals for the columns: No. of Transactions, Total kWh Units, Vendor Debits, Vendor Credits }

Security: All


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


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


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


Description: This Report will display all the details of Vendor’s Credit status.





Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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]




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.12. Last Response Requests Report

Report name: View Last Response Requests per Vendor


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 }




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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


Export To Excel Yes

8.2.14. Customer Transaction Details Report

Report name: View Customer Transaction Details per MSNO




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 69 of 108


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


Export To Excel Yes

8.2.15. Customer Transaction Details Per Account Report



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.16. Unallocated Pending Blocked Customers Report



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


Export To Excel Yes




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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 }




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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)


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


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}




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.21. Meter Not Registered Exception Report

Report name: Meter not Registered Exception Report


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.22. Customer Meter Data Exception Report

Report name: Customer/Meter Data Exception Report


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:




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 77 of 108

No/Invalid Account Number Invalid AT/TT Invalid SGC Invalid TI Invalid TI-SGC combination Invalid BIV Code }

Security: All


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 }




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 78 of 108

Effective Date [SORTABLE]

Security: Admin


Export To Excel Yes

8.2.24. Historic Tariff Status Report

Report name: Historic Tariff Status Report


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


Export To Excel Yes

8.2.25. BIV File Configuration Report

Report name: BIV File Configuration Report


Description: This Report shows the configuration of benefit indicator on the system.

Input Parameters: GL




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.26. Functions To User Mapping Report

Report name: Functions to User Mapping Report


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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


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


Export To Excel Yes

8.2.29. First Issued FBE Reconciliation Report

Report name: First Issued FBE Reconciliation Report


Description: This Report will display all the valid FBE transactions per Vending Agent per month.





Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 82 of 108

Agent Name Date Meter Number Action Performed Parameters for particular action (Parameters to be defined)

Security: All


Export To Excel Yes

8.2.31. Vendor Average Sales Report

Report name: Vendor Average Sales Report


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


Export To Excel Yes

8.2.32. Vendor Credit Movement Report

Report name: Vendor Credit Movement Report


Description: This Report will track the movement of each Vending Agent’s credit on a daily basis.





Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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


Export To Excel Yes

8.2.33. Credit Audit Trail Report

Report name: Credit Audit Trail Report


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 84 of 108

End date selected Report Created on Report Columns: Date Timestamp PSG/Vendor ID, Agent Original Amount Amended Amount

Security: All


Export To Excel Yes

8.2.34. SGC/KRN Detail Report

Report name: SGC/KRN Detail Report


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


Export To Excel Yes

8.2.35. Meter Base Date Summary Report

Report name: Meter Base Date Summary Report


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” }




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 85 of 108

KRN : { KRN 1 and KRN2} Report Columns: Total number of Meters Per SGC Per KRN

Security: All


Export To Excel Yes

8.2.36. Vend Transaction Dashboard for a period

Report name: Vend Transaction Dashboard


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 86 of 108



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


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.


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 87 of 108


7. Manage Client ID’s 7. Can add new client IDs by uploading a client id file that has new ids.


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


Vendor Controller and Operator


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


Operator 7. Reports

7. To run any of the reports on OVS

8. Vendor Credit 8. Read only view

9.1.2. PSG Administrator


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 88 of 108



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.


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


Super User


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


AgentCred, AgentCust and AgentTech





Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





Page 89 of 108


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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:




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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.




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018





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




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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 96 of 108



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 97 of 108



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 98 of 108



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.


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%


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


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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 99 of 108



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%


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


DEM-02737-T6L7_DEM_OVS REPLACEMENT Demand Form

Online Vending Processes ver2.13

Online Vending Reporting Requirements ver2.2

https://hyperwave.eskom.co.za/Eskom/Group%20IT/PROJECT%20DELIVERY%20DEPARTMENT/Group%20IT%20Projects/Projects%20Operational%20Records/02%20-%20Small%20Projects%20%28Old%20BAU%29/IO100000011248%20-%20KRN%20%28STS%29%20Key%20Rollover%20Project/AAA-Pre-Project%20Planning%20Phase/User%20Requirements%20%28BRS%29/KRN%20-%20DEM-00812-J0L3%20-%20GIT%20Project%20User%20Requirements%20Specification%20-%20pre-planning%20-%20final%202%20-%20signed.pdf

https://hyperwave.eskom.co.za/Eskom/Group%20IT/PROJECT%20DELIVERY%20DEPARTMENT/Group%20IT%20Projects/Projects%20Operational%20Records/02%20-%20Small%20Projects%20%28Old%20BAU%29/IO100000009257%20-%20OVS%20bulk%20key%20tokens%20functionality%20project/ERA-Execution%20Phase/11-System%20Development%20Lifecycle/01%20-%20Analysis/URS/474-9429%20URS%20Bulk%20KCT%20Ver3_2017.pdf

https://hyperwave.eskom.co.za/Eskom/Group%20IT/BUSINESS%20PROCESS%20MANAGEMENT/BPM%20Sections/Customer%20Services/Operational%20records/Demands/Registered/DEM-01730-P8M9_BRS1_OVS%20Business%20Continuity%20%20DR/DEM-01730-P8M9_BRS1_OVS%20Business%20Continuity%20%20DR%20-%20v0.8.4.pdf






Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 102 of 108



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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 103 of 108




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




Template Identifier

240-83570075 Rev 4

Authorisation Date

14 May 2018



Page 104 of 108




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




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






106

Section Number


BRS1 BRS2 BRS A


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






107

Section Number


BRS1 BRS2 BRS A


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


Specification (BRS) Online Vending System (OVS) Replacement Project

DEM-02737-T6L7




108

Appendix A – OVS High Level DR Design 20.

Documents

Group IT Template Business Requirement Identifier ... D - DEM-02737... · formal documentation, the deliverable(s), of course, and some impacts, which can be positive and/or negative