opasa vms user guide v1.0

8/8/2019 Opasa Vms User Guide v1.0

1/62

OPASAVMSUserGuideVersion1.0

OPASATeam


2/62

Copyright 2007 Opasa Pvt. Ltd. 2

LEGAL INFORMATIONThe information in this document is subject to change without notice and describes only the product defined in the introductionof this documentation. This document is intended for the use of Opasa VMS customers only for the purposes of the agreementunder which the document is submitted, and no part of it may be reproduced or transmitted in any form or means without the

prior written permission of Opasa. The document has been prepared to be used by professional and properly trained personnel,and the customer assumes full responsibility when using it. Opasa welcomes customer comments as part of the process ofcontinuous development and improvement of the documentation.

Opasa has made all reasonable efforts to ensure that the instructions contained in the document are adequate and free ofmaterial errors and omissions. Opasa will, if necessary, explain issues which may not be covered by the document.

Opasas liability for any errors in the document is limited to the documentary correction of errors. Opasa WILL NOT BERESPONSIBLE IN ANY EVENT FOR ERRORS IN THIS DOCUMENT OR FOR ANY DAMAGES, INCIDENTAL OR CONSEQUENTIAL (INCLUDINGMONETARY LOSSES), that might arise from the use of this document or the information in it.

This document and the product it describes are considered protected by copyright according to the applicable laws.

Other product names mentioned in this document may be trademarks of their respective companies, and they are mentioned foridentification purposes only.

CopyrightOpasaSolutionsPvt.Ltd.2007.Allrightsreserved.


3/62


TableofContents1 Introduction.......................................................................................................................................... 7

2 Acronyms.............................................................................................................................................. 7

3 Systemfunctionality............................................................................................................................. 8

3.1 Architecture.................................................................................................................................. 8

3.2 3rdpartysoftware.......................................................................................................................... 8

3.3 Provider......................................................................................................................................... 9

3.3.1 Attributes.............................................................................................................................. 9

3.3.2 Lifecycle............................................................................................................................... 9

3.4 Distributor..................................................................................................................................... 9

3.4.1

Attributes............................................................................................................................

10

3.4.2 Lifecycle............................................................................................................................. 11

3.5 Product........................................................................................................................................ 11

3.5.1 Attributes............................................................................................................................ 11

3.5.2 Lifecycle............................................................................................................................. 12

3.6 Order........................................................................................................................................... 12

3.6.1 Attributes............................................................................................................................ 12

3.6.2 Lifecycle............................................................................................................................. 13

3.7 Batch........................................................................................................................................... 13

3.7.1 Attributes............................................................................................................................ 13

3.7.2 Lifecycle............................................................................................................................. 14

3.8 Voucher....................................................................................................................................... 14

3.8.1 Attributes............................................................................................................................ 14

3.8.2 Lifecycle............................................................................................................................. 15

3.9 PINgeneration............................................................................................................................ 15

3.10

VMSentity

relationship

..............................................................................................................

16

3.11 ProcessSequence........................................................................................................................ 16

3.11.1 BatchVoucherGeneration.................................................................................................. 16

3.11.2 SingleVoucherGeneration................................................................................................. 17

3.12 Jobs............................................................................................................................................. 18


4/62


3.12.1 GenerateBatchVoucher.PL.................................................................................................. 18

4 Databasemodel.................................................................................................................................. 19

5 Systemconfiguration.......................................................................................................................... 21

5.1 Systemparameters..................................................................................................................... 21

5.2 Environmentvariables................................................................................................................ 22

5.3 DataSource................................................................................................................................. 22

6 Systeminstallation.............................................................................................................................. 23

6.1 Step1.......................................................................................................................................... 24

6.2 Step2.......................................................................................................................................... 25

6.3 Step3.......................................................................................................................................... 25

6.4 Step4.......................................................................................................................................... 25

6.5

Step5..........................................................................................................................................

26

6.6 Step6.......................................................................................................................................... 26

6.7 Step7.......................................................................................................................................... 26

6.7.1 VerifyVMSUIandApacheAxis........................................................................................... 26

6.7.2 VerifyVMSWebservices.................................................................................................... 27

6.8 ImportantURLs........................................................................................................................... 28

7 Operationalconsideration.................................................................................................................. 28

8 Webservicesinterface........................................................................................................................ 29

8.1 Singlevoucher............................................................................................................................. 29

8.2 Batchvoucherrequest................................................................................................................ 30

8.3 Validatevoucher......................................................................................................................... 31

8.4 Getvoucherdetail....................................................................................................................... 32

8.5 Updatevoucherstatus................................................................................................................ 33

9 Filebasedinterface............................................................................................................................. 34

9.1 Voucherfile................................................................................................................................. 34

9.1.1

Filenaming

convention

.......................................................................................................

35

9.1.2 Fileformat........................................................................................................................... 36

10 UserInterface................................................................................................................................. 39

10.1 URL.............................................................................................................................................. 39

10.2 Browserspecification.................................................................................................................. 39

10.3 Popupblockers.......................................................................................................................... 39


5/62


10.4 Mainscreenlayout...................................................................................................................... 41

10.5 NavigationBar............................................................................................................................. 42

10.6 Adddistributorscreen................................................................................................................ 42

10.6.1 Layout.................................................................................................................................. 42

10.6.2 Description.......................................................................................................................... 43

10.6.3 Navigationpath................................................................................................................... 45

10.7 Modifydistributorscreen........................................................................................................... 45

10.7.1 Layout.................................................................................................................................. 46

10.7.2 Description.......................................................................................................................... 46

10.7.3 Navigationpath................................................................................................................... 48

10.8 Removedistributorscreen.......................................................................................................... 49

10.8.1

Layout..................................................................................................................................

49

10.8.2 Description.......................................................................................................................... 49

10.8.3 Navigationpath................................................................................................................... 49

10.9 Requestsinglevoucherscreen................................................................................................... 49

10.9.1 Layout.................................................................................................................................. 50

10.9.2 Description.......................................................................................................................... 50

10.9.3 Navigationpath................................................................................................................... 51

10.10 Requestbatchvouchersscreen.............................................................................................. 51

10.10.1 Layout.............................................................................................................................. 52

10.10.2 Description...................................................................................................................... 52

10.10.3 Navigationpath............................................................................................................... 54

10.11 Providerdetailscreen............................................................................................................. 54

10.11.1 Layout.............................................................................................................................. 54

10.11.2 Description...................................................................................................................... 55

10.11.3 Navigationpath............................................................................................................... 56

10.12

Productdetail

screen

..............................................................................................................

56

10.12.1 Layout.............................................................................................................................. 56

10.12.2 Description...................................................................................................................... 56

10.12.3 Navigationpath............................................................................................................... 58

10.13 Orderdetailscreen................................................................................................................. 58

10.13.1 Layout.............................................................................................................................. 58


6/62


10.13.2 Description...................................................................................................................... 59

10.13.3 Navigationpath............................................................................................................... 60

11 Troubleshooting.............................................................................................................................. 60

11.1 Logfiles....................................................................................................................................... 60

11.2 Errorcodesandmessages.......................................................................................................... 60

12 Changes........................................................................................................................................... 62


7/62


8/62


3 Systemfunctionality3.1 Architecture

3.2 3rd party softwareFollowing3rdpartysoftwareproductsandcomponentsareusedinVMS:

Oracle 10gR2

SunJava1.4.2_08

RedHatLinux3.0+

HTMLversion4.0

JavaApplicationServer ApacheTomcatv5.0

JDBCversion3.0(Thin)

Spring(Javaframework)v2.0

Web server

VMS database

Stored procedures

VMS Web services

Apache Tomcat

Application server

VMS UI

VMS GUI(Web browser)

3rd partyWeb services c lient

Webservice call

GenerateBatch.pl

Batch voucherfile(s) fordistributors

3rd partysystem

Fig: Overall architecture

Confidential & Proprietary


9/62


ApacheAxisv1.4

3.3 ProviderAProvideristheentitywhichprovidesthevouchermanagementinfrastructure. AProvidersetsupthe

VMSsystem

and

will

have

Distributors

associated

with

it.

E.g.say,anorganizationXYZdecidestosetupaVMSsystemandenableoneormorevendorstobeable

torequesttheXYZorganizationtogeneratethevouchersandsendthemtotheindividualrequesting

vendor.Inthiscase,XYZwillbesetupasProviderintheVMSsystem.

OPASAVMSismodeledinawaythatitsupportstheMVNEandMVNObusinessmodel.Typically,a

MVNEinstallstheVMSproductandwillhaveoneormoreMVNOs.EachMVNOwill,further,haveone

ormoredistributorsassociated.OPASAVMSprovidesamechanismtotheMVNEtosetupitsMVNOs

asProviders.EachdistributoroftheMVNO/ProviderissetupasDistributorinthesystem.

EachMVNE

can

install

one

or

more

instances

of

OPASA

VMS.

Each

VMS

instance

can

have

one

or

more

Providers(orMVNOs)setup.EachProvidercanhaveoneormoreDistributors.

OPASAVMSalsoprovidestheflexibilitytosetupaProviderasaDistributor.Thisisusefulinthe

businessmodelwhereaProviderhasoneormoredistributorswhorequestforthevouchersandalso,

theprovideritselfrequestsvouchersandsellsthem.

3.3.1 AttributesFollowingaretheattributesofaProviderinOPASAVMSsystem:

NameProvidernameneednotbeuniqueinthesystem.

Description

A

Provider

description

gives

more

detail

about

the

Provider.

Addressdetail

ContactnumberWhilesettingupaProvidertheprimarycontactnumberoftheProviders

representativecanbeadded.Thiscanbeused(byMVNE,e.g.)tocontacttheProviders

concernedperson,ifneeded.

Email WhilesettingupaProvidertheemailaddressoftheProvidersrepresentativecanbe

added.Thiscanbeused(byMVNE,e.g.)tocontacttheProvidersconcernedperson,ifneeded.

3.3.2 Life-cycleAProvider,oncecreated,alwaysremainsactiveintheOPASAVMSsystem.

3.4 DistributorADistributorisanentity,whichrequeststhevoucherstobeissuedfromoneormoreProviders.


10/62


E.g.say,avendorABCcontactstheorganizationXYZanddecidestousethevouchermanagement

serviceofXYZ.Inthiscase,ABCwillbesetupasaDistributorintheVMSsystemandwillberelatedwith

theProviderXYZ.

ADistributorisalwaysassociatedwithaProvider.OPASAVMSallowsmanytomanyrelationship

betweenProvides

and

Distributors.

One

Distributor

can

be

associated

with

one

or

more

Providers

and

oneormoreDistributorscanbeassociatedwithoneProvider.ADistributorisalwaysaddedata

ProviderlevelandhenceDistributorsarenotsharedacrossProviders.Ifsamedistributorneedstobe

associatedwithmultipleproviders,theDistributormustbeaddedtoeachProvider,individually.

3.4.1 AttributesFollowingaretheattributesofaDistributorinOPASAVMSsystem:

NameDistributornameneednotbeuniqueinthesystem.

DescriptionADistributordescriptiongivesmoredetailabouttheDistributor.

Addressdetail

ContactnumberWhilesettingupaDistributortheprimarycontactnumberoftheDistributors

representativecanbeadded.Thiscanbeused(byMVNO,e.g.)tocontacttheDistributors

concernedperson,ifneeded.

Email WhilesettingupaDistributortheemailaddressoftheDistributorsrepresentativecan

beadded.Thiscanbeused(byMVNO,e.g.)tocontacttheDistributorsconcernedperson,if

needed.

VoucheralgorithmOPASAVMSallowstheusertoassociateavoucheralgorithm(e.g.

algorithmtogenerate10digitvouchers)toaDistributor. Togeneratevouchersfora

distributor,thealgorithmassociatedwithitisused.Atanygiveninstanceoftime,onlyone

algorithmcanbeassociatedwithadistributor.OPASAVMSallowstheusertochangethe

algorithmforadistributor,ifneeded.

CreditlimitForeachdistributor,OPASAVMSallowstheusertospecifythemonetarycredit

limit.Thiscreditlimitisusedwhilegeneratingvouchersforthedistributortocheckwhetherthe

distributorhassufficientcredit.Incaseofinsufficientcredit,theOPASAVMSsystemdoesnt

generatethevouchersforthatdistributor.TheVMSsystemnotifiesaboutthiseventwhenan

orderisbeingplaced.

o Incaseofsinglevoucherrequest,OPASAVMSprocessestherequestonlyifthe

requestedvoucherdenominationis


11/62


3.4.2 Life-cycleFollowingdiagramshowsthelifecycleofaDistributorinOPASAVMSsystem:

ADistributorisremovedfromtheVMSsystemafteritiseitherdeletedorpurgedbythepurgingjob.

3.5 ProductAProductisanentity,whichrepresentsaproductbeingsoldbyadistributor.OPASAVMSallowsthe

usertoaddproductsattheProviderlevelaswellasattheDistributorlevel.TheProductsaddedatthe

ProviderlevelarevisibletoalltheDistributorsofthatProvider.TheProductsaddedattheDistributor

levelarevisibleonlytothatDistributor.

E.g.say,aDistributorD1issellingaProductP1anddoesnotwantanyotherDistributorD2ofthesame

ProvidertoviewitsProduct.Inthiscase,theProductP1willbeaddedtheDistributorD1level,notat

theProviderlevel.

AProductmustbesetupintheVMSsystembeforeplacingavoucherrequest.

3.5.1 AttributesFollowingaretheattributesofaProductinOPASAVMSsystem:

NameProductnameneednotbeuniqueinthesystem.

DescriptionAProductdescriptiongivesmoredetailabouttheProduct.


12/62


FacevalueThisisthedenominationoftheproduct.E.g.ifvouchersofdenomination$100

needstobegenerated,aproductmustbeconfiguredwithfacevalueof$100

TalkvalueThisisthenettalkvalueoftheproduct.E.g.avoucherwith$100denominationmay

haveatalkvalueof$95.$5maygotowardsservicecharges,taxes,etc.OPASAVMSallowsthe

usertostorethetalkvalueofaproduct,separately.Thisisaninformationalattributeandmust

bespecified

by

the

user

while

adding

aproduct

into

the

VMS

system.

ServicechargeOPASAVMSprovidesaproductattributetostoretheservicechargewhichis

applicabletoaproduct.Thisisaninformationalattributeandcanbespecifiedbytheuserwhile

addingaproductintotheVMSsystem.

TaxOPASAVMSprovidesaproductattributetostorethetaxwhichisapplicabletoa

product.Thisisaninformationalattributeandcanbespecifiedbytheuserwhileaddinga

productintotheVMSsystem.

StartdateEveryproductmusthaveadateonwhichtheproductbecomeseffectiveand

voucherscanberequestonitfromthatday.Theattributeallowstheusertospecifythe

effectivedateofaproduct.

EnddateThisattributeallowsusertorestrictthevalidityofaproduct.Ifauserspecifiesa

particularenddate,theproductexpiresonthatdateandnovoucherscanbegeneratedforit.If

noenddateisspecified,theproductneverexpires.

ValidityextensionOPASAVMSallowstheusertospecifythedurationbywhichtheaccount

creditexpiryneedstobeextended,inthebillingsystem.Thiscanbespecifiedindays,months

oryears.

3.5.2 Life-cycleAproduct,oncecreated,remainsintheVMSsystem.Iftheenddateisspecified,theproductexpires

afterthatdate.Otherwise,itremainsactive.

3.6 OrderAnOrderisanentity,whichiscreatedforaparticularDistributorandaProviderandisplacedbythe

DistributorintheVMSsystem.AnOrderisplacedbytheDistributortorequesttheVMSsystemto

generateasinglevoucherinrealtimeorbulkvouchersinbatches.Forbulk/batchvoucherrequest,an

Orderwillcontainoneormorebatchdetailintoit.

E.g.say,theDistributorABCwantstoget10,000vouchersgeneratedforProductP1and5,000vouchers

forProductP2.Inthiscase,theDistributorwillplaceanOrdertotheVMSsystemforProductP2,which

willhave2entriesforbulk/batchvoucher.


DescriptionAnorderdescriptiongivesmoredetailaboutanOrder

ProviderTheattributestorestheProvidertowhichtherequestingDistributorisassociated

with

DistributorTheattributestorestheDistributorwhohasplacedthevoucherorder


13/62


RequestindicatorAnindicatorshowingwhethertheorderisforasinglevoucherorforabatch

voucher

3.6.2 Life-cycleInOPASAVMS,anOrderexpiresafterthevouchersaregeneratedforit.Incaseofsinglevoucher

request,the

Order

expires

after

avoucher

is

generated

and

information

is

returned

back

to

the

user.

In

caseofbatchvoucherrequest,theOrderexpiresafterallthebatches,relatedtotheOrder,are

processedsuccessfully.

3.7 BatchABatchisanentity,whichispartofanOrderwhenaDistributorplacesabulk/batchvoucherrequest.

E.g.inthepreviousexample,whentheDistributorplacestheOrderforthegenerationof10,000

vouchersforProductP1and5,000vouchersforProductP2,2BatcheswillbecreatedintheVMS

system.Batch#1willbecreated,togenerate10,000vouchersforProductP1,andBatch#2willbe

created,togenerate5,000vouchersforProductP2.

OPASAVMSdoesnotallowtheusertodeleteaBatchfromthesystem,oncecreated.


DescriptionAbatchdescriptiongivesmoredetailaboutanBatch

OrderTheOrderwhichconstitutesofthisBatch

StatusStoresthecurrentstatusoftheBatch.SeetheLifecyclesectionfordifferentstatuses

andthevalidtransitions

DenominationThisattributeindicatesthedenominationofthevouchersintheBatch

NumberofvouchersThisattributeindicatesthenumberofvoucherstobegeneratedinthe

Batch

ExpirydateThisattributeindicatestheexpirydateofthevouchersintheBatch.Allthe

vouchersgeneratedfortheBatchwillexpireonthespecifieddate


14/62


3.7.2 Life-cycleFollowingdiagramshowsthelifecycleofaBatchinOPASAVMSsystem:

3.8 VoucherAVoucherisanentity,whichisgeneratedaspartoftheOrderplacedbyaDistributorofaProvider.A

singlevoucherisgenerated,inrealtime,whenaDistributorplacesanOrderforasinglevoucher.

Multiplevouchersaregenerated,inBatch,whenaDistributorplacesanOrderforbulkvouchers.

E.g.inthepreviousexample,when2Batchesarecreatedtogenerate10,000and5,000vouchersfor

ProductsP1andP2,respectively,theVMSsystemwillgeneratetheVouchersinthesystemforthe

Distributor.

3.8.1 AttributesFollowingaretheattributesofaVoucherinOPASAVMSsystem:

ProductThisattributeindicatestheProductforwhichthevoucherisgenerated

ProviderThisattributeindicatestheProviderforwhichthevoucherisgenerated

DistributorThisattributeindicatestheDistributorforwhomthevoucherisgenerated

Order ThisattributeindicatestheOrderforwhichthevoucherisgenerated

Batch ThisattributeindicatestheBatchforwhichthevoucherisgenerated.Thisattributewill

notcontainanythingforavouchergeneratedaspartofsinglevoucherrequest


15/62


PINnumberRandomuniquePINnumbergeneratedforthevoucher

Serialnumber

Expirydate Thisattributeindicatestheexpirydateofthevoucher.Thisiscalculatedbasedon

theexpirydatespecifiedbytheuserwhileplacingavoucherrequest.Ifnodateisspecifiedby

theuser,OPASAVMSusesasystemparametertocalculatetheexpirydate

Activationdate

Date

on

which

the

voucher

is

activated

3.8.2 Life-cycleFollowingdiagramshowsthelifecycleofavoucherinOPASAVMS:

3.9 PIN generationVMSsupportsmultiplealgorithmstogeneratePINs.Thealgorithmdiffersbasedonthepinlength.By

default,VMSprovideanalgorithmtogenerate10digitpins.Thealgorithmguaranteesthatthe

generatedpinnumbersareuniqueandrandom.


16/62


Theselectionofwhatalgorithmtobeusedisatthedistributorlevel.OntheAdddistributorscreenof

VMSUI,usercanselectthealgorithm,whichwillbeapplicabletothatdistributor.Thepinnumberswill

begeneratedbasedonthealgorithmattachedtothedistributor.

3.10VMS entity relationship

Followingdiagram

shows

how

the

different

OPASA

VMS

entities

(e.g.

Provider,

Distributor,

Product,

etc.)arerelatedwitheachotherandwhatkindofrelationshipexistsbetweenthem:

3.11Process Sequence

3.11.1BatchVoucherGenerationIntheBatchVoucherGenerationscenario,aProvider,first,issetupinthesystem.ForaProvider,a

Distributorisselected.TheDistributorselectsaProductandplacesanordertotheVMS,whichcreates

batchintotheVMSsystem.ThesebatchesareprocessedandtheVouchersaregenerated.

Thefollowingdiagramshowstheentityrelationshipforthebatchvouchergenerationscenario:

System (MVNE) Provider (MVNO/tenant) Distributor

Product

BatchVoucher

PIN

Algorithm

1.....n m.....n

1....1

1....n

1....n

n....1

1....1

1....n

Relationships:

1...1 - one-to-one1...n one-to-manym...n many-to-many


17/62

`

Followin

Step1

Step2

Step3

Step4

Step5

Step6

3.11.2 SIntheSin

Distribut

Voucher

Thefollo

stepsarein

Onth

Onth

Clicko

Follo

Clicko

Gener

vouch

ingleVouchgleVoucher

risselected.

ortheorder

ingdiagram

olvedinthe

VMSUIpag

Requestba

nAddtoord

step3toad

nPlaceorde

ateBatchjob

erfilesfordi

erGeneratienerations

TheDistribu

placed.

showsthe

e

Batch

Voucher

opyright

batchvouch

e,clickonRe

chvoucher

erbuttonto

dmorebatc

rbutton

processesth

tribution

onenario,aPr

torplacesan

tityrelation

Pr

O

007 Opasa

rgeneration

questVouch

creen,speci

addthebatc

estotheor

eorderand

vider,first,i

ordertothe

shipfor

the

s

vider

rder

Pvt. Ltd.

process:

er >Batch

ytherequir

htotheorde

er

llthebatche

setupinth

VMS.TheV

inglevouche

Distributor

Product

dvalues

r

swithinand

system.For

Ssystemge

rgeneration

17

createsbatc

aProvider,a

neratesthe

scenario:


18/62

Followin

Step1

Step2

Step3

3.12JoThissecti

3.12.1GTheGenevoucher

service.

batchesi

transacti

thebatch

request.

manyvou

voucherc

However,csvfilesa

ifbatchs

T

B

stepsarein

Onth

Onth

Clicko

detail

s

ndescribes,

enerateBatrateBatchV

rders.These

heneveran

CREATEDst

nsothatsa

eswhichhav

ncethevou

chersexisti

reationasw

ifany

of

the

redeletedfr

atusupdate

isjobcreate

TCH_JOB_L

olvedinthe

VMSUIpag

Requestsin

nGenerate

onthescree

indetail,var

chVoucher.ucherjobis

ordersareei

ewbatchisc

atusatthis

ebatchwill

ebeenputin

chersforthe

abatchand

llascsvfile

mfails

then

t

mthefilesy

itselffails,t

salogfilein

G_DIR.The

Ord

Voucher

opyright

singlevouch

e,clickonRe

glevoucher

oucherbutt

iousjobsVM

PLdesignedtothercreated

reated,itwill

omentand

notbepicke

toRUNNING

batcharecr

howmanyr

succeedsthe

heuncommi

stemandba

enbatchwil

thedirectory

logfilename

Provide

er

007 Opasa

rgeneration

questVouch

screen,speci

n.VMSgen

Ssystemha

hecktheba

fromtheV

beputinto

ovesthem

dupbymore

statusbyth

ated,thejo

cordscane

nthebatchs

ttedtransact

tchstatuswil

lbeleftinR

configured

formatisBa

Distr

Product

Pvt. Ltd.

process:

er >Single

ytherequir

ratesthevo

toaccompli

chtablefor

SUIorusin

REATED(1)

otheRUNNI

thanonein

job,itcreat

createsone

istinasingl

tatusismov

ionis

rolled

lbeupdated

NNINGstat

yenvironm

tchLogs__

18

playsthevo

nality.

ofnewbatc

hVoucherW

breadsthe

dcommitst

samejob.Fo

orthebatch

pendingonh

s).Ifbatch

TED(4)stat

eeded,relat

status.How

current

cher

b

e

rall

ow

s.

ed

ver,


19/62


time>.LOG.ItcontainsinformationaboutalltheVoucherIDandBatchIDbeingprocessedduringthis

run.Incase,thisjobexitswithnonzeroexitstatus,theoperatormustlookintothelogfileto

understandthereasonforfailure.

TheCSVfileswillbecreatedintoadirectoryconfiguredbythesystemparameter,

BATCH_FILE_OUTPUT_FOLDER.The

job

assumes

that

the

operator

has

ensured

that

adirectory

existunderthisoutputfolderforeverydistributor.Thisdirectorynameshouldbesameasdistributor

nameintheVMSsystems.

Followingcommandmustbeexecutedontheshellprompttorunthejob:

$> nohup ./GenerateBatchVoucher_V1.1.PL

Followingcommandmustbeexecutedontheshellprompttostopthejob:

$> kill -9 ./GenerateBatchVoucher_V1.1.PL

4 DatabasemodelFollowingdiagramshowstheVMSdatamodel.ItshowstheVSMentitiesandhowtheyarerelated.


20/62


21/62

5System

configuration

ThissectiondescribesthedifferentsystemconfigurationinformationusedbyVMS.

5.1 System parametersVMSprovidesmanysystemparameters,whichdriveitsfunctionality.EveryinstallationofVMSproduct

comeswithdefaultvaluessetfortheseparameters.Theseparameterscanalsobemodifiedforeach

implementationoftheVMSproduct.

Followingsystemparametersareavailable:

Parametername Description Defaultvalue

BATCH_FILE_OUTPUT_FOLDER

Pathwhere

the

batch

voucher

files

will

be

created

Thisparametervaluemaybechanged

basedontheVMSinstallationand

operationalneeds

/tmp/batch/output

BATCH_OUTPUT_FILE_EXTN Fileextensiontobeusedforthebatch

voucherfilename(e.g.VMS_109_1.csv)

csv

MAX_RECORDS_IN_BATCH_FILE Maximumnumberofpinsstoredinonebatchvoucherfile

50000

PURGING_PERIOD PurgingperiodY

in

Years

MinMonths

DinDays

5Y

VOUCHER_VALIDITY_PERIOD PeriodforwhichavoucherwillbevalidYinYears

MinMonths

DinDays

90D

BATCH_FILE_NAME_DELIM Delimiterusedinthebatchvoucherfiletoseparatetwovalues

,

(comma)

TheabovelistedsystemparametersarestoredinSYSTEMPARAMSREF tableofVMSschema.The

appropriatesupportandoperationsstaffmustbeconsultedinordertochangethevalues.

Changingthesystemparameterrequiresrestartingofthefollowing:

ApacheTomcatserver

GenerateBatchVoucher.PLjob


22/62


5.2 Environment variablesVMSusesmanyenvironmentvariables,whichdriveitsfunctionality.TheVMSinstallationprocesssets

theseenvironmentvariables.Thesevariablesvaluecanalsobemodifiedforeachimplementationof

theVMSproduct.

Followingenvironment

variables

are

available:

Variablename Description Defaultvalue

TWO_TASK Oracledatabasename None

Mustbeset

duringtheVMS

installationDB_USER_NAME UsernametoconnecttoVMSdatabase None

Mustbeset

duringthe

VMS

installationDB_PASSWORD PasswordtoconnecttoVMSdatabase None

Mustbeset

duringtheVMS

installationBATCH_JOB_LOG_DIR DirectorywheretheGenerateBatchjobcreatesthe

logfiles

None

Mustbeset

duringtheVMS

installationBATCH_JOB_RUN_FREQUENCY TimetheGenerateBatchjobwillwaitbefore

continuingthenextcycle

120minutes

Appropriatesupportandoperationsstaffmustbeconsultedinordertochangethevalues.

Changingtheenvironmentvariablesrequiresrestartingofthefollowing:

GenerateBatchVoucher.PLjob

5.3 Data Source

VMSuses

the

data

source

created

by

the

Apache

Tomcat

server.

Following

default

configuration

informationfortheDatasourceisspecifiedinthe

\conf\Catalina\localhost\axis.xmlfile:

factory


23/62


org.apache.commons.dbcp.BasicDataSourceFactory

maxWait

30000

maxActive

50

password

password

url

jdbc:oracle:thin:@localhost:1523:vmstestdb

driverClassName

oracle.jdbc.driver.OracleDriver

maxIdle

10

username

vmsuser

AreferencetotheVMSDatasourceisspecifiedinthe\axis\WEBINF\web.xmlfile

jdbc/vmsdb

javax.sql.DataSource

Container

ChangingtheDatasourceconfigurationrequiresrestartingofthefollowing:

ApacheTomcatserver

6 SysteminstallationInstallationofthefollowingsoftwareproductsandcomponentsareoutofscopeforthis

document:

RedHatLinux

SunJDK


24/62


Oracle10gdatabaseserver

ApacheTomcatserver

Perl

VMSapplicationisdeliveredasaVMS.tar.gzfile.Thiscompressedarchivecontainsalltherequired

andnecessary

files

for

installing

and

running

VMS

application.

FollowingstepsneedstobefollowedtoinstalltheOPASAVMSapplication:

6.1 Step 1Let'ssayuserhaschosen/usr/share/vmsastheinstallationfolder.Throughoutwe'llreferthisfolderas

VMS_INSTALL.

ExtractVMS.tar.gzfileinVMS_INSTALLfolderbyrunningthefollowingcommands:

gunzip VMS.tar.gz

tar -xvf VMS.tar

Thiswillcreatethefollowingfolders:

|___installvms

/axis

/lib

/vms

|___VMSSP.jar

|___VMSWS.jar

|___VMSUI.war

|___CREATE_VMSUSER.sql

|___CREATE_VMSSCHEMA.sql

|___CREATE_VMSREFDATA.sql

|___CREATE_VMSTRIGGER.sql

|___CREATE_GENERATEBATCHPROC.sql

|___GenerateBatch.pl

|___deployvms


25/62


|___undeployvms

6.2 Step 2Goto/vmsfolder.

Connect

to

Oracle

database

using

sqlplus

(or

any

other

tool

of

your

preference,

which

allows

you

to

runDDLandDMLstatements)andruntheCREATE_VMSUSER.sqlbyenteringthefollowingcommandat

thesqlplusprompt:

SQL> @CREATE_VMSUSER

ThiswillcreatetheVMSuserwiththenecessaryandsufficientpermissions.

6.3 Step 3LogoutfromsqlplusandreloginusingtheVMSuser,createdinthepreviousstep.

Onthesqlplusprompt,runtheCREATE_VMSSCHEMA.sqlandCREATE_VMSREFDATA.sqlbyentering

thefollowingcommands:

SQL> @CREATE_VMSSCHEMA

SQL> @CREATE_VMSTRIGGER

SQL> @CREATE_VMSREFDATA

SQL> @CREATE_GENERATEBATCHPROC

ThiswillcreatethedatabaseschemaforVMS,populatesthereferencedataofVMS,andcreatesthe

storedprocedurefortheGenerateBatch.pl.

6.4 Step 4ExitfromsqlplusandrunthefollowingcommandtostarttheVMSinstallation:

$>./installvms

Thisisaninteractivescript.Followtheinstructionstoproceedwiththeinstallation.

Thiswillchecktheprerequisites,databaseconnectivity,installsApacheAxis,copiestheVMSfilesinthe

VMS_HOME(specifiedbytheuserduringtheinstallation)folder,andcreatesasetvmsenvfile,which

containsthescripttosettherequiredenvironmentvariablesandtheCLASSPATH.

Theinstallercreatesthefollowingfoldersinthe$VMS_HOME:

vms containsalltheVMSfiles

lib containsallthe3rdpartyjarsVMSuses

bin containsalltheVMSexecutables

logs usedforcreatingthelogfilesbytheexecutables


26/62


6.5 Step 5GototheVMSinstalledfolderandsourcetheenvironmentscriptbyrunningthefollowingcommands

onthecommandprompt:

$> cd $VMS_HOME

$> . setvmsenv

ThiswillsetalltherequiredenvironmentvariablesandtheCLASSPATH.

6.6 Step 6Goto'bin'folderandruntheVMSdeployerbyrunningthefollowingcommand:

$> ./deployvms

Thiswillinstallanddeploythefollowing:

VMSstored

procedures

VMSWebservices

VMSUI

6.7 Step 7VerifyontheTomcatadminscreenthattheVMSUIandVMSWebservicesapplicationsaredeployed.

6.7.1 VerifyVMSUIandApacheAxisEnterthefollowingURLinthebrowsertoverifythattheVMSUIandApacheAxisaredeployedandare

running:

http://127.0.0.1:8080/manager/html/list

SpecifytheTomcatmanagerusernameandpassword,whenprompted.

Replace127.0.0.1withtheIPaddressormachinenamewhereTomcatserverisrunning.

Replace8080withtheportnumberwhereTomcatserverisrunning.


27/62

6.7.2 VEnterthe

h

Specifyth

RR

erifyVMSfollowingU

ttp://127.0.0

eTomcatm

eplace127.0

eplace8080

ebserviceLinthebro

.1:8080/axis

nagerusern

.0.1with

the

iththeport

opyright

sertoverify

servlet/Axis

ameandpas

IPaddress

o

numberwh

007 Opasa

thattheVM

ervlet

sword,when

machine

na

reTomcats

Pvt. Ltd.

Webservic

prompted.

ewhere

To

rverisrunni

saredeploy

mcatserver

i

ng.

27

ed:

srunning.


28/62

6.8 I U

h

e

U

h

p

7 Op

I

d

Followin

A

R

portant U

RLtoaccess

ttp://::/axis/

/VMS.htm

mponentsa

gingthe

VM

llrequireres

gthefollowi

services/

reoutofsco

Sapplication

tartingthefo

ng:

28

VMS

peforthis

:

llowing:


29/62


Changingthedatabaseconnectivityinformation(machine/portnumber/databasename/user

name/password/etc.changes)willrequirethefollowingtobemodified:

o \conf\Catalina\localhost\axis.xmlfile

o TWO_TASKenvironmentvariableifthedatabaseURLischanged

o DB_USER_NAMEenvironmentvariableiftheusernameischanged

o DB_PASSWORDenvironment

variable

if

the

password

is

changed

8 WebservicesinterfaceThissectiondescribestheWebserviceinterfaceindetail.ItdescribestheservicesexposedbyVMS,the

parameterdetailsandtherulesrelatedtoeachoftheservices,ifany.

8.1 Single voucherVMSprovidesaWebservice,whichallowsthecallertorequestasinglevoucherfromVMS.TheWeb

serviceplacesanorderintheVMS,whichgeneratesavoucherandreturnstheinformationaboutthe

newlygenerated

voucher

to

the

caller.

The

voucher

generation

is

in

real

time.

VMSprovidesthefollowingWebservicetorequestforasinglevoucher:

VoucherData requestSingleVoucher( int voucherProductId,

int providerId,

int distributorId,

double voucherDenomination,

String orderDesc,

Calendar voucherExpirationDate)

Inputparametersummary

Parameter

Description

Mandatory?

voucherProductId Idoftheproductforwhichavoucheristobe

generated

Yes

providerId Idoftheproviderwhosedistributorisplacingthe

request

Yes

distributorId Idofthedistributorwhoisplacingtherequest YesvoucherDenomination Voucherdenomination

e.g.$39.99

Yes

orderDesc Descriptionoftheorderbeingplaced YesvoucherExpirationDate Dateonwhichthevoucherwillexpire

Ifthe

caller

does

not

specify

this

parameter

value,

VMSreadstheconfigured

VOUCHER_VALIDITY_PERIODsystemparameterand

calculatesthevoucherexpirydate

e.g.thecallerdoesnotspecifythisparametervalue

andiftheVOUCHER_VALIDITY_PERIODsystem

parametervalueisconfiguredas90DthentheVMS

No


30/62


calculatedexpirydatewillbe:

todaysdate+90days

Outputparametersummary

Parameter DescriptionVoucherData Informationaboutthenewlygeneratedvoucher

FollowinginformationispartoftheVoucherData:

serialnumber

pinnumber

denomination(facevalue)

talkvalue

servicecharge

taxamount

expirydate

distributorid,forwhomthevoucherwasgenerated

distributordescription,forwhomthevoucherwasgenerated

batchid,partofwhichthevoucherwasgenerated

Incaseasinglepinwasrequestedbycallingtheabove

mentionedWebservice,thismethodwillreturn0,which

meansthevoucherwasnotgeneratedaspartofabatch

request

batchdescription

uniqueidentifierorderididentifyingtheorder,whichisplaced

bythedistributor

orderdescription

8.2 Batch voucher requestVMSprovidesaWebservice,whichallowsthecallertoplacearequestforbatchvouchergeneration

fromVMS.TheWebserviceplacesanorderintheVMSandreturnstheinformationaboutthenewly

generatedorderidtothecaller.Thevouchergenerationmodeisbatch.

VMSprovidesthefollowingWebservicetoplacearequestforbatchvouchergeneration:

long requestBatchVoucher( int providerId,

int distributorId,

BatchData[] batchRequests,

String orderDesc)


Parameter Description Mandatory?

providerId Idoftheproviderwhosedistributorisplacingthe Yes


31/62


requestdistributorId Idofthedistributorwhoisplacingtherequest YesbatchRequests AnarrayofBatchData.Eachelementrepresentsa

batchinformarion,like,theproductforwhichthe

batchrequestisbeingplaced,thedenomination,

number

of

vouchers,

etc

Thearraymustcontainatleastoneentry

BatchDatawillhavethefollowingdetail:

idoftheproductforwhichavoucherbatch

requestisplaced

descriptionidentifyingabatch

numberofvouchersinabatch

denominationofthevouchersinabatch

expirydateofthevouchersinabatch

Yes

orderDescDescription

of

the

order

being

placed

Yes


TheWebservicereturnstheuniqueidentifieridentifyingthenewlyplacedorder.

8.3 Validate voucherVMSprovidesaWebservice,whichallowsthecallertocheckifavoucherisvalid.TheWebservice

validatesthevoucherbasedontherulesintheVMSandreturnsavaluetothecallersayingwhetherthe

voucherisvalidornot.

Followingrulesareusedtovalidateavoucher:

IfthespecifieddistributoridmatcheswiththevoucherdistributoridinVMS

And,ifthevoucheriseitherinACTIVATEDorSOLDstatus

And,ifthevoucherexpirydateiseitheraftertodaydateornull(neverexpires)

And,ifthevoucherredeemdateiseitheraftertodaydateornull

And,ifthevoucherproductenddateiseitheraftertodaydateornull

Then,thevoucherisconsideredtobevalid.

VMS

provides

the

following

Web

service

to

validate

a

voucher:

boolean validateVoucher( long voucherSerialNbr,

String voucherPIN,

int distributorId)



voucherSerialNbr Serialnumberofthevoucher,whichistobe No


32/62


validated

ThisparameterismandatoryifvoucherPINisnot

specifiedbythecallervoucherPIN Pinnumberofthevoucher,whichistobevalidated

ThisparameterismandatoryifthevoucherSerialNbr

isnotspecifiedbythecaller

No

distributorId Distributoridforwhichthevoucherserial/pinnumberistobevalidated

Yes


TheWebservicereturnstheuniqueidentifieridentifyingthenewlyplacedorder.

8.4 Get voucher detailVMS

provides

aWeb

service,

which

allows

the

caller

to

read

the

voucher

detail.

VMSprovidesthefollowingWebservicetogetavoucherdetail:

VoucherData getVoucherDetail( long voucherSerialNbr,

String voucherPIN)



voucherSerialNbrSerial

number

of

the

voucher,

which

is

to

be

validated

ThisparameterismandatoryifvoucherPINisnot

specifiedbythecaller

Thecallermustpass0forthisfield,ifitdoesntwant

to specifytheserialnumber

No

voucherPIN Pinnumberofthevoucher,whichistobevalidated

ThisparameterismandatoryifthevoucherSerialNbr

isnotspecifiedbythecaller

Thecallermustpassnullorforthisfield,ifit

doesntwantto specifythepinnumber

No


Parameter Description


33/62


VoucherData Informationaboutthevoucher

8.5 Update voucher statusAvoucherintheVMSsystemhasalifecycle.Duringthelifecycle,itmovesfromonestatetoanother.

Followingdiagram

shows

the

valid

state

transitions

for

avoucher

in

VMS:

Refertosection3.8.2forthevoucherstatusesandvalidtransitions.

ThestatetransitionisnotautomaticinVMS.OPASAVMSdoesnotprovideabackgroundjobwhich

canbescheduledtochangethevoucherstatuses.ThenewstatusmustbepassedbythecallerandVMS,

basedontheaboveshowntransitiondiagram,decidedwhetherthetransitionfromtheoldstatetothe

newstateispermitted.

VMSprovidesaWebservice,whichallowsthecallertoupdateavoucherstatus/state.TheWebservice

checksifthetransitionfromoldstatetothenewisvalidbasedontherulesintheVMSandreturnsa

flagindicating

whether

the

status

update

was

successful.

VMSprovidesthefollowingWebservicetoupdateavoucherstatus:

boolean updateVoucherStatus( long voucherSerialNbr,

String voucherPIN,

long voucherOrderId,

int voucherBatchId,

int newVoucherStatus)



voucherSerialNbr Serialnumberofthevoucher,whosestatusistobe

updated.

Thisparameterismandatoryifneitherthe

voucherPINisspecifiednorthevoucherOrderIdand

voucherBatchIdisspecifiedbythecaller.

Incasethisparameterisnotbeingpassed,then

numberzero(0)mustbepassedasdefaultvalue.

Yes

voucherPIN Pinnumberofthevoucher,whosestatusistobeupdated


voucherSerialNbrnorthevoucherOrderIdand

voucherBatchIdisspecifiedbythecaller

No

voucherOrderId Orderidofthevouchers,whosestatusistobeupdated

Yes


34/62



voucherSerialNbrnorthevoucherPINisspecifiedby

thecaller.

If,only,voucherOrderIdisspecifiedthenstatusofall

thevouchersinthespecifiedorderisupdated.


numberzero(0)mustbepassedasdefaultvalue.voucherBatchId Batchidofthevouchers,whosestatusistobe

updated

voucherBatchIdmustbespecifiedalongwiththe

voucherOrderId

Ifspecified,thestatusofallthevouchersinthe

specifiedorderidandbatchidisupdated.


numberzero(0)mustbepassedasdefaultvalue.

Yes

newVoucherStatus NewstatusofthevoucherFollowingarethepossiblevaluesforthisparameter:

EnumVoucherStatus.CREATED

EnumVoucherStatus.DISTRIBUTED

EnumVoucherStatus.ACTIVATED

EnumVoucherStatus.SOLD

EnumVoucherStatus.REDEEMED

EnumVoucherStatus.CANCELLED

EnumVoucherStatus.EXPIRED

EnumVoucherStatus.UNREDEEMED

EnumVoucherStatus.QUEUEDFORPURGING

Yes


TheWebservicereturnsflagindicatingwhetherthevoucherstatusisupdatedsuccessfullyinVMS.

9 FilebasedinterfaceForthebatchvoucherrequests,VMSproducesoneormoreCommaSeparatedValues(csv)files.These

filescanberetrievedbyany3rdpartysystemforfurtherprocessing,suchas,transformingittoa

differentformat,encryption,sendingmails,sendingSNMPtrapmessages,etc.

9.1 Voucher fileWhenadistributorplacesarequestforbatchvouchergeneration,VMSbackgroundprocessesthat

requestandcreatesoneormoreoutputbatchfilesforthatdistributor.

Thefilehasthefollowingformat:


35/62


Serial Rowtype Description Occurrence

1 Header Headerrow 1

2 Body Body

containing

thevoucher

pin

and

serial

number

1..n

Nisdecidedbasedonthe

number

of

records,

which

can

bestoredinafile.Thisis

configuredinVMSas

MAX_RECORDS_IN_BATCH_FILE

systemparameter.Default

valueis50000

3 Trailer Trailerrow 1

IfnumberofvouchersrequestedbyadistributorinabatchisvalueofMAX_RECORDS_IN_BATCH_FILE

systemparameter,multiplefilesarecreatedbyVMSeachhavingamaximumof

MAX_RECORDS_IN_BATCH_FILErecords.Inthiscase,aserialnumberisappendedtothefilenameto

identifythesequenceinwhichthefilesaregenerated.

9.1.1 FilenamingconventionThebatchvoucherfilesaregeneratedandstored,byVMS,atthelocationspecifiedbythe

BATCH_FILE_OUTPUT_FOLDERVMSsystemparameter.E.g.ifthesystemparameterissetto

/opt/vms/datathenthebatchfileswillbestoredin/opt/vms/datadirectory.

For

each

distributor,

VMS

creates

a

directory

with

distributor

name

under

the

BATCH_FILE_OUTPUT_FOLDERdirectory.Underthedistributorspecificdirectory,VMSstoresallthe

batchvoucherfilesrelatedtothatdistributor.E.g.fortheBSNLdistributor,VMSwillstorethefileunder

the/opt/vms/data/BSNLdirectory.

FollowingistheVMSbatchvoucherfilenamingconvention:

VMS__[_serial number].

Fileextension()isdecidedbasedontheBATCH_OUTPUT_FILE_EXTNVMSsystem

parameter. Serialnumberisapplicableonlyifmorethanonefileisgeneratedforadistributor.E.g.iffor

a

distributor

only

one

file

is

generated

for

an

order

id

108

and

batch

id

1,

the

file

name

will

be

VMS_108_1.csvandtheabsolutepathofthefilewillbe/opt/vms/data/BSNL/VMS_108_1.csv.Iftwo

filesaregeneratedfororderid108andbatchid2,followingwillbethefilenameofthetwofiles:

VMS_108_2.csv

VMS_108_2_2.csv

and,theabsolutefilenameswillbe:

/opt/vms/data/BSNL/VMS_108_2.csv


36/62


/opt/vms/data/BSNL/VMS_108_2_2.csv

9.1.2 FileformatThissectiondescribes,indetail,thebatchvoucherfileformat.

9.1.2.1 Header

Serial Fieldname Fielddescription Fieldtype Min,

Max

length

Mandatory Sampledata

1 Header

indicator

Characterindicatingthat

therowisaheaderrow

N/A 1,1 Yes H

2 Voucher

expiration

date

Expirationdateofthe

voucher

Ifexpirationdateisnot

availablein

VMS,

this

field

willhaveavalueof

99999999

Date

Formatof

thisfieldis

YYYYMMDD

8,8 Yes 20080925

3 Voucher

status

Statusofthevoucher

1CERATED

2DISTRIBUTED

3ACTIVATED

4SOLD

5REDEEMED

6 CANCELLED

7

EXPIRED8 UNREDEEMED

9 QUEUEDFORPURGING

Enumerator 1,1 Yes 1

4 Voucher

orderid

Orderidaspartofwhich

thevoucherisgenerated

Numeric 3,19 Yes 108

5 Batchid Batchidforpartofwhich

thevoucherisgenerated

Forasinglevoucherthis

fieldvaluewillbe0

Numeric 1,10 Yes 1

6 Batch

denomination

Denominationofthe

vouchersin

the

file

Double 1,20 Yes 39.99

7 Batchrequest

indicator

Indicatorshowing

whetherthevoucherwas

generatedaspartofa

batchornot

Forsinglevoucher

requests,thisfieldvalue

String 1,1 Yes Y


37/62


willbeN

8 Voucher

ordercreated

time

Timethevoucherorder

wascreatedinVMS

system

Date&time

Formatof

thisfieldis

YYYYMMDD

HHMMSSss

17,17 Yes 200809251024593

9 ABN DistributorABNnumber Numeric 1,10 Yes 670338632

10 Distributor

name

Distributorname String 1,45 Yes BSNL

11 Distributor

status

Statusofthedistributor

1active

2inactive

3queuedforpurging

Enumerator 1,1 Yes 1

12 Creditlimit Distributorscurrent

creditlimit

Numeric 1,10 Yes 34598.23

13 Contactname Distributorsprimary

contactpersonname

String 45 Yes SunilKumar

14 Provider

name

Providername String 45 Yes OXYGEN

15 Contactname Providersprimary

contactpersonname

String 45 Yes PerryMurthy

16 Product

name

Voucherproductname

forwhichthevoucheris

generated

String 45 Yes BSNL_REJOICE

17 Productface

value

Facevalueofthevoucher

product

Double 1,20 Yes 500

18 Producttalk

value

Talkvalueofthevoucher

product

Double 1,20 Yes 375

19 Product

service

charge

Servicechargeapplicable

totheproduct

Double 1,20 Yes 12

(inpercentage)

20 Tax Taxapplicabletothe

product

Double 1,20 Yes 8

(inpercentage)

21 Productstart

date

Effectivedateofthe

voucherproduct

Date

Formatof

thisfieldis

YYYYMMDD

8,8 Yes 20080101

22 Productend

date

Expirydateofthevoucher

product

Ifexpirationdateisnot

availableinVMS,thisfield

willhaveavalueof

Date

Formatof

thisfieldis

YYYYMMDD

8,8 Yes 20081231


38/62


99999999

23 Product

validity

extension

Validityextension

applicabletothevoucher

product

Numeric 1,10 Yes 12

(inmonths)

9.1.2.2 Body

Serial Fieldname Field

description

Fieldtype Min,Max

length

Mandatory Sampledata

1 VoucherPIN

number

Pinnumber String 10,10

Thelengthis

dependent

uponthe

lengthofthe

PINa

distributor

requestsfor

Yes 6198308864

2 Voucher

serial

number

Serial

number

Numeric 1,19 Yes 65479

9.1.2.3 Trailer

Serial

Fieldname

Field

descriptionField

type

Min,

Max

lengthMandatory

Sample

data

1 Trailer

indicator

Indicator

showing

thattherow

inthefileis

atrailer

1,1 Yes T

2 Numberof

records

Total

numberof

recordsin

thefile

Numeric 1,10

Max.lengthis

dependent

uponthe

pin

lengtha

distributor

requestsfor

Yes 50000

3 Currentdate Dateon

whichthe

fileis

generated

Date 8,8

Formatofthis

fieldis

Yes 20080521


39/62


YYYYMMDD

4 Currenttime Timeon

whichthe

fileis

generated

Time 6,9

Thelengthwill

varybasedon

the

fraction

of

seconds

Formatofthis

fieldis

HHMMSS[ssss]

032744001

10UserInterface10.1URL

Following

is

the

URL

to

launch

the

VMS

UI

in

the

browser:

http://:/VMSUI/static/com.opasa.vms.VMS/VMS.html

E.g.http://127.0.0.1:8080/VMSUI/static/com.opasa.vms.VMS/VMS.html

10.2Browser specificationAbrowserisaprogramthatallowsyoutoaccesspagesontheWorldWideWeb.ThePortalandWeb

Administrationapplicationsweredevelopedtospecificallytakeadvantageoffeaturesavailablewithin

InternetExplorer6.0orhigher.Otherbrowsers,suchasMozillaFireFoxandNetscape,arenotcertified

atthistime.

Youcan

download

the

latest

version

of

Internet

Explorer,

free

of

charge,

at

http://www.microsoft.com/windows/ie/downloads/default.mspx

10.3Popup blockersIfyouhaveapopupblockerinstalled,youwillneedtoallowpopupsfromtheOPASAVMSWebsite.

Ifyoudonothaveapopupblockerinstalled,youcanskiptothenextsection.

ToallowpopupsfromtheOPASAVMSWebsiteusingInternetExplorer6.0,followtheseprocedures:

Step1:ClickonTools >InternetoptionsmenuinInternetExplorer


40/62


Step2:

Click

on

the

Privacy

tab

Step3:ClickonSettingsbuttoninthePopupBlockersubpanel.SpecifytheVMSUIURLintheAddress

ofWebsitetoallowtextareaandclickonAddbuttontoaddittotheAllowedsiteslist


41/62

10.4MFollowin

in screen

isthelayout

layout

oftheVMS

opyright

creen:

007 Opasa Pvt. Ltd. 41


42/62

10.5NFollo

The

10.6A

10.6.1 LThi

vigation B

wingisthel

avigationb

Manage

to/fromt

o A

os

o R

s

Request

Ithasthe

o S

si

o B

v

Orderde

Productd

Provider

d distribu

ayoutsscreenallo

ar

youtofthe

rhasthefoll

istributor

heVMSsyst

ddThisopt

odify

This

stem

emoveThi

stem

oucherThi

followingsu

ingleThiso

nglevoucher

atchThiso

ouchers

ail

This

opt

etailThiso

etailThis

tor screen

stheusert

opyright

avigationba

owingmain

hismenuite

m.Ithasthe

ionwillbeu

optionwill

b

optionwill

smenuitem

menuitem

ptionwillbe

tionwillbe

ionwill

be

u

ptionwillbe

ptionwillbe

enteradist

007 Opasa

r:

enuitems:

mwillbeus

followingsu

edtoadda

usedto

mo

eusedtore

willbeused

s:

usedtoplac

usedtoplac

edto

view

o

usedtoview

usedtovie

ributordetai

Pvt. Ltd.

dtoAdd,M

bmenuitem

istributorto

difyan

existi

oveanexis

toplaceasin

anorderto

abatchord

rderdetail

fo

aproductd

aprovider

landcreate

dify,orRem

s:

theVMSsys

gdistributor

tingdistribut

gleorbatch

theVMSsys

rtotheVM

radistributo

tail.

etail.

hedistributo

42

oveadistrib

tem

inthe

VMS

orfromthe

oucherrequ

emtogener

togenerate

r.

rintheVMS

tor

MS

est.

tea

bulk

.


43/62

10.6.2DLabel

Name

Descriptio

Voucher

algorithm

ABN

Address

line1

escriptionDescriptio

Specifies

the

distributo

name

n Specifies

the

distributo

descriptio

Displaysth

listof

algorithms

whichcan

beusedto

generate

thevouch

forthe

particular

distributo

ABN

Numbero

the

distributo

Addressli

1forthe

n Type

Textfield

max.45

character

alphanu

Textarea

max.255

character

anytext

e

,

r

List:max

character

Textfield

e Textfield

max.255

opyright

Validat

:

s,

eric

Valuei

alphan

:

s,

None

80

s

None

: None

: None

007 Opasa

ion Def

s

umeric

Non

Non

Def

alg

con

int

VM

syst

Non

Non

Pvt. Ltd.

ault Man

e Yes

e Yes

ult

rithm

igured

e

em

Yes

e Yes

e Yes

datory

43


44/62


distributor

address

characters

Address

line2

Addressline

2forthe

distributor

address

Textfield:

max.255

characters

None None Yes

Zipcode

Zip

code

Text

field:

max.10

characters,

numeric

Valueis

numericNone Yes

Contact

name

Nameofthe

primary

contact

personof

the

distributors

organisation

Textfield:

max.45

characters,

alphabets

Alphabets None Yes

Contact

number

Contact

numberof

theprimary

contact

person

Textfield:

max.20

characters

Valueis

numericand/or

following

special

characters:

Hyphen(),

plussign(+)

None No

Email Emailidof

theprimary

contact

person

Textfield:

max.45

characters

Value

matcheswith

theemail

format(e.g.

[email protected])

None No

Creditlimit Creditlimit

ofthedistributor.

Thisisused

whena

distributor

placesa

voucher

requestto

verifythat

the

distributor

has

sufficient

credit

Textfield:

Number,long

Valueis

numericandupto2

decimal

places

0.00 Yes

Available

products

Displaysthe

listof

products

availableat

theprovider

levelinthe

system

Multi

selectionlist

None Listof

products

Yes


45/62


Distributor

products

Displaysthe

listof

products

selected

fromthelist

ofAvailable

products

andadded

tothe

distributor

Multi

selectionlist

Atleastone

entrymust

exist

Emptylist Yes

Add

distributor

Addsa

distributor

toVMS

Button None N/A N/A

Reset Clearsall

thefields of

theAdd

distributor

Button None N/A N/A

10.6.3NavigationpathFollowingisthenavigationpathfortheAdddistributorscreen:

Managedistributor >Add

10.7Modify distributor screenThisscreenallowstheusertomodifydistributorinformationintheVMS.


46/62

10.7.1 L

10.7.2DLabel

Distributo

ayout


Displaysth

listof

distributo

names,wh

n Type

e

ich

List

opyright

Validati

None

007 Opasa

n Defa

Thef

entry

sorte

Pvt. Ltd.

lt Man

irst

inthe

dlist

Yes

datory

46


47/62


areactivein

VMS.Thislist

ofdistributor

namesis

sorted

alphabetically

Status

Displaysthe

listof

possible

distributor

statuses.

List

None The

current

statusof

the

distributor

Yes

Description Specifiesthe

distributor

description

Textarea:

max.255

characters,

anytext

None Description

ofthe

selected

distribution

Yes

Voucher

algorithm

Displaysthe

listof

algorithms,

which

can

be

usedto

generatethe

voucherfor

theparticular

distributor

List:max

80

characters

None Algorithm

name

associated

with

the

selected

distributed

Yes

ABN ABNNumber

ofthe

distributor

Textfield: None ABNofthe

selected

distributor

Yes

Address

line1

Addressline

1forthe

distributor

address

Textfield:

max.255

characters

None Address

line1of

the

selected

distributor

Yes

Address

line2

Addressline

2forthe

distributor

address

Textfield:

max.255

characters

None Address

line2of

the

selected

distributor

Yes

Zipcode Zipcode Textfield:

max.10

characters,

numeric

Valueis

numeric

Zipcodeof

the

selected

distributor

Yes

Contact

name

Nameofthe

primary

contact

personofthe

distributors

organisation

Textfield:

max.45

characters,

alphabets

Alphabets Primary

contact

nameof

the

selected

distributor

Yes

Contact

number

Contact

numberof

theprimary

contact

person

Textfield:

max.20

characters

Valueis

numeric

and/or

following

special

Primary

contact

numberof

the

selected

No


48/62


characters:

Hyphen(),

plussign(+)

distributor

Email Emailidof

theprimary

contact

person

Textfield:

max.45

characters

Value

matcheswith

theemail

format(e.g.

[email protected])

Emailidof

the

selected

distributor

No

Creditlimit Creditlimitof

the

distributor.

Thisisused

whena

distributor

placesa

voucher

requestto

verifythat

the

distributor

hassufficient

credit

Textfield:

Number,

long

Valueis

numericand

upto2

decimal

places

Creditlimit

ofthe

selected

distributor

Yes

Available

products

Displaysthe

listof

products

availableat

theprovider

levelinthe

system

Multi

selection

list

None Listof

products

ORempty

list

Yes

Distributor

products

Displaysthe

listof

products

selectedfrom

thelistof

Available

productsand

addedtothe

distributor

Multi

selection

list

Atleastone

entryexists

Listof

products

whichwere

addedto

the

distributor

Yes

Modify

distributor

Modifiesa

distributor

information

in VMS

Button None N/A N/A

Reset Clearsallthe

fields

ofthe

Add

distributor

Button None N/A N/A

10.7.3NavigationpathFollowingisthenavigationpathfortheModifydistributorscreen:


49/62

10.8ReThisscre

10.8.1L

10.8.2DLabel

Distributo

Remove

10.8.3NFollowin

10.9ReThisscre

anagedistri

move dist

nallowsthe

ayout


Displaysth

listof

distributo

names,wh

areactive

VMS.This

ofdistribu

namesis

sorted

alphabetic

Deletesth

distributo

fromthe

VMS

avigationpis

the

navig

anagedistri

quest sing

nallowsthe

utor >Mod

ibutor scr

usertoremo

n Type

e

ich

in

listtor

ally

List

e Button

athtion

path

for

utor >Rem

le voucher

usertoplace

opyright

ify

een

veadistribu

Validati

None

None

the

Remov

ove

screen

arequestfo

007 Opasa

tortheVMS.

n Defa

Thef

entry

sorte

N/A

distributor

rasinglevo

Pvt. Ltd.

lt Man

irst

inthe

dlist

Yes

N/A

screen:

cher.

datory

49


50/62

10.9.1 L

10.9.2DLabel

Provider

Distributo

Order

descriptio

Product

ayout

escriptionDescrip

Display

listof

provide

namesi

system.

listof

provide

names

isorted

alphab

Display

listof

distribu

namesi

system.

listof

provide

namesi

sorted

alphab

Specifi

descrip

aboutt

orderb

placed

generat

Display

listofp

tion Type

the

r

nthe

This

r

s

tically

List

the

tor

nthe

This

r

s

tically

List

sthe

ion

he

eing

or

ing

Text

max.

char

the

roduct

List

opyright

Valid

None

None

area:

255

cters

None

None

007 Opasa

tion Def

The

entr

the

list

The

entr

the

list

Non

The

entr

Pvt. Ltd.

ult Man

first

yin

orted

Yes

first

yin

orted

Yes

e No

first

yin

Yes

datory

50


51/62


namesinthe

system.This

listofproduct

namesis

sorted

alphabetically

thesorted

list

Denomination

Thevoucher

denominationText

field:

NumberValue

is

numericand

upto2

decimal

places

The

product

facevalue,

whichis

relatedto

the

product

selectedin

the

Product

namelist

Yes

Expirydate Thevoucher

expiry

date

Textfield:

Date

Datewith

format

dd/mm/yyyy

or

mm/dd/yyyy

depending

uponthe

format

configured

intheVMS

system

Expiry

date

calculated

basedon

theexpiry

period

configured

inthe

VMS

system

Yes

Generate

voucher

Generates

thevoucher

intheVMS

Button None N/A N/A

Reset

Cancelsthe

voucher

generation.It

clears

Button

None N/A N/A

10.9.3NavigationpathFollowingisthenavigationpathfortheRequestsinglevoucherscreen:

Requestvoucher >Single

10.10Request batch vouchers screenThisscreenallowstheusertoplaceabatchrequestforbulkvouchergeneration.


52/62

10.10.1

10.10.2Label

Provider

Distributo

Layo

Desc

Descrip

Display

listof

provide

namesi

system.listof

provide

namesi

sorted

alphab

Display

listof

distribu

t

iptiontion Type

the

r

nthe

This

r

s

tically

List

the

tor

List

opyright

Valid

None

None

007 Opasa

ation Def

The

entr

the

list

The

entr

the

Pvt. Ltd.

ult Man

first

yin

sorted

Yes

first

yin

sorted

Yes

datory

52


53/62


namesinthe

system.This

listof

provider

namesis

sorted

alphabetically

list

Order

description

Specifiesthe

description

aboutthe

orderbeing

placedfor

generating

Textarea:

max.255

characters

None None No

Product Displaysthe

listofproduct

namesinthe

system.This

listofproduct

names

is

sorted

alphabetically

List None Thefirst

entryin

thesorted

list

Yes

Numberof

vouchers

Specifiesthe

numberof

vouchersto

begenerated

Textfield:

Number

Valueis

numeric

withno

decimal

placesand

value>1

None Yes

Denomination Thevoucher

denomination

Textfield:

Number

Valueis

numericand

upto2

decimal

places

The

product

facevalue,

whichis

relatedto

the

product

selectedin

the

Product

namelist

Yes

Expirydate Thevoucher

expirydate

Textfield:

Date

Datewith

format

dd/mm/yyyy

or

mm/dd/yyyy

dependinguponthe

format

configured

intheVMS

system

Expiry

date

calculated

basedon

theexpiry

periodconfigured

inthe

VMS

system

Yes

Description Batch

description

Textarea:

max.255

characters

Valueisnot

empty

None Yes


54/62

Addtoord

Orderdet

X

Placeorde

Reset

10.10.3Followin

R

10.11PThisscre

10.11.1

er Addsth

batchd

tothe

details

ils Display

listofb

detaila

tothe

Remov

corresp

batche

fromth

Order

table

r Addsth

vouche

orderin

VMS

Resetsfields

Navig

isthenavig

equestvouc

rovider d

nallowsthe

Layo

e

etail

rder

table

Com

box

the

atches

dded

rder

Tabl

sthe

onding

ntry

e

etails

Butt

e

rbatch

the

Butt

he

Butt

ationpathtionpathfor

er >Batch

tail scree

usertoview

t

opyright

bo Atlea

entry

inth

detail

None

n None

n None

n

None

theReques

aproviderd

007 Opasa

stone

exists

Order

stable

N/A

Non

Non

N/A

N/A

tbatchvouc

tail.

Pvt. Ltd.

N/A

e N/A

e N/A

N/A

N/A

erscreen:

54


55/62


10.11.2 DescriptionLabel Description Type Validation Default Mandatory

Provider Displaysthe

listof

provider

namesinthe

system.This

listof

provider

namesis

sorted

alphabetically

List None Thefirst

entryin

thesorted

list

Yes

Name Displaysthe

provider

nameofthe

selected

provider

None None None N/A

Description Displaysthe

provider

descriptionof

theselected

provider

None None None N/A

Addressline

1

Addressline1

ofthe

selected

provider

None None None N/A

Addressline

2

Addressline2

ofthe

selected

provider

None None None N/A

Zip

code

Zip

code

of

theselected

provider

None

None None N/A

Contactname Primary

contactname

ofthe

selected

provider

None None None N/A

Contact

number

Primary

contact

numberofthe

selected

provider

None None None N/A

Email

Email

of

the

selected

provider

None

None None N/A

Productdetail

table

Displaysthe

Productand

the

corresponding

Description

Table None None N/A


56/62

Distributo

detailtabl

10.11.3Followin

P

10.12PThisscre

10.12.1

10.12.2Label

Provider

ofallth

product

provide

Display

Distrib

andthe

correspDescri

ofallth

distribu

thepro

has

Navig

isthenavig

roviderdetai

roduct de

nallowsthe

Layo

Desc

Descrip

Display

listof

provide

namesi

system.

e

sthe

rhas

the

tor

onding

tion

e

tors

ider

Tabl

ationpathtionpathfor

l

ail screen

usertoview

t

iptiontion Type

the

r

nthe

This

List

opyright

None

theProvide

aproductde

Valid

None

007 Opasa

Atl

one

exis

rdetailscre

tail.

tion Def

All

Pvt. Ltd.

ast

entry

N/A

n:

ult Man

Yes

datory

56


57/62


listof

provider

namesis

sorted

alphabetically

Distributor Displaysthe

listof

distributor

namesinthe

system,for

theselected

provider.This

listof

distributor

namesis

sorted

alphabetically

List None All Yes

Product Displaysthe

list

of

productsin

thesystemfor

theselected

provider.This

listofproduct

namesis

sorted

alphabetically.

List None Thefirst

entry

in

thesorted

list

Yes

Name Nameofthe

selected

product

None None None N/A

Description Descriptionof

theselected

product

None None None N/A

Facevalue Facevalueof

theselected

product

None None None N/A

Talkvalue Talkvalueof

theselected

product

None None None N/A

Service

charge

Servicecharge

ofthe

selected

product

None None None N/A

Tax

Taxset

for

the

selected

product

None

None None N/A

Startdate Effectivedate

ofthe

selected

product

None None None N/A

Enddate Enddateof

theselected

None None None N/A


58/62


product

Validity

extension

Extension

periodofthe

selected

product

None None None N/A

10.12.3 NavigationpathFollowingisthenavigationpathfortheAdddistributorscreen:

Productdetail

10.13Order detail screenThisscreenallowstheusertoviewtheorderdetail,whichisplacedbyadistributorforaprovider.

10.13.1 Layout


59/62


10.13.2 DescriptionLabel Description Type Validation Default Mandatory

Distributor Displaysthe

listof

distributor

namesinthe

system.This

listof

distributor

namesis

sorted

alphabetically

List None Thefirst

entryin

thesorted

list

Yes

Provider Displaysthe

listof

provider

namesinthe

system.This

listof

providernamesis

sorted

alphabetically

List None Thefirst

entryin

thesorted

list

Yes

Ordersper

page

Specifiesthe

numberof

ordersdetail

tobe

displayedon

onepage

Textfield:

numeric,

max.3

characters

1=

N/A


60/62


Ordersper

page

ELSE

Not

clickable


61/62


11014 MissingsystemparameterinVMS

11015 Invalidsystemparameter

11016 Failedtoaddmappingbetweenprovideranddistributor

11017 Failedtoreadrecordfromdatabase

11018 Thedistributorhasinsufficientcredit

11019

Failedto

read

distributor

credit

limit

from

VMS

11020 Failedtoretrievealgorithmusedbythedistributortogeneratevouchers

11021 Failedtocreatevoucherorderrequest

11022 Failedtocreatevoucherintothedatabase

11023 Failedtoupdatevouchergenerationalgorithminformation

11024 Failedtoreadorderandbatchinformation

11025 Theenteredpininformationisincorrect

11026 Failedtocreatebatchforthisorder

11027 Failedtoretrieveorderdetailsforthegivenorderanddistributorinformation

11028 Failedtoclosedatabasepreparedstatement

11029 FailedtoreadvoucherorderfromVMS

11030 FailedtoreadvoucherdetailfromVMS

11031 Failedtoupdatedistributorcreditlimit

11032 Failedtoreadvoucherdata

11033 Thecustomattributetogenerateran

opasa vms user guide v1.0

Documents