VxOne
-
Upload
amitchoubey -
Category
Documents
-
view
214 -
download
1
description
Transcript of VxOne
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 1 of 93
VxOneTM Provisioning & Administration Guide
Abstract
This document describes the provisioning and subscriber administration facilities of VxOneTM.
Release Version 6.0 Document Version 1.3 Date 15 May 2006 Pages 93
-
Commercial in Confidence
Page 2 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Table of Contents
1 INTRODUCTION ..............................................................................................................5
1.1 Scope............................................................................................................................5
1.2 Related Documents.......................................................................................................5
1.3 Document Audience ......................................................................................................5
1.4 Document Conventions .................................................................................................5
2 PROVISIONING................................................................................................................6
3 XML BULK LOAD ............................................................................................................7
3.1 Overview .......................................................................................................................7
3.2 XML Bulk Load provisioning mechanism.......................................................................7
3.3 Planning XML Bulk provisioning ....................................................................................7
3.3.1 XML file creation ........................................................................................................8
3.3.2 Property file configuration ........................................................................................11
3.3.3 Pre - Encrypted Data ...............................................................................................12
3.3.4 Bulk XML Upload .....................................................................................................12
4 LDAP AUTO PROVISION ..............................................................................................13
4.1 Overview .....................................................................................................................13
4.2 LDAP provisioning mechanism....................................................................................13
4.3 Planning LDAP provisioning ........................................................................................14
4.3.2 Provision email accounts on the email store. ...........................................................19
4.3.3 Point the LDAP connector to the right directory server. ...........................................19
4.3.4 Set the right context for searches on the particular schema.....................................19
4.3.5 Configure all tags for the LDAP search. ...................................................................20
4.3.6 Verify LDAP schema................................................................................................20
4.3.7 Pre Encrypted Data...............................................................................................21
4.3.8 Verify User and Email Account defaults. ..................................................................21
4.3.9 Activate LDAP auto provisioning..............................................................................21
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 3
4.3.10 Restart the server. ...................................................................................................21
4.4 Creating new Automatic Provisioning plug-in ..............................................................21
5 PROVISIONING ON DEMAND.......................................................................................22
5.1 Overview .....................................................................................................................22
5.2 Provisioning Service....................................................................................................22
6 ADMINISTRATION SOAP INTERFACE.........................................................................23
6.1 Overview .....................................................................................................................23
6.2 Attribute Description ....................................................................................................23
6.3 Methods Overview.......................................................................................................25
6.4 Response Codes.........................................................................................................28
6.5 Method Description .....................................................................................................31
6.5.1 CreateUser service ..................................................................................................31
6.5.2 CreateCompleteCWUser Service ............................................................................35
6.5.3 RetrieveUsers service..............................................................................................37
6.5.4 RetrieveUserDetails service.....................................................................................41
6.5.5 RetrieveUserDetailsByLogin ....................................................................................45
6.5.6 RetrieveSpecificUserDetails service ........................................................................49
6.5.7 UpdateUser service .................................................................................................50
6.5.8 UpdateCWUserIdentifiedByLogin service ................................................................54
6.5.9 UpdateCWUserMSISDN..........................................................................................56
6.5.10 DeleteUser service ..................................................................................................57
6.5.11 DeleteUserOnAppAndMailStore Request ................................................................59
6.5.12 CreateEmailAccount service....................................................................................60
6.5.13 RetrieveEmailAccounts service................................................................................63
6.5.14 RetrieveEmailAccountDetails service.......................................................................64
6.5.15 UpdateEmailAccount service ...................................................................................67
6.5.16 DeleteEmailAccount service ....................................................................................70
6.5.17 RetrieveRegisteredDevices service .........................................................................71
6.5.18 UpdateRegisteredDevices service ...........................................................................73
-
Commercial in Confidence
Page 4 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.6 SOAP Message Examples ..........................................................................................76
6.6.1 Request message....................................................................................................76
6.6.2 Response message .................................................................................................76
6.7 SOAP ADMIN PROPERTIES......................................................................................77
6.7.1 Validation.................................................................................................................77
Any trademarks or service marks referred to within this document are the property of their respective owners.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 5
1 Introduction
1.1 Scope This document provides configuration and operational information relating to the automatic user provisioning and administration interfaces of VxOneTM.
1.2 Related Documents The following documents should be read to gain a full understanding of the deployment process.
Document Name Document Description
[1] Configuration Guide This document details all configuration files relating to VxOneTM
[1] Operations Guide This document describes the procedures to operate VxOneTM.
1.3 Document Audience The intended audience for this document are IT Support and Operations staff within the organisation.
1.4 Document Conventions The table below highlights the values that are to be used when there is a Document Reference mentioned within this document.
Document Reference Value
[VOXSURF_HOME] The directory where VxOneTM has been
deployed
[VOXSURF_PROPERTIES] The directory where the VxOne shadow property files have been deployed
-
Commercial in Confidence
Page 6 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
2 Provisioning VxOneTM provides three mechanisms for the automatic provisioning of users:
XML bulk load LDAP auto-provisioning SOAP provision on demand Administration SOAP interface
All mechanisms allow deployment operators to specify a few essential parameters within the bulk load files or LDAP directories while a more blanket definition of the other values can be provided with default properties files.
The VoxSurf LDAP Connector is just one implementation of an automatic provisioning APD. Alternative solutions can be implemented by created new automatic provisioning plug in modules.
Please Note: All configuration changes should be made to the property files located within the system shadow level ONLY. Please refer to the VxOneTM Configuration Guide for more information relating to shadow property files.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 7
3 XML Bulk Load
3.1 Overview The VxOneTM XML Bulk load tool provisions subscribers within the RDBMS (Relational Database Management System). The tool does not currently create any email accounts on the email store. It is assumed that accounts will be created on the email store by a different mechanism, although support for specific email stores can be added on a custom basis.
3.2 XML Bulk Load provisioning mechanism The VxOneTM XML Bulk load tool requires an XML file as the basis to provision subscribers into the system. The XML DTD (Document Type Definition) can be found in section Appendix 1: Bulk Load DTD.
The bulk load tool does not create the account on the mail store, although this feature can be added for specific email stores on a custom basis.
The high-level steps required to provision subscribers using this mechanism are as follows:
Provision email accounts on the mail store (unless they already exist) Create one XML file, which contains the elements for each of the
subscribers. Each element defines:
o User Details o Application Details o Email Account Details
Some of the elements within the element are mandatory and some are optional. The optional elements are denoted within the DTD by an asterisk (*). If these elements are not included within the XML, the default values are configured from the following configuration files:
o [VOXSURF_PROPERTIES]/system/VxsProvisioningDefaultUser.properties
o [VOXSURF_PROPERTIES]/system/VxsProvisioningDefaultEmailAccount.properties
Execute the file [VOXSURF-HOME]\WEB-INF\bin\provisioning\provision.sh
Review the log file to ensure all subscribers have been provisioned successfully. The log file should be located in the directory where the bulk load is run from.
3.3 Planning XML Bulk provisioning The XML Bulk tool requires the following components to be configured prior to executing the process
XML file creation - Create one XML file, which contains the elements for each of the subscribers.
-
Commercial in Confidence
Page 8 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Configure the default values specified within the following configuration files: o [VOXSURF_PROPERTIES]/system/VxsProvisioningDefaultUser.propert
ies
o [VOXSURF_PROPERTIES]/system/VxsProvisioningDefaultEmailAccount.properties
3.3.1 XML file creation The following table contains information about all the items that the Bulk Load tool requires in order to provision a subscriber.
Refer to section Appendix 2: Bulk Load XML Example for an example file, or alternatively, locate the example.xml file within the directory [VOXSURF-HOME]\WEB-INF\bin\provisioning\VoxSurf
Fields in bold are mandatory. All others are optional and may be left unmapped so that default values are picked up from property files.
[1] Fields may be pre encrypted. See the corresponding boolean in VxsProvisoning.properties.
3.3.1.1 Domain Element
Element Attribute(s) Description Value Example
Domain Value The domain number in which the subscribers will be provisioned too.
0000
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 9
3.3.1.2 UserDetails Element
Element Attribute(s) Description Value Example
UserId Value A unique numeric id used to identify this user. If no value is supplied an id will be assigned.
56484511
AccountNumber Value The subscribers account number. This should be numeric
12345678
AccountPin [1] Value The subscribers pin number 1234
Question Value The forgotten question text Mothers Name
Answer [1] Value The forgotten question answer
Smith
RegisteredEmailAddress
Value The subscribers registered email address
FirstName Value The subscribers first name Alan
LastName Value The subscribers last name Smith
Title Value The subscribers title Employee
Organisation Value The subscribers organisation Company
Industry Value The industry Telecoms
Administrator Value Should the subscriber have administration rights
True
MobilePhoneNumber CountryCode phoneNumber
The country code of the numberThe mobile phone number
44
7855 360915
LandLine1PhoneNumber CountryCode phoneNumber
The country code of the numberThe first registered land line phone number
44
207 759 9250
LandLine2PhoneNumber CountryCode phoneNumber
The country code of the numberThe first registered land line phone number
44
207 759 9251
Unified Value CountryCode PhoneNumber SMSNotification
Should the user be unified The country code of the number The mobile phone number
Should SMS notification be enabled
True
44
7855 360 915
True
-
Commercial in Confidence
Page 10 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
3.3.1.3 ApplicationDetails Element
Element Attribute(s) Description Value Example
FaxEnabled Value Should the subscriber be fax enabled
True
Language Value The subscribers default language. En
VoiceDetails StartPoint emailAccStartPoint
SendOnHangUp
Speed
Volume
The starting point of the voice application -
E for email
V for voicemail
T for the top (main) menu The starting point for email accounts within the voice application
P for the primary account
M for the main email menu
When composing a message in voice, should the message still be sent if the caller hangs-up rather than explicitly says Send Message
The default voice speed
The default voice volume
T
P
True
135
9
MessageHeaderDetails EmsgNum
ErcvdDate Eorig
VMMsgNum
VMRcvdDate
VMOrig
Default voice settings the subscriber will hear the message number when listening to an email message
Default voice settings the subscriber will hear the message received date when listening to an email message
Default voice settings the subscriber will hear the originator when listening to an email message
Default voice settings the subscriber will hear the message number when listening to a voicemail message
Default voice settings the subscriber will hear the message received date when listening to a voicemail message
Default voice settings the subscriber will hear the originator when listening to a voicemail message
True
True
True
True
True
True
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 11
3.3.1.4 EmailAccountDetails Element
Element Attribute(s) Description Value Example
AccountName Value The name of the email account
Work
EmailDisplayName Value The subscribers preferred display name
A Smith
EmailAddress Value The subscribers email address
Locked Value Should the account be locked from subscriber edit
False
MailServer Name protocol port secure
The mail server IP address The connection protocol, IMAP / POP The connection port number Should the connection to the Mail Server be secure
10.0.0.1
IMAP
143
false
Username Value The email account username
a.smith
Password [1] Value The email account password 1234
SMTPRelay Name
port
secure
The SMTP relay IP Address
The SMTP relay Port
Should the connection to the SMTP relay be secure
10.0.0.2
25
False
EnableSentItems Value Should the sent items folder be enabled for the subscriber
False
EnableDeletedItems Value Should the deleted items folder be enabled for the subscriber
False
RootFolderName Value The name of the root folder for the subscriber. An example is INBOX. A blank option will default to INBOX
3.3.2 Property file configuration Bulk provisioning retrieves user information from the xml files containing data for each specific user. If a value is not specified in the XML file (non mandatory values), the bulk provisioning mechanism looks for a default value in the shadow properties location.
The property files relating to the defaults for both bulk load and LDAP auto provisioning can be found within the following directory:
-
Commercial in Confidence
Page 12 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
[VOXSURF_PROPERTIES]\system\
VxsProvisioningDefaultEmailAccount.properties - Refer to section Appendix 3: VxsProvisioningDefaultEmailAccount.properties for configuration suggestions.
VxsProvisioningDefaultUser.properties - Refer to section Appendix 4: VxsProvisioningDefaultUser.properties for configuration suggestions.
3.3.3 Pre - Encrypted Data By default bulk provisioning assumes that the sensitive fields being passed in (AccountPIN, Answer and Password) are loaded unencrypted and then encrypted internally by VxOneTM. If however the data is pre encrypted, the provisioning mechanism must be set to not encrypt the relevant values. This is done by setting the relevant property to false, in the file:
[VOXSURF_PROPERTIES]\system\
VxsProvisioning.properties Refer to VxOne Configuration Guide
3.3.4 Bulk XML Upload Before proceeding with the actual bulk load, it is imperative that property files and the XML file have been configured properly and no mandatory information is left unspecified.
The bulk upload tool should be executed from the console in command-line mode. The file can be found in the following location
[VOXSURF-HOME]\WEB-INF\bin\provisioning\provision.bat.
The batch file requires 1 parameter, which is the full path details and filename of the XML file, for example
C:\voxsurf\WEB-INF\bin\provisioning\provision.bat c:/temp/xmlimport.xml
Once the process is complete, please review the log file for the transaction details of the upload. The log file should be located in the directory where the bulk load is run from.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 13
4 LDAP Auto Provision
4.1 Overview The VxOneTM LDAP Connector synchronizes users information between VxOneTM and LDAP directory servers. The LDAP Connector allows VxOneTM to utilise subscriber information, stored in an LDAP directory server to automatically provision information in the RDBMS.
The VxOneTM LDAP Connector enables the automatic provisioning and management of users on pre-existing LDAP directory servers.
The VxOneTM LDAP Connector supports RFC 2251 (LDAP v3) and RFC 1777 (LDAP v3) compliant LDAP directory servers connecting via anonymous or basic SASL authentication binding mechanisms.
The LDAP Connector API can be called from external java applications to trigger the provisioning of users in bulks if required.
The bulk load tool does not create the account on the mail store, although this feature can be added for specific email stores on a custom basis.
4.2 LDAP provisioning mechanism The VxOneTM LDAP Connector retrieves customer information from an LDAP directory server every time a user logs into the application but his / her authentication information (i.e. Login ID, CLI, DDI) is not recognised. This information is used to provision the user information in the RDBMS.
This way of dealing with provisioning has a number of important advantages:
Users can be provisioned on the fly within VxOneTM without the need for any preliminary provisioning activity.
Since provisioning is done on the fly only the first time the user access the application, there are no performance implications.
Service Providers can keep a centralised repository of customer information in an LDAP server, which is used to drive the provisioning of all components. For example, most of the mail stores support an LDAP directory for provisioning. This dramatically simplifies the management of customers and their authorisation and eliminates the problem of synchronisation among different systems.
The VxOneTM LDAP Connector is a heavily customisable component that can be modified to cope with different LDAP structures and can be adapted to the needs of each particular deployment. The VxOneTM The next release of the VoxSurf LDAP Connector will also support various SASL binding mechanisms.
LDAP connector does not require changes to the LDAP schema to support provisioning. The LDAP schema could be enhanced to provide more personalised information for each user.
When the VxOneTM LDAP Connector attempts to automatically provision a user it retrieves all available information from the LDAP server. If some of the (non-mandatory) values are not available, default values are used that can be configured on a server. If, for example, the LDAP server has no information about the name of the email server
-
Commercial in Confidence
Page 14 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
that the user has an account on, this value will be obtained from the default properties file.
The order of precedence is therefore:
1. Data on the LDAP server;
2. Default values from the default properties files (described in the remainder of the chapter).
The Provisioning procedure is therefore as specified in the following diagram:
Notify User and Exit
User Logs in Using LoginIDand PIN (numeric values)
Profile Data is retrievedfrom the CPOC LDAP
server
Is the userprovisioned on the
system (LDAPbind)?
Create New User inselected domain and
populate user
Is the userprovisioned on theVoxSurf system?
NO
YES
Start Application
NO
YES
Provisioning Data
First nameLast nameRegistered Mobile NumberLanguageIs VoxSurf Email enabled?Is VoxSurf UM enabled?Is VoxSurf Fax enabled?Email addressEmail ServerEmail Account Type (IMAP/POP)Email acct IDTimestampDomainRegistered CLI1, CLI2, CLI3, CLI4Is Admin of Domain, X, Y, ZIs Root Admin
4.3 Planning LDAP provisioning The VxOneTM LDAP Connector can be configured to cope with any particular LDAP schema by modifying a LDAP context parameter, and can adapt to make searches on any parameter to isolate a particular subscriber. The connector expects a small number of parameters to be available in the LDAP schema for each particular user. The picture shows a typical database schema, but the actual structure of the particular directory schema could vary depending on the particular deployment.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 15
4.3.1.1 User Information
The following table contains all the items that the VxOneTM LDAP Connector looks for in the LDAP schema for specific user information.
Each of the names of the properties can be configured to make it compatible with the particular schema. The table column Tag Example contains example values, but these could change for each schema. E.g. the last name is sometimes assigned to an object called sn, and sometimes (e.g. in Microsoft Exchange) to an object called surname.
Fields in bold are mandatory. All others are optional and may be left unmapped so that default values are picked up from property files.
[1] Fields may be pre encrypted. See the corresponding boolean in VxsProvisoning.properties.
-
Commercial in Confidence
Page 16 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Tag ID Tag Example Description Value Example USER_ID
uid An optional unique id for this user.
56484511
DOMAIN_ID DOMAIN_ID Id of the VxOneTM domain 0000
LOGIN_ID UserId The users Login Id 02077599250 PIN [1] PIN The users PIN 23453266
FIRST_NAME cn The users firstname John
LAST_NAME Gn This users lastname Doe FORGOTTEN_QUESTION FORGOTTEN_QUESTION Security question asked to the
user when he forgets his login information
Mother maiden name
FORGOTTEN_ANSWER [1] FORGOTTEN_ANSWER Answer to secret question required to unlock sending of user login information
Franklin
TITLE TITLE Title CEO ORGANISATION Organisation Organisation VoxSurf INDUSTRY INDUSTRY Industry Telecommunications
REGISTERED_EMAIL Mail The users registered email address. (Where login information is sent to)
Mail
SUBSCRIBER_NUMBER SUBSCRIBER_NUMBER Used to identify a device when accessing the application using a WAP phone. Subscriber numbers are passed by WAP gateways and identify a particular phone.
123456789
IS_VOICEMAIL_ENABLED IS_VOICEMAIL_ENABLED Determines if the user has voicemail enabled.
true
IS_EMAIL_MESSAGING_ENABLED
IS_EMAIL_MESSAGING_ENABLED Determined if the user has email messaging enabled.
true
IS_FAX_SERVICE_ENABLED
IS_FAX_SERVICE_ENABLED Determines if the user is allowed to send faxes
true
IS_ADMINISTRATOR ADMINISTRATOR Determines is the user is an administrator.
false
PHONE_MOBILE_COUNTRY_CODE
PHONE_MOBILE_COUNTRY_CODE Country code of the registered mobile phone number (this is the number SMS notifications are sent to)
44
PHONE_MOBILE_REST_OF_NUMBER
PHONE_MOBILE_REST_OF_NUMBER Area code and phone number of the registered mobile phone (this is the number SMS notifications are sent to)
777983421
PHONE_MOBILE_MESSAGE_DEPOSIT_ENABLED
PHONE_MOBILE_MESSAGE_DEPOSIT_ENABLED
Indicate if registered mobile phone has message deposit enabled.
true
ALL_MESSAGES_TO_MOBILE
ALL_MESSAGES_TO_MOBILE Indicate whether all voicemails are sent to an MMS enabled mobile for the user account.
true
PHONE_LAND1_COUNTRY_CODE
PHONE_LAND1_COUNTRY_CODE Country code of a registered landline number 1.
44
PHONE_LAND1_REST_OF_NUMBER
PHONE_LAND1_REST_OF_NUMBER National code of a registered landline number 1.
2077599250
PHONE_LAND1_MESSAGE_DEPOSIT_ENABLED
PHONE_LAND1_MESSAGE_DEPOSIT_ENABLED
Indicate if registered land line 1 has message deposit enabled.
true
PHONE_LAND2_COUNTRY_CODE
PHONE_LAND2_COUNTRY_CODE Country code of a registered landline number 2. 44
PHONE_LAND2_REST_OF_NUMBER
PHONE_LAND2_REST_OF_NUMBER National code of a registered landline number 2. 2077599250
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 17
PHONE_LAND2_MESSAGE_DEPOSIT_ENABLED
PHONE_LAND2_MESSAGE_DEPOSIT_ENABLED
Indicate if registered land line 2 has message deposit enabled.
false
UNIFIED_PHONE_REST_OF_NUMBER
UNIFIED_PHONE_REST_OF_NUMBER Country code of the DDI assigned to a user for their answer service (should be defined for voicemail)
44
UNIFIED_PHONE_COUNTRY_CODE
UNIFIED_PHONE_REST_OF_NUMBER Area code of the DDI assigned to a user for their answer service (should be defined for voicemail)
2073425453
4.3.1.2 Email Account information
The following table contains all the items that the VxOneTM LDAP Connector looks for in the LDAP schema for the email account of a specific user.
Each of the names of the properties can be configured to make it compatible with the particular schema. The table column Tag Example contains example values, but these could change for each schema. E.g. the last name is sometimes assigned to an object called sn, and sometimes (e.g. in Microsoft Exchange) to an object called surname.
Fields in bold are mandatory. All others are optional and may be left unmapped so that default values are picked up from property files.
[1] Fields may be pre encrypted. See the corresponding boolean in VxsProvisoning.properties.
Tag ID Tag Example Description Value Example
EMAIL_ACCT_TYPE EMAIL_ACCT_TYPE Type of email account. Possible values:
IMAP: IMAP4 account.
POP: POP3 account.
Exchange: Microsoft Exchange 5.5 or 2000 account with MAPI access and Addressbook, Calendaring and Tasks capability.
IMAP
EMAIL_ACCT_STORE_ADDRESS
EMAIL_ACCT_STORE_ADDRESS Network address or IP address of mail store
imap.voxsurf.com
EMAIL_ACCT_STORE_USER_ID
EMAIL_ACCT_STORE_USER_ID Account ID of the user on the mail store. This must always be defined on the LDAP directory. If it is not specified, the LDAP provisioning module (Java strategy) can be modified to locate account information from an alternative source or obtain it from available information (e.g. accountId = firstName.lastName
john.doe
EMAIL_ACCT_STORE_PASSWORD [1]
EMAIL_ACCT_STORE_PASSWORD Password of the user on the mail store (if not specified, a default password can be located in the defaults properties files).
Secret
-
Commercial in Confidence
Page 18 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
EMAIL_ACCT_STORE_PORT EMAIL_ACCT_STORE_PORT Port of the email account (default is 143 for IMAP and 110 for POP; 993 for SecIMAP etc).
143
EMAIL_ACCT_STORE_SSL EMAIL_ACCT_STORE_SSL Should use and SSL tunnel for connectivity to the email store
false
EMAIL_ACCT_EMAIL_ADDRESS
Mail Users email address [email protected]
EMAIL_ACCT_DISPLAY_NAME
Common Name This is the name and last name shown next to the email address (e.g. the name in: John Doe [email protected])
John Doe
EMAIL_ACCT_NAME EMAIL_ACCT_NAME Name given to the email account within VxOneTM (e.g. work, home, com, demo etc)
demo
EMAIL_ACCT_LOCKED EMAIL_ACCT_LOCKED Email accounts can be locked so that subscribers cannot modify them. This saves from subscribers invalidating their accounts and unnecessary support calls to be initiated.
true
EMAIL_ACCT_ROOT_FOLDER
EMAIL_ACCT_ROOT_FOLDER Root folder of an email account (some email accounts support namespaces so that the specification of a root folder such as the INBOX is necessary)
inbox
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 19
The file VxsProvisioningJNDI.properties can be modified to adapt it to the particular schema (refer to the Operations Guide and the Configuration Guide for information on locating, editing and managing configuration files.
The steps to configure the VxOneTM LDAP connector are described in the following diagram:
4.3.2 Provision email accounts on the email store. The VxOneTM LDAP Connector does not provide this functionality currently. The functionality can be added by customising the user creation strategy as specified in chapter: 4.4 Creating new Automatic Provisioning plug-in
4.3.3 Point the LDAP connector to the right directory server. The following property must be changed in the VxsProvisioningJNDI.properties configuration file:
Server info:
# ProviderUrl (i.e. ldap://:) providerUrl=ldap://10.0.0.1:389
If a username and password are required for the connection to the directory server, they are set with the security principle and credentials as follows:
securityPrincipal=username securityCredentials=password
4.3.4 Set the right context for searches on the particular schema. The context must be set to adapt the LDAP connector to the specific LDAP schema. Please consult your LDAP administrator to obtain the right context for the section in the schema containing context information.
2: Point LDAP connector to the LDAP server
3: Set right context for searches
4: Configure LDAP searches tags
5: Verify LDAP schema
6: Verify User and Email Account defaults
7: Activate LDAP provisioning
8: Restart the server
1: Create email accounts on the email store
-
Commercial in Confidence
Page 20 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
The example that follows represents the context in a typical Microsoft Exchange 5.5. active directory deployment. The name of the property is context and the search string is the whole argument to the right of the first =, that is ou=DOMAIN,o=Voxsurf,co=UK in the example.
# Context (i.e. ou=DOMAIN,o=Voxsurf,co=UK) context=ou=DOMAIN,o=Voxsurf,co=UK
If you are unsure about the particular directory schema, a standard LDAP browser can be used to analyse the directory structure (a powerful, easy to use LDAP browser can be downloaded from http://www.ldapbrowser.com/). Just open the directories in the sub tree until you localise the directory containing all the user records. The right context is the full ID of that node.
For example, dealing with the following type of schema:
Each user can be identified with a search with context:
CN=Users,DC=crayfish,DC=voxsurf,DC=com.
In the above mentioned browser, just right click on the directory containing the users and click on properties to obtain the name of the node
4.3.5 Configure all tags for the LDAP search. Configure the tags defined in the user information and email account information tables described above. The tags can be located in the VxsProvisioningJNDI.properties file. Some of the tags need to be adapted to the particular schema (e.g. use sn for LAST_NAME), and some can be left unchanged in the configuration file if new fields will be added to the existing directory.
4.3.6 Verify LDAP schema.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 21
Make sure that the mandatory fields for both users and email accounts (as described in the user information and email account information tables above) are defined for all users in the directory server.
4.3.7 Pre Encrypted Data By default provisioning assumes that the sensitive fields being passed in (AccountPIN, Answer and Password) are loaded unencrypted and then encrypted internally by VxOneTM. If however the data is pre encrypted, the provisioning mechanism must be set to not encrypt the relevant values. This is done by setting the relevant property to false, in the file:
[VOXSURF_PROPERTIES]\system\
VxsProvisioning.properties Refer to VxOne Configuration Guide 4.3.8 Verify User and Email Account defaults.
Verify that all necessary information has been specified correctly in the files for defaults for user accounts and email accounts. A complete guide to the default value available can be found in section(s) Appendix 3: VxsProvisioningDefaultEmailAccount.properties and Appendix 4: VxsProvisioningDefaultUser.properties
For example, if the system will provision users that are allowed to send faxes, a default value of true for the faxServiceEnabled property in the VxsProvisioningDefaultUser.properties configuration file, or, to provision users that all have their email account on a server called, for example, imap.voxsurf.com the property mailServerAddress, in the VxsProvisioningDefaultEmailAccount.properties class can be modified accordingly.
4.3.9 Activate LDAP auto provisioning. This can be accomplished by setting the property AutoProvisioningOn to true in the VxsEnvironment.properties file.
4.3.10 Restart the server. The application server (just the servlets container, not the whole machine) must be restarted for changes to take effect.
4.4 Creating new Automatic Provisioning plug-in The VxOneTM LDAP connector is just one possible version of the VxOneTM automatic provisioning plug-in. The module can be customised to cope with special requirements or to deal with completely different mechanisms (e.g. radius etc). For example, if email account ID and email account password are not available on the LDAP server but can be obtained from an alternative repository, the LDAP provisioning strategy can be modified to fetch and manipulate information as required.
The VxsProvisionUserStrategy class, described in section Appendix 5: VxsProvisionUserStrategy can be implemented by an alternative provisioning strategy. This gives flexibility to use different provisioning mechanisms (e.g. radius, xml sources, soap) to do automatic provisioning.
To write an alternative mechanism implement the VxsProvisionUserStrategy interface and edit the VxsProvisioning.properties to make the application use the alternative strategy. To activate the new provisioning mechanism modify the following property: ProvisioningStrategyClass=com.voxsurf.provisioning.VxsProvisionLDAPUserStrategy
-
Commercial in Confidence
Page 22 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
To make it point to the new strategy, place the new class in a location contained in the application server class path and the application will use the alternative provisioning mechanism).
5 Provisioning on Demand
5.1 Overview As well as provisioning users automatically, VxOneTM provides a web service interface to provision users on demand. This allows a call to be made via a SOAP interface to the provisioning service to force a user with a given subscriber id to be provisioned immediately.
5.2 Provisioning Service The VxOneTM provisioning-on-demand service is a SOAP web service that exposes a single method:
/**
* Loads a single subscriber.
*
* @param subscriberId the subscriber to be loaded
* @return the status code of the load
*/
public int load(long subscriberId);
The Web Services Description Language definition for the service can be found in Appendix 6: Provision-on-Demand WSDL Definition.
The load method takes in a long value which represents the id of the user to be provisioned via LDAP. This corresponds to the USER_ID tag defined in 4.3 Planning LDAP provisioning. When the load method is called, the user is provisioned immediately, using the same mechanism used for auto-provisioning, and the user details are stored in the database.
If the user does not exist in the database, it will be created, and the email account will be added. If the user already exists in the database, it will be updated. If the user has an existing email account with the same name as the provisioned account, it will be updated, otherwise a new account will be created.
The status code returned by the load method may be one of:
1. The user has been successfully provisioned.
2. The user has not been provisioned due to an error.
3. An exception was raised initializing the LDAP context.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 23
6 Administration SOAP Interface
6.1 Overview As well as provisioning users, VxOneTM provides a SOAP interface for administration of users. This allows external Customer Care tools to be integrated with VxOneTM providing the following functionality:
User Administration o Creating new users. o Searching for existing users. o Retrieving user details. o Updating existing users. o Delete existing users.
Email Account Administration o Create email accounts for a user. o Searching for email accounts for a given user. o Retrieving a users specific account details. o Update existing email account. o Delete existing email account.
Registered Device Administration o Retrieving registered devices for a user. o Update registered devices for a user.
The Web Services Description Language definition for the administration service can be found in Appendix 7.
The SOAP Interface also has an XML schema, the VoxSurf.xsd that defines valid requests and responses, and can be found in Appendix 8.
6.2 Attribute Description This section describes the attributes used in the SOAP interface to pass user information to and from VxOneTM.
Attribute Description User ID A synthetic user account ID that is unique across all users and domains.
If this is not specified in the create method, VxOne will generate one internally.
LoginID This is the VoxSurf account login ID. It is unique to the user and used, by the user, to log in to the VoxSurf Email application. In the edit mode the administrator cannot modify this field, as it must remain unique to the user.
FirstName This is the users first name, LastName This is the users last name. primaryEmailAddress This is the users primary email address. It is the address that the login
details will be sent to when the user has answered their security question
-
Commercial in Confidence
Page 24 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Attribute Description correctly.
AccountLocked This is a flag to indicate whether the users account is locked. After a configurable number of failed login attempts, a users account will be locked for security
Administrator This sets Administrator status for the user. AuthenticationAccountId This is a secondary authentication account identifier for the user. If VxOne
is configured to use an external authentication mechanism, this is the identifier that will be passed through.
ClassOfService This defines the users class of service, which defines a logical grouping of users for which application attributes can be configured.
domainID This is the ID of the domain that a user belongs to. ForgottenAnswer This is the answer to the users security question. ForgottenQuestion This is the security question that will be asked on the Forgotten Personal
Identification Number screen in the HTML Email application if the user forgets their login details.
Locale This is the users choice of language for the VoxSurf Email application (this is not applicable to the Voice application). The options within this drop down are taken from the VxsLanguages.properties file, which lists the supported languages. This overwrites the machine locale when the user logs in.
NumberOfVisits This is the number of times the user has accessed the VoxSurf application. PIN This is the users login password. It is used in association with the users
Account Number to log in to the Voxsurf Email application. PinChangeRequired This defines whether this account is protected by a PIN. PinProtection This defines whether a user can disable PIN authentication for login when
using a registered device. SubscriberNumber This is the users WAP registration number. It is automatically added when
the user accesses the WAP application. TimeZone This is the users local time zone, which is used to localise time stamps on
messages within VxOne. The options within this drop down are taken from the VxsTimeZones.properties file, which lists the supported time zones.
VoiceboxCountryCode This is the country code of the DDI voicebox number VoiceboxNumber This is the DDI number that a call must be diverted to or called directly to
leave the user a voicemail message. EmailDestinations This sets where the user is taken to after saying the global command go
to email in the Voice application.
HtmlLookAndFeel This specifies which look and feel should be used for the html interface. FaxEnabled This sets whether the fax service is enabled for the user. MessagesPerPage This sets the number of messages displayed per page on the HTML Email
application folder view page. Speed This is the words spoken per minute by the Voice application. It ranges
between 20 and 300 and has a default value of 135. Volume This is the volume setting for the Voice application. It ranges between 1
and 10 and has a default value of 8. Persona This sets the style of the Voice application. Changing the persona
changes the voice of the application, and the commands the user can give the application.
voicemailMmsDirect This checkbox determines whether the user requires their voicemails to be sent to them as MMS attachments directly to their mobile phone rather than being sent as audio files to their email account.
VoicemailEnabled 1 This defines whether the user has access to the Voicemail service. If the voicemail service is disabled through shadow properties this value cannot be set on a per user basis.
emailEnabled This defines whether the user has access to the Email service. StartPoints This sets where the user is taken to after logging in successfully to the
Voice application. Title This is the users title e.g. Mr., Mrs. Organisation This is the organisation that the user works for. Industry This is the industry that the user works in.
1 Can not be set if the property is disabled at a system level Email Account ID The email account ID. This is created by VxOne, but required for the other
operations on this profile (such as updating and deleting).
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 25
Attribute Description emailAccountName This is the name of the email account. This name may not be the same as
that for another email account for the selected user. PrimaryAccount Flag to set this account as primary. There must always be one and only
one primary email account. EmailName This is the users email name. It is the name that will be displayed when
someone receives an email sent from the selected account. EmailAddress This is the email address for the selected account. Reply to This is the
email address for replies to emails sent from the selected account.. Locked Flag to indicate the selected account as locked. The user in the HTML
Email application cannot edit any account that is locked. The administrator, however, can always edit an email account through the administration tool
VoiceMail Enables the selected account as the voice mail account. ServerAddress This is the selected email accounts mail server, e.g. pop.mail.yahoo.com ServerType These define what type of server protocol the account uses. Valid types
are either POP3, IMAP4, or Exchange. ServerPort This is the server port number. This is defaulted to 143 for IMAP 4
accounts and 110 for POP3 accounts. SslRequired This defines whether the mail protocol is encrypted over SSL. SmtpServerAddress The name of the SMTP server SmtpServerPort The port of the SMTP server. IMAP email settings UserName. This is the users user name for the selected email account Password This is the users password for the selected email account. ReplyTo This is the users reply to email address. SentMailFolder 2 The name of the folder used to store sent messages. DeletedMailFolder 2 The name of the folder used to store deleted messages DraftsMailFolder 2 The name of the folder used to store draft messages EnableDeletedMail 2,4 Enables the deleted mail folder. EnableDraftsMail 2,4 Enables the drafts mail folder. EnableSentMail 2,4 Enables the sent mail folder. RootFolder 2 This should be specified if the users personal folders exist below a folder
other than the default root folder. Usually inbox NTDomain 3 This is the name of the NT Domain which the Exchange server is in. ContactsSource. 3 This specifies whether the Exchange account should be used as the
source for contacts within VxOne CalendarSource. 3 This specifies whether the Exchange account should be used as the
source for calendaring within VxOne TasksSource. 3 This specifies whether the Exchange account should be used as the
source for tasks within VxOne
2 Only applicable to accounts that support multiple folders (IMAP4) 3 Only applicable to accounts of type Exchange 4 Can not be set if the property is disabled at a system level
Devices AdvancedNotificationEnabled 5 To enable advanced notification types. AdvancedNotificationMethod 5 The type of advanced notification to send, SMS or MMS. BasicNotificationEnabled 5 To enable sending message for the user via MWI CountryCode The country code of the registered device. NationalCode The national number of the registered device. PinRequired This flag specifies whether a pin is required when the device is used to
access the system. MessageDepositEnabled This flag specifies whether the device can deposit messages. DeviceType This specifies the type of device. Currently mobile, fixed or pager
5 If there are no registered devices capable of receiveing the notification, the SOAP interface will not persist changes to the notification values. Currently at least one mobile device must be specified before these settings become active.
6.3 Methods Overview
-
Commercial in Confidence
Page 26 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Each SOAP administration method requires a different set of required and optional and attributes. The method can return either an XML document with the attributes listed below, or an error response with an error code and message detailed in the following section.
Method Required Attributes Optional Attributes Returned Attributes createUser LoginID
FirstName LastName PrimaryEmailAddress
Id AccountLocked Administrator AuthenticationAccountId ClassOfService DomainId ForgottenAnswer ForgottenQuestion Locale NumberOfVisits Pin PinChangeRequired PinProtection SubscriberNumber TimeZone VoiceboxCountryCode VoiceboxNumber EmailDestinations HtmlLookAndFeel MessagesPerPage Persona Speed StartPoints VoicemailMmsDirect Industry Organisation Title
UserID
retrieveUsers
FirstName LastName AccountNumber DomainID EmailAddress MatchCase MatchWholeWord
List of UserID accountNumber FirstName LastName EmailAddress DomainID
retrieveUserDetails userID DomainID ClassOfService accountNumber PINChangeRequired AuthenticationAccountID AccountLocked Question Answer PrimaryEmailAddress FirstName LastName Title Organisation Industry NumberOfVisits FaxService Speed Volume Language TimeZone Administrator HtmlLookAndFeel Persona PinProtection VoicemailEnabled EmailEnabled Voicebox Number
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 27
Method Required Attributes Optional Attributes Returned Attributes VoicemailMmsDirect VoicemailNotificationOption StartPoint EmailDestination
updateUserDetails UserID AccountLocked Administrator AuthenticationAccountId ClassOfService DomainId ForgottenAnswer ForgottenQuestion Locale NumberOfVisits Pin PinChangeRequired PinProtection SubscriberNumber TimeZone VoiceboxCountryCode VoiceboxNumber EmailDestination HtmlLookAndFeel MessagesPerPage Persona Speed StartPoint Volume VoicemailMmsDirect FirstName Industry LastName Organisation PrimaryEmailAddress Title
deleteUser userID
createEmailAccount EmailAccountName EmailAddress EmailName Locked Password PrimaryAccount ServerAddress ServerType UserName Voicemail
CalendarSource ContactsSource DeletedMailFolder DraftsMailFolder EnableDeletedMail EnableDraftsMail EnableSentMail NTDomain ReplyTo RootFolder SentMailFolder ServerAddress ServerPort SMTPServerAddress SMTPServerPort SSLRequired TasksSource
emailAccountID
retrieveEmailAccounts userID List of
emailAccountID retrieveEmailAccountDetails emailAccountID CalendarSource
ContactsSource DeletedMailFolder DraftsMailFolder EmailAccountName EmailAddress EmailName EnableDeletedMail EnableDraftsMail EnableSentMail Locked NTDomain
-
Commercial in Confidence
Page 28 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Method Required Attributes Optional Attributes Returned Attributes Password PrimaryAccount ReplyTo RootFolder SentMailFolder ServerAddress ServerPort ServerType SMTPServerAddress SMTPServerPort SSLRequired TasksSource UserName Voicemail
updateEmailAccountDetails emailAccountID CalendarSource ContactsSource DeletedMailFolder DraftsMailFolder EmailAccountName EmailAddress EmailName EnableDeletedMail EnableDraftsMail EnableSentMail Locked NTDomain Password PrimaryAccount ReplyTo RootFolder SentMailFolder ServerAddress ServerPort ServerType SMTPServerAddress SMTPServerPort SSLRequired TasksSource UserName Voicemail
deleteEmailAccount emailAccountID
retrieveRegisteredDevices userID AdvancedNotificationEnabled AdvancedNotificationMethod BasicNotificationEnabled List of CountryCode DeviceType MessageDepositEnabled NationalCode PinRequired
updateRegisteredDeviceDetails UserID List of CountryCode DeviceType MessageDepositEna
bled NationalCode PinRequired
AdvancedNotificationEnabledAdvancedNotificationMethod BasicNotificationEnabled
6.4 Response Codes
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 29
Once a request has been made to the administration SOAP interface, a response XML document is generated that contains a status code indicating whether the request was successful or not. The caller of the service will receive a XML document as a response. It can contain a number of status messages, each of which has a code and value, which can be broken down into three groups, success, exception and failure.
Success Code 0 in the response means the response was carried out successfully. UpdateEmailAccount 0
Exception
Code 2 in the response means that an exception has occurred whilst processing the request. If the exception has a message associated it becomes the Value. UpdateEmailAccount 2 Values Missing during mapping
Failure
Before the response is carried out a number of validation checks are done on the information contained within the response. If any problems are found during the validation a specific code and value are produced for each error. Only after all the values are deemed to be valid will the requested service be fulfilled. CreateEmailAccount 5006 missing email address 5008 missing pop server
Failure status messages-
Code Value 1 {General code - exception message} 3 Error with mailstore 1001 Invalid {order number device appers in request} country code. 1002 Invalid {order number device appers in request} number. 1003 Missing {order number device appers in request} country code 1004 Missing {order number device appers in request} number 1005 The {order number device appers in request} number is already registered
-
Commercial in Confidence
Page 30 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
1006 {order number device appers in request} number has already been used 1007 {order number device appers in request} number has already been used Message desposit field
must be a boolean 1007 Device {order number device appears in request} Message desposit field must be a boolean 1008 {order number device appears in request} number has already been used Pin required field must be
a boolean 1008 Device {order number device appears in request} Pin required field must be a boolean 1009 {order number device appears in request} number has already been used has invalid device type. 1009 Device {order number device appears in request} has invalid device type. 2001 Invalid PIN number 2002 No PIN has been entered 2006 The account number must be between $1 and $2 digits 2007 Invalid account number 2008 No first name has been entered 2009 No last name has been entered 2011 No question has been entered 2012 No answer has been entered 2013 No title has been entered 2014 No email address has been entered 2017 Number of visits is invalid 2018 Number of messages per HTML page is invalid 2019 Speed must be between 20 and 300 2020 Volume must be between 1 and 100 2021 Number of messages per HTML page is not within range 2024 No more users can be added to this domain 2025 That domain does not exist 2026 Invalid domain Id 2027 Invalid registered email address 2028 No account number has been entered 2033 Invalid Administrator Boolean 2039 Account number already taken 2040 Invalid password change required field 2041 Invalid PIN protection value 2042 User Id already in use 2043 User not found 2044 Email destination must be of specified enum value 2045 Start point must be of specified enum value 2046 Invalid User Id 3001 Invalid subscriber number 3002 Voice box number in use 3003 Invalid voice box number 3004 Invalid voice box number country code 3005 voice box number not allowed 3006 Missing voice box number 3007 Missing voice box country code 3008 Invalid Voice MMS Direct Field 4018 boolean value must be entered for advanced notification enabled 4019 boolean value must be entered for basic notification enabled 4020 Advanced notification method must be of enum value. 4044 Email destination must be of specified enum value 4045 Start point must be of specified enum value 5001 email account exists 5002 missing account name 5003 No user name has been entered 5005 missing user name 5006 No email address has been entered 5008 missing pop server 5009 missing pop server port 5011 missing smtp server port 5017 The sent mail folder name entered is too long. 5018 The deleted items folder name entered is too long. 5020 Invalid registered email address 5021 Invalid reply email address 5024 Invalid sent mail folder name
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 31
5025 Invalid deleted mail folder name 5026 Invalid drafts folder name 5027 invalid email account type 5028 invalid email account locked 5032 Invalid value in calendar source field 5033 Invalid contacts source boolean 5034 Invalid value in Trash enabled field 5035 Invalid value in Drafts enabled field 5036 Invalid value in Sent enabled field 5037 Invalid value in PrimaryAccount field 5038 Invalid value in TasksSource field 5039 Invalid value in VoiceMail field 5040 Invalid value in EnableSSL field
6.5 Method Description This section describes the methods supported by the Administration SOAP interface, along with XML schema definitions for each method and example XML for requests and responses.
6.5.1 CreateUser service This method creates a new user using the information provided in the parameters.
The userID of the new account is returned.
-
Commercial in Confidence
Page 32 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.1.1 Request Schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 33
The place the voice app should go after saying "go to email". P=Primary Account, M=Main Menu The voice app entry point. E=Email, T=Top, V=Voicemail
-
Commercial in Confidence
Page 34 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.1.2 Example request XML payload CreateUser false true authId Gold 0000 answer question en_GB 99775533 0 1234 false false 192837465 Europe/London 44 8833774466 M Mercier 25 Paula 10 T 10 false FirstName Telecom LastName Organisation [email protected] CEO
6.5.1.3 Response schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 35
6.5.1.4 Example response XML payload CreateUser
0
6.5.2 CreateCompleteCWUser Service The method creates a ready-to-use subscriber, creating a subscriber on VxOne and a corresponding mailbox on the mailstore. It uses the LoginId element as:
- The subscribers MSISDN primary registered phone
- LoginId
- The mailbox name on the mailstore
6.5.2.1 Request Schema
-
Commercial in Confidence
Page 36 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.2.2 Example request XML payload CreateCompleteCWUserr 0812345678 AdvancedVoicemailWithContacts th 7531 false
6.5.2.3 Response Schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 37
6.5.2.4 Example response XML payload
CreateCompleteUser 0
6.5.3 RetrieveUsers service This method retrieves the userIDs of subscribers for a given set of criteria.
6.5.3.1 Request Schema
-
Commercial in Confidence
Page 38 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.3.2 Example request XML payload
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 39
RetrieveUsers 0000
6.5.3.3 Response schema
-
Commercial in Confidence
Page 40 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 41
6.5.3.4 Example response XML payload RetrieveUsers
0
0000 99999999 Root Administrator Root Administrator [email protected] 0000 11335577 Timo Ahokas [email protected] 0000 99775533 FirstName LastName [email protected]
6.5.4 RetrieveUserDetails service This method retrieves the complete user details for a given userID.
6.5.4.1 Request schema
-
Commercial in Confidence
Page 42 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.4.2 Example request XML payload RetrieveUserDetails
6.5.4.3 Response schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 43
The place the voice app should go after saying "go to email". P=Primary Account, M=Main Menu The voice app entry point. E=Email, T=Top, V=Voicemail
-
Commercial in Confidence
Page 44 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.4.4 Example response XML payload RetrieveUserDetails
0
false true authId Gold 0000 answer question en_GB 99775533 0 1234 false false 192837465 Europe/London 44 8833774466
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 45
M Mercier 25 Paula 10 T 10 false S FirstName Telecom LastName Organisation [email protected] CEO
6.5.5 RetrieveUserDetailsByLogin This method returns a the details of a subscriber for a given LoginId
6.5.5.1 Request Schema
6.5.5.2 Example request XML payload
RetrieveUserDetailsByLogin
6.5.5.3 Response schema
-
Commercial in Confidence
Page 46 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 47
The place the voice app should go after saying "go to email". P=Primary Account, M=Main Menu The voice app entry point. E=Email, T=Top, V=Voicemail
-
Commercial in Confidence
Page 48 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.5.4 Example response XML payload RetrieveUserDetailsByLogin 0 false false Everything 0000 42 What is the answer? en_GB 0812457863 0 1357 false GMT-05:00 M styled 5 135 T 50 false 0812457863 0812457863 [email protected] title
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 49
6.5.6 RetrieveSpecificUserDetails service This method returns a limited amount of details for a given LoginId.
6.5.6.1 Request Schema
6.5.6.2 Example request XML payload RetrieveUserDetailsByLogin
6.5.6.3 Response schema
-
Commercial in Confidence
Page 50 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.6.4 Example response XML payload
RetrieveSpecificUserDetails 0 AdvancedVoicemailWithContacts th 0812345678 true
6.5.7 UpdateUser service This method updates the user details for a given userID.
6.5.7.1 Request Schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 51
-
Commercial in Confidence
Page 52 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
The place the voice app should go after saying "go to email". P=Primary Account, M=Main Menu The voice app entry point. E=Email, T=Top, V=Voicemail
6.5.7.2 Example request XML payload UpdateUser
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 53
false false authId Gold 0000 answer question en_GB 0 1234 false false 192837465 Europe/London 44 8833774455 P Mercier 20 Paula 10 T 10 false First Finance Last Organisation [email protected] CEO
6.5.7.3 Response schema
-
Commercial in Confidence
Page 54 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.7.4 Example response XML payload UpdateUser
0
6.5.8 UpdateCWUserIdentifiedByLogin service This method updates PIN, ClassOfService, Locale and ECC notification settings.
6.5.8.1 Request schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 55
6.5.8.2 Example request XML payload
UpdateCWUserIdentifiedByLogin AdvancedVoicemailWithContacts en 1357 false
6.5.8.3 Response Schema
-
Commercial in Confidence
Page 56 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.8.4 Example response XML payload
UpdateCWUserIdentifiedByLogin
0
6.5.9 UpdateCWUserMSISDN This methodupdates the user details when an MSIDN change is nessecary.
6.5.9.1 Request schema
6.5.9.2 Example request XML payload
UpdateCWUserMSISDN 081299999
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 57
6.5.9.3 Response schema
6.5.9.4 Example response XML payload UpdateCWUserMSISDN
0
6.5.10 DeleteUser service This method deletes the user account for a given userID
6.5.10.1 Request schema
-
Commercial in Confidence
Page 58 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.10.2 Example request XML payload DeleteUser
6.5.10.3 Response schema
6.5.10.4 Example response XML payload DeleteUser
0
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 59
6.5.11 DeleteUserOnAppAndMailStore Request This method deletes the subscriber from VxOne and the associated mailbox from the mailstore.
6.5.11.1 Request schema
6.5.11.2 Example request XML payload
DeleteUserOnAppAndMailStore
6.5.11.3 Response schema
-
Commercial in Confidence
Page 60 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.11.4 Example response XML payload
DeleteUserOnAppAndMailStore
0
6.5.12 CreateEmailAccount service This method creates a new email account for a given userID using the information given in the parameters.
The emailAccountID of the new email account is returned.
6.5.12.1 Request schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 61
ServerTypes: POP3, IMAP4, EXCHANGE
6.5.12.2 Example request XML payload CreateEmailAccount false false Deleted Items Test
-
Commercial in Confidence
Page 62 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Drafts Folder Test Test Account Black4 [email protected] black4EmailName true true true false SomeDomain 1234 false [email protected] SomeRoot Sent Items Test devcp.voxsurf.com 143 IMAP4 smtp.voxsurf.com 25 false false black4username true
6.5.12.3 Response schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 63
6.5.12.4 Example response XML payload CreateEmailAccount
0
6.5.13 RetrieveEmailAccounts service This method returns the emailAccountIDs of the email accounts for a given userID.
6.5.13.1 Request schema
6.5.13.2 Example request XML payload RetrieveEmailAccounts
6.5.13.3 Response schema
-
Commercial in Confidence
Page 64 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.13.4 Example response XML payload RetrieveEmailAccounts
0
6.5.14 RetrieveEmailAccountDetails service This method returns the email account details for a given emailAccountID.
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 65
6.5.14.1 Request schema
6.5.14.2 Example request XML payload RetrieveEmailAccountDetails
6.5.14.3 Response schema
-
Commercial in Confidence
Page 66 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
ServerTypes: POP3, IMAP4, EXCHANGE
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 67
6.5.14.4 Example response XML payload RetrieveEmailAccountDetails
0
false false Deleted Items Drafts Test Account Black4 [email protected] black4 false false false false 1234 false [email protected] INBOX Sent Items devcp.voxsurf.com 143 IMAP4 devcp.voxsurf.com 25 false false black4 false
6.5.15 UpdateEmailAccount service This method updates the email account details for a given emailAccountID.
6.5.15.1 Request schema
-
Commercial in Confidence
Page 68 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
ServerTypes: POP3, IMAP4, EXCHANGE
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 69
6.5.15.2 Example request XML payload UpdateEmailAccount false false Deleted Items Drafts Test Account Black3 [email protected] black3 false false false false 1234 false [email protected] Sent Items 192.168.1.27 143 IMAP4 192.168.1.27 25 false false black3 false
6.5.15.3 Response schema
-
Commercial in Confidence
Page 70 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.15.4 Example response XML payload UpdateEmailAccount
0
6.5.16 DeleteEmailAccount service This method deletes the email account for a given emailAccountID.
6.5.16.1 Schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 71
6.5.16.2 Example request XML payload DeleteEmailAccount
6.5.16.3 Response schema
6.5.16.4 Example response XML payload DeleteEmailAccount
0
6.5.17 RetrieveRegisteredDevices service This method returns the deviceIDs of the registered devices for a given userID.
6.5.17.1 Request schema
-
Commercial in Confidence
Page 72 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.5.17.2 Example request XML payload RetrieveRegisteredDevices
6.5.17.3 Response schema
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 73
Available advanced notification methods: MMS or SMS. The registered device types: PHONE_MOBILE (M), PHONE_FIXED (F), PAGER (P)
6.5.18 UpdateRegisteredDevices service This method returns the deviceIDs of the registered devices for a given userID.
6.5.18.1 Request schema
-
Commercial in Confidence
Page 74 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Available advanced notification methods: MMS or SMS. The registered device types: PHONE_MOBILE (M), PHONE_FIXED (F), PAGER (P)
6.5.18.2 Example request XML payload UpdateRegisteredDevices
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 75
44 M true 12345678 false 44 F false 23456789 false
6.5.18.3 Response schema
6.5.18.4 Example response XML payload UpdateRegisteredDevices
0
-
Commercial in Confidence
Page 76 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
6.6 SOAP Message Examples Listed below is an example of a full HTTP request message with the corresponding response message. The messages contain the appropriate SOAP messages for the RetrieveUser service.
6.6.1 Request message POST /voxsurf/services/CustomerCareWS HTTP/1.0 Content-Type: text/xml; charset=utf-8 Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: Axis/1.1 Host: 127.0.0.1 Cache-Control: no-cache Pragma: no-cache SOAPAction: "" Content-Length: 1081 RetrieveUsers 0000 99887733 FirstName LastName [email protected]
6.6.2 Response message HTTP/1.1 200 OK Content-Type: text/xml;charset=utf-8 Date: Tue, 22 Feb 2005 12:01:44 GMT Server: Apache-Coyote/1.1 Connection: close RetrieveUsers
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 77
0
0000 99887733 FirstName LastName [email protected]
6.7 SOAP ADMIN PROPERTIES Properties that control aspects of SOAP provisioning are found in -
[VOXSURF_PROPERTIES]/system/VxsProvisioning.properties
6.7.1 Validation SOAPAdminValidator property controls if validation occurs on the request values before the service is carried out e.g. checking that values are booleans. By default, validation is turned on by setting the property to true. Validation can be quite expensive. If SOAP Admin is being used for Bulk provisioning, it may be wise to consider turning off the validation, by setting the property to false.
-
Commercial in Confidence
Page 78 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Appendix 1: Bulk Load DTD
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 79
-
Commercial in Confidence
Page 80 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
phoneNumber CDATA #REQUIRED smsNotification (True|False) #REQUIRED>
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 81
-
Commercial in Confidence
Page 82 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Appendix 2: Bulk Load XML Example
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 83
Appendix 3: VxsProvisioningDefaultEmailAccount.properties Please refer to the Configuration Guide for more details on this property file.
Field Description Possible Values
Example
accountName The default Email Account Name VoxSurf accountType The default Email Account Type IMAP,POP IMAP enableDeletedItems Enable the Deleted Items Folder TRUE enableSentItems Enabled the Sent Items Folder TRUE locked Locked from subscriber edit TRUE mailServerAddress The default Mail Server IP Address 10.0.0.1 mailServerPort The default Mail Server Port 143, 110, 993,
995 143
mailServerSecure The default Mail Server Secure Connection True/false FALSE password The default password 1234 rootFolderName The default Root folder name INBOX INBOX smtpRelayName The default SMTP Relay IP Address 10.0.0.1 smtpRelayPort The default SMTP Relay Port 25,465 25 smtpRelaySecure The default SMTP Relay Secure Connection True/False FALSE
-
Commercial in Confidence
Page 84 1999 - 2005 VoxSurf Ltd VxOne Provisioning & Administration Guide
Appendix 4: VxsProvisioningDefaultUser.properties
Please refer to the Configuration Guide for more details on this property file.
Field Description Possible Values Example domainID The default domain id to import the
subscribers in to 0000
accountPin The default pin for the subscribers 1357 title The default title Employee organisation The default organisation VoxSurf industry The default industry IT umEnabled Should the subscribers be Unified
Messaging enabled True, False FALSE
administrator Should the subscriber have administrative rights
True, False FALSE
faxServiceEnabled Should the subscriber have the fax facility enabled
True, False FALSE
language The default subscriber locale en TimeZone The user's default time zone, in the format
defined by java.util.TimeZoneData. The time zone defined here MUST be of the format region/time_zone_city, and may NOT be a three letter abbreviation (e.g. GMT, EST), as these are just aliases for the true time zone ID.
Europe/London
clock24Hour Should the user's times be shown in 12 or 24 hour mode
True, False TRUE
newMsgsPerHTMLPage The default number of messages to display per html page
10
sendOnHangUp Should composed messages be sent on user hang-up?
TRUE
voiceApplicationStartingPoint
The starting point for the voice application. Available options are -V - VoicemailE - EmailT - Top (main menu)
V,E,T V
voiceApplicationEmailStartingPoint
The starting point for email access. Available options are -P - Primary email accountM - Main email menu
P,M M
emailReceivedDate Should the received date be played in email header?
True, False FALSE
emailMessageNumber Should the email message number be played in email header?
True, False FALSE
emailOriginator Should the sender be played in email header?
True, False FALSE
voiceMailReceivedDate Should the received date be played in voicemail header?
True, False FALSE
voiceMailMessageNumber Should the voicemail message number be played in voicemail header?
True, False FALSE
voiceMailOriginator Should the sender be played in voicemail header?
True, False FALSE
-
Commercial in Confidence
VxOne Provisioning & Administration Guide 1999 - 2005 VoxSurf Ltd Page 85
Appendix 5: VxsProvisionUserStrategy package com.voxsurf.provisioning;
import javax.naming.directory.Attributes;
import javax.naming.directory.SearchResult;
import javax.naming.NamingEnumeration;
import javax.naming.directory.Attribute;
import com.voxsurf.core.entities.VxsUser;
import com.voxsurf.core.VxsException;
import com.voxsurf.core.entities.VxsUserId;
import com.voxsurf.util.VxsLogger;
import com.voxsurf.ldap.VxsLdapContext;
/*
* Copyright VoxSurf Software, All rights reserved.
*/
/**
* Retrieves a user from a provisioning mechanism and provisions it in the voxsurf system. T