User Management API - Aministrator Manual

OmniVista 8770

User Management APIRelease 3.0 - May 2016

8AL90710USAB Ed.01

Legal notice:

The information presented is subject to change without notice.

ALE International assumes no responsibility for inaccuracies containedherein.

Copyright © ALE International, 2016

Disclaimer:

While efforts were made to verify the completeness and accuracy of theinformation contained in this documentation, this document is provided “asis”. To get more accurate content concerning Cross Compatibilities, ProductLimits, Software Policy and Feature Lists, please refer to the accuratedocuments published on the Business Partner Web Site.

In the interest of continued product development, ALE International reservesthe right to make improvements to this documentation and the products itdescribes at any time, without notice or obligation.

The CE mark indicates that this product conforms to the following CouncilDirectives:- 2014/53/EU for radio equipment- 2014/35/EU and 2014/30/EU for non radio equipment (including wiredTelecom Terminal Equipment)- 2014/34/EU for ATEX equipment- 2011/65/EU (RoHS)

Chapter 1Overview

Introduction ................................................................................................ 5

API sources delivered in the OmniVista 8770 server .................. 6

On using this document ........................................................................ 6

Chapter 2Detailed description

API objects ................................................................................................. 8

Hierarchy of API objects .................................................................................. 8

Schema objects ............................................................................................... 9

Data objects ..................................................................................................... 9

Template objects ............................................................................................14

Set of operations supported by the API ..........................................15

Overview .........................................................................................................16

Header ............................................................................................................16

Get method .....................................................................................................16

Create method ................................................................................................18

Update method ...............................................................................................18

Delete method ................................................................................................19

Error handling ..........................................................................................20

3/20

Backward compatibility ........................................................................20

4/20

1.1 Introduction

The OmniVista 8770 provides an API (Application Programming Interface) solution toconfigure users and devices from third party applications. This API solution is based on theSimple Object Access Protocol (SOAP).

The API allows to create, read, update or delete users from third party applications. Thisapplies to any of the following:

- Basic Company Directory users. They are not associated to a device and they are notrelated to a communication server (OpenTouch or OmniPCX Enterprise)

- OXE users associated to a device declared in the OmniPCX Enterprise without any accessto OpenTouch applications

- OXE users (also called standard users) associated to a device declared in the OmniPCXEnterprise with access to OpenTouch applications or voice mailboxes on OTMC

- OT users (also called the OpenTouch users) associated to a device declared in theOpenTouch with or without access to OpenTouch applications

The API also allows to create devices and associate/dissociate devices to/from users. Thisonly applies to devices that can be deployed without their MAC address (self-assignment) andapplications. To see the list of devices with self-assignment and applications, refer to theOmniVista 8770 feature list (reference: 8AL91400USAA).

These operations are similar to those provided by the Users application of the OmniVista8770. The API does not allow to configure:

- Meta profiles

- Devices not associated to a user

- Users and devices via mass provisioning

The API use requires a dedicated license in the OmniVista 8770 (called OpenAPI). Thelicense status can be verified from the help menu of an OmniVista 8770 client (access path:Help > About).

5/20

Figure 1.1: API solution overview for user and device configuration from a third partyapplication (API user)

Data exchanged with third party applications is encrypted using HTTPS. Each HTTPS requestis authenticated using a dedicated OmniVista 8770 administrator account (login andpassword), created at OmniVista 8770 server installation.

The number of parallel transactions from different third party applications using this API islimited by an entry in the LDAP application configuration settings (access path in theAdministration application of OmniVista 8770: nmc > Application Configuration >Applications Settings > OpenApiManagement > OpenApi). The master server must to berestarted to implement the change. When the limit is exceeded, the next transaction is rejectedwith the following error message: Too many parallel requests.

1.2 API sources delivered in the OmniVista 8770 server

All API sources are delivered in the OmniVista 8770 server (access path:/8770/client/data/import). The file named openapisamplelient.zip includes thesources for an example, wsdl, and xsd.

1.3 On using this document

This document details:

- The API objects and their hierarchy, provided they can be modified from an API client

Chapter 1

6/20

- The set of operations supported by the API

This document does not cover any OmniVista 8770 installation or administration information,nor does it provide any description of the API client.

7/20

2.1 API objects

2.1.1 Hierarchy of API objects

Data returned by the API are included in objects defined in the following hierarchy.

Figure 2.1: API object hierarchy

8/20

The following table provides the hierarchy of data objects (also called resources) returned bythe API:

table 2.1: Hierarchy of data objectsHierarchy Resource

/ov8770 Ov8770 hierarchy

/ov8770/schema Schema

/ov8770/schema/user User schema

/ov8770/schema/device Device schema

/ov8770/schema/metaprofile Meta profile schema

/ov8770/schema/devicetemplate Device template schema

/ov8770/schema/listresult List result

Note:

Description of list result (schema) returned by a

Get operation.

/ov8770/data/users Users

/ov8770/data/users/{UID} A user whose uid={UID}where {UID} corresponds to a user name

/ov8770/data/users/{UID}/devices Devices associated to a user whose uid={UID}where {UID} corresponds to a user name

/ov8770/data/users/{UID}/devices/{directorynumber}

Device whose directorynumber={directorynumber}where {directorynumber} corresponds toa device directory number

/ov8770/templates/metaprofiles User meta profiles

/ov8770/templates/metaprofiles/{cn}

A user meta profile whose cn={cn}where {cn} corresponds to a meta profilename

/ov8770/templates/devicetemplates OpenTouch device templates

/ov8770/templates/devicetemplates/{dn}

An OpenTouch device template whose ldapDn={dn}where {dn} corresponds to a device templatedistinguished name

2.1.2 Schema objects

A schema instance listed in the hierarchy (see: table: Hierarchy of data objects ) is an XML filethat defines the parameters of an object returned by the API.

For example, the user schema provides the description of user parameters.

Note:

The xml stream is compliant with the gmi format defined in gmi.xsd.

2.1.3 Data objects

9/20

2.1.3.1 Overview

This section details the contents of the schema definition as returned by a Get request(/ov8770/schema/xxx).

2.1.3.2 User

Users can be OT users, OXE users, or OXE users with access to OpenTouch or OTMCapplications (also called standard users). They are declared in the OmniVista 8770, and in thecorresponding nodes (OmniPCX Enterprise, OpenTouch, and/or OTMC) to which they areassociated.

During the creation of a user using a meta profile, a device can also be created and associatedto this user (only available for OT users).

The user parameters returned by the API are listed in the table below. The other parametersare either included in meta profiles and/or keep their default values.

Attribute Access Filtering Description Remarks

directoryhier-archy

WCRE-ATE_RUPDATE

N OmniVista 8770directory hier-archy in whichthe user is cre-ated (it corres-ponds to the ex-isting dn attributein LDAP)

Mandatory forCreate operation.It cannot be modi-fied.Defined in the Om-niVista 8770 LDAPDB by the OmniV-ista 8770 adminis-trator or the clientadministrator usingthe standard LDAPprotocol. The val-ues can be ob-tained with LDAPquery. The APIdoes not provideany value. If avalue is specified, itmust exist in theOmniVista 8770.

uid READONLY Y User identifier(unique for an in-stance)

Mandatory for Get(using ID),Update, and De-lete operations.Not applicable forCreate operation

sn READWRITE Y User last name (itcorresponds tothe existing sn at-tribute in LDAP)

Mandatory forCreate operation.Optional for Up-date operation

Chapter 2

10/20


givenname READWRITE Y User first name (itcorresponds tothe existinggivenName attrib-ute in LDAP)

login WCRE-ATE_RUPDATE

N User authentica-tion login

If there is no value,it is generated froma login creationrule defined in themeta profile andOmniVista 8770

Salutation READWRITE Y User title Mandatory forCreate operationwhen meta profilesare used.Optional for Up-date operation.The value is in-cluded in the XSD

mail READWRITE Y User e-mail iden-tifier (it corres-ponds to the ex-isting mail attrib-ute in LDAP)

Mandatory forCreate operationwhen meta profilesare used.Optional for Up-date operation.

TelephoneNumber

WCRE-ATE_RUPDATE

Y Directory numberof the user

Optional, will bederived if no valueis provided

MetaProfile WCRE-ATE_RUPDATE

N Name of themeta profile ap-plied to the user

Optional for Cre-ate, Update, andGet operations

Node READONLY N Node name onwhich the user iscreated

Applicable for theGet operation only.This concerns theprimary node onwhich the user iscreated (OmniPCXEnterprise orOpenTouch node)

GUIPassword WRITEONLY* N Authenticationpassword to ac-cess GUI applica-tions

Optional for Cre-ate, Update, andGet operations.This value over-rides the valuedefined in a metaprofile

11/20


TUIPassword WRITEONLY N Authenticationpassword to ac-cess TUI applica-tions

Optional for Cre-ate, Update, andGet operations.This value over-rides the valuedefined in a metaprofile

CostCentername READWRITE Y Cost center towhich the userbelongs. It isused for account-ing purposes

Optional for Cre-ate, Update, andGet operations.This value over-rides the valuedefined in a metaprofile.The value musthave been previ-ously configured onthe OmniPCX En-terprise node

Devicekey WCRE-ATE_RUPDATE

N Device key Applicable for theCreate operation,only if a meta pro-file is used and in-cludes a devicetemplate.The OmniVista8770 provides thedefault value.

Devicepassword WRITEONLY N Device password Applicable for theCreate operation,only if a meta pro-file is used and in-cludes a devicetemplate.The OmniVista8770 provides thedefault value.

DeviceType WCRE-ATE_RUPDATE

N Type of deviceassociated to theuser

Only applicablewhen meta profilesare used. Thisvalue overrides thevalue defined in ameta profile.

Note:

The list of applicable

values is provided in

the API documenta-

tion and in the XSD.

Chapter 2

12/20


DeviceDirect-oryNumber

WCRE-ATE_RUPDATE

N Directory numberof the device

Optional. It is de-rived if no value isprovided

ClientId WCRE-ATE_RUPDATE

Y Client identifierdefined duringthe user creation

Optional. By de-fault, this value isset to OpenAPI

keyProfile READWRITE N Predefined func-tion keys pro-grammed on thedevice

Optional

WRITEONLY access: This concerns attributes such as passwords. The Get operation doesnot return any value for this attribute or returns a value such as ********.

WCREATE_RUPDATE access: The value for the corresponding attribute can only be specifiedduring the Create operation (not applicable for the Update operation).

2.1.3.3 Device

Devices can only be created if associated to a user. In an API context, devices are createdand associated to a user using meta profiles including a device template. Only the devices thatcan be deployed without their MAC address are supported.

A new device can be created and associated to the user at the time of user creation, or at anytime after user creation.

The device parameters returned by the API are listed in the table below. The other parametersare either included in device templates and/or keep their default values.


DeviceId READONLY Y Device identifier(unique for an in-stance)

On Create, thevalue will be de-rived.

deviceType READONLY Y Type of device Derived fromdevice template;applicable only forGet

directoryNumber WCREATE Y Directory num-ber of the device

Mandatory for Getand Delete opera-tions.Optional for theCreate operation(see the note be-low)Mandatory for Get,Delete; Optionalfor Create,

13/20


DeviceTemplate WCREATE N Template to beused to assignpredefined para-meters to thedevice

Mandatory for theCreate operation

DeviceKey WCREATE N Device key re-quested the firsttime a user con-nects to the set(login entry)

Set to the device'sdirectory number ifthis field is not com-pleted.Optional for theGet operation

DevicePassword WRITEONLY N Device passwordrequested thefirst time a userconnects to theset (passwordentry)

Set to the device'sdirectory number ifthis field is not com-pleted.Optional for theGet operation

deviceFreeNum-berRange

WCREATE N Free numberrange used toprovide an avail-able directorynumber to thedevice

Optional (see thenote below)

Note:

When a device is created for a user, its directory number is assigned in the following order:

1. Use directoryNumber from the input device data if provided, if not:

2. Get directoryNumber from deviceFreeNumberRange if provided, if not:

3. Get directoryNumber from the user.metaprofile.deviceFreeNumberRange if provided, if not:

4. Error. Failed to get directoryNumber

2.1.4 Template objects

2.1.4.1 Meta profile

The meta profiles contain the parameters required to create OT or OXE users. Meta profilessimplify user creation: they avoid having to tediously enter parameters one by one for eachnew user. Parameters are completed with the values defined in the selected meta profile.

Meta profiles can also contain OmniPCX Enterprise profiles and OpenTouch templatescreated on their respective nodes and retrieved by the OmniVista 8770 after synchronization.

The meta profiles cannot be configured using an API. They must created and configured usingthe Users application of OmniVista 8770.

The API can only return a minimum subset of meta profile parameters via the Get operation(see: Get method ). The meta profile parameters returned by the API are:

Chapter 2

14/20


cn READONLY Y Name of the metaprofile (it corres-ponds to the exist-ing cn attribute inLDAP)

To be specified in theuser object during cre-ation

Description READONLY N Description of themeta profile

For information only

UserType READONLY N Type of user OXE or OT user

NodeDN READONLY Y The LDAP Distin-guished Name ofthe primary nodeon which the usermust be created

OmniPCX Enterpriseor OpenTouch node

devicetemplate READONLY N Device template Template used to cre-ate and associate adevice to the user

2.1.4.2 Device template

The device templates contain a list of predefined parameters to create and associate a deviceto OT users at their creation

Device templates cannot be configured using an API. They must be created on their respectivenodes and retrieved by the OmniVista 8770 after synchronization.

The API can only return a minimum subset of device template parameters via the Getoperation (see: Get method ). The device template parameters returned by the API are:


cn READONLY Y Name of thedevice template(it correspondsto the existing cnattribute inLDAP)

To be specified inthe device objectduring creation

modelName Device modelname (that isdevice type)

Description READONLY N Description ofthe device tem-plate

For information only

NodeDN READONLY Y The LDAP Dis-tinguished Nameof the primarynode on whichthe device mustbe created

OpenTouch node

2.2 Set of operations supported by the API

15/20

2.2.1 Overview

The API supports the following operations (also called methods):

- Get (hierarchy, data)

- Create (hierarchy, data)

- Update (hierarchy, data)

- Delete (hierarchy)

Where:

- hierarchy is a URI (Uniform Resource Identifier) string used to identify an object (see:table: Hierarchy of data objects )

- data is a string that can be an empty string (null), an LDAP filter string, or a string in xmlformat

Note:The xml string is compliant with the gmi format defined in gmi.xsd.

- <xxx> notation indicates values to be provided for the key attribute xxx

2.2.2 Header

The header area in every transaction must include the following attributes/values:

- Login (the administrator account previously created in the OmniVista 8770)

- Password (password for the administrator login, previously defined in the OmniVista 8770)

- Client Identification (ASCII text stored in the OmniVista 8770). It can also be used forsearches from the API. If no value is specified, the value is set by default to OpenAPI)

- Client Remarks (optional): this is a free text allowing end users to identify their operations.The value is not stored in the OmniVista 8770, but appears in the log file entries

2.2.3 Get method

The generic usage of the Get method is as follows:

Syntax Information provided Comments

Get (hierarchy, null) Return object instance(s)specified in the hierarchy(see: table: Hierarchy of dataobjects )

General syntax

Get (hierarchy, fil-ter)

Return all the object IDs spe-cified in the hierarchy andthat match the filter criteria

Only the object IDs are re-turned during the search oper-ation. The search criterionmust be specified in the stand-ard LDAP syntax

Notes:

- For all Get operations that can potentially return multiple items, the maximum number of search

Chapter 2

16/20

results is predefined in the OmniVista 8770 but can be modified.

- If the search result has only one item, the returned data is the xml data of that object.

- If the search result has more than one item, the returned data is the xml data in the listResult format

The following table provides the available hierarchy strings and filters that can be applied tothe Get method. In the table, an empty cell indicates that there is no filter available for this Getmethod.

table 2.7: Available usages for the Get methodHierarchy Filtering Result

/ov8770 Ov8770 hierarchy

/ov8770/schema List of schema

/ov8770/schema/user User schema

/ov8770/schema/device Device schema

/ov8770/schema/metaprofile

Meta profile schema

/ov8770/schema/devicetemplate

Device template schema

/ov8770/schema/listresult

List result schema

/ov8770/data/users A valid LDAP searchfilter string.For example:&(sn=A*)(gi ven-name=L *)

In the example provided, the API re-turns the list of UIDs of users whoselast name starts by A and first namestarts by L.If there is only one user found, theuser data is returned.Exception if filter is null or invalid.

/ov8770/data/users/{UID}

Data of the user whose uid={UID}where {UID} corresponds to a username

/ov8770/data/users/{UID}/devices

List of devices associated to the userwhose uid={UID}where {UID} corresponds to a username

/ov8770/data/users/{UID}/device s/{directorynumber}

Data of device whose directorynum-ber={directorynumber} and as-sociated to a {UID}where {directorynumber} corres-ponds to a device directory number

/ov8770/templates/metaprofiles

A valid LDAP searchfilter string.For example: cn=A*

List of all meta profiles

17/20

Hierarchy Filtering Result

/ov8770/templates/metaprofiles/{cn}

Data of the metaprofile whosecn={cn}where {cn} corresponds to a metaprofile name

/ov8770/templates/devicetemplates

A valid LDAP searchfilter string.For example: cn=A*

List of all OpenTouch device tem-plates

/ov8770/templates/devicetemplates/{dn}

Data of the OpenTouch device tem-plate whose ldapDn={dn}where {dn} corresponds to a devicetemplate distinguished name

2.2.4 Create method

The generic usage of the Create method is as follows:


Create (hierarchy,data in XML format)

Create the object instance(s)specified in the hierarchy

The following table provides the available hierarchy string that can be applied to the Createmethod.

table 2.9: Available usages for the Create methodHierarchy Result

Create(/ov8770/data/users,data in XML format)

Create a user with the values specified by the inputdata in xml format (this can include device andvoice mailbox data). The user is created in theOmniVista 8770, and the corresponding nodes(OmniPCX Enterprise, OpenTouch, and/or OTMC)to which they are associated. Devices are createdand associated to the user, and configuration filesare created for the device commissioning.

Create(/ov8770/data/users/{UID}/devices, data in XML format)

Create a device with the values specified by the in-put data in xml format and associate this device tothe user which uid={UID}

Notes:

- The Create operation is only supported for user objects or device objects associated to users

- The Create operation does not support partial success as would the OmniVista 8770 client

- Only devices with self-assignment or applications can be created. To see the list of auto-provisioneddevices and applications, refer to the OmniVista 8770 feature list (reference: 8AL91400USAA).

2.2.5 Update method

The generic usage of the Update method is as follows:

Chapter 2

18/20


Update (hierarchy,data in XML format)

Update the object instancespecified in the hierarchy

The following table provides the available hierarchy string that can be applied to the Updatemethod.

table 2.11: Available usage for the Update methodHierarchy Result

Up-date(/ov8770/data/users/{UID},data in XML format)

Update the user with the values specified by the in-put data in xml format

Notes:

- Update operation is only supported for user objects

- Update operation does not support partial success as would the OmniVista 8770 client

- The data in XML format used for update must contain only the attributes and the values to update.For the MetaProfile attribute, if the input XML data contains the metaProfile attribute with novalue, the user is converted to a basic company directory user. If an input XML data contains anattribute (other than metaprofile) without value, it means that the attribute's value will be removed

2.2.6 Delete method

The generic usage of the Delete method is as follows:


Delete (hierarchy) Delete the object instancespecified in the hierarchy,and its associated objects

The following table provides the available hierarchy strings that can be applied to the Deletemethod.

table 2.13: Available usages for the Delete methodHierarchy Result

De-lete(/ov8770/data/users/{UID})

Delete the user which uid={UID} and the associ-ated devices

De-lete(/ov8770/data/users/{UID}/devices/{directorynumber})

Dissociate the device whosedirectorynumber={directorynumber} from theuser whose uid={UID}, and delete the device fromthe OmniVista 8770, and from the correspondingnodes of the device

De-lete(/ov8770/data/users/{UID}/devices)

Dissociate all devices from the user whichuid={UID}, and delete the device from the OmniV-ista 8770, and from the corresponding nodes ofdevices

19/20

2.3 Error handling

The exceptions raised by the API include the following information:

- Error code (see the common error codes listed below)

- Additional info: id or attribute and the value that has triggered the exception

- Error message provided in English

The common error codes are:

- 11. Operation not supported

- 12. Invalid input data

- 13. Invalid hierarchy

- 14. Unknown id

- 15. Duplicate id

- 16. Invalid filter

- 17. Missing attribute(s)

- 18. Too many parallel requests

- 19. Not Licensed

- 20. Not Authenticated

- 21. Processing Error in 8770/Nodesa. Time outb. Node not reachablec. Error from Noded. Invalid entry

2.4 Backward compatibility

The API is compatible with a release N+1 of the OmniVista 8770. This means that the APIdefined in the OmniVista 8770 R2.0 is compliant with the next major release of the OmniVista8770.

The XML version provided in the schema must be 2.0, corresponding to the OmniVista 8770R2.0.

Chapter 2

20/20

User Management API - Aministrator Manual

Documents

Transcript of User Management API - Aministrator Manual