ECE Sample Programs

23 ECE Sample Programs

You use the sample programs included in the Oracle Communications Elastic Charging Engine (ECE) SDK to learn how to call the ECE APIs.

See Elastic Charging Engine Java API Reference for more information about the ECE SDK.

Topics in this document:

About the ECE Sample Programs

The ECE SDK includes sample programs that demonstrate how to use the ECE API for sending requests to ECE.

You can use these sample programs in the following ways:

Use the sample programs as code samples for calling the ECE APIs.
Use the sample programs as code samples for writing custom applications.
Run sample programs to send requests to ECE and receive responses.

The sample programs print information about the messages exchanged.
Use the sample program scripts to get an idea of the configuration and dependencies that are required for integrating the ECE client into your build system (Maven, Ant, and so on).

You can also look at the sample program source code to see how it works. For example, if you want to write a program that sends a unit-based debit request to ECE, examine SampleDebitRefund to:

View the methods to use in your code.
How to use the libraries and calls.

Finding the Sample Programs

Table 23-1 shows the ECE SDK software directory structure, where ECE_home is the directory in which the ECE Server software is installed.

Table 23-1 Elastic Charging Engine Sample Program Directories

Directory	Description
ECE_home/ocecesdk/bin	Directories that contain shell scripts for compiling and running various types of sample programs.
ECE_home/ocecesdk/bin/extensions	Shell scripts for extension-implementation sample programs.
ECE_home/ocecesdk/bin/notification	Shell scripts for notification sample programs.
ECE_home/ocecesdk/bin/plugin	Shell scripts for the custom plug-in sample programs.
ECE_home/ocecesdk/bin/policy	Shell scripts for policy sample programs.
ECE_home/ocecesdk/bin/query	Shell scripts for query sample programs.
ECE_home/ocecesdk/bin/update	Shell scripts for update sample programs.
ECE_home/ocecesdk/bin/usage	Shell scripts for usage sample programs.
ECE_home/ocecesdk/config	Configuration files common to all sample programs.
ECE_home/ocecesdk/config/extensions	Configuration files for extension-implementation sample programs.
ECE_home/ocecesdk/source	All Java sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/extensions	Source files for extension-implementation sample programs (for pre-request-processing and post-request-processing). Includes the data loader used for extensions.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/notification	Source files for notification sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/plugin	Source files for custom plug-in sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/policy	Source files for policy sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/query	Source files for query sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/update	Source files for update sample programs.
ECE_home/ocecesdk/source/oracle/communication/brm/charging/sdk/usage	Source files for usage sample programs.

Descriptions of the Sample Programs

All of the sample programs can work with the ready-to-use sample data included with the ECE Server software installation. The sample programs are supported on the Linux platform.

Each sample program includes these supporting files:

Source files to view or modify for your own applications
Shell scripts to compile and run the sample programs

The sample programs use the generic .ecc script sdk_production_loader.ecc.

Note:

The ECE sample programs do not work well with data you load using the simulator loader utility.

For a list of each sample program, their descriptions, the shell scripts used to compile and run them, and the applicable .ecc script, see:

To determine which parameter values you must use for running a sample program, you can use the sample script's help option. For descriptions of the methods the sample programs use, see oracle.communication.brm.charging.sdk in Elastic Charging Engine Java API Reference.

Usage Request Sample Programs

Table 23-2 lists the usage sample programs, their descriptions, the shell scripts used to compile and run them, and the applicable .ecc script.

Table 23-2 ECE Sample Programs for Usage Requests

Sample Program	ECC Script	Shell Script	Description
SampleAccountingOnOff	sdk_production_loader.ecc	sample_accounting_on_off.sh	Simulates an accounting on/off request being sent from the mediation client.
SampleDataSession	sdk_production_loader.ecc	sample_data_session.sh	Simulates a simple data session, including an INITIATE, an UPDATE and a TERMINATE request.
SampleDebitRefundSession	-	sample_debit_refund_session.sh	Shows how to send debit and refund requests with multiple values in unit-based and amount-based mode. See "Example of SampleDebitRefundSession".
SampleGenericSession	-	sample_generic_session.sh	Simulates any kind of voice or data session.
SampleGprsSession	-	sample_gprs_session.sh	Simulates a GPRS session.
SampleIncrementalUsageRequestLauncher	sdk_production_loader.ecc	sample_incremental_usage_request.sh	Simulates a voice session with incremental mode.
SampleMultipleServicestLauncher	sdk_production_loader.ecc	sample_multiple_service.sh	Shows how to send usage requests for the Multiple Services Credit Control (MSCC) case (multiple subrequests are sent in a single usage request).
SamplePriceEnquiry	sdk_production_loader.ecc	sample_price_enquiry.sh	Sends a price enquiry request.
SampleReAuthRequest	sdk_production_loader.ecc	sample_RAR.sh	Sample program that shows the generation of a reauthorization request (RAR) message. Also shows how to consume notification messages. This portion of the code is for illustration only and is disabled.
SampleStartUpdateAccountingRequestLauncher	-	sample_start_update_accounting_request.sh	Simulates a sample usage session including a START_ACCOUNTING, UPDATE_ACCOUNTING, and TERMINATE request. For example, a usage session for a DSL data download in a postpaid scenario.
SampleUsageRequestLauncher	sdk_production_loader.ecc	sample_usage_request.sh	Enables you to send custom voice usage requests. Customer ID, number of requests to send, request type (INITIATE/UPDATE...) and duration must be given as arguments (e.g. sample_usage_request.sh run 6500000000 2 TERMINATE 120).
SampleVoiceSession	sdk_production_loader.ecc	sample_voice_session.sh	Simulates a simple voice session, including an INITIATE, an UPDATE and a TERMINATE request.

Update Request Sample Programs

Table 23-3 lists the update sample program.

Table 23-3 ECE Sample Programs for Update Requests

Sample Program	ECC Script	Shell Script	Description
SampleExternalTopUpRequestLauncher	-	sample_external_topup_notification_request.sh	Shows how third party systems can perform direct top ups in ECE.

Policy Request Sample Programs

Table 23-4 lists the policy sample programs.

Table 23-4 ECE Sample Programs for Policy Requests

Sample Program	ECC Script	Shell Script	Description
SamplePolicySessionRequestLauncher	-	sample_policy_session_request.sh	Simulates a policy session. Shows how to send a policy request to ECE that requests both Sp and Sy information.
SampleSpendingLimitReportRequestLauncher	-	sample_spending_limit_report_request.sh	Simulates a policy Sy query request. Shows how to send a request to retrieve policy counter status information.
SampleSubscribeNotificationRequestLauncher	-	sample_subscribe_notification_request.sh	Simulates a policy Sp query request. Shows how to send a request to retrieve the value for a specified set of subscriber preferences and subscribe for receiving notifications when the values of the preferences change. For example, shows how to retrieve the channel a subscriber prefers for receiving policy-related notifications (SMS or email) or the language in which the subscriber prefers the notification to be written (French, English).
SampleSubscriberPreferenceUpdateRequestLauncher	-	sample_subscriber_preference_update_request.sh	Simulates a policy-related update request. Shows how to update the subscriber preferences in ECE.
SampleUserDataRequestLauncher	-	sample_user_data_request.sh	Simulates a policy Sp query request without subscription. Shows how to send a request to retrieve the values for subscriber preferences configured for a customer's service.

Query Request Sample Programs

Table 23-5 lists the query sample programs.

Table 23-5 ECE Sample Programs for Query Requests

Sample Program	ECC Script	Shell Script	Description
SampleAuthenticationQuery	sdk_production_loader.ecc	sample_auth_query_request.sh	Sends an authentication query request.
SampleBalanceQueryRequestLauncher	sdk_production_loader.ecc	sample_balance_query_request.sh	Sends a balance query request.

Extension Implementation Sample Programs

Table 23-6 lists the extension sample programs.

Table 23-6 ECE Sample Programs for Extension Implementations

Sample Program	ECC Script	Shell Script	Description
-	-	sample_extensions_loader	Data loader for extension implementations.
-	-	build_deploy_extension	Sample extension implementation.
-	-	tax_configuration.spec	Sample extension implementation.
-	-	tax_configuration_data.csv	Sample extension implementation.

Notification Sample Programs

Table 23-7 lists the notifications sample programs.

Table 23-7 ECE Sample Programs for Notifications

Sample Program	ECC Script	Shell Script	Description
SampleDurableJmsClient	-	sample_durable_jms_client.sh	Simulates a durable JMS client.
SampleJmsClient	-	sample_jms_client.sh	Simulates a JMS client.
SampleJmsServer	-	sample_jms_server.sh	Simulates a JMS server.

Custom Plug-In Sample Programs

Table 23-8 lists the custom plug-in sample programs.

Table 23-8 ECE Sample Programs for Custom Plug-In

Sample Program	ECC Script	Shell Script	Description
SampleRatedEventFormatterCustomPlugin	-	build_deploy_plugin.sh	Writes rated events into CDR records.
SampleRatedEventFormatterKafkaCustomPlugin	-	build_deploy_plugin.sh	Writes fully rated events into a JSON file that is published to Kafka topics.

Compiling and Running the Sample Programs

You compile and run a sample program with the shell script provided for that sample program.

To compile and run a sample program:

Open the ECE_home/config/eceTopology.conf file.
Uncomment the line where the sdkCustomerLoader node is defined.

You are required to uncomment this line to be able to run the SDK sample programs.

Caution:

Do not run the customerLoader utility without the -incremental parameter in a production environment.
Go to the ECE server bin directory:
```
cd ECE_home/bin
```
Load the ECE runtime environment:
```
./ecc 'load sdk_production_loader.ecc'
```
Go to the ECE SDK bin subdirectory that contains the shell script for compiling and running the sample program you want to run:
```
cd ECE_home/ocecesdk/bin/sample_program_directory
```
where sample_program_directory is extensions, notification, plugin, policy, query, update, or usage. See Table 23-1 for more information.

For example, to compile and run the sample_voice_session.sh sample program (the sample program for sending a voice session usage request to ECE), you must be in the ECE_home/ocecesdk/bin/usage directory.
Compile the sample program:
```
sh ./scriptname.sh build
```
You must compile the sample program once.

For example, to compile the sample_voice_session.sh sample program, enter:
```
sh ./sample_voice_session.sh build
```
Run the sample program.
```
sh. /scriptname.sh run
```
Some programs require that you enter parameters. The run command output gives you information about what parameters are required. You can also run the command with no parameters to use default parameter values from the SDK scripts.
When you are done with the sample program, shut down the ECE runtime environment:
```
ecc stop server
```

Example of SampleDebitRefundSession

The following shows an example of how to run the SampleDebitRefundSession sample program.

sample_debit_refund_session.sh  build | run | defaultrun  userId  requestType  correlationId  [BALANCE_ELEMENT_ID,AMOUNT BALANCE_ELEMENT_ID,AMOUNT ...]  [TOTAL,IN,OUT TOTAL,IN,OUT ...]

where:

build compiles the related SDK source files.
run runs the SDK program (debit refund) according to the parameters you provide. You can supply the parameters in the command line or provide no parameters to run the program with default parameter values.
defaultrun builds and runs the SDK program. No parameters are required. The program uses the default parameter specified inside the shell script.
The order of parameters are fixed and if one optional parameter is provided then all values of other optional parameters must be supplied.
requestType is either DEBIT_AMOUNT, REFUND_AMOUNT, DEBIT_UNIT, or REFUND_UNIT.
DEBIT_AMOUNT or REFUND_AMOUNT, BALANCE_ELEMENT_ID is the well-known ISO code for balance elements, such as 840 for US Dollars or 95 for Included Minutes.
DEBIT_UNIT or REFUND_UNIT, TOTAL, IN, and OUT must be specified with numbers in MB (megabytes).

For example, the following command debits 10 USD and 25 Included Minutes:

sample_debit_refund_session.sh run 650999777 DEBIT_AMOUNT CORR_ID 840,10 95,25

This example command refunds 50 USD and 5 Included Minutes:

sample_debit_refund_session.sh run 650999777 REFUND_AMOUNT CORR_ID 840,50 95,5

Compiling and Deploying SampleRatedEventFormatterCustomPlugin

To compile and deploy the SampleRatedEventFormatterCustomPlugin sample program:

Configure Rated Event Formatter by doing the following:
1. Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans".
2. Expand the ECE Configuration node.
3. Expand charging.ratedEventFormatters.Instance_Name, where Instance_Name is the name of the instance you want to configure such as ratedEventFormatter1.
4. Expand Attributes.
5. Set the pluginType attribute to oracle.communication.brm.charging.sdk.plugin.SampleRatedEventFormatterKafkaCustomPlugin.
Go to the ECE_home/ocecesdk/bin/plugin directory and then build the sample program:
```
sh ./build_deploy_plugin.sh build SampleRatedEventFormatterKafkaCustomPlugin
```

Deploy the sample program:

sh ./build_deploy_plugin.sh deploy SampleRatedEventFormatterKafkaCustomPlugin

Ensure that your Kafka Server is up and running.
Create a topic in your Kafka Server for the rated events.

For example, this command creates a Kafka topic named RatedEvent:
```
bin/kafka-topics.sh --create --bootstrap-server kafkaHost:port --replication-factor 1 --partitions 1 --topic RatedEvents
```
where kafkaHost and port are the host and port that the Kafka client will connect to in a bootstrap Kafka cluster the first time it starts.
Wait until the entire configuration is ready and all components are up and running.
Perform usage, such as initiate, update, or terminate, for one of your customers.

Rated events will be published to the Kafka topic in JSON format. Also, JSON information will be added to the ratedEventFormatter1.log file under the ECE_home/log directory.
Confirm that the event was published to the Kafka topic by running the Kafka console consumer:
```
bin/kafka-console-consumer.sh --bootstrap-server kafkaHost:port --topic RatedEvents
```
When you are done with the sample program, shut down the ECE runtime environment:
```
ecc stop server
```