Latest Release: 10.2 (Dec 2023)
General
The System Management Service (SMS) exposes management and provisioning features of Communication Manager. This service enables SMS clients to display, list, add, change and remove specific managed objects in Communication Manager. This service provides programmatic access to a subset of the administration objects available via the Communication Manager SAT screens.
The System Management Web Service (SMS) SDK is included in the IP Communication SDK CD. The SDK can be found at http://devconnect.avaya.com
The SMS Web Service SDK file is smssvc-sdk.zip. Expand the SDK ZIP files using any application or tool that recognizes the ZIP file format. All of the SMS SDK files are placed into a directory named smssvc.
The System Management Web Service WSDL is available via the following AES URLs:
New XML formatted interface introduced in AES 5.2
- https://<AEServices-ServerDNSName-or-IP>:443/smsxml/SystemManagementService.php?wsdl (secure)
- http://<AEServices-ServerDNSName-or-IP>:80/smsxml/SystemManagementService.php?wsdl (non-secure)
Deprecated String based interface
- https://<AEServices-ServerDNSName-or-IP>:443/sms/SystemManagementService.php?wsdl (secure)
- http://<AEServices-ServerDNSName-or-IP>:80/sms/SystemManagementService.php?wsdl (non-secure)
Starting with AE Services Release 5, SMS logging is enabled through the Web Management
Console (https://<ip-of-AE-Services>) via the AE Services -> SMS ->
SMS Properties page. Set the SMS Logging to ""VERBOSE", and CM Proxy Trace
Logging to "VERBOSE" and click on Apply Changes. The Tomcat log file location
is /opt/mvap/logs/tomcat; other logs are in
/var/log/avaya/aes/ossicm.log by default.
In older AE Services releases, it is necessary to modify a configuration file on the Linux file system. Start by logging into an AE Services shell session using secure shell.
To capture SMS log messages make the following changes to the
/opt/mvap/web/sms/saw.ini file.
ProxyOptions=-n -V web_service_message_trace_enable=true
The SMS logs are in the following files:
/var/log/messages /var/log/httpd/ssl_error_log *
* In AE Services Release 4.0 and later, SMS messages will go the file
/var/log/httpd/ssl_error_log, provided the default Apache log file
configuration has not been changed. Otherwise, if you have customized your Apache
configuration, these messages will go to whatever log location has been configured for
Apache messages. If in doubt, refer to your apache configuration file(s) located in the
/etc/httpd/conf folder. In prior AE Services releases the SMS log files went to
a file named error_log in the directory described above.
"Connection failed" errors in SMS Client application occur when the SMS module in the AE Service Server cannot successfully establish a connection to the Communication Manager SAT Service. Follow the steps below to identify the issue.
- The address for CM that is being provided is incorrect. Try using the sms_test.php interface (https://< ip-address-of-AES >/sms/sms_test.php), and in the OSSI Login ID field use a valid CM SAT login, in the format of "login@< ip-or-dns-of-CM >:port" where :port is optional and only necessary if a port other than 5023 is being used to verify that connectivity between AES and CM can be established.
- The saw.ini file for SMS (located on AE Service Server at /opt/mvap/web/sms/saw.ini) specifies a CMHost server (should be localhost), or a CMport that is incorrect.
- The CMHost server is referenced as a host name, but no DNS service is operational and the host name is not configured on the AE Service Server in /etc/hosts.
- The Communication Manager SAT is not enabled. Try opening a telnet session to CM's IP address on port 5023 and logging in with CM SAT credentials.
Authentication Failures indicate that the credentials (OSSI Login ID and Password) are not valid on the Communications Manager. Valid Communications Manager Administration login and password must be used.
'Proxy File is inaccessible' indicates that the file /opt/mvap/web/sms/templates_c/proxyhost cannot be created or written to. Usually this indicates a permission problem. The file must be readable/writable by SMS, which is running under Apache (httpd). Check the permissions on this file if it exists, and on the folder /opt/mvap/web/sms/templates_c, and ensure that the httpd process has full read/write privileges to this location. Important Note: If SELinux (security-enhanced linux) is enabled, then httpd may not necessarily have write access even if the linux DAC permissions appear to be set correctly. SELinux should never be enabled on RedHat Linux 3. It may, however, be enabled by default on customer-configured (software-only) installations running on RedHat Linux4. To confirm whether this is the problem in such a case, disable SELinux for httpd and retry the failing SMS operation.
This error indicates that the connection proxy between the SMS and the CM server cannot be established. Check the settings in the /opt/mvap/web/sms/saw.ini file for ProxyHost, ProxyPort and ProxyPortRange.
- ProxyHost: This should always point to the local host address (the default value is "localhost"). Verify that one can successfully "ping localhost". Depending on the /etc/hosts configuration, other firewall/security settings "localhost" may become irresolvable or unreachable by SMS. Try setting this value to the local loopback address (ProxyHost=127.0.0.1).
- ProxyPort and ProxyPortRange: They define the range of ports the connection proxy process (ossicm) will use. The default is 16 ports, beginning with port 4001. Confirm that no other processes have any of these ports in use (netstat -lpnt).
There is now an SMS test application for the new XML formatted interface which is available with AE Service Release 5.2 or newer. The old string based format is now deprecated, but can still be used in AE Services 5.2, and is the only option for AE Services systems older than 5.2.
Users can access the SMS XML test application by pointing a browser to
http://<ip-address-or-hostname-of-AE_Services>/smsxml/smsxml_test.php.
Users can access the SMS string based test application by going to
http://<ip-address-or-hostname-of-AES>/sms/sms_test.php. This interface
allows users to construct requests and get the responses. Users need to provide information
into the Communication Manager SAT (System Access Terminal) Login ID, Password, SMS Host (AE
Services IP), Model, Operation, Qualifier (when necessary) and Fields areas.
Perform the following steps to determine the object, qualifier and field information.
- Gain access to a SAT window via Avaya Site Administration or other means, issue the
command, and then do a list history. The list history output will show the command
broken into action, object (name), and qualifier fields.
- The SAT action corresponds to the SMS operation
- The SAT object corresponds to the SMS model
- The SAT qualifier corresponds to the SMS qualifier. Since some commands do not require a qualifier it may not be shown.
- Be sure to use a Communication Manager login ID and password that has rights to run the commands being used. For instance the user group prof18 gives a user rights to run any command. User groups 20-69 are custom and have to be set up properly in Communication Manager. For example, if the command 'list station' is run and a message from Communication Manager is given that says "station is an invalid entry; please press HELP", then most likely the login ID does not have the proper permissions to run the command.
- This step is for the XML based test application. If you are having trouble with the Fields specifier, don't specify any fields. This will return all the field data for that object. Examine the XML return_data, and look at all of the tags within the specified Model to get the fields that are available to be retrieved. Starting with AE Services 5.2 you can access array based fields by name with this XML based interface. It is important to know what operation you need to be using to access the array fields you are retrieving. For example, button data for the Station model can only be retrieved when using the operation 'display'. Be sure to specify the Position field, which is in red, when accessing ArrayType fields. Also, if you are manually updating the XML (entering XML into the request text box below the Update XML button) there is a note that when you are done updating you need to click the Update XML button. Failure to do so will result in the loss of your changes, and the request that was performed last before you hit the Update XML button will be sent to SMS.
- This step is for the string based test application. If you are having trouble with the Fields specifier, try using a star "*". This will return all the field data for that object. Examine the result_data items and use the syntax from the response to specify the fields you wish to retrieve separating them with the pipe "|" character. It is not possible to request array-based fields by name. The only way to read array-based data is to read fields="*" or by using specific references, e.g. array[1]|array[2].
- For both interfaces you can also get information on the supported models by clicking on Model Documentation on the left hand side of the test application.
Users can find the answer to this question by pointing a browser to http://< ip-address-of-AES >/sms/getModelClasses.php
This document is an online reference for each supported model. When a model is double clicked, the corresponding page shows the supported operations and the selectable fields. The possible qualifiers can be determined by accessing a SAT window via Avaya Site Administration and issue a command "< action > < object name >" and then hitting F5 (help). The SAT interface will show the possible command modifiers.
The jar files the SMS client is using are too recent. Check them against the ones in the sample code and modify them as appropriate smssvc\example\bin\*.jar.
This exception indicates that the credentials (extension and extension password from the station form) are not recognized by the system that received the request.
There are error messages similar to the one below, and they represent a file permission problem.
Warning: Smarty error: problem creating directory "templates_c/%%-13/%%-1361846814" in /opt/mvap/web/sms/Smarty.class.php on line 999
This is the same problem as described in the "Connection Failure" section, under the subheading "Proxy File Inaccessible". Follow the directions there to resolve this issue.
The IP addresses of the stations can be obtained from the SMS Web Service in AE Services server 4.1 by executing the 'list RegisteredIPStations' command where 'list' is the operation type and 'RegisteredIPStations' is the model type. This gives the IP addresses of the stations in the 'Station_IP_Address' field and the corresponding station's extension in the Station_Extension field. To avoid having the command timeout, it may be necessary to provide a starting extension and a count and break the response in to small groups of extensions. This functionality is supported from AE Services server version 4.1 onwards.
There is no license requirement to develop and run System Management Web Service applications in AE Services release 3.x and 5.x. In release 4.x a license was required for each simultaneous connection to a Communication Manger. Thus if three SMS applications needed to interface to three separate Communication Managers, and it was expected that all three applications would simultaneously be accessing 'their' Communication Manager, three licenses were required.
There are Application Enablement Services (AES) API called System Management Service (SMS) which supports a subset of the commands allowed at the System Access Terminal (SAT). In release 4.0 of AES, working with 3.X and 4.0 of Communication Manager (CM), this API supports one of the required commands associated with the SA8420 service (enable ip-registration). Alternatively, to perform call center Agent login and logout, both JTAPI/TSAPI and DMCC APIs can use feature access codes to log agents in and out. DMCC can also push buttons on the station it is monitoring which allows a more static configuration behavior.
No. SMS is for system management and administration that would be the inappropriate web service. Instead, use JTAPI/TSAPI to obtain this information.
Through SMS and the SAT, only an "init" user/login has privileges to view the Security_Code (station's password). The init login is not available to customers, business partners or other non-Avaya personal.
In order for a "non-init" user to access a station's Security_Code through SMS, the ProxyOptions parameter needs to be changed from the default value of "-n" to "-n -z" in the /opt/mvap/web/sms/saw.ini file on the AE Server. This allows all applications utilizing the AE Server to access this data so changing this permission level should be done with care.
In AE Services Release 4.1 you can communicate with up to 16 different CMs simultaneously through a single AES. Each connection to a CM consumes a single SMS license. Each license can allow multiple application sessions to interface a CM at the same time. A CM is defined here as an IP address or DNS name. An AE Server can have up to 5 application sessions to a single CM at the same time, for a maximum total of 80 (16 * 5) simultaneous sessions.
The 'Time Out' error occurs when Communication Manager (CM) takes a long time to process the request before sending the response. When the request processing time exceeds the request timeout interval, a 'Time Out' error response is received by the application. To set the "Time Out Interval" for SMS Web Services the value of the field named "OSSI_ResponseTimeout" present in the saw.ini file needs to be changed. This file is located at /opt/mvap/web/sms in AE Services server. Also, in the SMS Web Service test application 'sms_test.php', there is a field called 'SOAP Request Timeout (seconds)' which specifies the time out period when querying the server.
On Communication Manager, a profile specifies which System Access Terminal (SAT) screens can be accessed by a user account assigned to that profile. The profile further defines the type of access to each screen. The commands available through SMS web service are governed by the following profile settings:
- The user profile for the account should have at least 'readonly' access to the 'usage' group (category Q) and the permission is set to 'r-' (category and permission may change depending upon the SAT commands the user needs to execute).
- The user profile/group and account/login is added to 'Maintenance' web interface. As 'list' command needs 'readonly' access, all the default logins ('cust' or 'craft') should work. These logins have read/write permissions to 'usage' category and are already added to the 'Maintenance' web interface.
If a SMS application is using an account with customized profile on the Communication Manager, then the user needs to ensure that the items mentioned above are configured.
Capture as much diagnostic information as possible to share with Avaya support. All of the following may be useful:
1. Use the FAQ "How can the logs be turned on (trace, tracing)?" to enable VERBOSE tracing.
2. Re-attempt the operation(s) causing problems.
3. Gather the following files. (For logfiles, if large, gather just the tail end of the
log
containing the most recent messages relevant to the problem):
/var/log/messages /var/log/httpd/ssl_error_log /opt/mvap/web/sms/saw.ini /opt/mvap/web/sms/templates_c/proxyhost
4. Run the following linux commands and capture/record the results:
rpm -qa | grep sms rpm -qa | grep httpd rpm -qa | grep php ps -Aefww | grep ossicm ps -Aefww | grep httpd ls -ld /opt/mvap/web/sms/templates_c
SMS is not able to provide the requested information because the request has not been specified correctly. Instead of specifying 'ext 0 to-ext 10' as the Qualifier, valid extension numbers must be specified. For example, for listing the extensions from 2000 to 2010, the Qualifier should be 'ext 2000 to-ext 2010'. The number specified after ext and to-ext must be a valid extension number in accordance with the dial plan provisioned for Communication Manager.
SMS web service can be used to obtain the list of IP addresses, CLAN, PROCR etc, provisioned on Communication Manager. There is a two-step process to get the CLAN IP addresses. Use the 'SubmitRequest' method from the SMS service and pass Request Parameters as mentioned in the following steps:
- Get the list of node names Set the Model field to ListNodeNames and the Operation field to List. This response will contain the list of nodes (CLAN, PROCR etc.) with corresponding IP addresses in Communication Manager.
- For each of the node names returned in the previous step, check if the type is CLAN. Set the Model field to IPInterface and the Operation field to display. Check the value for field type, if this is clan, then the IP address refers to the CLAN IP address.
AE services server supports two types of Web Services: Telephony web service and System Management Service (SMS) web service and licensing requirements for these services are different.
Telephony Web Service - Communication Manager requires Computer Telephony Adjunct Links to be licensed for Web Services. AE Services requires a TSAPI Basic license for Telephony Web Services (denoted as "TSAPI Simultaneous Users" in the License file and web screen).
System Management Service (SMS) - Communication Manager does not require that any features be licensed for SMS. AE Services requires the following feature to be licensed for SMS: "SMS Proxy Connections"
To verify how many licenses are available (provisioned and in-use) to use Web Services on the AE Services server, use a web browser to access http://<ip-address-of-AE-Services> select WebLM Administration and then login (these credentials may be obtained from whomever you procured the AE Services server from) to the WebLM License Administrator page on the AE Services server and select Application Enablement.
For more information, please refer to Avaya MultiVantage® Application Enablement Services Administration and Maintenance Guide, Release 4.2, 02-300357, Issue 10, May 2008 for details about WebLM and administration of licenses. This document is available on www.avaya.com/devconnect.
The information related to all XML APIs or requests for any web service can be found in the WSDL file for the web service. For the SMS web service, the WSDL URL is 'http://<AE_services_server_address>/sms/SystemManagementService.wsdl'.
If the user is using a utility such as wsdl2java to create stubs and use them in the application, then information about the methods and parameters can be found in the web service document Application Enablement Services Web Services Programmer Guide, Release 4.1, Avaya MultiVantage® Communications Application, 02-300362, Issue 4.0, December 2007, available on the DevConnect portal (http://www.avaya.com/devconnect).
The AE Services SMS web service interface allows executing Communication Manager commands from the web application using web service calls. For retrieving the provisioned Skill Level and Skill Number information of an Agent, the application needs to invoke the submitRequest Web Service method with the following set of parameters: model = Agent, operation = display, qualifier = Login_ID (e.g. 50001), objectName = "" (an empty string), and field = "*".
A developer can see the format of a response by using the https://<server name>/sms/sms_test.php page, providing all the above mentioned values in the corresponding textboxes and by clicking on the Submit Request button. The response displayed in the Response textbox will include the list of Skill Levels and Skill Numbers of the Agent.
The below sample code snippet shows how to send the request for retrieving the Agent's
provisioned Skill Numbers and Skill Levels.
// Request all the fields.
private String fields = "*";
Result result = null; // will hold the response
try
{
// Access SMS at the root URL (http(s)://smshostaddress)
// and the fixed path "/sms/SystemManagementService.php"
String root = "http://localhost"; // assuming SMS Web Service is
// running on localhost.
URL url = new URL(root + "/sms/SystemManagementService.php" );
// Bind to a port on the AES service locator.
bindingObject = new SystemManagementBindingStub(url, locator);
// Set a timeout for the web service response. Here we allow 30,000 ms
// (30 seconds)
bindingObject.setTimeout(30000);
}
catch (AxisFault axisFault)
{
System.out.println("Fault generated during SOAP binding: " +
axisFault);
return false; // request failed
}
try
{
// Send the SOAP request to SMS running on the AES server
SubmitRequestType req = new SubmitRequestType();
req.setModel(model);
req.setOperation(operation);
req.setObjectname(objectName); // objectName, not presently used
req.setQualifier(qualifier);
req.setFields(fields);
result = bindingObject.submitRequest(req).get_return();
// The result code indicates success or failure (CM rejected the
// request)
if( result.getResult_code() == 0 ) // 0 indicate request was successful
{
// retrieve the data from result
String data = result.getResult_data();
if ( data.length() > 0 )
{
// Separate result data values into an array.
String [] values = result.getResult_data().split("\\|");
System.out.println("Result is :");
for (String output : values)
{
System.out.println(output);
}// end of for
}// end if inner if
}// end of if
else
{
// In case CM rejected the request, the message text will
// contain CM's explanation
System.out.println( "The request returned an error " );
System.out.println( "Reason: " + result.getMessage_text() );
}
}// end of try
catch (RemoteException exception)
{
// A exception was raised. The exception message will contain the
// explanation
System.out.println("A SOAP exception was raised: " +
exception.getMessage());
}// end of catch
The output of the above code is shown below. Please note that the sample code returns all the
skills provisioned for the given agent.
Result is : Login_ID=50001 Name=Agent TN=1 COR=1 Coverage_Path= Security_Code= AAS=n AUDIX=n LWC_Log_External_Calls=n AUDIX_Name_for_Messaging= Login_ID_For_ISDN_Display=n Auto_Answer=station MIA_Across_Skills=system ACW_Agent_Considered_Idle=system Aux_Work_Reason_Code_Type=system Logout_Reason_Code_Type=system Maximum_Time_In_ACW_Before_Logout=system Direct_Agent_Skill= Call_Handling_Preference=skill-level Local_Call_Preference=n Password=12345 Password_Confirmation=12345 SN[1]=11 SN[2]=1 SN[3]=3 SL[1]=1 SL[2]=1 SL[3]=1
The provisioned Skill Numbers and Skill Levels of an Agent can then be obtained by parsing the result text as appropriate.
The developer can go through www.avaya.com/devconnect -> Sample Applications -> Web Services Sample Applications -> System Management Services (SMS) Web Portal for information about an existing sample application which uses SMS to access Communication Manager provisioned data.
In AE Services 4.x a license (SMS_OSSI) was imposed on the number of allowed SMS connections to Communication Manager(s). This licensing is removed in release 5.2 and beyond. The licensing was not present in release 3.x.
The license restricted how many Communication Managers AE Services could simultaneously communicate with up to a maximum of 16.
Each license allowed up to five (5) simultaneous client 'sessions' to be active between SMS applications and a particular Communication Manager. This limit of 5 is just a maximum, and not a licensed value.
A maximum of 16 connections to Communication Manager is supported. This allows a maximum of 5*16 simultaneous client sessions to be active.
In all releases, these same maxima limits are imposed:
- 16 separate Communication Managers at any one time (the upper limit was restricted by a license in AE Services release 4.x)
- 5 simultaneous sessions per Communication Manager.
There is also no upper bound on the number of client applications that can utilize the SMS service over a period of time. The limit of simultaneous client sessions is a function of the limits described above.
When performing any function on System Management Services (SMS) you must first know how to get the information from Communication Manager using the SAT interface. When using the command "list configuration software-version" the Communication Manager version is returned.
The SMS test application, found at https://[aesip]/smsxml/smsxml_test.php, has a
link to the model documentation on the left-hand side. You will notice that the
Configuration model supports the "list configuration" command. Since the “software-version”
qualifier brings up a totally different form with different fields the
SoftwareVersion model was created. Running this model in the SMS test
application with the list operation will send the request "list configuration
software-version" to Communication Manager, and will return the proper fields to the test
application. Once you verify its functionality with the test application you can add the
model request to your own application.
If you are new to SMS there are sample applications on this website at http://www.devconnectprogram.com/site/global/products_resources/avaya_aura_application_enablement_services/educational_resources/sample_applications/sms_web_service/index.gsp.
The first two applications listed make use of the SMS web service.
When running the SoftwareVersion model with the list operation the result data will look something like this:
<result_data>
<SoftwareVersion>
<Version>R016x.03.0.124.0</Version>
<Version_On_Disk>R016x.03.0.124.0</Version_On_Disk>
<Translation_Date>10:00 pm THU MAY 14, 2015</Translation_Date>
<Translation_Date_On_Disk>10:00 pm THU MAY 14, 2015</Translation_Date_On_Disk>
<Disk_Second_Copy>good</Disk_Second_Copy>
</SoftwareVersion>
</result_data>
The “Version” portion of the response contains the Communication Manager software version. The “R01” is part of the version recognized by development but is not relevant to the version that is posted on Avaya’s support website. That leaves 6x.03.0.124.0. The ‘x’ next to 6 is also not relevant to the version. So this is particular Communication Manager is 6.3.0 build 124. That is the base GA (Generally Available) posted on Avaya’s support site for version 6.3. Currently there is not a way via SMS to get the patch level, as there is no way to find it via the Communication Manager SAT.