Opasa Vms User Guide v1.0

OPASA VMS™ User Guide
Version 1.0
OPASA Team

LEGAL INFORMATION
The information in this document is subject to change without notice and describes only the product defined in the introduction
of this documentation. This document is intended for the use of Opasa VMS customers only for the purposes of the agreement
under 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 of
continuous 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 of
material errors and omissions. Opasa will, if necessary, explain issues which may not be covered by the document.
Opasa’s liability for any errors in the document is limited to the documentary correction of errors. Opasa WILL NOT BE
RESPONSIBLE IN ANY EVENT FOR ERRORS IN THIS DOCUMENT OR FOR ANY DAMAGES, INCIDENTAL OR CONSEQUENTIAL (INCLUDING
MONETARY 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 for
identification purposes only.
Copyright © Opasa Solutions Pvt. Ltd. 2007. All rights reserved.
Copyright© 2007 Opasa Pvt. Ltd. 2

Table of Contents
1 Introduction .......................................................................................................................................... 7
2 Acronyms .............................................................................................................................................. 7
3 System functionality ............................................................................................................................. 8
3.1 Architecture .................................................................................................................................. 8
3.2 3rd party software .......................................................................................................................... 8
3.3 Provider ......................................................................................................................................... 9
3.3.1 Attributes .............................................................................................................................. 9
3.3.2 Life‐cycle ............................................................................................................................... 9
3.4 Distributor ..................................................................................................................................... 9
3.4.1 Attributes ............................................................................................................................ 10
3.4.2 Life‐cycle ............................................................................................................................. 11
3.5 Product ........................................................................................................................................ 11
3.5.1 Attributes ............................................................................................................................ 11
3.5.2 Life‐cycle ............................................................................................................................. 12
3.6 Order ........................................................................................................................................... 12
3.6.1 Attributes ............................................................................................................................ 12
3.6.2 Life‐cycle ............................................................................................................................. 13
3.7 Batch ........................................................................................................................................... 13
3.7.1 Attributes ............................................................................................................................ 13
3.7.2 Life‐cycle ............................................................................................................................. 14
3.8 Voucher ....................................................................................................................................... 14
3.8.1 Attributes ............................................................................................................................ 14
3.8.2 Life‐cycle ............................................................................................................................. 15
3.9 PIN generation ............................................................................................................................ 15
3.10 VMS entity relationship .............................................................................................................. 16
3.11 Process Sequence........................................................................................................................ 16
3.11.1 Batch Voucher Generation .................................................................................................. 16
3.11.2 Single Voucher Generation ................................................................................................. 17
3.12 Jobs ............................................................................................................................................. 18

3.12.1 GenerateBatchVoucher.PL .................................................................................................. 18
4 Database model .................................................................................................................................. 19
5 System configuration .......................................................................................................................... 21
5.1 System parameters ..................................................................................................................... 21
5.2 Environment variables ................................................................................................................ 22
5.3 Data Source ................................................................................................................................. 22
6 System installation .............................................................................................................................. 23
6.1 Step 1 .......................................................................................................................................... 24
6.2 Step 2 .......................................................................................................................................... 25
6.3 Step 3 .......................................................................................................................................... 25
6.4 Step 4 .......................................................................................................................................... 25
6.5 Step 5 .......................................................................................................................................... 26
6.6 Step 6 .......................................................................................................................................... 26
6.7 Step 7 .......................................................................................................................................... 26
6.7.1 Verify VMS UI and Apache Axis ........................................................................................... 26
6.7.2 Verify VMS Web services .................................................................................................... 27
6.8 Important URLs ........................................................................................................................... 28
7 Operational consideration .................................................................................................................. 28
8 Web services interface ........................................................................................................................ 29
8.1 Single voucher ............................................................................................................................. 29
8.2 Batch voucher request ................................................................................................................ 30
8.3 Validate voucher ......................................................................................................................... 31
8.4 Get voucher detail ....................................................................................................................... 32
8.5 Update voucher status ................................................................................................................ 33
9 File based interface ............................................................................................................................. 34
9.1 Voucher file ................................................................................................................................. 34
9.1.1 File naming convention ....................................................................................................... 35
9.1.2 File format ........................................................................................................................... 36
10 User Interface ................................................................................................................................. 39
10.1 URL .............................................................................................................................................. 39
10.2 Browser specification .................................................................................................................. 39
10.3 Pop‐up blockers .......................................................................................................................... 39

10.4 Main screen layout...................................................................................................................... 41
10.5 Navigation Bar ............................................................................................................................. 42
10.6 Add distributor screen ................................................................................................................ 42
10.6.1 Layout .................................................................................................................................. 42
10.6.2 Description .......................................................................................................................... 43
10.6.3 Navigation path ................................................................................................................... 45
10.7 Modify distributor screen ........................................................................................................... 45
10.7.1 Layout .................................................................................................................................. 46
10.7.2 Description .......................................................................................................................... 46
10.7.3 Navigation path ................................................................................................................... 48
10.8 Remove distributor screen .......................................................................................................... 49
10.8.1 Layout .................................................................................................................................. 49
10.8.2 Description .......................................................................................................................... 49
10.8.3 Navigation path ................................................................................................................... 49
10.9 Request single voucher screen ................................................................................................... 49
10.9.1 Layout .................................................................................................................................. 50
10.9.2 Description .......................................................................................................................... 50
10.9.3 Navigation path ................................................................................................................... 51
10.10 Request batch vouchers screen .............................................................................................. 51
10.10.1 Layout .............................................................................................................................. 52
10.10.2 Description ...................................................................................................................... 52
10.10.3 Navigation path ............................................................................................................... 54
10.11 Provider detail screen ............................................................................................................. 54
10.11.1 Layout .............................................................................................................................. 54
10.11.2 Description ...................................................................................................................... 55
10.11.3 Navigation path ............................................................................................................... 56
10.12 Product detail screen .............................................................................................................. 56
10.12.1 Layout .............................................................................................................................. 56
10.12.2 Description ...................................................................................................................... 56
10.12.3 Navigation path ............................................................................................................... 58
10.13 Order detail screen ................................................................................................................. 58
10.13.1 Layout .............................................................................................................................. 58

10.13.2 Description ...................................................................................................................... 59
10.13.3 Navigation path ............................................................................................................... 60
11 Troubleshooting .............................................................................................................................. 60
11.1 Log files ....................................................................................................................................... 60
11.2 Error codes and messages .......................................................................................................... 60
12 Changes ........................................................................................................................................... 62


1 Introduction
This document is the user guide for the VMS product. This User’s Guide describes product
• Concepts
• Architecture,
• Feature functionality,
• Database entity design
• Configuration
• Installation instructions
• Trouble shooting – Error codes and Log files
• APIs / Web Services
• User Interface functionality

This User’s Guide will also describe following GUI operations:
• Add distributor
• Modify distributor
• Remove distributor
• Request single voucher
• Request batch voucher
• View product detail
• View order detail
• View provider detail
2 Acronyms
Acronym Description
VMS Voucher Management System
API Application Programming Interface
SOAP Simple Object Access Protocol
WSDL Web Service Definition Language
GUI Graphical User Interface
UI User Interface
ABN Australian Business Number
CSV Comma Separated Values
SNMP Simple Network Management Protocol
CATALINA_HOME Apache Tomcat installation directory

3 System functionality
3.1 Architecture

VMS GUI 3rd party 3rd party

(Web browser) Web services client system
Web
service call
Web server
Apache Tomcat
Application server
VMS UI VMS Web services
Stored procedures
GenerateBatch.pl
VMS database
Batch voucher
file(s) for
distributors
Fig: Overall architecture
Confidential & Proprietary

3.2 3rd party software
Following 3rd party software products and components are used in VMS:
• Oracle™ ‐ 10g R2
• Sun Java™ – 1.4.2_08
• Red Hat™ Linux 3.0+
• HTML version 4.0
• Java Application Server ‐ Apache Tomcat v5.0
• JDBC version 3.0 (Thin)
• Spring (Java framework) v2.0

• Apache Axis v1.4

3.3 Provider
A Provider is the entity which provides the voucher management infrastructure. A Provider sets up the
VMS system and will have Distributors associated with it.
E.g. say, an organization XYZ decides to setup a VMS system and enable one or more vendors to be able
to request the XYZ organization to generate the vouchers and send them to the individual requesting
vendor. In this case, XYZ will be setup as Provider in the VMS system.
OPASA VMS ™ is modeled in a way that it supports the MVNE and MVNO business model. Typically, a
MVNE installs the VMS product and will have one or more MVNOs. Each MVNO will, further, have one
or more distributors associated. OPASA VMS™ provides a mechanism to the MVNE to setup its MVNOs
as Providers. Each distributor of the MVNO/Provider is setup as Distributor in the system.
Each MVNE can install one or more instances of OPASA VMS™. Each VMS instance can have one or more
Providers (or MVNOs) setup. Each Provider can have one or more Distributors.
OPASA VMS™ also provides the flexibility to setup a Provider as a Distributor. This is useful in the
business model where a Provider has one or more distributors who request for the vouchers and also,
the provider itself requests vouchers and sells them.
3.3.1 Attributes
Following are the attributes of a Provider in OPASA VMS™ system:
• Name – Provider name need not be unique in the system.
• Description – A Provider description gives more detail about the Provider.
• Address detail
• Contact number – While setting up a Provider the primary contact number of the Provider’s
representative can be added. This can be used (by MVNE, e.g.) to contact the Provider’s
concerned person, if needed.
• E‐mail ‐ While setting up a Provider the e‐mail address of the Provider’s representative can be
added. This can be used (by MVNE, e.g.) to contact the Provider’s concerned person, if needed.
3.3.2 Lifecycle
A Provider, once created, always remains active in the OPASA VMS™ system.
3.4 Distributor
A Distributor is an entity, which requests the vouchers to be issued from one or more Providers.

E.g. say, a vendor ABC contacts the organization XYZ and decides to use the voucher management
service of XYZ. In this case, ABC will be setup as a Distributor in the VMS system and will be related with
the Provider XYZ.
A Distributor is always associated with a Provider. OPASA VMS™ allows many‐to‐many relationship
between Provides and Distributors. One Distributor can be associated with one or more Providers and
one or more Distributors can be associated with one Provider. A Distributor is always added at a
Provider level and hence Distributors are not shared across Providers. If same distributor needs to be
associated with multiple providers, the Distributor must be added to each Provider, individually.
3.4.1 Attributes
Following are the attributes of a Distributor in OPASA VMS™ system:
• Name – Distributor name need not be unique in the system.
• Description – A Distributor description gives more detail about the Distributor.
• Address detail
• Contact number – While setting up a Distributor the primary contact number of the Distributor’s
representative can be added. This can be used (by MVNO, e.g.) to contact the Distributor’s
concerned person, if needed.
• E‐mail ‐ While setting up a Distributor the e‐mail address of the Distributor’s representative can
be added. This can be used (by MVNO, e.g.) to contact the Distributor’s concerned person, if
needed.
• Voucher algorithm – OPASA VMS™ allows the user to associate a voucher algorithm (e.g.
algorithm to generate 10‐digit vouchers) to a Distributor. To generate vouchers for a
distributor, the algorithm associated with it is used. At any given instance of time, only one
algorithm can be associated with a distributor. OPASA VMS™ allows the user to change the
algorithm for a distributor, if needed.
• Credit limit – For each distributor, OPASA VMS™ allows the user to specify the monetary credit
limit. This credit limit is used while generating vouchers for the distributor to check whether the
distributor has sufficient credit. In case of insufficient credit, the OPASA VMS™ system doesn’t
generate the vouchers for that distributor. The VMS system notifies about this event when an
order is being placed.
o In case of single voucher request, OPASA VMS™ processes the request only if the
requested voucher denomination is <= distributor credit limit
o In case of batch voucher request, OPASA VMS™ processes the request only if the total
requested vouchers denomination is <= distributor credit limit

3.4.2 Lifecycle
Following diagram shows the life‐cycle of a Distributor in OPASA VMS™ system:
A Distributor is removed from the VMS system after it is either deleted or purged by the purging job.
3.5 Product
A Product is an entity, which represents a product being sold by a distributor. OPASA VMS™ allows the
user to add products at the Provider level as well as at the Distributor level. The Products added at the
Provider level are visible to all the Distributors of that Provider. The Products added at the Distributor
level are visible only to that Distributor.
E.g. say, a Distributor D1 is selling a Product P1 and does not want any other Distributor D2 of the same
Provider to view its Product. In this case, the Product P1 will be added the Distributor D1 level, not at
the Provider level.
A Product must be setup in the VMS system before placing a voucher request.
3.5.1 Attributes
Following are the attributes of a Product in OPASA VMS™ system:
• Name – Product name need not be unique in the system.
• Description – A Product description gives more detail about the Product.

• Face value – This is the denomination of the product. E.g. if vouchers of denomination $100
needs to be generated, a product must be configured with face value of $100
• Talk value – This is the net talk value of the product. E.g. a voucher with $100 denomination may
have a talk value of $95. $5 may go towards service charges, taxes, etc. OPASA VMS™ allows the
user to store the talk value of a product, separately. This is an informational attribute and must
be specified by the user while adding a product into the VMS system.
• Service charge – OPASA VMS™ provides a product attribute to store the service charge which is
applicable to a product. This is an informational attribute and can be specified by the user while
adding a product into the VMS system.
• Tax – OPASA VMS™ provides a product attribute to store the tax which is applicable to a
product. This is an informational attribute and can be specified by the user while adding a
product into the VMS system.
• Start date – Every product must have a date on which the product becomes effective and
vouchers can be request on it from that day. The attribute allows the user to specify the
effective date of a product.
• End date – This attribute allows user to restrict the validity of a product. If a user specifies a
particular end date, the product expires on that date and no vouchers can be generated for it. If
no end date is specified, the product never expires.
• Validity extension – OPASA VMS™ allows the user to specify the duration by which the account
credit expiry needs to be extended, in the billing system. This can be specified in days, months
or years.
3.5.2 Lifecycle
A product, once created, remains in the VMS system. If the end date is specified, the product expires
after that date. Otherwise, it remains active.
3.6 Order
An Order is an entity, which is created for a particular Distributor and a Provider and is placed by the
Distributor in the VMS system. An Order is placed by the Distributor to request the VMS system to
generate a single voucher in real‐time or bulk vouchers in batches. For bulk/batch voucher request, an
Order will contain one or more batch detail into it.
E.g. say, the Distributor ABC wants to get 10,000 vouchers generated for Product P1 and 5,000 vouchers
for Product P2. In this case, the Distributor will place an Order to the VMS system for Product P2, which
will have 2 entries for bulk/batch voucher.
3.6.1 Attributes
• Description – An order description gives more detail about an Order
• Provider – The attribute stores the Provider to which the requesting Distributor is associated
with
• Distributor – The attribute stores the Distributor who has placed the voucher order

• Request indicator – An indicator showing whether the order is for a single voucher or for a batch
voucher
3.6.2 Lifecycle
In OPASA VMS™, an Order expires after the vouchers are generated for it. In case of single voucher
request, the Order expires after a voucher is generated and information is returned back to the user. In
case of batch voucher request, the Order expires after all the batches, related to the Order, are
processed successfully.
3.7 Batch
A Batch is an entity, which is part of an Order when a Distributor places a bulk/batch voucher request.
E.g. in the previous example, when the Distributor places the Order for the generation of 10,000
vouchers for Product P1 and 5,000 vouchers for Product P2, 2 Batches will be created in the VMS
system. Batch #1 will be created, to generate 10,000 vouchers for Product P1, and Batch #2 will be
created, to generate 5,000 vouchers for Product P2.
OPASA VMS™ does not allow the user to delete a Batch from the system, once created.
3.7.1 Attributes
• Description – A batch description gives more detail about an Batch
• Order – The Order which constitutes of this Batch
• Status – Stores the current status of the Batch. See the ‘Life‐cycle’ section for different statuses
and the valid transitions
• Denomination – This attribute indicates the denomination of the vouchers in the Batch
• Number of vouchers – This attribute indicates the number of vouchers to be generated in the
Batch
• Expiry date – This attribute indicates the expiry date of the vouchers in the Batch. All the
vouchers generated for the Batch will expire on the specified date

3.7.2 Lifecycle
Following diagram shows the life‐cycle of a Batch in OPASA VMS™ system:
3.8 Voucher
A Voucher is an entity, which is generated as part of the Order placed by a Distributor of a Provider. A
single voucher is generated, in real‐time, when a Distributor places an Order for a single voucher.
Multiple vouchers are generated, in Batch, when a Distributor places an Order for bulk vouchers.
E.g. in the previous example, when 2 Batches are created to generate 10,000 and 5,000 vouchers for
Products P1 and P2, respectively, the VMS system will generate the Vouchers in the system for the
Distributor.
3.8.1 Attributes
Following are the attributes of a Voucher in OPASA VMS™ system:
• Product – This attribute indicates the Product for which the voucher is generated
• Provider – This attribute indicates the Provider for which the voucher is generated
• Distributor – This attribute indicates the Distributor for whom the voucher is generated
• Order ‐ This attribute indicates the Order for which the voucher is generated
• Batch ‐ This attribute indicates the Batch for which the voucher is generated. This attribute will
not contain anything for a voucher generated as part of single voucher request

• PIN number – Random unique PIN number generated for the voucher
• Serial number
• Expiry date ‐ This attribute indicates the expiry date of the voucher. This is calculated based on
the expiry date specified by the user while placing a voucher request. If no date is specified by
the user, OPASA VMS™ uses a system parameter to calculate the expiry date
• Activation date – Date on which the voucher is activated
3.8.2 Lifecycle
Following diagram shows the life‐cycle of a voucher in OPASA VMS™:
3.9 PIN generation
VMS supports multiple algorithms to generate PINs. The algorithm differs based on the pin length. By
default, VMS provide an algorithm to generate 10 digit pins. The algorithm guarantees that the
generated pin numbers are unique and random.

The selection of what algorithm to be used is at the distributor level. On the ‘Add distributor’ screen of
VMS UI, user can select the algorithm, which will be applicable to that distributor. The pin numbers will
be generated based on the algorithm attached to the distributor.
3.10 VMS entity relationship
Following diagram shows how the different OPASA VMS™ entities (e.g. Provider, Distributor, Product,
etc.) are related with each other and what kind of relationship exists between them:
Algorithm
1....1
System (MVNE) 1.....n Provider (MVNO/tenant) m.....n Distributor
1....n
Product
1....n
1....n
Voucher n....1 Batch

1....1
PIN
Relationships:
1...1 - one-to-one
1...n – one-to-many
m...n – many-to-many
3.11 Process Sequence
3.11.1 Batch Voucher Generation
In the Batch Voucher Generation scenario, a Provider, first, is setup in the system. For a Provider, a
Distributor is selected. The Distributor selects a Product and places an order to the VMS, which creates
batch into the VMS system. These batches are processed and the Vouchers are generated.
The following diagram shows the entity relationship for the batch voucher generation scenario:

Pro
ovider
Voucher Distributor
Batch Product
O
Order
`
Followingg steps are invvolved in the batch voucheer generation
n process:
Step 1 On the
e VMS UI page, click on Re
equest Vouch
her ‐> Batch
Step 2 On the
e Request battch voucher sscreen, speciffy the requireed values
Step 3 Click o
on Add to ord
der button to add the batch to the ordeer
Step 4 w step 3 to add more batch
Follow hes to the ord
der
Step 5 Click o
on Place order button
Step 6 GenerateBatch job processes the order and aall the batchees within and creates batch
h
vouche
er files for disstribution
3.11.2 Siingle Vouch her Generatiion

In the Singgle Voucher G
Generation sccenario, a Proovider, first, iss setup in thee system. For a Provider, a
Distributo
or is selected.. The Distributor places an order to the VMS. The VM MS system geenerates the
Voucher ffor the order placed.
wing diagram shows the en
The follow ntity relationsship for the single voucher generation scenario:
C
Copyright© 2
2007 Opasa Pvt. Ltd. 17
7

Providerr
Voucher Distributor
Ord
der Product
Followingg steps are invvolved in the single voucheer generation
n process:
Step 1 On the
e VMS UI page, click on Re
equest Vouch
her ‐> Single
Step 2 On the
e Request sin
ngle voucher sscreen, speciffy the requireed values
Step 3 Click o on. VMS geneerates the voucher and dissplays the vou

on Generate vvoucher butto ucher
detail on the screen
n
3.12 Job
bs
This sectio
on describes, in detail, varrious jobs VM
MS system hass to accomplissh the functio
onality.
3.12.1 GenerateBat
G chVoucher.P PL
The Generate Batch Vo oucher job is designed to ccheck the battch table for tthe existence of new batch h
voucher o orders. These orders are eiither created from the VM MS UI or usingg requestBatchVoucher Weeb
service. WWhenever a new batch is created, it willl be put into C CREATED (1) status. This jo ob reads the
batches in n CREATED status at this m moment and m moves them tto the RUNNING status and commits th he
transactioon so that samme batch will not be picked d up by moree than one insstance of the same job. Fo or all
the batches which havve been put in nto RUNNING G status by thee job, it creattes vouchers ffor the batch
request. O Once the vouchers for the batch are creeated, the job b creates onee or more (depending on how
many vou n a batch and how many reecords can exxist in a singlee file) csv file(s). If batch
uchers exist in
voucher ccreation as we ell as csv file ssucceeds then the batch status is moveed to COMPLEETED (4) statu us.
However, if any of them fails then tthe uncommittted transaction is rolled b back. Also, if n
needed, relatted
om the file syystem and battch status willl be updated to ERRORED status. Howeever,
csv files are deleted fro
if batch sttatus updatess itself fails, th
hen batch willl be left in RU
UNNING statu us.
Th
his job creates a log file in the directoryy configured b
by environmeent variable
BA
ATCH_JOB_LO OG_DIR. The log file name format is BattchLogs_<currrent date>_<<current
C
Copyright© 2
8

time>.LOG. It contains information about all the Voucher ID and Batch ID being processed during this
run. In case, this job exits with non‐zero exit status, the operator must look into the log file to
understand the reason for failure.
The CSV files will be created into a directory configured by the system parameter,
BATCH_FILE_OUTPUT_FOLDER. The job assumes that the operator has ensured that a directory
exist under this output folder for every distributor. This directory name should be same as distributor
name in the VMS systems.
Following command must be executed on the shell prompt to run the job:
$> nohup ./GenerateBatchVoucher_V1.1.PL
Following command must be executed on the shell prompt to stop the job:
$> kill -9 ./GenerateBatchVoucher_V1.1.PL
4 Database model
Following diagram shows the VMS data model. It shows the VSM entities and how they are related.

5 System configuration
This section describes the different system configuration information used by VMS.
5.1 System parameters
VMS provides many system parameters, which drive its functionality. Every installation of VMS product
comes with default values set for these parameters. These parameters can also be modified for each
implementation of the VMS product.
Following system parameters are available:
Parameter name Description Default value

BATCH_FILE_OUTPUT_FOLDER Path where the batch voucher files will be /tmp/batch/output
created

This parameter value may be changed
based on the VMS installation and
operational needs
BATCH_OUTPUT_FILE_EXTN File extension to be used for the batch csv
voucher file name (e.g. VMS_109_1.csv)
MAX_RECORDS_IN_BATCH_FILE Maximum number of pins stored in one 50000
batch voucher file
PURGING_PERIOD Purging period 5Y
Y – in Years
M – in Months
D – in Days
VOUCHER_VALIDITY_PERIOD Period for which a voucher will be valid 90D
Y – in Years
M – in Months
D – in Days
BATCH_FILE_NAME_DELIM Delimiter used in the batch voucher file to ,
separate two values (comma)

The above listed system parameters are stored in SYSTEMPARAMSREF table of VMS schema. The
appropriate support and operations staff must be consulted in order to change the values.
Changing the system parameter requires restarting of the following:
• Apache Tomcat server
• GenerateBatchVoucher.PL job

5.2 Environment variables
VMS uses many environment variables, which drive its functionality. The VMS installation process sets
these environment variables. These variables’ value can also be modified for each implementation of
the VMS product.
Following environment variables are available:
Variable name Description Default value

TWO_TASK Oracle database name None

Must be set
during the VMS
installation
DB_USER_NAME User name to connect to VMS database None

Must be set
during the VMS
installation
DB_PASSWORD Password to connect to VMS database None

Must be set
during the VMS
installation
BATCH_JOB_LOG_DIR Directory where the GenerateBatch job creates the None
log files
Must be set
during the VMS
installation
BATCH_JOB_RUN_FREQUENCY Time the GenerateBatch job will wait before 120 minutes
continuing the next cycle

Appropriate support and operations staff must be consulted in order to change the values.
Changing the environment variables requires restarting of the following:
• GenerateBatchVoucher.PL job
5.3 Data Source
VMS uses the data source created by the Apache Tomcat server. Following default configuration
information for the Data source is specified in the
<CATALINA_HOME>\conf\Catalina\localhost\axis.xml file:
<Resource name="jdbc/vmsdb" type="javax.sql.DataSource"/>

<ResourceParams name="jdbc/vmsdb">
<parameter>
<name>factory</name>

<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<parameter>
<name>maxWait</name>
<value>30000</value>
</parameter>
<parameter>
<name>maxActive</name>
<value>50</value>
</parameter>
<parameter>
<name>password</name>
<value>password</value>
</parameter>
<parameter>
<name>url</name>
<value>jdbc:oracle:thin:@localhost:1523:vmstestdb</value>
</parameter>
<parameter>
<name>driverClassName</name>
<value>oracle.jdbc.driver.OracleDriver</value>
</parameter>
<parameter>
<name>maxIdle</name>
<value>10</value>
</parameter>
<parameter>
<name>username</name>
<value>vmsuser</value>
</parameter>
</ResourceParams>
A reference to the VMS Data source is specified in the <CATALINA_HOME>\axis\WEB‐INF\web.xml file
<resource-ref>
<res-ref-name>jdbc/vmsdb</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Changing the Data source configuration requires restarting of the following:
6 System installation

Installation of the following software products and components are out‐of‐scope for this
document:
• RedHat™ Linux
• Sun JDK™

• Oracle™ 10g database server
• Perl
VMS application is delivered as a VMS.tar.gz file. This compressed archive contains all the required
and necessary files for installing and running VMS application.
Following steps needs to be followed to install the OPASA VMS™ application:
6.1 Step 1
Let's say user has chosen /usr/share/vms as the installation folder. Throughout we'll refer this folder as
VMS_INSTALL.
Extract VMS.tar.gz file in VMS_INSTALL folder by running the following commands:
• gunzip VMS.tar.gz
• tar -xvf VMS.tar
This will create the following folders:
<VMS_INSTALL>
|___ 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

|___ undeployvms
6.2 Step 2
Go to <VMS_INSTALL>/vms folder.
Connect to Oracle database using sqlplus (or any other tool of your preference, which allows you to
run DDL and DML statements) and run the CREATE_VMSUSER.sql by entering the following command at
the sqlplus prompt:
SQL> @CREATE_VMSUSER
This will create the VMS user with the necessary and sufficient permissions.
6.3 Step 3
Logout from sqlplus and re‐login using the VMS user, created in the previous step.
On the sqlplus prompt, run the CREATE_VMSSCHEMA.sql and CREATE_VMSREFDATA.sql by entering
the following commands:
SQL> @CREATE_VMSSCHEMA
SQL> @CREATE_VMSTRIGGER
SQL> @CREATE_VMSREFDATA
SQL> @ CREATE_GENERATEBATCHPROC
This will create the database schema for VMS, populates the reference data of VMS, and creates the
stored procedure for the GenerateBatch.pl.
6.4 Step 4
Exit from sqlplus and run the following command to start the VMS installation:
$>./installvms
This is an interactive script. Follow the instructions to proceed with the installation.
This will check the pre‐requisites, database connectivity, installs Apache Axis, copies the VMS files in the
VMS_HOME (specified by the user during the installation) folder, and creates a setvmsenv file, which
contains the script to set the required environment variables and the CLASSPATH.
The installer creates the following folders in the $VMS_HOME:
• vms ‐ contains all the VMS files
• lib ‐ contains all the 3rd party jars VMS uses
• bin ‐ contains all the VMS executables
• logs ‐ used for creating the log files by the executables

6.5 Step 5
Go to the VMS installed folder and source the environment script by running the following commands
on the command prompt:
$> cd $VMS_HOME
$> . setvmsenv
This will set all the required environment variables and the CLASSPATH.
6.6 Step 6
Go to 'bin' folder and run the VMS deployer by running the following command:
$> ./deployvms
This will install and deploy the following:
• VMS stored procedures
• VMS Web services
• VMS UI
6.7 Step 7
Verify on the Tomcat admin screen that the VMSUI and VMS Web services applications are deployed.
6.7.1 Verify VMS UI and Apache Axis
Enter the following URL in the browser to verify that the VMS UI and Apache Axis are deployed and are
running:
http://127.0.0.1:8080/manager/html/list
Specify the Tomcat manager user name and password, when prompted.
Replace 127.0.0.1 with the IP address or machine name where Tomcat server is running.
Replace 8080 with the port number where Tomcat server is running.

6.7.2 Verify VMS W
V Web servicess
Enter the following UR
RL in the brow
wser to verify that the VMSS Web servicees are deployed:
htttp://127.0.0.1:8080/axis//servlet/AxisSServlet
he Tomcat maanager user name and password, when prompted.
Specify th
Replace 127.0.0.1 with the IP address orr machine nam
me where Tomcat server iis running.
with the portt number wheere Tomcat seerver is running.
Replace 8080 w
C
Copyright© 2
7

6.8 Im
mportant UR
RLs
• URL to access V VMS Web serrvices
http://<to omcat host tname>:<tomcat porrt>/axis/s
services/VMS
7.0.0.1:8080/axis/service/V
e..g. http://127 VMS
• URL to access V VMS UI
http://<to omcat host tname>:<tomcat
port>/VMSU UI/static/ /com.opasa.vms.VMSS/VMS.html
l
7 Ope
erational considerration

In
nstallation of the followingg software pro
oducts and co
omponents are out‐of‐sco
ope for this
doocument:
• RedHaat Linux
• Sun JDDK
• Oraclee 10g databasse server
• Apache Tomcat serrver
• Perl
Followingg operational consideration
ns must be m
made for manaaging the VMS application:
• Any change to the VMS Datta source con nfiguration will require resttarting the fo
ollowing:
o Apache Tomcat serrver
• Restarting VMS database seerver will require restartin
ng the following:
o Apache Tomcat serrver
o GenerateBatch.PL
C
Copyright© 2
8

• Changing the database connectivity information (machine/port number/database name/user
name/password/etc. changes) will require the following to be modified:
o <CATALINA_HOME>\conf\Catalina\localhost\axis.xml file
o TWO_TASK environment variable if the database URL is changed
o DB_USER_NAME environment variable if the user name is changed
o DB_PASSWORD environment variable if the password is changed
8 Web services interface
This section describes the Web service interface in detail. It describes the services exposed by VMS, the
parameter details and the rules related to each of the services, if any.
8.1 Single voucher
VMS provides a Web service, which allows the caller to request a single voucher from VMS. The Web
service places an order in the VMS, which generates a voucher and returns the information about the
newly generated voucher to the caller. The voucher generation is in real‐time.
VMS provides the following Web service to request for a single voucher:
VoucherData requestSingleVoucher( int voucherProductId,

int providerId,
int distributorId,
double voucherDenomination,
String orderDesc,
Calendar voucherExpirationDate)
Input parameter summary
Parameter Description Mandatory?

voucherProductId Id of the product for which a voucher is to be Yes
generated
providerId Id of the provider whose distributor is placing the Yes
request
distributorId Id of the distributor who is placing the request Yes
voucherDenomination Voucher denomination Yes
e.g. $39.99
orderDesc Description of the order being placed Yes
voucherExpirationDate Date on which the voucher will expire No

If the caller does not specify this parameter value,
VMS reads the configured
VOUCHER_VALIDITY_PERIOD system parameter and
calculates the voucher expiry date

e.g. the caller does not specify this parameter value
and if the VOUCHER_VALIDITY_PERIOD system
parameter value is configured as 90D then the VMS

calculated expiry date will be:
today’s date + 90 days

Output parameter summary
Parameter Description
VoucherData Information about the newly generated voucher

Following information is part of the VoucherData:
• serial number
• pin number
• denomination (face value)
• talk value
• service charge
• tax amount
• expiry date
• distributor id, for whom the voucher was generated
• distributor description, for whom the voucher was generated
• batch id, part of which the voucher was generated
In case a single pin was requested by calling the above
mentioned Web service, this method will return 0, which
means the voucher was not generated as part of a batch
request
• batch description
• unique identifier order id identifying the order, which is placed
by the distributor
• order description

8.2 Batch voucher request
VMS provides a Web service, which allows the caller to place a request for batch voucher generation
from VMS. The Web service places an order in the VMS and returns the information about the newly
generated order id to the caller. The voucher generation mode is batch.
VMS provides the following Web service to place a request for batch voucher generation:
long requestBatchVoucher( int providerId,

int distributorId,
BatchData[] batchRequests,
String orderDesc)


providerId Id of the provider whose distributor is placing the Yes

request
distributorId Id of the distributor who is placing the request Yes
batchRequests An array of BatchData. Each element represents a Yes
batch informarion, like, the product for which the
batch request is being placed, the denomination,
number of vouchers, etc

The array must contain at least one entry

BatchData will have the following detail:
• id of the product for which a voucher batch
request is placed
• description identifying a batch
• number of vouchers in a batch
• denomination of the vouchers in a batch
• expiry date of the vouchers in a batch
orderDesc Description of the order being placed Yes

The Web service returns the unique identifier identifying the newly placed order.
8.3 Validate voucher
VMS provides a Web service, which allows the caller to check if a voucher is valid. The Web service
validates the voucher based on the rules in the VMS and returns a value to the caller saying whether the
voucher is valid or not.
Following rules are used to validate a voucher:
• If the specified distributor id matches with the voucher distributor id in VMS
• And, if the voucher is either in ACTIVATED or SOLD status
• And, if the voucher expiry date is either after today date or null (never expires)
• And, if the voucher redeem date is either after today date or null
• And, if the voucher product end date is either after today date or null
Then, the voucher is considered to be valid.
VMS provides the following Web service to validate a voucher:
boolean validateVoucher( long voucherSerialNbr,

String voucherPIN,
int distributorId)

voucherSerialNbr Serial number of the voucher, which is to be No

validated

This parameter is mandatory if voucherPIN is not
specified by the caller
voucherPIN Pin number of the voucher, which is to be validated No

This parameter is mandatory if the voucherSerialNbr
is not specified by the caller
distributorId Distributor id for which the voucher serial/pin Yes
number is to be validated

The Web service returns the unique identifier identifying the newly placed order.
8.4 Get voucher detail
VMS provides a Web service, which allows the caller to read the voucher detail.
VMS provides the following Web service to get a voucher detail:
VoucherData getVoucherDetail( long voucherSerialNbr,

String voucherPIN)


voucherSerialNbr Serial number of the voucher, which is to be No
validated

This parameter is mandatory if voucherPIN is not
specified by the caller

The caller must pass 0 for this field, if it doesn’t want
to specify the serial number
voucherPIN Pin number of the voucher, which is to be validated No

This parameter is mandatory if the voucherSerialNbr
is not specified by the caller

The caller must pass null or “” for this field, if it
doesn’t want to specify the pin number

Parameter Description

VoucherData Information about the voucher

8.5 Update voucher status
A voucher in the VMS system has a life cycle. During the life cycle, it moves from one state to another.
Following diagram shows the valid state transitions for a voucher in VMS:
Refer to section 3.8.2 for the voucher statuses and valid transitions.
The state transition is not automatic in VMS. OPASA VMS™ does not provide a background job which
can be scheduled to change the voucher statuses. The new status must be passed by the caller and VMS,
based on the above shown transition diagram, decided whether the transition from the old state to the
new state is permitted.
VMS provides a Web service, which allows the caller to update a voucher status/state. The Web service
checks if the transition from old state to the new is valid based on the rules in the VMS and returns a
flag indicating whether the status update was successful.
VMS provides the following Web service to update a voucher status:
boolean updateVoucherStatus( long voucherSerialNbr,

String voucherPIN,
long voucherOrderId,
int voucherBatchId,
int newVoucherStatus)


voucherSerialNbr Serial number of the voucher, whose status is to be Yes
updated.

This parameter is mandatory if neither the
voucherPIN is specified nor the voucherOrderId and
voucherBatchId is specified by the caller.
In case this parameter is not being passed, then
number zero (0) must be passed as default value.
voucherPIN Pin number of the voucher, whose status is to be No
updated

voucherSerialNbr nor the voucherOrderId and
voucherBatchId is specified by the caller
voucherOrderId Order id of the vouchers, whose status is to be Yes
updated


voucherSerialNbr nor the voucherPIN is specified by
the caller.
If, only, voucherOrderId is specified then status of all
the vouchers in the specified order is updated.
voucherBatchId Batch id of the vouchers, whose status is to be Yes
updated

voucherBatchId must be specified along with the
voucherOrderId
If specified, the status of all the vouchers in the
specified order id and batch id is updated.
newVoucherStatus New status of the voucher Yes

Following are the possible values for this parameter:
• EnumVoucherStatus.CREATED
• EnumVoucherStatus.DISTRIBUTED
• EnumVoucherStatus.ACTIVATED
• EnumVoucherStatus.SOLD
• EnumVoucherStatus.REDEEMED
• EnumVoucherStatus.CANCELLED
• EnumVoucherStatus.EXPIRED
• EnumVoucherStatus.UNREDEEMED
• EnumVoucherStatus.QUEUEDFORPURGING

The Web service returns flag indicating whether the voucher status is updated successfully in VMS.
9 File based interface
For the batch voucher requests, VMS produces one or more Comma Separated Values (csv) files. These
files can be retrieved by any 3rd party system for further processing, such as, transforming it to a
different format, encryption, sending mails, sending SNMP trap messages, etc.
9.1 Voucher file
When a distributor places a request for batch voucher generation, VMS background processes that
request and creates one or more output batch files for that distributor.
The file has the following format:

Serial Row type Description Occurrence
1 Header Header row 1
2 Body Body 1..n
containing
the voucher N is decided based on the
pin and number of records, which can
serial be stored in a file. This is
number configured in VMS as
MAX_RECORDS_IN_BATCH_FILE
system parameter. Default
value is 50000
3 Trailer Trailer row 1

If number of vouchers requested by a distributor in a batch is <= value of
MAX_RECORDS_IN_BATCH_FILE system parameter, a single file is created by VMS for the distributor.
If number of vouchers requested by a distributor in a batch is > value of MAX_RECORDS_IN_BATCH_FILE
system parameter, multiple files are created by VMS each having a maximum of
MAX_RECORDS_IN_BATCH_FILE records. In this case, a serial number is appended to the file name to
identify the sequence in which the files are generated.
9.1.1 File naming convention
The batch voucher files are generated and stored, by VMS, at the location specified by the
BATCH_FILE_OUTPUT_FOLDER VMS system parameter. E.g. if the system parameter is set to
/opt/vms/data then the batch files will be stored in /opt/vms/data directory.
For each distributor, VMS creates a directory with distributor name under the
BATCH_FILE_OUTPUT_FOLDER directory. Under the distributor specific directory, VMS stores all the
batch voucher files related to that distributor. E.g. for the BSNL distributor, VMS will store the file under
the /opt/vms/data/BSNL directory.
Following is the VMS batch voucher file naming convention:
VMS_<voucher order id>_<batch id>[_serial number].<extension>
File extension (<extension>) is decided based on the BATCH_OUTPUT_FILE_EXTN VMS system
parameter. Serial number is applicable only if more than one file is generated for a distributor. E.g. if for
a distributor only one file is generated for an order id 108 and batch id 1, the file name will be
VMS_108_1.csv and the absolute path of the file will be /opt/vms/data/BSNL/VMS_108_1.csv. If two
files are generated for order id 108 and batch id 2, following will be the file name of the two files:
VMS_108_2.csv
VMS_108_2_2.csv
and, the absolute file names will be:
/opt/vms/data/BSNL/VMS_108_2.csv

/opt/vms/data/BSNL/VMS_108_2_2.csv
9.1.2 File format
This section describes, in detail, the batch voucher file format.
9.1.2.1 Header

Serial Field name Field description Field type Min, Mandatory Sample data

Max
length
1 Header Character indicating that N/A 1,1 Yes H
indicator the row is a header row
2 Voucher Expiration date of the Date 8,8 Yes 20080925
expiration voucher
date Format of
If expiration date is not this field is
available in VMS, this field YYYYMMDD
will have a value of
99999999
3 Voucher Status of the voucher Enumerator 1,1 Yes 1
status
1 – CERATED
2 – DISTRIBUTED
3 – ACTIVATED
4 – SOLD
5 – REDEEMED
6 ‐ CANCELLED
7 ‐ EXPIRED
8 ‐ UNREDEEMED
9 ‐ QUEUEDFORPURGING
4 Voucher Order id as part of which Numeric 3,19 Yes 108
order id the voucher is generated
5 Batch id Batch id for part of which Numeric 1,10 Yes 1
the voucher is generated

For a single voucher this
field value will be 0
6 Batch Denomination of the Double 1,20 Yes 39.99
denomination vouchers in the file
7 Batch request Indicator showing String 1,1 Yes Y
indicator whether the voucher was
generated as part of a
batch or not

For single voucher
requests, this field value

will be N
8 Voucher Time the voucher order Date & time 17,17 Yes 20080925 10245934
order created was created in VMS
time system Format of
this field is
YYYYMMDD
HHMMSSss
9 ABN Distributor ABN number Numeric 1,10 Yes 670338632
10 Distributor Distributor name String 1,45 Yes BSNL
name
11 Distributor Status of the distributor Enumerator 1,1 Yes 1
status
1‐active
2‐inactive
3‐queuedforpurging
12 Credit limit Distributor’s current Numeric 1,10 Yes 34598.23
credit limit
13 Contact name Distributor’s primary String 45 Yes Sunil Kumar
contact person name
14 Provider Provider name String 45 Yes OXYGEN
name
15 Contact name Provider’s primary String 45 Yes Perry Murthy
contact person name
16 Product Voucher product name String 45 Yes BSNL_REJOICE
name for which the voucher is
generated
17 Product face Face value of the voucher Double 1,20 Yes 500
value product
18 Product talk Talk value of the voucher Double 1,20 Yes 375
value product
19 Product Service charge applicable Double 1,20 Yes 12
service to the product
charge (in percentage)
20 Tax Tax applicable to the Double 1,20 Yes 8
product (in percentage)
21 Product start Effective date of the Date 8,8 Yes 20080101
date voucher product
Format of
this field is
YYYYMMDD
22 Product end Expiry date of the voucher Date 8,8 Yes 20081231
date product
Format of
If expiration date is not this field is
available in VMS, this field YYYYMMDD
will have a value of

99999999
23 Product Validity extension Numeric 1,10 Yes 12
validity applicable to the voucher (in months)
extension product

9.1.2.2 Body

Serial Field name Field Field type Min, Max Mandatory Sample data

description length
1 Voucher PIN Pin number String 10,10 Yes 6198308864
number
The length is
dependent
upon the
length of the
PIN a
distributor
requests for
2 Voucher Serial Numeric 1,19 Yes 65479
serial number
number

9.1.2.3 Trailer

Serial Field name Field Field type Min, Max Mandatory Sample data

description length
1 Trailer Indicator 1,1 Yes T
indicator showing
that the row
in the file is
a trailer
2 Number of Total Numeric 1,10 Yes 50000
records number of
records in Max. length is
the file dependent
upon the pin
length a
distributor
requests for
3 Current date Date on Date 8,8 Yes 20080521
which the
file is Format of this
generated field is

YYYYMMDD
4 Current time Time on Time 6,9 032744001
which the
file is The length will
generated vary based on
the fraction of
seconds

Format of this
field is
HHMMSS[ssss]
10 User Interface
10.1 URL
Following is the URL to launch the VMS UI in the browser:
http://< address>:<port number>/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.2 Browser specification
A browser is a program that allows you to access pages on the World Wide Web. The Portal and Web
Administration applications were developed to specifically take advantage of features available within
Internet Explorer 6.0 or higher. Other browsers, such as Mozilla FireFox and Netscape, are not certified
at this time.

You can download the latest version of Internet Explorer, free of charge, at
http://www.microsoft.com/windows/ie/downloads/default.mspx

10.3 Pop‐up blockers
If you have a pop‐up blocker installed, you will need to allow pop‐ups from the OPASA VMS™ Web site.
If you do not have a pop‐up blocker installed, you can skip to the next section.

To allow pop‐ups from the OPASA VMS™ Web site using Internet Explorer 6.0, follow these procedures:

Step 1: Click on Tools ‐> Internet options… menu in Internet Explorer


Step 2: Click on the Privacy tab

Step 3: Click on Settings button in the Pop‐up Blocker sub‐panel. Specify the VMS UI URL in the Address
of Web site to allow text area and click on Add button to add it to the Allowed sites list


10.4 Maain screen llayout
Followingg is the layoutt of the VMS sscreen:
C
Copyright© 2
1

10.5 Naavigation Bar
Follo
owing is the laayout of the N
Navigation baar:
The N
Navigation baar has the folllowing main m
menu items:
• Manage d distributor – TThis menu iteem will be useed to Add, Mo odify, or Remove a distribu utor

to/from the VMS systeem. It has thee following sub‐menu items:
o Add – This opt
A distributor to the VMS systtem
tion will be ussed to add a d
o Modify – This
M option will bee used to moddify an existin
ng distributorr in the VMS
syystem
o Remove – Thiss option will b be used to remmove an existting distributor from the VVMS
syystem
• Request vvoucher – This menu item will be used tto place a single or batch vvoucher requ uest.
It has the following sub b‐menu items:
o Siingle – This option will be used to placee an order to the VMS systtem to generaate a
siingle voucherr
o Batch – This op ption will be used to placee a batch ordeer to the VMSS to generate bulk
voouchers
• Order dettail – This opttion will be ussed to view order detail foor a distributo
or.
• Product ddetail – This option will be used to view w a product deetail.
• Provider d detail – This o
option will bee used to view
w a provider d detail.
10.6 Ad
dd distributtor screen
10.6.1 Layout
ws the user to
This screen allow o enter a distributor detail and create tthe distributo
or in the VMS.
C
Copyright© 2
2

10.6.2 Description
D
Label Description Type Validattion Defaault Manndatory
Name Specifies Text field: Value iss Non
ne Yes
the max. 45 alphanumeric
distributorr characterrs,
name alphanum meric
Description
n Specifies Text area: None Non
ne Yes
the max. 255
distributorr characterrs,
description n any text
Voucher Displays thhe List: max 80 None Defaault Yes
algorithm list of characterrs algoorithm
algorithmss, conffigured
which can in th
he
be used to o VMSS
generate system
the vouche er
for the
particular
distributorr
ABN ABN Text field: None Non
ne Yes
Number off
the
distributorr
Address Address linne Text field: None Non
ne Yes
line‐1 1 for the max. 255
C
Copyright© 2

distributor characters
address
Address Address line Text field: None None Yes
line‐2 2 for the max. 255
distributor characters
address
Zip code Zip code Text field: Value is None Yes
max. 10 numeric
characters,
numeric
Contact Name of the Text field: Alphabets None Yes
name primary max. 45
contact characters,
person of alphabets
the
distributor’s
organisation
Contact Contact Text field: Value is None No
number number of max. 20 numeric
the primary characters and/or
contact following
person special
characters:
Hyphen (‐),
plus sign (+)
E‐mail E‐mail id of Text field: Value None No
the primary max. 45 matches with
contact characters the e‐mail
person format (e.g.
abc@xyz.com)
Credit limit Credit limit Text field: Value is 0.00 Yes
of the Number, long numeric and
distributor. up to 2
This is used decimal
when a places
distributor
places a
voucher
request to
verify that
the
distributor
has
sufficient
credit
Available Displays the Multi‐ None List of Yes
products list of selection list products
products
available at
the provider
level in the
system

Distributor Displays the Multi‐ At least one Empty list Yes
products list of selection list entry must
products exist
selected
from the list
of ‘Available
products’
and added
to the
distributor
Add Adds a Button None N/A N/A
distributor distributor
to VMS
Reset Clears all Button None N/A N/A
the fields of
the Add
distributor

10.6.3 Navigation path
Following is the navigation path for the ‘Add distributor’ screen:
• Manage distributor ‐> Add
10.7 Modify distributor screen
This screen allows the user to modify distributor information in the VMS.

10.7.1 Layout
10.7.2 Description
D
Label Description Type Validatio
on Defau ult Manddatory
Distributorr Displays th
he List None The first Yes
list of entryy in the
distributorr sorted list
names, wh hich
C
Copyright© 2
6

are active in
VMS. This list
of distributor
names is
sorted
alphabetically
Status Displays the List None The Yes
list of current
possible status of
distributor the
statuses. distributor
Description Specifies the Text area: None Description Yes
distributor max. 255 of the
description characters, selected
any text distribution
Voucher Displays the List: max None Algorithm Yes
algorithm list of 80 name
algorithms, characters associated
which can be with the
used to selected
generate the distributed
voucher for
the particular
distributor
ABN ABN Number Text field: None ABN of the Yes
of the selected
Address Address line Text field: None Address Yes
line‐1 1 for the max. 255 line 1 of
distributor characters the
address selected
distributor
Address Address line Text field: None Address Yes
line‐2 2 for the max. 255 line 2 of
distributor characters the
address selected
distributor
Zip code Zip code Text field: Value is Zip code of Yes
max. 10 numeric the
characters, selected
numeric distributor
Contact Name of the Text field: Alphabets Primary Yes
name primary max. 45 contact
contact characters, name of
person of the alphabets the
distributor’s selected
organisation distributor
Contact Contact Text field: Value is Primary No
number number of max. 20 numeric contact
the primary characters and/or number of
contact following the
person special selected

characters: distributor
Hyphen (‐),
plus sign (+)
E‐mail E‐mail id of Text field: Value E‐mail id of No
the primary max. 45 matches with the
contact characters the e‐mail selected
person format (e.g. distributor
abc@xyz.com)
Credit limit Credit limit of Text field: Value is Credit limit Yes
the Number, numeric and of the
distributor. long up to 2 selected
This is used decimal distributor
when a places
distributor
places a
voucher
request to
verify that
the
distributor
has sufficient
credit
Available Displays the Multi‐ None List of Yes
products list of selection products
products list OR empty
available at list
the provider
level in the
system
Distributor Displays the Multi‐ At least one List of Yes
products list of selection entry exists products
products list which were
selected from added to
the list of the
‘Available distributor
products’ and
added to the
distributor
Modify Modifies a Button None N/A N/A
information
in VMS
Reset Clears all the Button None N/A N/A
fields of the
Add
distributor

Following is the navigation path for the ‘Modify distributor’ screen:

• M
Manage distrib
butor ‐> Modify
10.8 Reemove distrributor scrreen
This screeen allows the user to remo
ove a distributtor the VMS.
10.8.1 Layout
10.8.2 Description
D
Label Description Type Validatio
on Defau ult Manddatory
Distributorr Displays th
he List None The first Yes
list of entryy in the
distributorr sorted list
names, wh hich
are active in
VMS. This list
of distributtor
names is
sorted
alphabetically
Remove Deletes the e Button None N/A N/A
distributorr
from the
VMS

10.8.3 Navigation p
N ath
Followingg is the navigaation path forr the ‘Removee distributor’ screen:
• M
Manage distrib
butor ‐> Remove
10.9 Reequest single voucherr screen
This screeen allows the user to placee a request for a single vou
ucher.
C
Copyright© 2
9

10.9.1 Layout
10.9.2 Description
D
Label Descrip ption Type e Validaation Defaault Manddatory
Provider Displayss the List None The first Yes
list of entryy in
provide er the ssorted
names iin the list
system. This
list of
provide er
names iis
sorted
alphabe etically
Distributorr Displayss the List None The first Yes
list of entryy in
distributor the ssorted
names iin the list
system. This
list of
provide er
names iis
sorted
alphabe etically
Order Specifie es the Text area: None Nonee No
n
description descripttion max. 255
about th he charaacters
order being
placed ffor
generatting
Product Displayss the List None The first Yes
list of product entryy in
C
Copyright© 2
0

names in the the sorted
system. This list
list of product
names is
sorted
alphabetically
Denomination The voucher Text field: Value is The Yes
denomination Number numeric and product
up to 2 face value,
decimal which is
places related to
the
product
selected in
the
‘Product
name’ list
Expiry date The voucher Text field: Date with Expiry Yes
expiry date Date format date
dd/mm/yyyy calculated
or based on
mm/dd/yyyy the expiry
depending period
upon the configured
format in the
configured VMS
in the VMS system
system
Generate Generates Button None N/A N/A
voucher the voucher
in the VMS
Reset Cancels the Button None N/A N/A
voucher
generation. It
clears

Following is the navigation path for the ‘Request single voucher’ screen:
• Request voucher ‐> Single
10.10 Request batch vouchers screen
This screen allows the user to place a batch request for bulk voucher generation.

10.10.1 Layou
ut
10.10.2 Descrription
Label Descrip ption Type e Validaation Defaault Mandatory
Provider Displayss the List None The first Yes
list of entrry in
provide er the sorted
names iin the list
system. This
list of
provide er
names iis
sorted
alphabe etically
Distributorr Displayss the List None The first Yes
list of entrry in
distributor the sorted
C
Copyright© 2
2

names in the list
system. This
list of
provider
names is
sorted
alphabetically
Order Specifies the Text area: None None No
description description max. 255
about the characters
order being
placed for
generating
Product Displays the List None The first Yes
list of product entry in
names in the the sorted
system. This list
list of product
names is
sorted
alphabetically
Number of Specifies the Text field: Value is None Yes
vouchers number of Number numeric
vouchers to with no
be generated decimal
places and
value > 1
Denomination The voucher Text field: Value is The Yes
denomination Number numeric and product
up to 2 face value,
decimal which is
places related to
the
product
selected in
the
‘Product
name’ list
Expiry date The voucher Text field: Date with Expiry Yes
expiry date Date format date
dd/mm/yyyy calculated
or based on
mm/dd/yyyy the expiry
depending period
upon the configured
format in the
configured VMS
in the VMS system
system
Description Batch Text area: Value is not None Yes
description max. 255 empty
characters

Add to ord
der Adds the Combo At leaast one N/A N/A
batch detail box entry exists
to the ‘OOrder in thee ‘Order
details’ table detaills’ table
Order detaails Displayss the Tablee None Non
ne N/A
list of baatches
detail added
to the oorder
X Remove es the Butto
on None Non
ne N/A
corresponding
batch entry
from the
‘Order d details’
table
Place order Adds the on
Butto None N/A N/A
voucherr batch
order inn the
VMS
Reset Resets tthe Butto
on None N/A N/A
fields

10.10.3 Naviggation path
Followingg is the navigaation path forr the ‘Requestt batch vouch
her’ screen:
• Request vouch
her ‐> Batch
10.11 Provider de
P etail screen
n
This screeen allows the user to view a provider deetail.
10.11.1 ut
Layou
C
Copyright© 2
4

10.11.2 Description
Label Description Type Validation Default Mandatory
Provider Displays the List None The first Yes
list of entry in
provider the sorted
names in the list
system. This
list of
provider
names is
sorted
alphabetically
Name Displays the None None None N/A
provider
name of the
selected
provider
Description Displays the None None None N/A
provider
description of
the selected
provider
Address line‐ Address line 1 None None None N/A
1 of the
selected
provider
Address line‐ Address line 2 None None None N/A
2 of the
selected
provider
Zip code Zip code of None None None N/A
the selected
provider
Contact name Primary None None None N/A
contact name
of the
selected
provider
Contact Primary None None None N/A
number contact
number of the
selected
provider
E‐mail E‐mail of the None None None N/A
selected
provider
Product detail Displays the Table None None N/A
table ‘Product’ and
the
corresponding
‘Description’

of all the
productts the
provider has
Distributorr Displayss the Tablee None At leeast N/A
detail tablee ‘Distribuutor’ one entry
and the existt
corresponding
‘Descripption’
of all the
distributors
the provvider
has

10.11.3 Naviggation path
Followingg is the navigaation path forr the ‘Provider detail’ screeen:
• Provider detail
10.12 Product det
P tail screen
This screeen allows the user to view a product deetail.
10.12.1 ut
Layou
10.12.2 Descrription
Label Descripttion Type e Validaation Defaault Manddatory
Provider Displayss the List None ‐All‐ Yes
list of
provider
names in the
system. This
C
Copyright© 2
6

list of
provider
names is
sorted
alphabetically
Distributor Displays the List None ‐All‐ Yes
list of
distributor
names in the
system, for
the selected
provider. This
list of
distributor
names is
sorted
alphabetically
Product Displays the List None The first Yes
list of entry in
products in the sorted
the system for list
the selected
provider. This
list of product
names is
sorted
alphabetically.
Name Name of the None None None N/A
selected
product
Description Description of None None None N/A
the selected
product
Face value Face value of None None None N/A
the selected
product
Talk value Talk value of None None None N/A
the selected
product
Service Service charge None None None N/A
charge of the
selected
product
Tax Tax set for the None None None N/A
selected
product
Start date Effective date None None None N/A
of the
selected
product
End date End date of None None None N/A
the selected

product
Validity Extension None None None N/A
extension period of the
selected
product

Following is the navigation path for the ‘Add distributor’ screen:
Product detail
10.13 Order detail screen
This screen allows the user to view the order detail, which is placed by a distributor for a provider.
10.13.1 Layout

10.13.2 Description
Label Description Type Validation Default Mandatory
Distributor Displays the List None The first Yes
list of entry in
distributor the sorted
names in the list
system. This
list of
distributor
names is
sorted
alphabetically
Provider Displays the List None The first Yes
list of entry in
provider the sorted
names in the list
system. This
list of
provider
names is
sorted
alphabetically
Orders per Specifies the Text field: 1=< Value 10 Yes
page number of numeric, <= 100
orders detail max. 3
to be characters
displayed on
one page
Get order Reads the Button None None N/A
detail orders detail
for the
selected
distributor
and the
provider
Order ##### Displays the Table None The order N/A
individual table is
order detail, not visible
which were
placed by the
selected
distributor for
the selected
provider
Next> Takes the user Hyperlink None Clickable if N/A
to the next the
order detail number of
page orders
returned
by the
VMS
system >

Orders per
page
ELSE
Not
clickable
<Prev Takes the user Hyperlink None Not N/A
to the clickable
previous
order detail
page

Following is the navigation path for the ‘Order detail’ screen:
• Order detail
11 Troubleshooting
11.1 Log files
• VMS UI and Web services append their log messages to <CATALINA_HOME>\logs\stdout.txt file.
In case of error, this file would be referred to see the detail about the error/exception.
• GenerateBatch.PL job creates a log file in the directory configured by environment variable
BATCH_JOB_LOG_DIR. The log file name format is BatchLogs_<current date>_<current
time>.LOG. It contains information about all the Voucher ID and Batch ID being processed during
this run. In case, this job exits with non‐zero exit status, the operator must look into the log file
to understand the reason for failure.
11.2 Error codes and messages
Code Message
11001 Failed to add distributor in VMS
11002 Failed to get distributor(s) detail from VMS
11003 Failed to mark the distributor as removed in VMS
11004 Failed to modify the distributor in VMS
11005 Failed to get the order detail from VMS
11006 Failed to get the voucher detail from VMS
11007 Failed to get the voucher product detail from VMS
11008 Invalid voucher status
11009 Missing algorithm in VMS
11010 Missing distributor in VMS
11011 Failed to read sequence
11012 One or more parameter values are missing or invalid
11013 Failed to update the voucher status in VMS

11014 Missing system parameter in VMS
11015 Invalid system parameter
11016 Failed to add mapping between provider and distributor
11017 Failed to read record from database
11018 The distributor has insufficient credit
11019 Failed to read distributor credit limit from VMS
11020 Failed to retrieve algorithm used by the distributor to generate vouchers
11021 Failed to create voucher order request
11022 Failed to create voucher into the database
11023 Failed to update voucher generation algorithm information
11024 Failed to read order and batch information
11025 The entered pin information is incorrect
11026 Failed to create batch for this order
11027 Failed to retrieve order details for the given order and distributor information
11028 Failed to close database prepared statement
11029 Failed to read voucher order from VMS
11030 Failed to read voucher detail from VMS
11031 Failed to update distributor credit limit
11032 Failed to read voucher data
11033 The custom attribute to generate random number is not valid
11034 Failed to remove mapping between distributor and product
11035 Failed to add mapping between distributor and products
11036 Failed to retrieve voucher product information
11037 Failed to create voucher in the VMS system
11038 The batch record for the given batch information does not exist in the VMS system
11039 Failed to get the products for distributors
11040 Failed to get the products for providers
11041 Failed to get the distributors for provider
11042 Failed to get the provider detail
11043 Failed to read the provider name and id information
11044 Failed to read the distributor name and id information
11045 Failed to read the distributor status name and id information
11046 Failed to read the voucher product name and id information
11047 Failed to read the algorithm name and id information
11048 Failed to read the voucher status name and id information
11049 Failed to read the batch status name and id information
11050 Error getting the database connection
11051 Problem encountered while executing the stored procedure
The current voucher status does not allow system to move its status to the entered new
11052 voucher status because it violates voucher life cycle
11035 Failed to add mapping between distributor and products
2001 Failed to create batch file

2002 Unable to open file <batch file name> for writing
2003 Failed to fetch rows from VMS database
2004 Failed to update row in VMS database
2005 Failed to retrieve distributor for VOUCHERORDER_ID = <order id being processed>
2006 Failed to update batch status in VMS
2007 Failed to call DB function, which generates vouchers for a batch
2008 Failed to read SYSTEMPARAMSREF table for parameter name = <system parameter name>

12 Support
For more information and questions on this documents, write to support@opasasolutions.com
13 Changes
Version Date Author Description
1.0 1‐Oct‐2007 OPASA Team Initial version


Opasa Vms User Guide v1.0

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Opasa Vms User Guide v1.0

Uploaded by

Copyright:

Available Formats

Copyright© 2007 Opasa Pvt. Ltd. 2

Copyright© 2007 Opasa Pvt. Ltd. 3

Copyright© 2007 Opasa Pvt. Ltd. 4

Copyright© 2007 Opasa Pvt. Ltd. 5

Copyright© 2007 Opasa Pvt. Ltd. 6

Copyright© 2007 Opasa Pvt. Ltd. 7

VMS GUI 3rd party 3rd party

VMS UI VMS Web services

Fig: Overall architecture

Confidential & Proprietary

Copyright© 2007 Opasa Pvt. Ltd. 8

Copyright© 2007 Opasa Pvt. Ltd. 9

Copyright© 2007 Opasa Pvt. Ltd. 10

Copyright© 2007 Opasa Pvt. Ltd. 11

Copyright© 2007 Opasa Pvt. Ltd. 12

Copyright© 2007 Opasa Pvt. Ltd. 13

Copyright© 2007 Opasa Pvt. Ltd. 14

Copyright© 2007 Opasa Pvt. Ltd. 15

Voucher n....1 Batch

Copyright© 2007 Opasa Pvt. Ltd. 16

3.11.2 Siingle Vouch her Generatiion

Step 3 Click o on. VMS geneerates the voucher and dissplays the vou

$> nohup ./GenerateBatchVoucher_V1.1.PL

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

Copyright© 2007 Opasa Pvt. Ltd. 19

Parameter name Description Default value

Variable name Description Default value

<Resource name="jdbc/vmsdb" type="javax.sql.DataSource"/>

Copyright© 2007 Opasa Pvt. Ltd. 22

Copyright© 2007 Opasa Pvt. Ltd. 23

Copyright© 2007 Opasa Pvt. Ltd. 24

Copyright© 2007 Opasa Pvt. Ltd. 25

Copyright© 2007 Opasa Pvt. Ltd. 26

VoucherData requestSingleVoucher( int voucherProductId,

Parameter Description Mandatory?

Copyright© 2007 Opasa Pvt. Ltd. 29

long requestBatchVoucher( int providerId,

Parameter Description Mandatory?

Copyright© 2007 Opasa Pvt. Ltd. 30

boolean validateVoucher( long voucherSerialNbr,

Parameter Description Mandatory?

Copyright© 2007 Opasa Pvt. Ltd. 31

VoucherData getVoucherDetail( long voucherSerialNbr,

Parameter Description Mandatory?

Copyright© 2007 Opasa Pvt. Ltd. 32

boolean updateVoucherStatus( long voucherSerialNbr,

Parameter Description Mandatory?

Copyright© 2007 Opasa Pvt. Ltd. 33

Copyright© 2007 Opasa Pvt. Ltd. 34

VMS_<voucher order id>_<batch id>[_serial number].<extension>

Copyright© 2007 Opasa Pvt. Ltd. 35

Serial Field name Field description Field type Min, Mandatory Sample data

Copyright© 2007 Opasa Pvt. Ltd. 36

Copyright© 2007 Opasa Pvt. Ltd. 37

Serial Field name Field Field type Min, Max Mandatory Sample data

Serial Field name Field Field type Min, Max Mandatory Sample data

Copyright© 2007 Opasa Pvt. Ltd. 38

Copyright© 2007 Opasa Pvt. Ltd. 39

Copyright© 2007 Opasa Pvt. Ltd. 40

• Manage d distributor – TThis menu iteem will be useed to Add, Mo odify, or Remove a distribu utor

Copyright© 2007 Opasa Pvt. Ltd. 44

Copyright© 2007 Opasa Pvt. Ltd. 45

Copyright© 2007 Opasa Pvt. Ltd. 47