Ip Office Configuration Service Programmers Guide 3b

15-601473 Issue 03b - (20 February 2013)

IP Office Configuration ServiceProgrammer's Guide

IP Office

IP Office Configuration Service Programmer's Guide Page 215-601473 Issue 03b (20 February 2013)IP Office

2013 AVAYA All Rights Reserved.NoticeWhile reasonable efforts have been made to ensure that theinformation in this document is complete and accurate at the time ofprinting, Avaya assumes no liability for any errors. Avaya reservesthe right to make changes and corrections to the information in thisdocument without the obligation to notify any person or organizationof such changes.

Documentation disclaimer"Documentation" means information published by Avaya in varyingmediums which may include product information, operatinginstructions and performance specifications that Avaya generallymakes available to users of its products. Documentation does notinclude marketing materials. Avaya shall not be responsible for anymodifications, additions, or deletions to the original published versionof documentation unless such modifications, additions, or deletionswere performed by Avaya. End User agrees to indemnify and holdharmless Avaya, Avaya's agents, servants and employees against allclaims, lawsuits, demands and judgments arising out of, or inconnection with, subsequent modifications, additions or deletions tothis documentation, to the extent made by End User.

Link disclaimerAvaya is not responsible for the contents or reliability of any linkedwebsites referenced within this site or documentation provided byAvaya. Avaya is not responsible for the accuracy of any information,statement or content provided on these sites and does notnecessarily endorse the products, services, or information describedor offered within them. Avaya does not guarantee that these linkswill work all the time and has no control over the availability of thelinked pages.

WarrantyAvaya provides a limited warranty on its hardware and Software("Product(s)"). Refer to your sales agreement to establish the termsof the limited warranty. In addition, Avayas standard warrantylanguage, as well as information regarding support for this Productwhile under warranty is available to Avaya customers and otherparties through the Avaya Support website:http://support.avaya.com. Please note that if you acquired theProduct(s) from an authorized Avaya reseller outside of the UnitedStates and Canada, the warranty is provided to you by said Avayareseller and not by Avaya. "Software" means computer programs inobject code, provided by Avaya or an Avaya Channel Partner,whether as stand-alone products or pre-installed on hardwareproducts, and any upgrades, updates, bug fixes, or modifiedversions thereto.

LicensesTHE SOFTWARE LICENSE TERMS AVAILABLE ON THE AVAYAWEBSITE, HTTP://SUPPORT.AVAYA.COM/LICENSEINFO/ AREAPPLICABLE TO ANYONE WHO DOWNLOADS, USES AND/ORINSTALLS AVAYA SOFTWARE, PURCHASED FROM AVAYA INC.,ANY AVAYA AFFILIATE, OR AN AUTHORIZED AVAYA RESELLER(AS APPLICABLE) UNDER A COMMERCIAL AGREEMENT WITHAVAYA OR AN AUTHORIZED AVAYA RESELLER. UNLESSOTHERWISE AGREED TO BY AVAYA IN WRITING, AVAYA DOESNOT EXTEND THIS LICENSE IF THE SOFTWARE WAS OBTAINEDFROM ANYONE OTHER THAN AVAYA, AN AVAYA AFFILIATE OR ANAVAYA AUTHORIZED RESELLER; AVAYA RESERVES THE RIGHT TOTAKE LEGAL ACTION AGAINST YOU AND ANYONE ELSEUSING OR SELLING THE SOFTWARE WITHOUT A LICENSE. BYINSTALLING, DOWNLOADING OR USING THE SOFTWARE, ORAUTHORIZING OTHERS TO DO SO, YOU, ON BEHALF OF YOURSELFAND THE ENTITY FOR WHOM YOU ARE INSTALLING,DOWNLOADING OR USING THE SOFTWARE (HEREINAFTERREFERRED TO INTERCHANGEABLY AS "YOU" AND "END USER"),AGREE TO THESE TERMS AND CONDITIONS AND CREATE ABINDING CONTRACT BETWEEN YOU AND AVAYA INC. OR THEAPPLICABLE AVAYA AFFILIATE ( "AVAYA").

Avaya grants you a license within the scope of the license typesdescribed below, with the exception of Heritage Nortel Software, forwhich the scope of the license is detailed below. Where the orderdocumentation does not expressly identify a license type, theapplicable license will be a Designated System License. Theapplicable number of licenses and units of capacity for which thelicense is granted will be one (1), unless a different number oflicenses or units of capacity is specified in the documentation orother materials available to you."Designated Processor" means a single stand-alone computingdevice."Server" means a Designated Processor that hosts a softwareapplication to be accessed by multiple users.

License typesDesignated System(s) License (DS). End User may install and useeach copy of the Software only on a number of DesignatedProcessors up to the number indicated in the order. Avaya mayrequire the Designated Processor(s) to be identified in the order bytype, serial number, feature key, location or other specificdesignation, or to be provided by End User to Avaya throughelectronic means established by Avaya specifically for this purpose.

Concurrent User License (CU). End User may install and use theSoftware on multiple Designated Processors or one or more servers,so long as only the licensed number of Units are accessing and usingthe Software at any given time. A "Unit" means the unit on whichAvaya, at its sole discretion, bases the pricing of its licenses and canbe, without limitation, an agent, port or user, an e-mail or voice mailaccount in the name of a person or corporate function (e.g.,webmaster or helpdesk), or a directory entry in the administrativedatabase utilized by the Software that permits one user to interfacewith the Software.Units may be linked to a specific, identified Server.

Database License (DL). End User may install and use each copy ofthe Software on one Server or on multiple Servers provided thateach of the Servers on which the Software is installed communicateswith no more than a single instance of the same database.

CPU License (CP). End User may install and use each copy of theSoftware on a number of Servers up to the number indicated in theorder provided that the performance capacity of the Server(s) doesnot exceed the performance capacity pecified for the Software. EndUser may not re-install or operate the software on Server(s) with alarger performance capacity without Avayas prior consent andpayment of an upgrade fee.

Named User License (NU). You may: (i) install and use the Softwareon a single Designated Processor or Server per authorized NamedUser (defined below); or (ii) install and use the Software on a Serverso long as only authorized Named Users access and use theSoftware. "Named User", means a user or device that has been expresslyauthorized by Avaya to access and use the Software. At Avayas solediscretion, a "Named User" may be, without limitation, designated byname, corporate function (e.g., webmaster or helpdesk), an e-mailor voice mail account in the name of a person or corporate function,or a directory entry in the administrative database utilized by theSoftware that permits one user to interface with the Software.

Shrinkwrap License (SR). You may install and use the Software inaccordance with the terms and conditions of the applicable licenseagreements, such as "shrinkwrap" or "clickthrough" licenseaccompanying or applicable to the Software ("Shrinkwrap License").


Heritage Nortel Software"Heritage Nortel Software" means the software that was acquired byAvaya as part of its purchase of the Nortel Enterprise SolutionsBusiness in December 2009. The Heritage Nortel Software currentlyavailable for license from Avaya is the software contained within thelist of Heritage Nortel Products located athttp://support.avaya.com/licenseinfo under the link "Heritage NortelProducts". For Heritage Nortel Software, Avaya grants Customer alicense to use Heritage Nortel Software provided hereunder solely tothe extent of the authorized activation or authorized usage level,solely for the purpose specified in the Documentation, and solely asembedded in, for execution on, or (in the event the applicableDocumentation permits installation on non-Avaya equipment) forcommunication with Avaya equipment. Charges for Heritage NortelSoftware may be based on extent of activation or use authorized asspecified in an order or invoice.

CopyrightExcept where expressly stated otherwise, no use should be made ofmaterials on this site, the Documentation, Software, or hardwareprovided by Avaya. All content on this site, the documentation andthe Product provided by Avaya including the selection, arrangementand design of the content is owned either by Avaya or its licensorsand is protected by copyright and other intellectual property lawsincluding the sui generis rights relating to the protection ofdatabases. You may not modify, copy, reproduce, republish, upload,post, transmit or distributein any way any content, in whole or in part, including any code andsoftware unless expressly authorized by Avaya. Unauthorizedreproduction, transmission, dissemination, storage, and or usewithout the express written consent of Avaya can be a criminal, aswell as a civil offense under the applicable law.

Virtualization

Third Party Components"Third Party Components" mean certain software programs orportions thereof included in the Software that may contain software(including open source software) distributed under third partyagreements ("Third Party Components"), which contain termsregarding the rights to use certain portions of the Software ("ThirdParty Terms"). Information regarding distributed Linux OS sourcecode (for those Products that have distributed Linux OS source code)and identifying the copyright holders of the Third Party Componentsand the Third Party Terms that apply is available in theDocumentation or on Avayas website at:http://support.avaya.com/Copyright. You agree to the Third PartyTerms for any such Third Party Components.

Note to Service ProviderThe Product may use Third Party Components that have Third PartyTerms that do not allow hosting and may need to be independentlylicensed for such purpose.

Preventing Toll Fraud"Toll Fraud" is the unauthorized use of your telecommunicationssystem by an unauthorized party (for example, a person who is nota corporate employee, agent, subcontractor, or is not working onyour company's behalf). Be aware that there can be a risk of TollFraud associated with your system and that, if Toll Fraud occurs, itcan result in substantial additional charges for yourtelecommunications services.

Avaya Toll Fraud InterventionIf you suspect that you are being victimized by Toll Fraud and youneed technical assistance or support, call Technical Service CenterToll Fraud Intervention Hotline at +1-800-643-2353 for the UnitedStates and Canada. For additional support telephone numbers, seethe Avaya Support website: http://support.avaya.com. Suspectedsecurity vulnerabilities with Avaya products should be reported toAvaya by sending mail to: [email protected].

TrademarksThe trademarks, logos and service marks ("Marks") displayed in thissite, the Documentation and Product(s) provided by Avaya are theregistered or unregistered Marks of Avaya, its affiliates, or otherthird parties. Users are not permitted to use such Marks withoutprior written consent from Avaya or such third party which may ownthe Mark.Nothing contained in this site, the Documentation and Product(s)should be construed as granting, by implication, estoppel, orotherwise, any license or right in and to the Marks without theexpress written permission of Avaya or the applicable third party.

Avaya is a registered trademark of Avaya Inc.

All non-Avaya trademarks are the property of their respectiveowners, and "Linux" is a registered trademark of Linus Torvalds.

Downloading DocumentationFor the most current versions of Documentation, see the AvayaSupport website: http://support.avaya.com.

Contact Avaya SupportSee the Avaya Support website: http://support.avaya.com forproduct notices and articles, or to report a problem with your Avayaproduct.For a list of support telephone numbers and contact addresses, go tothe Avaya Support website: http://support.avaya.com, scroll to thebottom of the page, and select Contact Avaya Support.


Contents

ContentsIP Office Configuration Service1.

..................................................................... 101.1 Key Terms Used in this Document

..................................................................... 111.2 Runtime Requirements

Architectural Overview2...................................................................... 162.1 Configuration Consistency

IP Office Configuration ServiceMethods

3.

..................................................................... 183.1 ConnectAndGetUnitDetails

..................................................................... 193.2 Primary Service Methods

............................................................................ 193.2.1 GetUnitConfiguration Method

............................................................................ 203.2.2 SetUnitConfiguration Method

............................................................................ 213.2.3 GetSEUnitConfiguration

............................................................................ 213.2.4 SetSEUnitConfiguration

............................................................................ 213.2.5 IP Office Server Edition Usage Notes

XML Format4...................................................................... 244.1 Document Root

..................................................................... 254.2 User

............................................................................ 284.2.1 DSS Keys

............................................................................ 304.2.2 DSS Key Examples

..................................................................... 314.3 Groups

............................................................................ 334.3.1 Group Membership

Hosting and Secure ConfigurationGuides

5.

..................................................................... 365.1 Configuring Secure Transport on IP Office

..................................................................... 385.2 Hosting Under IIS

...............................................................................39Index


IP Office ConfigurationService

Chapter 1.


IP Office Configuration Service:

1. IP Office Configuration ServiceThis document details the Application Programming Interface (API) for the IP Office Configuration Service component. Itdetails the operation of the API and the data that is exchanged to effect the supported configuration changes on user andgroup objects.

The API is only supported with IP Office systems operating in IP Office Essential Edition, IP Office Preferred Edition, IPOffice Advanced Edition or IP Office Server Edition mode and running IP Office Release 4.2 or higher. See RuntimeRequirements for further details.

The API enables integrators and ISVs to incorporate robust configuration changes into their solution via a web serviceinterface, expressing configuration changes via an XML document. It enables changes to be made to the following IP Officeentities:

User

Group

Subsets of the available fields are supported for each entity, which fulfils the majority of use-cases targeted by thisrelease. These supported fields are documented in the XML document section.

Various methods are exposed by the service interface. These are designed to support hosting under IIS or can be selfhosted. The service interface utilizes the Windows Communications Foundation (WCF); this technology supports a numberof hosting scenarios, such as self hosted. The IIS hosted approach is the only method discussed in this document. The primary service methods are used to get the configuration from the IP Office (GetUnitConfiguration ) and to setthe configuration (SetUnitConfiguration ) respectively (for IP Office Server Edition systems the alternate methodsGetSEUnitConfiguration and SetSEUnitConfiguration are used).

These methods work by supplying or consuming an XML document. The XML format is consistent across a get/set forthe supported User/Group entity fields. When making configuration changes, an Opp (Operation Code) attribute is used toindicate the desired operation against an entity. The following Opp attributes are supported:

Add

Update

Delete

For new or updated data, the XML document need only contain the change fields for the new or updated data. A summarydocument is returned for a set method to indicate if the configuration changes were successfully applied, or if the changesresulted in a validation message. The following validation levels are used:

Informational

Warning

Error

The GetUnitConfiguration method call returns the supported User and Group entities and their supported fields, alongwith additional supporting information such as the handset for the User record.

Additional supplemental data is also supplied; this can be used to support your validation logic if required.

The data supplied includes:

Unit Name and software version number

Extensions, Extn Number, Port, Phone Type

User Rights, template name

Existing Validation, messages

Note It is imperative that you have a good understanding of the configuration and management of IP Office and thatyou are comfortable using the IP Office Manager application.

11

19 19

20

21 21

24


1.1 Key Terms Used in this DocumentGeneral industry terms and their acronyms are introduced inline, as in "TCP" (Transmission Control Protocol) when firstused in a section, if the term is either sufficiently new or specific to this architecture then it will be documented in thissection and an explanation provided.

BINDING WCF (see below) binding directive, used to configure the protocol utilized, for example basicHttpBinding andwsHttpBinding. Binding also can be configured to affect policy and security.

GUID Global Unique Identifier. A 128 bit number written as a sequence of hexadecimal digits.

OPP Operation Code, an attribute supplied that identifies how an element and its data should be processed. The definedoperations are Update, Add and Delete.

UCC Upper Camel Case. Naming convention, where words are compounded together and the first letter of each word iscapitalized.

WCF Windows Communications Foundation, a unified communications programming model implemented as part of the.Net 3.0 technology stack.

WinFx Microsofts Framework for delivering key Communications/Presentation API on Windows XP (SP2)/Vista clientoperating systems and Windows 2003 and Longhorn Server.

When there are important concepts to explain a note section will be used to breakout the detail and bring them to yourattention.

Note These notes provide useful information, about the current subject


IP Office Configuration Service: Key Terms Used in this Document

1.2 Runtime Requirements

Software Component Requirement

IP Office System IP Office Essential Edition, IP Office Preferred Edition, IP Office Advanced Edition or IPOffice Server Edition systems only.

IP Office Release 4.2 or higher.

PC Operating System Windows Server 2003 SP1 (Standard Edition, Enterprise Edition, or DatacenterEdition), depending on load/usage a client OS Windows Vista or Windows XP may beadequate (subject to your own load and capacity evaluation).

Windows 7 32-bit and 64-bit.

Windows 8 32-bit and 64-bit.

Windows Server 2008 R2

Web Server for hosting theweb service

IIS 6.0

Additional RuntimesInstalled

Windows 7/ Windows server 2008, 64 bit Support - Install Avaya IP OfficeConfigServiceHost prerequisite

.NET Framework Version 3.0

ASP.NET 2.0

Visual Studio 2005 C++ SPI C/C++ runtime

You install IIS 6.0 by using the Windows Control Panel. For details, see the Windows Server documentation.

To download Service Pack 1 for Windows Server 2003, go to http://www.microsoft.com/windowsserver2003/downloads/servicepacks/sp1/default.mspx.

To download the .NET Framework, go to http://www.microsoft.com/downloads/details.aspx?familyid=10CC340B-F857-4A14-83F5-25634C3BF043&displaylang=en.

To download the C++ runtime (Visual Studio 2005 SP1), go to http://www.microsoft.com/downloads/details.aspx?FamilyID=200b2fd9-ae1a-4a14-984d-389c36f85647&DisplayLang=en.

http://www.microsoft.com/windowsserver2003/downloads/servicepacks/sp1/default.mspxhttp://www.microsoft.com/downloads/details.aspx?familyid=10CC340B-F857-4A14-83F5-25634C3BF043&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?familyid=10CC340B-F857-4A14-83F5-25634C3BF043&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=200b2fd9-ae1a-4a14-984d-389c36f85647&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=200b2fd9-ae1a-4a14-984d-389c36f85647&DisplayLang=en


Architectural Overview

Chapter 2.


2. Architectural OverviewThe solution targets the Windows 2003 Server platform and utilizes the Microsoft .Net framework 3.0 to provide a robustand scalable service implementation. The service interface is hosted using the Windows Communications Framework(WCF), to enable flexible hosting of the service as a standalone executable or via IIS. The web service enables nonwindows platforms to consume its services if required, based on a standard http based binding.

Communication between the Avaya IP Office Configuration Service and the customers IP Office is over TCP using a secureconnection. Transport Layer Security (TLS) is utilized to establish a session between the configuration service and the IPOffice for the duration of a transfer to/from the service and the IP Office.

The port number of the IP Office services can be configured for individual systems using the security manager (introducedin the IP Office Manager Release 4.1) when the system is commissioned. The default ports are as follows:

IP Office Service Unsecured Secured Comment

Configuration 50804 50805 This is the only interface utilized by the Avaya IPOffice configuration component.

Program 50806 50807

System Status Interface 50808 50809

Directory Lists 50810 50811

Security Administration 50812 50813

Whois_2 50802 Utilized by IP Office Manager, replaces UDPbased whois.

These ports are based on a base port defined via the security manager, so adjustments to the base port move the portsen bloc; please review the necessary IP Office 4.1 details for these and other changes/options regarding TCP/UDPservices.

IP Office can be configured to meet different security expectations; the security configuration is separate from the coreunit configuration. With the exception of the Whois_2 port, the IP Office enables the security to be configured to supportinsecure/secure and secure or insecure access to these services, dependant on the level of authentication required. LegacyUDP based service can also be locked down.

A secure port only will be used to access the IP Office, the level must be set to low (the inbuilt certificate that IP Officegenerates will be utilized, when a secure service is configured). The certificate is used to enable key exchange only and isnot verified. The service will trust the inbuilt certificate presented from the IP Office to enable the secure session to beestablished.

Note The security level must be set to low, to enable use of the inbuilt certificate.


Architectural Overview:

The services utilizes the secure connection and authentication credentials supplied to retrieve the binary configuration filefrom the IP Office, the file is unpacked into an object representation before converting the supported subset of informationinto XML. The same steps are taken when applying configuration changes, retrieve the file from the IP Office at the latestpossible moment, before applying the changes embodied in the XML configuration, validation takes place duringprocessing if no errors are detected representation is repacked and transferred back to the IP Office.

Figure 1 - Logical Architecture


2.1 Configuration ConsistencyThe following strategies are used to handle data consistency.

Data changes are always applied to the most recent configuration. This involves fetching the configuration binaryfrom the unit, prior to applying the updates and then returning the configuration binary promptly. These steps aresequential within a service invocation.

The configuration XML file contains the entities and field changes only, these changes are applied to theconfiguration. Scoping the changes to only the fields that have been affected reduces the amount of data requiredto be processed and ensures only the data that needs to be touched is affected. This approach is embodied in theformat of the XML changes document.

The entity level flag on the changed item (user, group, etc) is set to indicate which entities have been changed.This enables the IP Office to process the new configuration file specifically merging the entities that have beenmarked. This isolates the impact of locally changed values at an entity level, as a binary diff is used to identifychanges to records. Being explicit ensures that entities that have not been flagged explicitly are not considered formerging.

The approach above reduces the impact on the total system configuration and focus the changes to just the affectedentities and within these entities only the relevant fields.

The overall configuration strategy is no less vulnerable than having two local manager instances, where last change wins.If the entity changes are not overlapping, then both updates will be successful. These behaviors and operations will beconsistent with the standalone IP Office Manager operation.

It is recommended that consumers of the service implement a strategy to avoid concurrent overlapping configurationwrites. If your application supports multiple concurrent clients, then your solution should aggregate these requests andserialize the requests to the configuration service.

Note If your integration requires multiple concurrent requests, provide a service faade to queue the requests beforecalling the service. IP Office makes live the configuration changes approximately 2 seconds after processing thereceived configuration.


IP Office ConfigurationService Methods

Chapter 3.


3. IP Office Configuration Service MethodsThe service exposes a utility method, ConnectAndGetUnitDetails , that can be used to check if the IP Office systemis reachable. The following primary methods can then be used to get and to set configuration settings:

GetUnitConfiguration

SetUnitConfiguration

GetSEUnitConfiguration (used with IP Office Server Edition systems only)

SetSEUnitConfiguration (used with IP Office Server Edition systems only)

The service interface utilizes a string type to return the XML representation of the configuration items and likewise the SetUnitConfiguration method will accept an XML document defined as a string type to transfer the configurationupdates.

This arrangement allows the same interface to be utilized as the solution evolves over time; the content of the XML inferswhat operations are required and the structure is kept simple to allow future extensibility.

Note The service interface is hosted under IIS, via a "svc" file. The URL of the service endpoint is determined byyour configuration. You will typically need to access the Web Services Description Language (WSDL) of theservice to build a proxy in your development environment.

3.1 ConnectAndGetUnitDetailsThe service exposes a utility method, ConnectAndGetUnitDetails, that can be used to check if the IP Office system isreachable. The method also returns some basic unit information:

Unit Name

IP Address

Type

Version

Unit MAC Address

Mode

The following example is the XML returned by an IP500 V2 based Expansion System in a IP Office Server Edition network:

00E007057148 148.147.206.154 IP 500 V2 9.0 (102029) 00e007057148 IPO S-EDITION(E)

The service utilizes the internal implementation to assert if the unit is reachable before attempting to retrieve configurationdata from the IP Office.

18

19

20

21

21


IP Office Configuration Service Methods: ConnectAndGetUnitDetails

3.2 Primary Service MethodsThe two service methods enable you to retrieve (GetUnitConfiguraiton ) configuration data as XML and makechanges to configuration (SetUnitConfiguration ) via a XML configuration document. These methods are stateless, anew session is created per request, and this enables multiple services to be deployed across PCs utilising a load balancerif high scalability is required.

For IP Office Server Edition systems, the alternate service methods GetSEUnitConfiguration andSetSEUnitConfiguration are used instead.

3.2.1 GetUnitConfiguration MethodThe following parameters are required:

Unit IP Address (string)

Unit Configuration Service Port number (string)

Service Account Name (string)

Service Account Password (string)

The return value is an XML document that represents the configuration elements on success or a fault message indicatingthe nature of the error.

19

20

21

21


3.2.2 SetUnitConfiguration MethodThe following parameters are required:





Configuration XML directives (string)

Batch Transactional (string)

The return value is an XML document with summary request data or a fault contract that represents the nature of thefailure "ConnectivityFault" containing a fault reason code and an error description. The "ConnectivityFault" is returned toindicate an unrecoverable condition, such as the unit being unreachable, failing authentication or invalid XML beingsupplied.

The summary return data provides feedback on the number of issues related to the changes processed, if the informationis informational or a warning then the changes would have been applied, indicated by the "ConfigTransferred" elementcontaining a true value.

If errors are detected, these will be indicated in the Errors element as a count, details of the validation errors arereturned, referencing the original GUID used and a detailed description of the failure.

Note When errors are caused by incoming change requests a decision is made based on the "BatchTransactional"flag, either to continue disregarding the failed change request and continue processing other potential validrequests or fail all changes and not commit back the configuration. In either case, if errors are detected in thecompleted configuration update, they are never committed back to the IP Office. This enables you to acceptfailures and get feedback, while only applying valid changes that pass validation to succeed.

Setting "BatchTransactional" to false will enable partial changes to succeed, while a true setting will not allowpartial failures.

Example: Summary Return Data on a Successful Method Call

0000FalseTrue

Note When adding a new user or group, a GUID is supplied as a unique reference, the GUID in this case is only validfor the request, IP Office will allocate a new GUID for the record and utilize its own MAC address for therelevant portion of the GUID. Any errors or validation issues will utilize the supplied GUID to ensure aconsistent reference, it should not be persisted.


IP Office Configuration Service Methods: Primary Service Methods

3.2.3 GetSEUnitConfigurationThis method can only be used with IP Office Server Edition systems. The following parameters are required:





Unit Type (string) For IP Office Server Edition systems this is always IPOfficeMMManager.

The return value is an XML document that represents the configuration elements on success or a fault message indicatingthe nature of the error.

3.2.4 SetSEUnitConfigurationThis method can only be used with IP Office Server Edition systems. The following parameters are required:





Configuration XML directives (string)

Batch Transactional (string)

Unit Type (string) For IP Office Server Edition systems this is always IPOfficeMMManager.

The return value is an XML document with summary request data or a fault contract that represents the nature of thefailure "ConnectivityFault" containing a fault reason code and an error description. The "ConnectivityFault" is returned toindicate an unrecoverable condition, such as the unit being unreachable, failing authentication or invalid XML beingsupplied.

3.2.5 IP Office Server Edition Usage NotesUse ConnectAndGetUnitDetails first to get the and strings. These will indicate the role of theserver in the IP Office Server Edition network and the type of platform on which the server is based. The current possiblecombinations are:

IPO-Linux-PC IPO S_EDITION(P) This is the mode for a Linux based Primary Server in a IP Office Server Edition network.

IPO-Linux-PC IPO S-EDITION(S) This is the mode for a Linux based Secondary Server in a IP Office Server Edition network.

IPO-Linux-PC IPO S-EDITION(E) This is the mode for a Linux based Expansion System in a IP Office Server Edition network.

IP 500 V2 IPO S-EDITION(E) This is the mode for an IP500 V2 based Expansion System in a IP Office Server Edition network.

Use GetSEUnitConfiguration or SetSEUnitConfiguration calls with the Unit Type string set asIPOfficeMMManager.

18

21 21


XML Format

Chapter 4.


4. XML FormatThis section describes the format of the XML document used to effect configuration changes. The document is based onthe format retrieved as a result of a GetUnitConfiguration or GetSEUnitConfiguration method, with theaddition of an Opp code attribute value (Update, Add or Delete) to signify the intent of the change at a User/Grouplevel.

User records have additional DSSKey sub elements that can be individually set. An Opp code attribute can be expressedfor each individual element representing a key.

The document format is composed of a root element and sub elements that are categories of configuration data expressedas plurals for example "Users", these in turn contain the type of element using the singular, for example User.

The element that represents the record of an entity is composed of two attributes; the first is the GUID of the object (itsunique key) and the operation to be performed if the document is a configuration change document.

The child elements use the English IP Office Manager field names to identify the field of a record and the value iscontained as the inner text of the element.

The XML data must be UTF-8 encoded.

The elements and attributes use Upper Camel Case (UCC), to capitalize the first character of each word andcompound the name.

Note The XML naming is mainly aligned with the IP Office Manager application fields. IP Office Manager is a greatlearning tool for round tripping between the service to observe how your changes are applied/rendered in XML.

4.1 Document RootThe document root element is AvayaIPOConfiguration. The elements that support configuration changes are User andGroup; each contained in a parent element named Users and Groups respectively.

The table below shows how the overall XML document is structured.

Document Root Parent Elements Entity Element Comments

Root element

Users container

User record

Groups container

Group record

Table 1

19 21

25

31


XML Format: Document Root

4.2 UserUser elements are contained by the "Users" container as shown in Table 1 , they represent the user record and inbuiltusers such as "NoUser", a template used for new user records.

Note User records generally should be updated. A system automatically creates a user record for each extension andassociates the two. The ability exists to delete and add user records, if required.

User Mandatory/Optional

Attributes Comments

Mandatory Guid The GUID unique key of the userrecord.

Mandatory Opp Opp code for change "Add", "Update", "Delete".

Example:

Name

User Element Mandatory/Optional

Value Comments

Name Optional/Mandatory

The record name of the user,traditionally "Extn206". Mandatoryon an "Add" operation.

A textual key; must not containspaces or reserved characters.

Example:

Extn206

Note Name and FullName fields do not support the following punctuation characters ",(),#,?,/,-,+,=,,$,*,~,@,%,

Date post:	16-Nov-2015
Category:	Documents
Upload:	jose-meneses-jr
View:	45 times
Download:	1 times

Ip Office Configuration Service Programmers Guide 3b

Documents