System Management Service (SMS)
Usage Notes

Table of Contents

Table of Contents
Foreword
Service Description
SDK Contents
Service Architecture
Programming Interface
Authentication and Session Management
Service Method Reference
SMS Models and Operations
SMS Configuration
SMSXMLTest Client Application
Vector Support

Foreword

This Software Development Kit was designed to help new SMS developers get started with the basics of the System Management Service and kick start their application development. There are a few sample applications included with this SDK that help exemplify the typical SMS client behavior and show proper session maintenance with this Web Service.

What’s New?
In release 5.2 and later, there are a couple of new enhancements that developers should be aware of:

• XML Formatted Model and Fields –

Up until this release the SMS server and clients have been using a pipe-delimited string of key-value pairs to represent the field data contained in a particular request. Going forward, SMS will offer a new XML representation of the Model and Fields data in a new combined parameter called “modelFields.” This will enable consumers of the SMS web service to better leverage standard XML / SOAP parsers rather than writing code to parse or populate the pipe delimited string. This new interface will be exposed by a new WSDL document and many new XML schemas that will all be available on the SMS server via a new URL.
• UTF-8 Support -

A few particular models on the Communication Manager provide UTF-8 support for the Native Names fields. In this release SMS has provided support to handle UTF-8 encoding for the Native Names fields in the following SMS models:
o Station Model
o Agent Model
o TrunkGroup Model
o HuntGroup Model
o VDN Model
o Vector Model

Deprecation
It is also important to note that with the introduction of the XML formatted interface the previous string based SMS interface is to be considered deprecated. It is encouraged that developers use the new XML interface to develop new applications and update current ones before the 6.0 release of SMS.
Service Description
What is the System Management Service (SMS)?

The System Management Services (SMS) is a web service that exposes selected management features of Communication Manager (CM). SMS enables SOAP clients to display, list, add, change and remove specific managed objects on Communication Manager.

A key benefit to the use of SMS is that it allows for programmatic access, via a standard protocol (SOAP) to functionality that is otherwise only accessible either via a proprietary low-level CM protocol (OSSI), or terminal emulation via system administration (SAT) forms.
SDK Contents
The SMS Client SDK consists of the following directories and contents:
smssvc – top level folder containing a usage document (this document), and a readme.txt file.
smssvc\example\ant – Contains the ant libraries and files.
smssvc\example\bin – Contains Linux and Windows scripts to execute the ant command. Use these scripts to build and run the Java based sample applications contained in this SDK. For a complete list of targets execute: ant.sh -p <or> ant.bat –p
smssvc\example\build - Contains the compiled Java classes and Stub-Jar package generated by the "buildAll" ant target.
Note: you must manually swap out the example\build\lib stub jar with the example\lib stub jar to use your compiled version.
smssvc\example\lib – Contains all of the jar files needed to compile and run the sample Java clients.
Note: the systemmangementservice stub jar has been signed by Avaya.
smssvc\example\resources*.properties - Property files used to configure the run time behavior of the sample applications
smssvc\example\resources\wsdl_xml – Contains a sample WSDL file for the XML formatted input and output SMS service.
smssvc\example\resources\xsd – Contains the model XML schema documents referenced by the XML formatted input and output WSDL.
smssvc\example\src – Source code for the demonstration client application.
smssvc\example\src\sampleapps\smsxml - Source code for demonstrating Java and C# client applications with the new XML formatted input and output.
smssvc\support\supportedModels.htm– Contains an html output of the supported models schema for this release.

Note: The generated SOAP stubs provided in the smssvc\example\lib directory of this SDK are signed by Avaya and thus must be manually replaced if rebuilt. The jar file produced by invoking the Ant “buildAll” target can be found in the smssvc\example\build\lib directory after compilation.

The information in this SDK is supplemented by help information accessible directly from the SMS deployment, via the following URLs:

New XML Formatted Interface
https://<smshost>/smsxml/SystemManagementService.php?wsdl* WSDL specification
https://<smshost>/smsxml/xsd/models/*
XML schema documents referenced by the smsxml WSDL
https://<smshost>/smsxml/getModelClasses.php*
On-line reference for supported models, operations and fields
https://<smshost>/smsxml/smsxml_test.php* An interactive SOAP client that can be used to submit SMS requests and examine the results.

Deprecated String Based Interface
https://<smshost>/sms/SystemManagementService.php?wsdl* WSDL specification
https://<smshost>/sms/getModelClasses.php* On-line reference for supported models, operations and fields
https://<smshost>/sms/sms_test.php*
An interactive SOAP client that can be used to submit SMS requests and examine the results.
*Depending on how you deploy SMS, these may be accessible via http as well as https.

Service Architecture
The service architecture is illustrated in the figure below.

Clients of the service are fundamentally concerned with the SOAP interface (the WSDL file for the service interface is included in the SDK distribution).

It is also useful to understand the notion of “Models”, as these map closely to the notion of “forms” in the SAT administration interface. The client of SMS accesses CM administration functions by specifying the “model” on which to operate, along with the desired operation, fields, parameters and values as applicable, as described in the programmatic interface section.

SMS also maintains a notion of “session” on behalf of connection clients. The primary purpose of a session is to maintain an authenticated connection from the OSSI Proxy to the administered CM. This reduces the overhead that would be incurred if SMS required re-establishment of an authenticated session for every request. The details of session management are transparent to the client, however some responsibilities are imposed in terms of request header elements, as described in the programmatic interface section, below.

Programming Interface

The programming interface for SMS is defined by a SOAP WSDL (Web Services Definition Language) file. Sample WSDL files are supplied with the relevant SMS SDK, but dynamic WSDL files (containing the appropriate binding for your deployment of SMS) can also be accessed from the hosting web server via the following URLs:

​​​​            New XML Formatted Interface

http(s)://<host>:<port>/smsxml/SystemManagementService.php?wsdl

Deprecated String Based Interface
http(s)://<host>:<port>/sms/SystemManagementService.php?wsdl

where <smshost> is a DNS resolvable hostname
or an IPv4 address of the form "xxx.xxx.xxx.xxx"
or an IPv6 address of the form "[xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]".
Note: when specifying an IPv6 address with a port, the square braces are required.

The page retrieved should be saved as a WSDL file (e.g. sms.wsdl or smsxml.wsdl) on the development machine. This file can be compiled into client application stub code with a language specific SOAP toolkit’s WSDL compiler/code generator. This SDK includes the JAX-WS SOAP toolkit for use with the XML formatted interface while previous SMS SDKs used Apache Axis with the string based interface.

JAX-WS was chosen as a SOAP toolkit for the new XML sample application to show the power of consuming the XML formatted interface. The JAX-WS toolkit utilizes JAX-B for XML bindings to marshal and un-marshal XML generated by an SMS request/response to a simple Java object that can be easily manipulated with setter and getter methods. This is not the only toolkit that will exhibit this powerful behavior however there is no longer any need to write a custom parser to deal with the SMS field data! This is all accomplished through the new XML schema documents which you can find in this SDK at: smssvc\example\resources\xsd or dynamically on the SMS server at: http(s)://<smshost>:<port>/smsxml/xsd/models/

This document will not go in to great detail on how to compile client stubs and utilize the SOAP toolkit tools, however if the reader is interested in more details please reference the Ant “build.xml” file provided with this SDK in the smssvc\example\bin directory. Additional resources and the latest download of JAX-WS and Axis can be found at:
Apache Axis - http://ws.apache.org/axis/
JAX-WS - https://jax-ws.dev.java.net/

Authentication and Session Management

Session establishment with SMS is implicit, i.e., there is no explicit request to establish a session. SMS expects credentials to be provided with each request. These credentials are passed in the HTTP Authorization header using Basic authentication. (It is strongly recommended that SMS be accessed only via HTTPS to ensure privacy of this information.)

The JAX-WS stub code provides access to the user login name and credentials through the Binding Providers Request Context:

​​​​  requestContext.put(WSBindingProvider.USERNAME_PROPERTY, login);
​​​​  requestContext.put(WSBindingProvider.PASSWORD_PROPERTY, pw);

Other client environments will have different methods for setting the HTTP Authorization header appropriately. Refer to your SOAP toolkit documentation for more information.

It’s important to note that a session is established between the client and a single CM server at any given point in time. The login name and credentials specified are validated against the logins administered for the CM server.

The CM server host-address (and administration port, if other than the default) are specified with the login as follows: loginname@cmhostaddress (or loginname@cmhostaddress:port if a non-default port is used). Note: if you specify an IPv6 formatted address and a port, then the IPv6 address must be enclosed in square braces (e.g loginname@[ffff::10.0.0.1]:4101).

To properly maintain session information across requests, SMS maintains a SOAP header element named “sessionID”, in namespace “http://xml.avaya.com/ws/session.” The client application should send the SOAP header element sessionID with each request. The sessionID value should be null (empty) in the initial request, and this header, along with any returned value, should simply be copied into subsequent requests until the session is released.
The following portion of a soap request illustrates the sessionID header element being passed with a request, in this case, containing a 32-byte sessionID (generated by a previous SMS request).

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
soapenv:Header
<ns1:sessionID soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="1" xsi:type="xsd:string" xmlns:ns1="http://xml.avaya.com/ws/session">16576f025d9aaaefec1d553f54fd1081</ns1:sessionID>
</soapenv:Header>
soapenv:Body
…
</soapenv:Body>
</soapenv:Envelope>

The sessionID header element value must not be cached by the client, but should be copied from each server response into the next client request for the session. The SMS server is free to change the sessionID value at any time, and will do so under various circumstances. Simultaneous requests to SMS on the same sessionID are not supported. Should this occur, one or more of the simultaneous requests will be rejected with a “Session is Busy” fault. (If multiple threads will need to access SMS simultaneously, each thread should establish its own SMS session.)

When the client is finished with the session, the SMS release method should be called (again, passing in the same sessionID, as described above). This releases any resources assigned to the session. It will also invalidate the sessionID, returning an empty sessionID in the response header. Failure to call release will result in CM server resources being held unnecessarily for some period of time.

SMS will eventually release idle resources, after a timeout interval (approximately three minutes). This timeout is also transparent to SMS clients. In the event a client is idle for longer than the timeout period, and then resumes SMS activity, the client session will automatically be re-established (provided the login credentials provided are successfully re-authenticated).
Service Method Reference

This section will only describe the XML formatted interface introduced in the 5.2 and later releases of SMS. Please locate and download a 4.x SMS SDK if you need more information on the string based interface.

SMS supports just two methods:

submitRequest

This method is used to invoke any of the available commands for any of the supported models. The input parameters are:

modelFields An XML representation of the Model and Fields that are to be changed or retrieved.

This parameter is defined by the “modelChoices” Complex Type (please see smssvc/example/resources/xsd/ModelChoices.xsd) and is the basis of the XML formatted interface. When using the submitRequest method you must specify the Model and Fields that you wish to change or retrieve using this parameter.
operation This specifies the command to perform. Not all operations are supported by all models. The model support documentation in this SDK, available under smssvc/support/supportedModels.htm, will indicate which operations are supported for each model. The online model reference also supplies this information and is available at https://<smshost>/smsxml/getModelClasses.php.
objectname Reserved for possible future use. This should be left blank.
qualifier Usually a “key” identifier, required by some operations. For example, to add, change or remove a station object, the qualifier would be the station extension. The qualifier may also be used to specify additional parameters for some commands. Users who are familiar with SAT commands will recognize this as the third part of a SAT command. Documenting the full set of possible qualifier values for all available commands is beyond the scope of SMS. This information may be obtained from other available sources (such as the CM SAT help screens, for example).

The result is returned as a complex SOAP structure containing three elements:

result_code 0 for success, 1 for failure.
If a connection to OSSI fails, a SOAP fault is sent back. If a connection is established, but the OSSI request fails (for instance an invalid qualifier was specified), then a submitRequest response is returned and this field will contain a 1
result_data An XML representation of the Model and Fields that are retrieved from CM.
This parameter is also defined by the “modelChoices” Complex Type (please see smssvc/example/resources/xsd/ModelChoices.xsd).

For read commands (commands that return a single model object, such as display and status) – SMS will return a single Model Element that matches the submitted Model Element. For example, if you submit a display operation with Station in modelFields you will be returned a single Station in the result_data. This type of command will also utilize the position attribute on certain fields to represent what used to be considered an array based field.

For list commands (commands that return a list of model objects, such as list and occasionally status) – SMS will return a list of Model Elements that match the submitted Model Element. For example, if you submit a list operation with Station in modelFields you will be returned a list of Stations in the result_data.

For change command (commands that make modifications to the CM Administration, such as change, add, and remove) SMS will return an empty result_data with no Model Elements.

message_text If result_code is 1, this field contains the protocol failure message received from OSSI.
release

This operation must be called when a client is finished with the SMS session.

This operation takes no parameters. (Note, however, that the sessionID header element must still be handled appropriately as described in the Session Management section above.)

It returns the same result structure as the submitRequest method, however, in all cases, the result_code will be 0 (success), and result_data and message_text will be empty. (Any severe error conditions encountered during a release call will result in a SOAP fault being raised, as opposed to returning a result_code of 1.)
SMS Models and Operations

The SMS interface exposes selected CM administration objects (models) and operations on those objects. As noted above, the set of available models and operations is accessible by pointing your browser to the installation host machine at http://hostname/smsxml/getModelClasses.php or at smssvc/support/supportedModels.htm.

The information provided for each supported model includes the set of allowable operations, and the available fields.

Important Note: In order to create valid XML, it was necessary to remove invalid XML characters from some fields (e.g. ‘/’ in the ‘Active/Idle_Ringing’ field of the Station Model). To maintain backward compatibility these fields will still be returned with the invalid XML characters if the string based interface is used.

ModelFields

What is the modelFields parameter?
The ‘modelFields’ parameter was introduced in SMS 5.2 and, if you are familiar with previous releases of SMS, you will see that we have combined the ‘model’ and ‘fields’ parameters to replace it with this new one. The first thing to note about this parameter is that it is defined by a complex-type in an external XSD file called ModelChoices.xsd (the XML schema documents have been included / imported as needed in order to reduce the size and complexity of the WSDL). This is essentially a large XML choice element which contains all the different SMS models that a developer can choose from.

Now, the fact that each model in the choice element can occur 0 or more times does not mean that one should submit 0 or more instances of a model element in a request. If more that 1 model element is submitted SMS will ignore all instances except for the last one supplied in the modelFields request. On the other hand, submitting no model element will result in a SOAP fault because SMS does not know which model to operate on. The reason for a minOccurs=0 and maxOccurs=unbounded is to allow the modelChoices type to be re-used in the result_data.

How to use modelFields
The modelFields parameter is fairly straight-forward to use but to help understand its use some sample code using JAX-WS/JAX-B is given here along with the XML equivalent representation.

First, pick the model that needs to be operated on and create a new instance of it (in this example the Station model will be used). At the same time we will create a ModelChoices object to represent our modelFields element:

​​​​  ObjectFactory of = new ObjectFactory();
​​​​  ModelChoices modelFields = of.createModelChoices();
​​​​  StationType station = of.createStationType();

Next, populate the fields that need to be changed or displayed in the model object and, finally, add the model object to the modelFields element. Here are a few scenarios:

To display particular fields:

station.setExtension("");
station.setName("");
modelFields.getStation().add(station);

-XML Equivalent-
<modelFields>
<Station>
<Extension/>
<Name/>
<Station>
</modelFields>

To display all fields in a model (similar to deprecated fields=*):

​​​​            StationType station = of.createStationType();

// Do not set any fields!
modelFields.getStation().add(station);

-XML Equivalent-
<modelFields>
<Station/>
</modelFields>

To change particular fields:

​​​​  station.setExtension("4700");
​​​​  station.setName("John Doe");
​​​​  modelFields.getStation().add(station);

-XML Equivalent-
<modelFields>
<Station>
<Extension>4700</Extension>
<Name>John Doe</Name>
<Station>
</modelFields>

To clear a field:
station.setName(" ");
modelFields.getStation().add(station);

-XML Equivalent-
<modelFields>
<Station>
<Name> </Name>
<Station>
</modelFields>

Qualifiers

In the future, additional documentation may be provided on-line through the getModelClasses interface. In particular, the use of the “qualifier” parameter is currently undocumented, and requires some familiarity with the corresponding CM administration (SAT) command.

In general, for commands that operate on a particular object (such as “add”, “change” or “remove” station), the qualifier is the key identifying the object (the extension number, in the case of the Station model).

For other operations, such as list operations, the qualifier may be of the form:

<option-name> [<value>] [<option-name> [<value>] … ]

For example, the Station list operation (“list station” command) has the following options:

Name Value Description
ext nnnnnnn Extension to start with (if not administered, list starts with next highest administered extension)
to-ext nnnnnnn Extension to stop list at
count N Limit list to N stations
port xxxxxx List only stations with port assignments matching the value (works like a wildcard if a partial port number is specified)
type xxxxxx List only stations of the specified type (works like a wildcard if a partial type name is specified)
movable always, done, error, no. once List only stations for which the option value applies.

It is beyond the scope of this usage document to provide detailed documentation of all the possible combinations for each of the available models and operations. Detailed help is currently available for each of the CM administration commands via the SAT.

List Operations

Operations that return a list of objects on the administered CM have the potential to return substantially large amounts of data. If the result set is sizable enough, the command can easily exceed the configured SOAP client timeout or web request timeout values, and the request can fail. To avoid this, the following guidelines are recommended:

 Limit list results with the “count” option.
Many list operations accept a qualifier of “count N”, where N is a numeric limit. The maximum number of objects returned in this case will be N. For example:

​​​​            qualifier=”count 100”

Add the “ext” option to continue the list from the last extension retrieved, for example:

​​​​            qualifier=”ext 25106 count 100”

 Limit the fields returned by specifying them explicitly.

For example use:
<modelFields>
<Station>
<Extension/>
<Name/>
</Station>
</modelFields>

As opposed to:
<modelFields>
<Station/>
</modelFields>

Executing the list operation in this manner will substantially reduce the time needed to return the results.

Timed Out Operations

If you do submit a long-running request (e.g., list operation with <Station/> on a large CM with many extensions), then you may receive a fault message indicating that the operation has timed out. Depending on the size of the offending request, you may find that subsequent requests submitted on the same SMS session fail with a “Busy” fault. Should this occur, the best recovery option is to release the session, and initiate a new one. (See “Authentication and Session Management”, above, for details.)
SMS Configuration

In many cases, the default configuration will be acceptable for normal usage of SMS, however, most configurations can be administered with two AES OAM pages.

The SMS Proxy Ports can be administered on the CTI OAM Home > Network Configuration > Ports page.

SMS Proxy Ports Proxy Port Min Enter a Communication Manager proxy port range of up to 16 proxy ports. By default, the CM Proxy Port Range is 4101 to 4116.
Note: SMS can use up to 16 ports. If you change any of the SMS port assignments, make sure that there are no conflicts with other ports.
Proxy Port Max Enter a Communication Manager proxy port range of up to 16 proxy ports. By default, the CM Proxy Port Range is 4101 to 4116.
Note: SMS can use up to 16 ports. If you change any of the SMS port assignments, make sure that there are no conflicts with other ports.

Other common SMS configurations can be administered on the CTI OAM Home > SMS Configuration page. The SMS Configuration page provides you with the ability to edit the SMS configuration file called “saw.ini” from the AE Services OAM. Because SMS Configuration is a part of AE Services OAM, the saw.ini file will be backed up whenever you use the OAM Backup Database feature to backup the AE Server.

Several other options are also available for fine-tuning the behavior of the SMS Service by manually editing the saw.ini properties file, which can be located by following the “/etc/sms.ini” symbolic link.

General Properties

Property Description
connection Value is set to OSSI. DO NOT CHANGE THIS VALUE.
AllowHTTP If true, SMS SOAP requests can be submitted via HTTP as well as HTTPS. If false, only HTTPS access is permitted. (Submitting a request via HTTP will result in a SOAP fault.)

ACP Properties

These properties govern CM connection options.

Property Description
Name Reserved
ProxyHost Host machine running the proxy process that provides connectivity to CM. The only currently supported configuration is to run the proxy on the same machine where SMS is installed (localhost).
ProxyPort
OAM Configurable The initial TCP/IP port on which to connect to the CM proxy. A range of ports may be used, as specified by the ProxyPortRange property. Default is 4101.
ProxyPortRange
OAM Configurable Specifies how many proxy ports are available (beginning with the value set in ProxyPort). This value determines the maximum number of CM’s that can be concurrently managed via SMS. The maximum currently-supported value is 16. Thus, with the default settings, SMS will use ports in the range 4101-4116 for making connections to CM via the proxy.
CMHost
OAM Configurable The default CM to connect to if no host is specified in an SMS SOAP request. (Default is none, i.e., requests must specify a CM host)
CMPort
OAM Configurable The default administration port on which to connect to a SMS host, if no port is specified in an SMS SOAP request. The default is 5022.
ProxyFile Specifies a file that SMS will use to keep track of currently-active proxy connections. The default setting is “proxyhost” and should not be changed.
ProxyOptions
OAM Configurable Specifies a string of options governing the proxy connections to CM. Options may be specified, separated by spaces, and combined in any order, as follows:
• -k
Specifies the length of time in seconds that the proxy will stay alive before it is shutdown due to in-activity.
• -n
The only default option, specifies that logins are non-interactive, and is required for SMS
• -o
Specifies the length of time in seconds that the proxy will keep a SAT login alive when there is no activity.
• -m <num>
Specifies the maximum number of CM connections that SMS may open concurrently. The default is 5.
• -S
Causes CM connection activity to be logged to syslog. This may be useful for troubleshooting certain kinds of connection problems.
• -T
In the 4.0 release of SMS the SSH protocol was implemented and became the default protocol used for the proxy. To use the Telnet protocol, add this option and make any necessary adjustments to the “CMPort”.
• -V
Turns on verbose logging for troubleshooting purposes, and automatically logs to syslog. This may result in large amounts of data being written to syslog.
• -z
Enables CM superuser login access to station security codes. Normally only the “init” user can read station security codes. With this mode enabled, any customer-created superuser login to CM will be able to read as well as write station security codes.

Dev Properties

Most properties in this section are reserved for development and with the exception of the following, must not be altered.

msg_dst
OAM Configurable Determines where the SMS service will log its activity. The default (apache) when running as a web service accessible via Apache web server is to log to the standard apache logs. The other possible setting is “syslog”.
proxy_log_dst
OAM Configurable Determines where syslog will log the ossicm proxy activity. The default location is in /opt/mvap/log/ossicm.log.
web_service_log_enable Error, warning and some informational messages will be logged when set to “true” (the default). If “false”, only serious errors will be logged.
web_service_message_trace_enable If set to true, the contents of all SOAP messages exchanged with SMS will be written to the logs. The default setting is “false”. Setting this value to true should only be done for diagnostic purposes, as this will result in large amounts of data being written to the log.

Running SMS Client Applications

A test client, with source code, is included as part of this SDK. The test client demonstrates usage of the generated JAX-WS stubs, and basic interaction with SMS. It executes a single SMS request and displays the result, releases the SMS session and exits.

The client program can be found under the smssvc\example\src\sampleapps\smsxml\ folder.

The client stubs have also been compiled and placed under the smssvc\example\lib folder

The SMSXMLTest sample client application uses two properties files in the smssvc\example\resources\ directory to configure its run time behavior. These two files are smsxml.properties and SubmitRequest.xml.
But AEServices and StringNotation client applications are using one properties file aeservices.properties and stringnotation.properties respectively.

properties files

Common Configurations
sms.root =<rootURL> The root URL of the SMS server, either http://<smshost> or https://<smshost>

cm.login=<login@cmaddr[:port]> Specifies the login name and CM address, (and administration port, if non-default) Note: if the CM address is an IPv6 formatted address and the port is specified, then the CM address must be enclosed in square braces (e.g. mylogin@[ffff::10.0.0.1]:4101).
cm.password=<password> Specifies the password for the specified login .
output.format =<xml | key-value> This property controls the format that is used to display the SMS result. It can be either ‘xml’, a marshaled output of the result_data , or ‘key-value’, a key=value display of all model and fields returned from SMS.

The default format is ‘xml’.

SubmitRequest.xml

<ns2:submitRequest xmlns:ns2="http://xml.avaya.com/ws/SystemManagementService/2008/07/01" xmlns:ns3="http://xml.avaya.com/ws/session">
<modelFields>
<Station>
<Extension></Extension>
<Type></Type>
</Station>
</modelFields>
<operation>list</operation>
<objectname></objectname>
<qualifier>count 5</qualifier>
</ns2:submitRequest>
Any of the parameters in the SubmitRequest.xml file may be modified according to the guidelines specified in the “SMS Models and Operations” section of this document. Be sure that any modifications to this file still result in valid XML.

Running the Sample Application
To run the test program, navigate to the smssvc\example\bin folder, and issue the following command on the command line:

​​​​            Linux/Unix

$ ./ant.sh runSMSXMLTest (runAEServices, runStringNotation)

Windows

ant.bat runSMSXMLTest (runAEServices, runStringNotation)

This will execute the default command for the test application (list station count 5) using the selected CM and login. You can experiment with the properties and XML to try different commands.

The run files also illustrate the use of a truststore for secure SSL access via https. The provided file (avayaclient.keystore) has been configured with a default test certificate that should work with a default turnkey installation of MVAP and SMS. If the SMS server has been configured with a different certificate, then to use https, you will need to get a copy of the certificate and use the java keytool utility to add it as a trusted certificate to the avayaclient.keystore, or create your own truststore and reference it in the JVM parameters. Or you can use http instead of https (if SMS is configured to allow HTTP access.)

The source code is fully commented and also serves as a brief tutorial for coding SMS client applications in Java using JAX-WS. (The principles found there will carry over to other toolkits and/or languages.)

The source file (SMSXMLTest.java) is located under the smssvc\example\src\sampleapps\smsxml folder.
Vector Support

As of release 4.1, SMS has added support for the Vector model. This section has been added to help guide users who would like to create or modify Vectors through SMS. Since SMS is a programmatic interface the user experience can be quite different than manually logging into a SAT session on CM. This means that many times it will require extra time and effort to construct a command. The following is a guide that may be used to help construct your own Vector command to submit to SMS, however, many of the concepts given here can be applied to many other models.

• Open up a SAT terminal on CM (see CM administration guide for assistance with this). When constructing an SMS command it is recommended that you use a client test tool and the SAT terminal at the same time. Many fields have dependencies on other fields so it is helpful to use the SAT’s help/documentation features to assist in the construction of a command.
• Using the SAT, execute the command you intend to program SMS with. Example:
“change vector {number}”
• Determine the required fields. In this example we will be programming SMS to add a “queue-to” vector step, so using the SAT move to the first line of the Call Vector form and type “queue-to”. The SAT will now prompt us for a value. This value is one of the dependencies for this vector step. This is where the combination of the SMS Schema Tables (supportedModels.htm) and the SAT help documentation becomes very useful. Using the SAT help we see that we have the option to enter “best” or “skill”. Based on our selection, the dependencies can vary so use the SAT documented help to assist you in finding the rest of the required fields.
• Matching field dependencies in the SMS Schema Tables. From here you can save the vector and use SMS to display it and match up fields. Use one of the client test tools to submit:
ModelFields = <Vector/>
Operation = display
Qualifier = {number}

Results (yours may differ slightly):
<result_data>
<Vector>
<VectorNumber position="1">1</VectorNumber>
<VectorName position="1">Test</VectorName>
…
<VectorStep position="1">queue-to</VectorStep>
<QueueTo position="1">skill</QueueTo>
<QueueToSplitOrSkill position="1">1</QueueToSplitOrSkill>
<QueueToPriority position="1">t</QueueToPriority>
</Vector>
</result_data>

As you can see from the following snippet of the Vector model schema we only used a couple of the field dependences for the queue-to vector step (QueueTo, QueueToSplitOrSkill, and QueueToPriority). If we had chosen “best” instead of skill some of the other fields may have been required.
Field Uid Cardinality Length Label Keywords
QueueTo 6009ff01 100 1 QueueTo best or split,
QueueToBestAttendantExt 6601ff01 100 8 QueueToBestAttendantExt
QueueToBestHuntGrp 6602ff01 100 3 QueueToBestHuntGrp
QueueToSplitOrSkill 0025ff01 100 3 QueueToSplitOrSkill
QueueToPriority 0026ff01 100 1 QueueToPriority

Putting it all together, we can now construct the command we need to submit to SMS. Note, the VectorSteps are position based so if we had more than one we would use:

Operation = change
Qualifier = {number}