14:34 2025-09-24

Introduction

Overview

First of all, if necessary, ALE can offer you a quote for a Mentoring Service Pack
which will help you with O2G deployment and the use of O2G APIs with the support of dedicated ALE experts.
Contact your ALE representative for more details.

This package is not embedded in OXE, and it is able to address the installed OXE(s).

O2G API services are available according to the following rules regarding the licenses :

• Required license : No license required (free).

  O2G API services characterized in this way can be invoked without O2G license.

• Required license : [license name] - True.

  O2G API services characterized in this way require an O2G license [license name] of boolean type.
  These services can only be invoked if the corresponding O2G license [license name] value is TRUE.

• Required license : [license name] - one license per user.

  O2G API services characterized in this way require an O2G license [license name] that determines the maximum number
  of distinct OXE users (*) that can be controlled using these APIs, regardless of the number of active application sessions on O2G.
  For instance, if multiple application sessions need to collectively control up to 100 distinct OXE users through such API services,
  the corresponding O2G license [license name] value must be set to 100.
  Notes:
  - Refer to User Management service to see how to declare O2G users from OXE subscribers.
  - Directory numbers must be only digits to be monitored (Numbers without #, *, A, B, C or D char).

• Required license : [license name] - number of licenses greater than or equal to total number of OXE users on all OXE nodes.
• Required license : [license name] - number of licenses must be equal to total OXE users.

  O2G API services characterized in this way require the corresponding O2G license [license name] to be set to the maximum number of OXE subscribers
   across all OXE nodes.

• Required license : [license name] - N licenses required.

  O2G API services characterized in this way require O2G license [License name] to be set to the fixed value of N.
  Note: O2G license [License name] may also be required when using O2G API services enabling OXE user control.
  If both types of O2G API services are used, the value of O2G license [License name] must be set to the number of distinct OXE users controlled by the API plus N.
  For instance, if the need is to control up to 100 distinct OXE users through O2G API services subject to O2G license [License name] and
  to invokes O2G API services that require the fixed value of 40 O2G license [License name] ,
  O2G license [License name] value has to be set to 100 (OXE users) plus 40 (fixed number) = 140.

Each resource can be accessed through the following kind of URL:
http(s)://<host>:<port>/api/rest/<version>/<resource _name>
Where:

• <host> is the host name or IP address of the server
• <port> is the port of the server
• <version> is the resource version
• <resource_name> is the name of the invoked resources

Third party application can get available API versions by performing a GET http request on the root URL
(Only GET operation is available on this resource, else 405 HTTP error "Method Not Allowed" in returned)
The structure of the returned body can be found in RoxeRestApiDescriptor.
http(s)://<host>:<port>/api/rest

Example of response :

{
	"serverInfo": {	
		"productName": "O2G Solution",
		"productType": "O2G",
		"productVersion": {
			"major": "2.6",
			"minor": "000.000"
			},
		"haMode": true	
		},
	"versions" : [{
		"id" : "1.0",
		"status" : "CURRENT",
		"publicUrl" : "https://public-server/api/rest/authenticate?version=1.0",
		"internalUrl" : "https://server/api/rest/authenticate?version=1.0"
		}],
	"custoFeatures" : [{
		"CCD_LOAD_OPE_CCA" : true,
		"HOTEL_LOAD_Z_GUESTS" : true
		}]
}

Notes : The customizable options (custoFeatures) are:

• CCD_LOAD_OPE_CCA: Indicates that devices with parameters ACT_Type=AGENT and Ope_Cca=TRUE are taken into account
• HOTEL_LOAD_Z_GUESTS: Indicates that devices with parameters Station_Type=ANALOG, Teleservice=Phone, Function=Room and Occupation_Type=Client are taken into account

To validate these options, "customize.properties" file must be created in /var/data/system directory.
The allowed parameters are "acd.loadOpeCca" and "hotel.loadZGuests".
Example of content:
acd.loadOpeCca=true
hotel.loadZGuests=true

Vocabulary

• An application :

An application is a third party using the O2G system.
An application can create one or more O2G administrator sessions to interact with all users.
It can also have one or more O2G user sessions.

• An installer :

The person who administers the O2G system.
This person will be able to manage the O2G system, by connecting via an SSH link, using the roxeAdm account with the credentials configured during installation.

• An administrator :

It is an O2G user with administrator right.
The installer can create an administrator in O2G system, using the roxe-config.sh tool (or roxe-install.sh during installation).

• A subscriber :

It is a subscriber of the OXE system.
The installer can manage a subscriber in OXE system, by using MGR tool by example.

• A device :

It is a subscriber number of the OXE system or an external number.

• A user :

It is an O2G user with no administrator right.
An O2G user is associated with one OXE subscriber, or more in the case of a multi-device OXE configuration.
An O2G user is automatically created by the O2G system if an OXE subscriber has the A4980 right or if OXE subscriber is managed on demand (depending on the O2G configuration).

• An administrator account :

A O2G administrator account is a O2G session, associated to a O2G administrator.
To create an O2G administrator account, a third-party application must authenticate and log in (open a session).
A login and a password will be used to authenticate to the REST APIs.
(Method: GET https://server/api/rest/authenticate?version=1.0)
This administrator account will be able to use all REST APIs methods.
The login and password used are those administered in O2G by the installer.

• A user account :

A O2G user account is a O2G session, associated to a O2G user.
To create an O2G user account, a third-party application must authenticate and log in (open a session).
A login and a password will be used to authenticate to the REST APIs.
(Method: GET https://server/api/rest/authenticate?version=1.0)
This user account will be able to use only user REST APIs methods.
The login and password used depend on the choice of authentication mechanism, chosen by the installer.
Several authentication mechanisms are possible :

  The installer denies user authentication.
  In this case, no user can authenticate (no user session).
  Only an administrator account must use to perform an action for a user.

  The installer authorizes user authentication by O2G.
  In this case, the user authentication is checked by O2G (default mode).
  It is a basic HTTPS authentication, based on a login/password.
    The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
    The password is the Secret Code (4 digits), of the OXE subscriber.

  The installer authorizes user authentication by OXE.
  This configuration impacts all OXEs managed by O2G :
  Each OXE must be configured with a local authentication or
  with a LDAP authentication (only possible from OXE version N4.507.2).

  For a local authentication :
    The login is the Login of the subscriber.
    The password is the Password of the subscriber.
 
  For a LDAP authentication :
    The login is the Login of the subscriber.
    The password is the password of the user defined in the LDAP server.

• A loginName :

This attribute is used in many O2G REST API methods.
It corresponds to the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
This is true regardless of the login used by the authentication mechanism.

History

2.7.4

• added feature 'Authentication'
• modified feature 'Session management'
  • added in representation 'SessionInfo' :
    • login
  • added in representation 'SessionRequest' :
    • timeToLive
• modified feature 'Call control'
  • added in representation 'CallData' :
    • lastRedirecting
• modified feature 'Communication log'
  • added in representation 'ComHistoryRecord' :
    • holdDuration
    • transferredBy
    • associatedData
  • added in representation 'Participant' :
    • leg
• modified feature 'Call Center Management'
  • added methods :
    • Get advanced pilot information
• added feature 'Call Center Real Time'
• added feature 'Call Center Statistics'

2.7.3

• added feature 'User Management'
• modified feature 'Call control'
  • added in representation 'Identifier' :
    • multiLine
• modified feature 'Maintenance'
  • added in representation 'DRLink' :
    • initiator
  • added in representation 'SystemStatus' :
    • recordingStatus
• modified feature 'Call Center Agent'
  • added methods :
    • Cancel Agent Permanent listening
  • added in representation 'IntrusionMode' :
    • STOP

2.7.2

• modified feature 'Call control'
  • added in representation 'DeviceState' :
    • cause
• modified feature 'Call Center Pilot'
  • added methods :
    • MonitorStart pilot
    • MonitorStop pilot
  • added in notification 'OnPilotCallCreated' :
    • callData

2.7.1

• modified feature 'Call control'
  • added in representation 'CallData' :
    • trunkIdentification

2.7

• modified feature 'Session management'
  • added in representation 'SessionInfo' :
    • creationDate
    • otherSessions
• modified feature 'User information'
  • added in representation 'User' :
    • externalLogin
• modified feature 'User Management'
  • added in representation 'User' :
    • externalLogin
• modified feature 'Call control'
  • added methods :
    • Get pilot transfer information
• modified feature 'Maintenance'
  • added notifications :
    • OnServerStart
• modified feature 'Call Center Agent'
  • added notifications :
    • OnAgentSkillChanged
• added feature 'Call Center Management'
• added feature 'Call Center Pilot'

Change logs

Complete changes history can be found here.

Authentication mechanism

All resources are protected by the authentication mechanism.
A dedicated resource is provided to perform user/administrator authentication :
http(s)://<host>:<port>/api/rest/authenticate?version=1.0

The first action for an application is to authenticate on O2G.
Authentication is basic HTTPS authentication, based on a login and password.
The first action for an application is to authenticate on O2G.

Authentication for an administrator

Authentication is basic HTTPS authentication, based on a login/password.

• The login is managed in the configuration file
• The password is managed in the configuration file

The credentials (login and password) are first checked to see if they correspond to an O2G administrator.
JWT authentication is implemented to provide an identifier based on credentials.
This identifier must be passed in a cookie (AlcUserId) in all subsequent HTTPS requests, so that O2G can check their validity.

See below a sequence diagram for a Basic authentication.
Example:

  Request
	GET http://server/api/rest
  Response :
	200 OK
	Content-Type:  application/json
	{ 
		"versions" : [ {
		"id" : "1.0",
		"status" : "CURRENT",
		"publicUrl" : "https://public-server/api/rest/authenticate?version=1.0",
		"internalUrl" : "https://server/api/rest/authenticate?version=1.0"
		} ] 
	} 
  
  Request :
	GET https://server/api/rest/authenticate?version=1.0
	Authorization: Basic aW50ZXJuYWwyOTphbGNhdGVsMjk=

  Response :
  	200 OK  	
 
  	Set-Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...; Path=/
  	Content-Type:  application/json
  	{
   		"credential" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...",
   		"publicUrl" : "https://public-server/api/rest/1.0/sessions",
   		"internalUrl" : "https://server/api/rest/1.0/sessions",
   		"expired" : "false",
   		"login": "oxe1000"
  	}
  

Authentication for an user : Secure Access

An installer can authorize or deny user authentication.Enable these options through O2G configuration (root account only).
Several options are possible.

• An installer denies user authentication.

  In this case, no user can authenticate (no user session).
  Only an administrator account must use to perform an action for a user.

• An installer authorizes user authentication by O2G.

  In this case, the user authentication is checked by O2G (default mode).
  It is a basic HTTPS authentication, based on a login/password.

• The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
• The password is the Secret Code (4 digits), of the OXE subscriber.

See previous a sequence diagram for a Basic authentication.

• An installer authorizes user authentication by OXE.

  This configuration impacts all OXEs managed by O2G :
  Each OXE must be configured with a local authentication or
  with a LDAP authentication (only possible from OXE version N4.507.2).

  For a local authentication :

• The login is the Login of the subscriber.
• The password is the Password of the subscriber.

  For a LDAP authentication :

• The login is the Login of the subscriber.
• The password is the password of the user defined in the LDAP server.

   The authentication request response provides two additional parameters :
    First parameter is the O2G login for further request
    Second parameter is a optional boolean which indicate if the OXE password is expired or not.
     If this boolean is true, the password provided must be quickly changed using the proper API request
  ⚠ An expired password can quickly leads to authentication failure

  Note : For OXE LDAP authentication, the login is the Login of the subscriber must be the same of the user defined in the LDAP server.
  O2G checks the consistency between the LDAP login and the OXE subscriber login.

Session creation

All services are invoked through a session (user or administrator one).
The resource to perform user/administrator session creation is:
http(s)://<host>:<port>/api/rest/1.0/sessions
The session creation request and all the subsequent requests must contain the Cookie AlcUserId with value equals to the one received in the Set-Cookie of the authentication response.
Important: all the sessions are created with an initial time-to-leave of 1800 seconds (30 minutes): To see how to maintain the session, refer to SESSION MANAGEMENT chapter. Example:

  Request
	POST /api/rest/1.0/sessions HTTP/1.1

Content-Type: application/json
Host: (server address)
Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...
...
{
[body] : refer to Session Management section
}

  Response :
	200 OK
	Server: Apache/2.4.23
	Set-Cookie: JSESSIONID=88C00EA2B3C482E19825F1184D0BB50E.tomcat; Path=/api
	Content-Type:  application/json
	{ 
 		"timeToLive": 1800,
  		"publicBaseUrl": "http://public-server/api/rest/1.0",
  		"privateBaseUrl": "https://server/api/rest/1.0",
  		"services": [
    		{...
  
  

O2G Services Through Websocket

O2G REST service may be used through a websocket. This configuration could be interesting in a context where the security must be improved or if the opening of http ports on the local domain is considerd as an issue.
The solution is to use a reverse HTTP proxy over web socket. The aim is to provide a secure connection setup from the internal network to the external network in order to tunnel the API requests to internal O2G APIs from the external third party client.
A Web Socket agent run in the internal network (in front end of O2G API) establishes a single connection to a remote Web Socket server in secure mode. The Web socket agent is included in the O2G solution and may be configured thanks to the O2G configuration tool.
The web socket server side is not handled by O2G solution and it remains to the client to provide it.
A json formatted message protocol is used in the websocket to translate the http REST requests and responses.
In the same manner, the events the client has subcribed to are sent back by O2G through this socket towards the application. Moreover, an identifier may used as query parameter in the subscription request: in that manner, the events correponding to this susbscription will be automatically sent to the client through the web socket with this identifier (no need to open a chunk channel).

Here is the Ws protocol map:
Example of request/response for authentication through WS protocol:

Example of request/response for subscription through WS protocol:

Example of event through WS protocol:

Error management

Management of errors returned by REST services invocation follows the common practise which consists of providing as much information as possible to the user.
The returned information structure contains several fields, targetting all possible users of the API: see RestErrorInfo
The complete list of REST API errors is the following:

type	code	helpMessage	canRetry
NOT_READY	1000	The server is not yet available. Please retry later if the initialization is not finished.	true
INVALID_SESSION	1001	No valid session found for the given identifier. Please logout and login with correct credentials.	true
NOT_ALLOWED	1002	The operation is not allowed, because of insufficient rights or bad credential. Please contact the installer to fix the problem.	false
NOT_FOUND	1003	Missing or bad parameter sent by a request on a service. Fix the problem and retry.	true
NOT_EXPECTED	1004	The request can not be performed due to current user's state.Check the state or fix your request before sending it back.	true
NOT_SUPPORTED	1005	This operation is not supported. Please check the documentation.	false
BAD_PARAMETER	1006	Request parameters are not correct. Please fix the problem and send the request back.	true
SERVER_PROBLEM	1007	Server general problem. Please contact the installer to fix the problem.	false

Example 1: The service in charge of executing the invoked request is not installed, or the server is not properly configured.

{
	"httpStatus":"SERVICE_UNAVAILABLE",
	"code":1007,
	"helpMessage":"Server general problem. Please contact the installer to fix the problem.",
	"type":"SERVER_PROBLEM",
	"innerMessage":"AlcChameleonException.PLUGIN_NOT_INSTALLED 'PLUGIN_NAME' plugin is not installed",
	"canRetry":false
}

Example 2: Invalid session. The application has to log out, if previously logged in, and retry to log in.

{
	"httpStatus":"FORBIDDEN",
	"code":1001,
	"helpMessage":"No valid session found for the given identifier. Please logout and login with correct credentials.",
	"type":"INVALID_SESSION",
	"innerMessage":"AlcChameleonException.BAD_FRAMEWORK_SESSION_IDENTIFIER No framework session in API with this ID : ...323437343",
	"canRetry":true
}

High Availability (HA)

The HA solution is based on the redundancy of the server in a Primary/Secondary server pair.
Licenses :
Required in CAPEX mode (FlexLM server): ROXE_HA - true.
Required in OPEX mode (LMS server): No license required (free).

Client code samples

• JAVA samples
• JAVA Script (client side) sample
• PHP (server side) sample

Representations

booleanDestinationTypeHttpStatusintProductVersionRestErrorInfoRoutingErrorCauseRoutingErrorInfoRoutingErrorTypeRoxeRestApiDescriptorServerInfostringTelephonyErrorCauseTelephonyErrorInfoTelephonyErrorTypeUserPreferencesErrorInfoUserPreferencesErrorTypeDTOUserPreferencesParameterDTOVersion

Authentication

Presentation

The Authentication service allows a user or an administrator to authenticate on the O2G server. This is a prerequisite to create a session.
All resources are protected by the authentication mechanism.
A dedicated resource is provided to perform user/administrator authentication :
http(s)://<host>:<port>/api/rest/authenticate?version=1.0

The first action for an application is to authenticate on O2G.
Authentication is basic HTTPS authentication, based on a login and password.
The first action for an application is to authenticate on O2G.

Authentication is basic HTTPS authentication, based on a login/password.

Authentication for an administrator

• The login is managed in the configuration file
• The password is managed in the configuration file

Authentication for an user : Secure Access

An installer can authorize or deny user authentication.Enable these options through O2G configuration (root account only).
Several options are possible.

• An installer denies user authentication.

  In this case, no user can authenticate (no user session).
  Only an administrator account must use to perform an action for a user.

• An installer authorizes user authentication by O2G.

  In this case, the user authentication is checked by O2G (default mode).
  It is a basic HTTPS authentication, based on a login/password.

• The login is the QMCDU of the OXE subscriber prefixed by "oxe" (Ex: oxe70120).
• The password is the Secret Code (4 digits), of the OXE subscriber.

• An installer authorizes user authentication by OXE.

  This configuration impacts all OXEs managed by O2G :
  Each OXE must be configured with a local authentication or
  with a LDAP authentication (only possible from OXE version N4.507.2).

  For a local authentication :

• The login is the Login of the subscriber.
• The password is the Password of the subscriber.

  For a LDAP authentication :

• The login is the Login of the subscriber.
• The password is the password of the user defined in the LDAP server.

   The authentication request response provides two additional parameters :
    First parameter is the O2G login for further request
    Second parameter is a optional boolean which indicate if the OXE password is expired or not.
     If this boolean is true, the password provided must be quickly changed using the proper API request
  ⚠ An expired password can quickly leads to authentication failure

  Note : For OXE LDAP authentication, the login is the Login of the subscriber must be the same of the user defined in the LDAP server.
  O2G checks the consistency between the LDAP login and the OXE subscriber login.

JWT authentication is implemented to provide an identifier based on credentials: it is returned in the Set-Cookie header as the AlcUserId:
Set-Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...;
This identifier must be passed in a in all subsequent HTTPS requests in the cookie header:
Cookie: AlcUserId=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnRlcm5...;

History

Since version 2.7.4

Resource summary

Resource	Method	Description
/authenticate	GET	Ask request authentication.

Resource

/authenticate

Methods

Representations

AuthenticationResponsebooleanstring

Session management

Presentation

The Session service allows a user or an administrator to open a session on the O2G server. This is a prerequisite to any service usage and must happened after the authentication stage.
A session is created with an initial time-to-leave of 1800 seconds (30 minutes) : the application is responsible to keep the session alive by posting /sessions/keepalive request or other requests before each expiration of the timer. The TTL of the session is re-initialized on each request. If the TTL expires, the session is closed by the server.

Resources summary

Resource	Method	Description
/sessions	GET	Gets information of the opened session.
	POST	Open a session for a user or an administrator.
	DELETE	Closes a Session.
/sessions/keepalive	POST	Restarts the session timer.

Resources

/sessions

Methods

/sessions/keepalive

Methods

Representations

booleanintServiceSessionInfoSessionRequestSessionTokenInfostringSupervisedAccountSupervisedAccountTypeUserSession

User information

Presentation

The User service allows

• an administrator to retrieve the list of O2G users.
• a user to get information on another user account.
• a user to change its password or some parameter like supported language.

Resources summary

Resource	Method	Description
/logins	GET	An administrator can get the list of the users (login name).
/users	GET	Find information about a user from a company phone.
/users/{loginName}	GET	Gets information about a user account.
/users/{loginName}/password	PUT	Change user's password.
/users/{loginName}/preferences	GET	Gets information about user's preferences.
	POST	Updates information about user's preferences.
/users/{loginName}/preferences/supportedLanguages	GET	Gets information about supported languages for user's GUI language preference: Supported languages

Notifications summary

Notification	Description
OnUserCreated	This event is sent on creation of an user (only for administrator).
OnUserDeleted	This event is sent when user is deleted (only for administrator).
OnUserInfoChanged	This event is sent on any change on the user's data.

Resources

/logins

Methods

/users

Methods

/users/{loginName}

Methods

/users/{loginName}/password

Methods

/users/{loginName}/preferences

Methods

/users/{loginName}/preferences/supportedLanguages

Methods

Representations

ChangePasswordRequestDeviceDeviceTypeLoginsResponseOnUserCreatedOnUserDeletedOnUserInfoChangedstringSupportedLanguagesUserUserPreferencesVoicemailVoicemailType

User Management

Presentation

The User Management service allows an administrator to create/delete/get the O2G users.
O2G allows to create O2G users according to different methods:

• automatically when O2G starts, according to automatic user creation mode (through roxe-config.sh) which be can be:
  • ALL : all the OXE subscribers are taken in account without any filter.
  • 4980 : only the OXE subscribers with A4980 attribute set with a value different from NO_4980 are taken in account. This is the default mode.
  • NONE : no user is automatically created from OXE subscriber.
• through provisioning files. They have to be uploaded, one file per oxe node in /var/data/roxe/userprov/oxe.[nodeNbr], where [nodeNbr] is the unique node number of the oxe. One or several files respecting this naming may be set.
  Example:
  - /var/data/roxe/userprov/oxe.5
  - /var/data/roxe/userprov/oxe.101
  In order to take in account all the subscribers of an oxe, create an empty file.
  To define a list of devices to create, the content of the file MUST respect the following format CSV text on one or several lines, each element is:
  • a single device_Number
  • or a range [first number of the device range]-[size of the range]
  Example:
  40000-1000,50000-50
  60001,60002,60003,70000-10,80000-100
  90001,90002
  
  (The subscriber numbers which are not valid are ignored)
• or on demand through this REST service: the service allows to create one user, a list of users or all the users.

The 3 methods may be used together, a user created automatically or by provisioning may also be removed through the REST service.
"All the users" means all the configured oxe Subscribers.
The analog devices (Z) with Ghost feature may also used through O2G but their usage should be restricted to special services like generate a call followed by a blind transfer.
In any cases, there is no persistence: a user created on demand through this service is not kept after a server restart.
(Rem: If a user automatically created by 4980 is removed by API, it will be created again by midnight audit)

History

Since version 2.7.3

Resources summary

Resource	Method	Description
/usermanagement	GET	Get one or several users loginName.
	POST	Create and monitor one or several O2G user(s) associated to a pbx Subscriber, giving its(their) device number.
/usermanagement/{loginName}	GET	Get information about a user.
	DELETE	Remove an O2G user.

Resources

/usermanagement

Methods

GET/usermanagement

Get one or several users loginName.

Licenses

Required in CAPEX mode (FlexLM server): No license required (free).
Required in OPEX mode (LMS server): No license required (free).

Request

query parameters

parameter	type	description
nodeIds	string	This parameter is an optional search criterion which allows to select only the users belonging to the given pbx node(s). The given value must be one OXE nodeId or a comma separated list of nodeId.
deviceNumber	string	This parameter is an optional search criterion which allows to select only a user by its phone number. the device number may its main device or one of its secondary devices.

cookie parameters

parameter	type	description
AlcUserId	string	Identifier of the Session

Response

code	type	media types	description
200	LoginsResponse	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get all existing O2G user identifiers

request :

GET https://server/api/rest/1.0/usermanagement

response :

200 OK
 Content-Type:  application/json
 {
   {"loginNames":["oxe70020","oxe70021", ...]}
 }

[+] : Get all user's identifiers belonging to OXE node 7 or 8.

request :

GET https://server/api/rest/1.0/usermanagement?nodeIds=7,8

response :

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe70020","oxe70021","oxe70022"]}
 }

[+] : Get the user identifier corresponding to the secondary device 70124

request :

GET https://server/api/rest/1.0/usermanagement?deviceNumber=70124

response :

200 OK
 Content-Type:  application/json
 {
  {"loginNames":["oxe70123"]}
 }

POST/usermanagement

Create and monitor one or several O2G user(s) associated to a pbx Subscriber, giving its(their) device number.
If the oxe user is a multi device, the user may be created with its main number or with any of its secondary device.

Licenses

Required in CAPEX mode (FlexLM server): No license required (free).
Required in OPEX mode (LMS server): No license required (free).

Request

cookie parameters

parameter	type	description
AlcUserId	string	Identifier of the Session

body parameter

type	media types	description
UserCreateRequest	application/json	node and device phone number listUserCreateRequest

Response

Returns the list of created users only if the request does not concern all the users else return null

code	type	media types	description
200	Users	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
404		application/json	Not Found
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Create the user 70120 on node 7.

request :

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70120"]}

response :

200 Ok : the new created user
 Content-Type:  application/json
 {
 	"companyPhone":"70120",
 	"firstName":"F70120",
 	"lastName":"L70120",
 	"loginName":"oxe70120",
 		"voicemail": {
 		"number": "885",
		"voicemailtype": "VM_4645"
		},
 	"devices":[{"type":"DESKPHONE","id":"70120","label":"POC","subType":"NOE_C_Color_IP"}],
 	"nodeId":"7",
 	"externalLogin":"user70120@my.domain.com"
 }

[+] : Create the multi device user 70123 from its tandem device 70124 on node 7.

request :

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70124"]}

response :

200 Ok : the new created user
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70123",
   "firstName": "F70123",
     "lastName": "L70123",
      "loginName": "oxe70123",
      "voicemail": {
			"number": "885",
		 	"voicemailtype": "VM_4645"
  	},
    "devices": [
        {
              "type": "DESKPHONE",
              "id": "70124",
             	"subType": "NOE_C_Color_IP"
         },

         {
         "type": "DESKPHONE",
         "id": "70125",
         "subType": "NOE_C_Color_IP"
         },
         {
         "type": "DESKPHONE",
         "id": "70123",
         "subType": "NOE_C_Color_IP"
         }
 	],
   "nodeId": "7",
   "externalLogin": ""
  }
 ]
}

[+] : Create severals users corresponding to the devices: 70120,70121,70122 and 70123 on node 7.

request :

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","deviceNumbers":["70120",70121,70122,70123]}

response :

200 Ok : the new created users
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70120",
   ...

[+] : Create all the users corresponding to node 7.

request :

POST https://server/api/rest/1.0/usermanagement
 {"nodeId":"7","all":true}

response :

200 Ok : the new created users
 Content-Type:  application/json
 {
 "users": [
 {
   "companyPhone": "70120",
   ...

/usermanagement/{loginName}

Methods

GET/usermanagement/{loginName}

Get information about a user.
This operation provides user information:

• Name and first name of the user
• User's internal login name
• User's phone number
• User's voicemail information
• User's list of devices
• ...

Licenses

Required in CAPEX mode (FlexLM server): No license required (free).
Required in OPEX mode (LMS server): No license required (free).

Request

path parameters

parameter	type	description
loginName	string	Login name of the user to retrieve the account description.

cookie parameters

parameter	type	description
AlcUserId	string	Identifier of the Session

Response

Returns the result code and, if the code is SUCCESS, information about the concerned user User

code	type	media types	description
200	User	application/json	OK
400		application/json	Bad Request
403		application/json	Forbidden
500		application/json	Internal Server Error
503		application/json	Service Unavailable

Examples

[+] : Get information about a user

request :

GET https://server/api/rest/1.0/usermanagement/oxe70120

response :

200 OK
 Content-Type:  application/json
 {
 	"companyPhone":"70120",
 	"firstName":"F70120",
 	"lastName":"L70120",
 	"loginName":"oxe70120",
 	"devices":[{"type":"DESKPHONE","id":"70120","label":"POC","subType":"NOE_C_Color_IP"}],
 	"apiRights":[],"nodeId":"7"
 }

DELETE/usermanagement/{loginName}

Remove an O2G user.

Licenses

Required in CAPEX mode (FlexLM server): No license required (free).
Required in OPEX mode (LMS server): No license required (free).

Request

path parameters

parameter	type	description
loginName	string	loginName of the user to delete

cookie parameters

parameter	type	description
AlcUserId	string	Identifier of the Session

Response

Returns the result code

code	media types	description
204	application/json	No Content
400	application/json	Bad Request
403	application/json	Forbidden
404	application/json	Not Found
500	application/json	Internal Server Error
503	application/json	Service Unavailable

Examples

[+] : Remove the user corresponding to the device 1000.

request :

DELETE https://server/api/rest/1.0/usermanagement/oxe1000

response :

204 No Content

Representations

boolean

'boolean' is a data type, having two values (true and false).

Device

Describe a device.

Name	Type	Cardinality	Description
type	DeviceType	[0..1]	Device's type.
id	string	[0..1]	Device identifier which is used to identify the device in telephony requests and events.
subType	string	[0..1]	Device's subtype : For a DESKPHONE type, we could have : ANALOG, NOE_C_Color_IP, ...

[+] : JSON Example { "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE", "id": "string", "subType": "string" }

Associated method :

• GET /users/{loginName}/devices/{deviceId}

DeviceType

The device type values.

Value	Description
DECT	A wireless phone set used within the enterprise.
DESKPHONE	A phone set on an office's desk.
MOBILE	A mobile phone.
SOFTPHONE	A phone started from a computer with VOIP.

int

'int' is a 32-bit number (-2147483648 to 2147483647).

LoginsResponse

The get logins response.

Name	Type	Cardinality	Description
loginNames	string	[1..*]	List of logins matching the request.

[+] : JSON Example { "loginNames": [ "string" ] }

Associated methods :

• GET /logins
• GET /usermanagement

string

'string' represents character strings.

User

The description of a user

Name	Type	Cardinality	*1	*2	Description
companyPhone	string	[0..1]			User's company phone number.
firstName	string	[0..1]			First name of the User or Administrator owner of this Account. Note: Corresponds to the "UTF8_Phone_Book_First_Name" parameter. If this one is empty, it is the parameter "Annu_First_Name" which is taken into account.
lastName	string	[0..1]			Last name of the User or Administrator owner of this Account. Note: Corresponds to the "UTF8_Phone_Book_Name" parameter. If this one is empty, it is the parameter "Annu_Name" which is taken into account.
loginName	string	[0..1]			Login name which identifies the User Account.
voicemail	Voicemail	[0..1]			User's voicemail description.
devices	Device	[0..*]	X	X	User's devices.
nodeId	string	[0..1]			Node Id on which user is attached
externalLogin	string	[0..1]			Since version 2.7 External login of the user if set (only available with oxe > n1.271)

*1 : attribute only provided if the user is the session's owner or for an administrator session.
*2 : attribute only provided if the user is the session's owner or for an administrator session.

[+] : JSON Example { "companyPhone": "string", "firstName": "string", "lastName": "string", "loginName": "string", "voicemail": { "number": "string", "type": "VM_4635 | VM_4645 | EXTERNAL" }, "devices": [ { "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE", "id": "string", "subType": "string" } ], "nodeId": "string", "externalLogin": "string" }

Associated methods :

• GET /usermanagement/{loginName}
• GET /users
• GET /users/{loginName}

UserCreateRequest

O2G User on demand creation request

Name	Type	Cardinality	Description
nodeId	int	[1]	Node number.
deviceNumbers	string	[0..*]	List of device phone number(s). Must be present if the following all parameter is absent or false.
all	boolean	[0..1]	if all parameter is present with value true, the request is to create all the users corresponding to all the oxe devices. In this case the previous deviceNumbers list is ignored. !! The request to create all the users should be reserved to small OXE configuration.

[+] : JSON Example { "nodeId": int, "deviceNumbers": [ "string" ], "all": boolean }

Associated method :

• POST /usermanagement

Users

List of the created users

Name	Type	Cardinality	Description
users	User	[0..*]	List of users.

[+] : JSON Example { "users": [ { "companyPhone": "string", "firstName": "string", "lastName": "string", "loginName": "string", "voicemail": { "number": "string", "type": "VM_4635 | VM_4645 | EXTERNAL" }, "devices": [ { "type": "DECT | DESKPHONE | MOBILE | SOFTPHONE", "id": "string", "subType": "string" } ], "nodeId": "string", "externalLogin": "string" } ] }

Associated method :

• POST /usermanagement

Voicemail

Describes user's voicemail.

Name	Type	Cardinality	Description
number	string	[1]	Voicemail number.
type	VoicemailType	[1]	Voicemail type.

[+] : JSON Example { "number": "string", "type": "VM_4635 | VM_4645 | EXTERNAL" }

VoicemailType

Voicemail type values

Value	Description
VM_4635	Integrated 46x5 voice mail system
VM_4645	Integrated 46x5 voice mail system
EXTERNAL	External voice mail systems

POST https://server/api/rest/1.0/subscriptions
 	Content-Type: application/json
 	{
  "filter": {
	  "selectors": [ 
       {"ids": [ "userA" ],"names": [ "telephony" ]},
       {"ids": [ "userA" ],"names": [ "eventSummary" ]}
     ]
  },
  "version":"1.0"
 }

200 OK
 	{
 		"subscriptionId":"...93231353535373132393",
 		"publicPollingUrl":"https://public.server:8016/OTEvents?subscriptionId=...93231353535373132393",
 		"privatePollingUrl":"https://server:8016/OTEvents?subscriptionId=...93231353535373132393",
 		"status":"ACCEPTED",
 		"mode":"CHUNK", "format":"JSON"
 	}

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
  	"filter":{"selectors":[
  		{"ids":["*"],"names":["telephony"],"families":[],"origins":[]}
  		]
  	},
  	"sessionId":"...2303639373638343","version":"1.0",
  	"timeout":60
  }
  }

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			  {"names": [ "system" ]}
		]
		},
		"version":"1.0"
	}

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			  {"names": [ "pbxManagement" ]}
		]
		},
		"version":"1.0"
	}

POST https://server/api/rest/1.0/subscriptions
  Cookie: AlcUserId=eyJhbGciOiJIUzI.....
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			{"names": [ "pbxManagement" ]}
		]
		},
		"version":"1.0",
  	"webHookUrl": "https://[@IP address]:8091/webHookOTEvent"
	}

POST /webHookOTEvent HTTP/1.1
  Cookie: AlcUserId%3DeyJhbGciOiJIUzI...
  Content-type: application/json
  {"eventName":...

POST https://server/api/rest/1.0/subscriptions
  Content-Type: application/json
  {
		"filter": {
		 "selectors": [ 
			{"ids": [ "60141" ],"names": [ "pilot"]},
      	{"ids": [ "65000" ],"names": [ "rsi"]}
		]
		},
		"version":"1.0"
	}

PUT https://server/api/rest/1.0/subscriptions
 	Content-Type: application/json
 	{
 		"selectors":[
 			{"ids":["userA","userB"],"names":["telephony"]},
 			{"ids":["userA","userB"],"names":["eventSummary"]}
 		]
 	}

204 No Content

DELETE https://server/api/rest/1.0/subscriptions/...35373132393

204 No Content

{
   "selectors": [ {
      "ids": [ "string" ],
      "names": [ "string" ]
   } ]
}

{
   "ids": [ "string" ],
   "names": [ "string" ]
}

{
   "subscriptionId": "string",
   "message": "string",
   "publicPollingUrl": "string",
   "privatePollingUrl": "string",
   "status": "UNKNOWN | ACCEPTED | REFUSED"
}

{
   "filter": {
      "selectors": [ {
         "ids": [ "string" ],
         "names": [ "string" ]
      } ]
   },
   "sessionId": "string",
   "version": "string",
   "timeout": int,
   "webHookUrl": "string"
}