2 Using the Application Test Environment

The Application Test Environment (ATE) is a tool that lets you test your applications on a simulation of Oracle Communications Services Gatekeeper.

About the ATE

The ATE hosts a set of virtual communication services (VCSs) that correspond to many of the communication services provided by Services Gatekeeper.

You can develop applications that require interaction with Services Gatekeeper (for tasks such as opening sessions, sending and receiving messages, and examining delivery reports) through the VCSs without having to connect to the network operator´s Services Gatekeeper installation. When the time comes to test and later deploy the application with a real Services Gatekeeper installation, you need only to change a few URLs and authentication credentials in the application.

The ATE supports both Simple Object Access Protocol (SOAP) and Representational State Transfer (RESTful) application interfaces.

For information about the SOAP application interface, see Application Developer´s Guide. You can also access the Parlay X 2.1 specifications at

ftp://ftp.3gpp.org/Specs/archive/29_series/29.199-04/29199-04-650.zip

and the Parlay X 3.0 specifications at

ftp://ftp.3gpp.org/Specs/archive/29_series/29.199-02/29199-02-740.zip

For information abut the RESTful application interface, see RESTful Application Developer´s Guide.

Supported Communication Services

The ATE supports the following VCSs:

Session Manager
Short Messaging
MultiMedia Messaging
Terminal Location
Terminal Status
Payment/Diameter
Third Party Call
Binary Short Messaging

What You Can Do in the ATE

Using the ATE, you can:

Test the basic functionality of your application
Test the application's behavior with different configuration settings
Test the application's behavior with different authentication credentials
Test the application's behavior with policy restrictions

Basic Testing

This section provides a high-level workflow for performing basic testing.

To perform basic testing:

Set the endpoints in your application to point to the ATE.

See "Substituting the ATE´s Endpoints in the Application" for more information.
Change the credentials in the headers of your application's requests either to the default credentials or to those provided to you by the network operator.

See "Substituting Credentials in the Application" for more information.
Start the ATE.

See "Starting the ATE" for more information.
Add some elements to the ATE map or use existing elements.

By default, a mobile terminal element with the address "tel:1234" is provided in the default configuration. Your application can send messages to and receive messages and notifications from mobile terminals on the map. You can also verify whether a terminal has entered or left a defined notification area.

See "Setting Up and Using Map Elements" for more information.
Verify that the VCSs that your application uses are started.

They should be started by default, but if they are not, start them. See "Starting/Stopping a VCS" for more information.
Start your application.
(Optional) If your application uses the SOAP-based application interfaces and you want to see the SOAP content for each VCS request, do the following:
1. In the ATE, select Settings from the File menu.
  
  The Settings dialog box appears.
2. Select the Print SOAP content for each VCS request check box.
  
  The SOAP content is displayed in the command window from which you started the ATE. You must have started the ATE from a command window to use this option.
Use the application to send and receive messages and notifications to and from the elements that you created in step 4.
Check results in the ATE (to verify that messages were received) and in your application.

Test with Virtual Communication Service Configuration Settings

To test your application's behavior with different configuration settings:

Configure each VCS that corresponds to a communication service that your application uses.

See "Configuring VCS Settings" for more information.
Repeat the steps outlined in Basic Testing with different VCS configuration settings.

Test with Account Credentials

To test requests with credentials that are different from the defaults:

Set up one or more accounts using the Account Manager.

See "Managing Accounts" for more information.
Change the credentials in the headers of your application's requests to the credentials of the accounts that you set up in the ATE.
Repeat the steps outlined in Basic Testing with the credentials of your ATE accounts.

Test Policy Enforcement

To test simple policy enforcements:

Set up one or more value and rate enforcements using the SLA Manager.

See "Managing Service-Level Agreements" for more information.
Repeat the basic testing outlined in Basic Testing by sending requests that violate the SLA enforcements that you set up in the ATE.

Substituting the ATE´s Endpoints in the Application

To use the ATE, you must change the endpoints in your application to point to the ATE rather than to Services Gatekeeper.

See Appendix A, "ATE Endpoints" for the list of ATE endpoints.

For information about Services Gatekeeper endpoints for the SOAP interfaces, see Application Developer's Guide. For information about Services Gatekeeper endpoints for RESTful interfaces, see RESTful Application Developer's Guide.

Substituting Credentials in the Application

By default, the ATE enforces security.

Applications sending requests to the VCS must supply a user name/password combination in the SOAP header or Hypertext Transfer Protocol (HTTP) basic authentication credentials that correspond to the application´s account in the ATE.

The default credentials are:

User Name=domain_user
Password=domain_user

Your network operator may have set up a special ATE account for your application and configured your ATE for those credentials.

You can also create your own accounts. See "Managing Accounts" for more information.

Starting the ATE

The ATE is a standalone application. It is not necessary to install Services Gatekeeper to use the ATE.

Starting the ATE on UNIX

To start the ATE on UNIX:

Change directory to the SDK root directory.
At a command prompt, enter run.sh.

Starting the ATE on Windows

To start the ATE on Windows, do one of the following

To start the ATE from the Start menu, select Oracle Communications Services Gatekeeper, then select SDK.
To start the ATE from a command prompt, change directory to the SDK root directory and enter run.cmd.

Starting the ATE on Mac OS X

To start the ATE on Mac OS X:

Change directory to the SDK root directory.
Enter run.sh.

Stopping the ATE

To stop the ATE:

In the ATE window, select Exit from the File menu.

ATE Overview

The default configuration on startup resembles Figure 2-1. Your ATE may look different depending on how it has been customized by the network operator.

Figure 2-1 ATE

Description of "Figure 2-1 ATE"

The upper-left panel is the elements panel. In the Elements tab of this panel, you can create and configure elements representing mobile terminals that your application can send messages to and receive messages and notifications from. These elements are persistent. You can also create notification areas that your application can monitor. In the Messages tab of this panel, you can see a log of all the messages and notifications received by a VCS during the current session.

The upper-right panel is the map panel. You can place elements created in the elements panel on the map and drag them to another location on the map. You can also send messages from some elements and change the status of an element by right-clicking it on the map. If a notification area has been configured to monitor the location of any of the mobile terminals on the map, it will signal when a terminal has entered or left the area, depending on the configuration.

The lower-left panel is the VCS panel. Each tab accesses a different VCS, which simulates an actual communication service in Services Gatekeeper. You can display hidden VCS tabs by clicking the arrows in the tab region of the VCS panel. Each module, except the Session Manager, has two tabs: Controls and Configuration. In the Controls tab, you can stop and start the VCS module. The Configuration tab provides some configuration options, which vary for each VCS.

The Session Manager has a single panel from which you can start and stop the session manager.

The lower-right panel is the account manager/SLA manager/payment panel. In the Account Manager tab, you can set up accounts for your application to use. In the SLA Manager tab, you can set up simple enforcements based on values in a request or the rate of requests. In the Payment Account and Payment Account Detail tabs, you can monitor charging activity resulting from your application's requests in the Payment VCS.

You can hide and show these individual panels by clicking the small triangles at the edges of the panels. You can also resize the entire window and the individual panels.

Setting Up and Using Map Elements

The ATE provides three graphic elements to test applications:

Phone
Mobile elements that are not phones (truck)
Circular notification area

You add elements from the elements panel. After you have added elements to the map, you can move them by dragging around the map. Figure 2-2 shows an elements panel containing a a phone element, a circular notification area element, and a truck element.

Figure 2-2 Elements Panel

Description of "Figure 2-2 Elements Panel"

If the elements panel is not currently displayed, you can display it.

To display the elements panel:

Click one of the small black triangles at the edge of one of the panels that is displayed.
Click the Elements tab if it is not already selected.

Adding and Using Phone Elements

The phone element represents a mobile terminal that can send and receive messages. You use a phone element to test how your application handles incoming and outgoing messages to and from mobile phones.

Every phone has an address, a position, and a status.

Adding a Phone Element

To add a phone to the map from the elements panel:

Click the + symbol in the bottom left corner of the elements panel.

The Add Map Element dialog box appears.
From the menu, select Phone.
Click OK.

The Properties dialog box appears, with some default values.
In the address field, enter a value that is unique in the ATE in the tel: address format: for example tel: 1234.
From the status menu, select the status of the phone. Valid values are Busy, Reachable and Unreachable.
If desired, set the position of the phone by entering values in the longitude, latitude, and altitude fields.

For these values, the ATE considers a maximum precision of four positions after the decimal point.

You can also set the latitude and longitude by dragging the phone element across the map after it has been added.

Changing the phone element's position in the Properties dialog box may cause the phone to move off the map. You can still access the phone from the elements panel, even when it is not visible on the map.
Click OK.

The phone is added. If its position is within the coordinates of the map, it appears on the map.

Changing a Phone Element´s Properties

To change a phone element´s properties:

Access the phone´s properties by doing one of the following:
- In the elements panel, double-click the phone element.
- In the elements panel, select the phone element and click the pencil symbol in the bottom left corner of the elements panel.
The Properties dialog box appears.
Enter the values that you want to change.

See "Adding a Phone Element" for information about the individual fields.
Click OK.

Removing a Phone Element

To remove a phone, do one of the following:

In the map, right-click on the phone and select Remove.
In the elements panel, select the phone and click the - symbol in the bottom left corner of the elements panel.

Sending an SMS from a Phone Element

You can send an Short Message Service (SMS) message from a phone element that is on the map.

To send an SMS message:

Right-click the phone element that is sending the message and select Send SMS.

The SmsMessage dialog appears.
In the sourceAddress field, enter the address of the terminal sending the message.

The default is the phone element that you clicked, but you can enter a different address in this field.
In the destinationAddress field, enter the terminal/short code of the terminal that will receive the message.
In the message field, enter the text of the message.
Click OK.

Sending an MMS from a Phone Element

You can send an Multimedia Messaging Service (MMS) message from a phone element that is on the map.

To send an MMS message:

Right-click the phone element that is sending the message and select Send MMS.

The MmsMessage dialog appears.
In the sourceAddress field, enter the address of the terminal sending the message.

The default is the phone element that you clicked, but you can enter a different address in this field.
In the destinationAddress field, enter the terminal/short code of the terminal that will receive the message.
In the subject field, enter the subject line of the message.
In the priority field, enter the priority of the message.

This can be any text.
Click OK.

Sending a Binary SMS from a Phone Element

You can send a Binary SMS from a phone element that is on the map.

The binary data must be in hexadecimal format.

To send a Binary SMS:

Right-click the phone element that is sending the message and select Send Binary SMS.

The SmsBinaryMessage dialog appears.
In the sourceAddress field, enter the address of the terminal sending the message.

The default is the phone element that you clicked, but you can enter a different address in this field.
In the destinationAddress field, enter the terminal/short code of the terminal that will receive the message.
In the byteMessage field, enter message data formatted according to the TP-User Data (TP-UD), excluding the TP-User-Data-Header--Indicator (TP UDHI).

In the dcs_hex field, enter the data encoding schema used to encode the binary data.

Table 2-1 Data Encoding Schemes

Bits 7 6 5 4 3 2 1	Meaning
0 0 0 0 0 0 0 0	SMSC Default Alphabet
0 0 0 0 0 0 0 1	IA5 (CCITT T.50)/ASCII (ANSI X3.4)
0 0 0 0 0 0 1 0	Octet unspecified (8-bit binary)
0 0 0 0 0 0 1 1	Latin 1 (ISO-8859-1)
0 0 0 0 0 1 0 0	Octet unspecified (8-bit binary)
0 0 0 0 0 1 0 1	JIS (X 0208-1990)
0 0 0 0 0 1 1 0	Cyrllic (ISO-8859-5)
0 0 0 0 0 1 1 1	Latin/Hebrew (ISO-8859-8)
0 0 0 0 1 0 0 0	UCS2 (ISO/IEC-10646)
0 0 0 0 1 0 0 1	Pictogram Encoding
0 0 0 0 1 0 1 0	ISO-2022-JP (Music Codes)
0 0 0 0 1 0 1 1	reserved
0 0 0 0 1 1 0 0	reserved
0 0 0 0 1 1 0 1	Extended Kanji JIS(X 0212-1990)
0 0 0 0 1 1 1 0	KS C 5601
0 0 0 0 1 1 1 1	reserved
1 0 1 1 1 1 1 1	reserved
1 1 0 0 x x x x	GSM MWI control - see [GSM 03.38]
1 1 0 1 x x x x	GSM MWI control - see [GSM 03.38]
1 1 1 0 x x x x	reserved
1 1 1 1 x x x x	GSM message class control - see [GSM 03.38]

For more information about data encoding. see the data_encoding section of the SMPP v 3.4 specification.

In the protocolId_hex field, enter the protocol identifier.

The protocol identifier specifies the higher layer protocol being used or indicates networking with a certain type of telematic device. For more information, see 3GPP TS 23.040 V6.5.0, Technical realization of the Short Message Service (SMS) at

http://www.3gpp.org/ftp/Specs/html-info/23040.htm
Click OK.

Sending an Example Message from a Phone Element

This is identical to the procedure for sending an SMS.

See "Sending an SMS from a Phone Element" for more information.

Reading a Phone Element´s Received Messages

If a phone element has received messages, from another element on the map or from your application, a number next to the phone element indicates the number of messages in its inbox.

To read a phone element´s received messages:

Right-click the phone element and select Read Messages.

The phone element´s messages are displayed.

You can also view a log of the messages received by all the phone elements in the Messages tab of the elements panel.

Deleting a Phone Element´s Messages

To delete all of a phone element´s messages:

Right-click the phone element for which you want to delete messages and select Delete Messages.

The Delete Messages dialog box appears.
Select Yes.

To delete a selected message:

Right-click the phone element and select Read Messages.

The phone element´s messages are displayed.
Select the message that you want to delete.
Click the trash icon in the lower right corner of the message window.

The message is deleted.

Setting a Phone Element´s Status

To set a phone element´s status:

Right-click the phone element in the map.
Select Set Status.

A StatusMessage menu appears, displaying a status menu.
In the status menu, select the status of the phone. Valid values are Busy, Reachable and Unreachable.

You can also set a phone element´s status in the phone element´s Properties dialog box. See "Changing a Phone Element´s Properties" for more information.

Reading a Phone Element's Third Party Call Status

The Third Party Call VCS logs the call status of successful third party calls.

To read the log of third party calls:

Right-click the phone element on the map.
Select Read Call Status . . .

The Call Information window appears.

Figure 2-3 Third Party Call Log

Description of "Figure 2-3 Third Party Call Log"

The three status conditions that can be logged for successful third party calls are:

CallInitial: The call has been place but not yet connected.
CallConnected: The call has connected.
CallTerminated: The call has terminated.

If the caller or callee terminal status is Busy or Unreachable, the third party call is not established and not recorded in the log. See "Setting a Phone Element´s Status" for information about setting the terminal status.

The call log holds a maximum of ten calls. If more than ten calls are made, calls are automatically deleted from the log on a first-in first-out (FIFO) basis. The user can also manually delete a call from the log by selecting it and then clicking trash icon in lower left corner of the Call Information window.

Adding and Using Mobile Elements That Are Not Phones

The truck element symbolizes a mobile terminal that is not a phone. Typically it is used to represent a vehicle that contains a flat panel capable of receiving and displaying messages to a driver, but it can be used to represent other mobile devices as well.

A truck element has the same characteristics as a phone element.

To add, remove, configure, and use a truck element, follow the instructions for phone elements in Adding and Using Phone Elements.

Adding and Using Circular Notification Area Elements

The circular notification area element represents the geographic area for which the application wishes to receive notifications when a mobile terminal enters or leaves the area. The ATE supports multiple notification areas on the same map. Notification areas can overlap.

Adding a Circular Notification Area

To add a circular notification area to the map:

Click the + symbol in the bottom left corner of the elements panel.

The Add Map Element dialog box appears.
Select Circular Notification Area from the menu.
Click OK.

The Circular Notification Area Properties dialog box appears, with some default values.
In the id field, enter a unique identifier for the notification area.
In the addresses field, enter a comma-separated lists of the addresses for which notification is requested. The format is "tel:1234,tel:2345,tel:3456, . . .".
In the trigger field, specify whether notification is requested when terminals enter the area or when they leave the area. Valid values are MS_ENTERING and MS_LEAVING.
If desired, set the position of the area by entering values in the longitude and latitude fields. These coordinates represent the center of the notification area.

For these values, the ATE considers a maximum precision of four positions after the decimal point.

You can change the latitude and longitude of a notification area by dragging the area element across the map after it has been created.

Changing the position may cause the notification area to move off the map. You can still access the notification area from the elements panel, even when it is not visible on the map.
If desired, set the size of the notification area by entering a value in the radius field.

The ATE considers a maximum precision of four positions after the decimal point.
If desired, enter the frequency (in seconds) at which periodic location notifications should be sent to the application in the interval field.
If desired, enter the maximum duration (in seconds) for a notification request in the duration field.
If desired, enter the maximum number of notifications to be sent to the application in the count field. This value represents the number of notifications sent in total, not the number of notifications per mobile terminal address.

Changing a Circular Notification Area´s Properties

To change a notification area´s properties:

To access the notification area´s properties do one of the following:
- Double-click the notification area´s element in the elements panel.
- Select the notification area´s element in the elements panel and click the pencil symbol in the bottom left corner of the elements panel.
The Properties dialog box appears.
Enter the values that you want to change.

See "Adding a Circular Notification Area" for information about the individual fields.

Removing a Circular Notification Area

To remove a circular notification area, do one of the following:

In the map, right-click on the edge of the circular notification area and select Remove.
In the elements panel, select the circular notification and click the - symbol in the bottom left corner of the elements panel.

Displaying a Custom Map

You can substitute a map of your choice for the default map.

The map must be in BMP, JPEG, or PNG format.

You need to know the geographic coordinates of at least two diagonally-opposite corners of the map to be able to set the map´s latitude and longitude ranges.

For the latitude and longitude values that define the edges of the map, the ATE considers a maximum precision of four positions after the decimal point.

Figure 2-4 Custom Map with Coordinates Displayed

Description of "Figure 2-4 Custom Map with Coordinates Displayed"

If the map panel is not currently displayed, you can display it by clicking one of the small black triangles at the edge of one of the panels that is displayed.

You add a custom map from the map panel.

To display a custom map:

Click the following symbol, which appears in the lower-right corner of the map panel.

Description of the illustration map_config.png

The Map Properties dialog box appears.
In left Longitude field, enter the lowest longitude value for an east/west edge of the map.
In the right Longitude field, enter the highest longitude for the other east/west edge of the map.
In the left Latitude field, enter the lowest latitude value for a north/south edge of the map.
In the right Latitude field, enter the highest latitude value for the other north/south edge of the map.
If you want the values of the coordinates set in the preceding steps to be displayed in the map, check the Show Ranges check box.
Select the Custom Image option.

A file browser appears.
Navigate to the file that contains your map image.
Select the map image file.
Click OK.

The custom map appears in the map panel.

You can return to the default map by selecting the Default Image option in the Map Properties dialog box.

Any elements created after the substitution of a custom map will have their default coordinates adjusted to the coordinates of the new map.

Configuring, Starting and Stopping the VCS

You manipulate the VCS used by your application in the VCS panel.

Figure 2-5 shows the VCS panel with the Short Messaging/Controls tab selected.

Figure 2-5 VCS Panel

Description of "Figure 2-5 VCS Panel"

If the VCS panel is not currently displayed, you can display it by clicking one of the small black triangles at the edge of one of the panels that is displayed.

Each individual VCS is represented by a tab in the VCS panel. Choose the tabs that correspond to the services used by your application to access a particular VCS´s settings.

Starting/Stopping a VCS

By default, all VCSs are started when the ATE starts.

You can stop and restart a VCS using the Start and Stop buttons that appear in the Session Manager tab and in the Control sub-tabs displayed for the other VCSs.

VCS MBean Object and Class Names

If you want to connect your application to a VCS programmatically, you need to know the full paths of the MBean object and class names.

To view the object name and class name of any VCS:

Click a VCS tab.
Click the Configuration tab.
Click any attribute or operation in the VCS tab.

A panel appears displaying fields for configuration.
Click this icon, which appears at the top of the configuration panel when an operation or attribute is selected:

Description of the illustration vcs_info.png

A window displaying the VCS´s object name and class name appears.

Configuring VCS Settings

This section describes the attributes that you can configure and the operations you can perform in the ATE for a specific VCS.

These settings are for the purpose of testing the application´s behavior in the ATE and do not necessarily represent attributes and operations in Services Gatekeeper or in the application.

Configuring the Short Messaging VCS

To configure the Short Messaging VCS:

In the VCS panel, click the Short Messaging tab.

The Short Messaging panel appears.
Click the Configuration tab.

The Short Messaging VCS´s list of configuration options appears.
Select the operation that you want to perform.

A panel displaying fields for the operation´s input parameters and, if appropriate, a field for the operation´s output appears.
Enter any input parameters required by the operation.

Operations and parameters are listed below.
Click the green triangle, which performs the operation.

The Short Messaging VCS supports operations for configuring how offline notifications are handled.

An offline notification is a message received by the ATE when the application is offline. The ATE saves the message. When the application comes online and polls for mobile-originated messages, the ATE forwards the saved messages to the application if offline notification is enabled.

disableReceiveSms

Disables offline notification of a received SMS.

If offline notification is disabled, the ATE does not save or forward mobile-originated messages received while the application was offline.

Table 2-2 Parameters for disableReceiveSms

Parameter	Description
Correlator	The id value returned by the corresponding enableReceiveSms operation.

enableReceiveSms

Enables offline notification of a received SMS addressed to a specified shortcode.

The ATE notifies the application when it has received a message addressed to the specified shortcode in which the message contains a match to the specified criteria. If no criteria are specified, the ATE forwards all messages received by the specified shortcode while the application was offline.

Table 2-3 Parameters for enableReceiveSms

Parameter	Description
Shortcode	Destination address to which the message was sent.
Criteria	Optional. Text to match in the message. If the text matches, the application receives the notification.

listOfflineNotifications

Displays a list of registered offline notifications.

Configuring the Multimedia Messaging VCS

To configure the Multimedia Messaging VCS:

In the VCS panel, click the Multimedia Messaging tab.

The Multimedia Messaging panel appears.
Click the Configuration tab.

The Multimedia Messaging VCS´s list of configuration options appears.
Select the operation that you want to perform.

A panel displaying fields for the operation´s input parameters and, if appropriate, a field for the operation´s output appears.
Enter any input parameters required by the operation.

Operations and parameters are listed below.
Click the green triangle, which performs the operation.

The Multimedia Messaging VCS supports operations for configuring how offline notifications are handled.

An offline notification is a message received by the ATE when the application is offline. The ATE saves the message. When the application comes online and polls for mobile-originated messages, the ATE forwards the messages to the application if offline notification is enabled.

disableReceiveMms

Disables off-line notification of a received MMS.

If offline notification is disabled, the ATE does not save or forward mobile-originated messages received while the application was offline.

Table 2-4 Parameters for disableReceiveMms

Parameter	Description
Correlator	The value returned by the corresponding enableReceiveMms operation.

enableReceiveMms

Enables off-line notification of a received message sent to a specified short code. This is used by applications that poll for mobile-originated messages.

Table 2-5 Parameters for enableReceiveMms

Parameter	Description
Shortcode	Destination address to which the message was sent.
Criteria	Optional. Text in the message to match against. If the text matches the first word in the message, the application receives the notification.
AppInstanceID	Application instance identifier of the application instance receiving the notification.

listOfflineNotifications

Displays a list of registered offline notifications.

Configuring the Terminal Location VCS

To configure the Terminal Location VCS:

In the VCS panel, click the Terminal Location tab.

The Terminal Location panel appears.
Click the Configuration tab.

The Terminal Location VCS´s list of configuration options appears.
Click the attribute that you want to configure.

A panel displaying the attribute´s check box or field appears.
Set the attribute.

Attributes for the Terminal Location VCS are listed below.
If you want to restore all the settings to their default values, do the following:
1. Click the resetToDefault operation.
  
  The operation´s panel appears.
2. Click the green triangle in the panel, which re-sets the attributes to their default values.

The Terminal Location VCS supports the following attributes:

AltitudeAlwaysAvailable

If selected, altitude information is always available for all location responses.

AltitudeSometimesAvailable

If selected, altitude information is sometimes available for some or all location responses.

GeographicalNotificationAvailable

If selected, notifications can be set up based on geographical coordinates.

MaximumAddresses

Maximum number of addresses for which a notification can be requested.

MaximumCount

Maximum number of notifications that can be requested.

If zero or blank, there is no maximum. In this case, select UnlimitedCountAllowed also.

MaximumNotificationDuration

Maximum amount of time (in seconds) for which a notification can be set up.

MaximumNotificationFrequency

Maximum rate of notification delivery. Can also be viewed as the minimum interval (in seconds) between notifications.

MinimumAcceptableAccuracy

Minimum distance from the terminal that the application considers useful. The unit applies to distance (for example, meters or feet).

MinimumAccuracy

Minimum distance from the terminal for which the application wishes to receive location information. The unit applies to distance (for example, meters or feet).

MinimumTrackingAccuracy

Minimum tracking accuracy refers to the accuracy of the tracking technology, not to the accuracy of the notification area. For example, a low value is appropriate to a device tracking a person entering a building, while a high value would be appropriate to a device tracking a plane landing in a city.

The unit applies to distance (for example, kilometers or feet).

PeriodicNotificationAvailable

If selected, periodic notification can be set up for a set of terminals at an application-defined interval.

UnlimitedCountAllowed

If selected, an unlimited notification count is allowed.

Configuring the Terminal Status VCS

To configure the Terminal Status VCS:

In the VCS panel, click the Terminal Status tab.

The Terminal Status panel appears.
Click the Configuration tab.

The Terminal Status VCS´s list of configuration options appears.
Click the attribute that you want to configure.

A panel displaying the attribute´s check box or field appears.
Set the attribute.

Attributes for the Terminal Status VCS are listed below.
If you want to restore all the settings to their default values:
1. Click the resetToDefault operation.
  
  The operation´s panel appears.
2. Click the green triangle in the panel, which re-sets the attributes to their default values.

The Terminal Status VCS supports the following attributes:

BusyAvailable

If selected, busy can be returned as a status.

If not checked and the application includes the busy criterion in a Start Notification request, the client is not notified of the terminal's busy status and the VCS throws a policy exception.

MaximumAddresses

Maximum number of addresses for which a notification can be set up or statuses be retrieved.

MaximumCount

Maximum number of notifications that can be requested.

If zero or blank there is no maximum. In this case, select UnlimitedCountAllowed also.

MaximumNotificationDuration

Maximum amount of time (in seconds) for which a notification can be set up.

MaximumNotificationFrequency

Maximum rate of notification delivery. Can also be viewed as the minimum interval (in seconds) between notifications.

UnlimitedCountAllowed

If selected, an unlimited notification count is allowed.

Configuring the Payment VCS

To configure the Payment VCS:

In the VCS panel, click the Payment tab.

The Payment panel appears.
Click the Configuration tab.

The Payment VCS´s list of configuration options appears.
Click the attribute that you want to configure.

A panel displaying the attribute´s check box or field appears.
Set the attribute.

Attributes for the Payment VCS are listed below.
Select the operation that you want to perform.

A panel displaying fields for the operation´s input parameters and, if appropriate, a field for the operation´s output appears.
Enter any input parameters required by the operation.

Operations and parameters are listed below.
Click the green triangle, which performs the operation.

The Payment VCS supports the following attributes:

ExpiredTime

Duration of a reservation, in milliseconds.

The default is -1, which indicates that no duration is set.

SplitSupport

If checked, the chargeSplitAmount request is supported.

SplitNumbers

Maximum number of end users that can be charged in a single chargeSplitAmount request.

The Payment VCS supports the following operations:

createUserAccount

Creates a user account.

Table 2-6 Parameters for createUserAccount

Parameter	Description
username	User name for the account
originalAmount	Original amount of money in the account

listAllReservationRecords

Lists all the reservation records.

listAllUserAccounts

Lists all the user accounts.

listReservationRecord

Lists the reservation record detail for the specified session.

Table 2-7 Parameters for listReservationRecord

Parameter	Description
reservatiionID	Reservation ID for the reservation records to be described

listUserAccount

Lists user account information, including the account's current balance and original amount, for the specified account.

Table 2-8 Parameters for listUserAccount

Parameter	Description
userID	UserID for the account to be described

listUserChargeRecord

Lists the charge record detail for the specified account.

Table 2-9 Parameters for listUserChargeRecord

Parameter	Description
userID	User ID for the charge record to be described

refreshPaymentUI

Refreshes the Payment VCS user interface.

resetToDefault

Resets all the Payment VCS settings to their default values.

Configuring the Third Party Call VCS

To configure the Third Party Call VCS:

In the VCS panel, click the Third Party Call tab.

The Third Party Call panel appears.
Click the Configuration tab.

The Third Party Call VCS´s list of configuration options appears.
Click the attribute that you want to configure.

A panel displaying the attribute´s check box or field appears.
Set the attribute.

Attributes for the Third Party call VCS are listed below.
If you want to restore all the settings to their default values:
1. Click the resetToDefault operation.
  
  The operation´s panel appears.
2. Click the green triangle in the panel, which re-sets the attributes to their default values.

The Third Party Call VCS supports the following attributes:

ChargingAllowed: If selected, charging can be applied to calls.
StatusRententionTime: The length of time, in seconds, to retain status after the call has terminated.

Configuring the Binary Short Messaging VCS

To configure the Binary Short Messaging VCS:

In the VCS panel, click the Binary Short Messaging tab.

The Binary Short Messaging panel appears.
Click the Configuration tab.

The Binary Short Messaging VCS´s configuration option appears.
Click the green triangle, which performs the operation.

The Binary Short Messaging VCS supports the following operation.

listOfflineNotifications

Displays a list of registered offline notifications.

Troubleshooting

If your application does not perform as expected (for example, your messages and notifications are not received), check the exceptions thrown by the failing operation.

Exceptions with an SVC prefix indicate an error against the service. Exceptions with a POL prefix indicate a violation of a policy enforcement. See "Managing Service-Level Agreements" for information about setting policy enforcements in a VCS.

See Appendix B, "VCS Exception Codes" for the lists of exception codes for each VCS.

Simple Mobile-Terminated Test

A simple example is to test a Send Sms request from your application to a phone element in the ATE.

To test Send Sms:

In your application, change the endpoint for the Send Sms request to point to the ATE.

If you are using the SOAP interface, see Table A-5, "Endpoints for SOAP SendMessage Interface" for the endpoint. If you are using the RESTful interface, see Table A-21, "Endpoints for RESTful Send SMS Operation".
Start the SDK.
Add a phone element to the map.

See "Adding a Phone Element" for information about adding a phone element.
Click the Short Messaging VCS tab to verify that the Short Messaging VCS is running. Click the Start button if it is not running.
Start the application.
From the application, send an SMS to the phone element.
Read the received message in the ATE.

See "Reading a Phone Element´s Received Messages" for more information.

If the message text does not appear in the ATE, check the exceptions associated with the Send Sms request to identify the source of the problem. See "Short Messaging Exception Codes" for more information.

You can use this procedure as a general outline for testing mobile-terminated requests.

Simple Mobile-Originated Test

A simple example is to test a Receive Sms request by sending an SMS from a phone element in the ATE to an address in your application.

To test Receive Sms:

In your application, change the endpoint for the Receive Sms request to point to the ATE.

If you are using the SOAP interface, see Table A-7, "Endpoints for SOAP ReceiveMessage Interface" for the endpoint. If you are using the RESTful interface, see Table A-24, "Endpoints for RESTful Get Received SMS Operation".
Start the SDK.
Add a phone element to the map.

See "Adding a Phone Element" for information about adding a phone element.
Click the Short Messaging VCS tab to make sure that the Short Messaging VCS is running. Click the Start button if it is not running.
Start the application.
From the phone element, send an SMS to an address defined in the application.
Fetch the SMS in the application using the Receive Sms request.

If the message is not available in the application, check the exceptions associated with the Receive Sms request to identify the source of the problem. See "Short Messaging Exception Codes" for more information.

You can use this procedure as a general outline for testing mobile-originated requests.

Managing Accounts

The ATE is configured with a default application account: domain_user/domain_user.

You can remove this default account.

You can also set up additional accounts.

To set up an account:

In the account manager/sla manager panel, click the Account Manager tab.
Click the + symbol.

A new row for the account information appears with the default values name/password.
Overwrite the name with the account´s user name in the User Name field.
Overwrite the password with the account´s password in the Password field.

The account is set up. An application should pass the user name/password values for its account before it submits a request to a secure VCS.

To modify an account´s user name or password:

In the account manager/sla manager panel, click the Account Manager tab.
Overwrite the values that you want to change.

To remove an account:

In the account manager/sla manager panel, click the Account Manager tab.
Select the account that you want to remove.
Click the - symbol.

The account is removed.

Managing Service-Level Agreements

You can set up simple service-level agreement (SLA) enforcement for VCS requests to use in your tests. The ATE supports two types of enforcement:

Value enforcement: rejects a request based on a specific value in the request; for example: the subject of an SMS contains the string "foo"
Rate enforcement: rejects a request based on a rate value: for example, a specified number of requests per minute

To enable/disable simple SLA enforcement:

In the account manager/sla manager panel, click the SLA Manager tab.
Do one of the following:
- To enable SLA enforcement, select the Enable SLA enforcements check box.
- To disable SLA enforcement, select the Disable SLA enforcements check box.

All SLA enforcements set up for the VCS are either enabled or disabled as a group. You cannot selectively enable or disable a subset of them.

Managing Value Enforcements

To set up a value enforcement:

In the account manager/sla manager panel, click the SLA Manager tab.
Click the Value Enforcements tab.
Click the + symbol.
In the Path field, enter the element in the VCS request against which the value will be enforced; for example: SendMessage.subject, SendMessage.charging.currency, GetLocation.maximumAge. No spaces are permitted in the Path field.

If you do not know the exact name of the element, click the magnifying glass icon next to the Path field. A browser appears in which you can locate the path by expanding the entry for the appropriate service.

Figure 2-6 Browser for Element Paths

Description of "Figure 2-6 Browser for Element Paths"
From the Operation menu, select the operation to be applied. Valid values are: CONTAINS, DOES_NOT_CONTAIN.
In the Value field, enter the value against which the element will be tested.

Figure 2-7 shows two value enforcements in the SLA Manager. The first allows messages in which the subject contains the word urgent. The second allows messages in which the charging currency does not contain renminbi.

Figure 2-7 SLA Manager Value Enforcements Tab

Description of "Figure 2-7 SLA Manager Value Enforcements Tab"

To modify a value enforcement:

In the account manager/sla manager panel, click the SLA Manager tab.
Overwrite the values that you want to change.

To remove a value enforcement:

In the account manager/sla manager panel, click the SLA Manager tab.
Click the Value Enforcements tab.
Select the value enforcement that you want to remove.
Click the - symbol.

The enforcement is removed.

Managing Rate Enforcements

To set up a rate enforcement:

In the account manager/sla manager panel, click the SLA Manager tab.
Click the Rate Enforcements tab.
Click the + symbol.
In the Request Name field, select the request for which the enforcement will be enforced. No spaces are permitted in the Request field.
In the Request Count field, enter an integer representing the maximum number of requests allowed in a specified time period.
In the Time Amount field, enter an integer representing the time period against which the request count is applied.
From the Time Unit menu, select the unit of time to which the time amount applies. Valid values are SECONDS, MINUTES, or HOURS.

Figure 2-8 shows a rate enforcement in the SLA Manager. It allows a maximum of 5 sendSms requests every 10 seconds.

Figure 2-8 SLA Manager Rate Enforcements Tab

Description of "Figure 2-8 SLA Manager Rate Enforcements Tab"

Monitoring Payment Accounts

You can test the charging functionality in your application by monitoring changes in the Payment Account and Payment Account Detail tabs.

To test charging:

Create one or more subscriber accounts using the createUserAccount operation in the Payment VCS. See "createUserAccount" for more information.

Or use a default account displayed in the Payment Account tab. The Payment VCS creates a subscriber account for every phone element in the ATE.
In your application, charge and refund the subscriber accounts created in step 1 using various Payment requests such as chargeAmount, refundAmount, and chargeSplitAmount.
Click the Payment Account tab.

The amounts in the Credits column reflect the resulting balance of the charges and refunds made by the application for each account.
Click the Payment Account Detail tab.

Each charge and refund made by the application against subscriber accounts is logged here.

Example Module

A VCS example module is deployed in the SDK.

You can find it in the ocsg_sdk_5.1/lib/modules subdirectory of your SDK installation.