Fusion Web Services User Manual
Contents
1. 8 getUnitIdS Fr EE re n EES ER SCH 10 deleteUnittype KK TA AST 11 getUnittypes AE A a aa en DI 12 AAdOTChANGEPTOfIlE EE 13 deleteProfile EE 14 getProfiles aaun RE aitta EE KD 15 Redirection Troubleshocting EE 16 Appendix nie bias bens dN eee ere k Bias AKA sk SKANES Al te 16 1 Add Change unit chapter 4 1 5 1 Eeer 15 2 EE EE 1 Document Introduction 1 1 Document Purpose The purpose of the document is to explain the Fusion Web Services interface 1 2 Document Audience Developers of Fusion Web Service Clients and Fusion Administrators 1 3 Document History 1 1 0 5 5 M M Simonsen 23 Mar 09 Mar 09 Initial Initial public version version 1 0 6 M Simonsen 29 Sep 09 Revised edition added info about SSL connection password 1 1 E M Simonsen 19 Oct 09 Complete rework of documentation Added getUnits and deleteUnit many changes to existing service 2 M Simonsen 11 May 10 Added 7 new methods for manipulating Unit Type amp Profile and to return all unitIds for a set of search criteria User permissions are now integrated into the services 1 3 1 M Simonsen 24 Jun 11 Changed the getUnits services to allow for more complex searches Added some restrictions on the usage of unit id sear2. lt unit gt lt GetUnitsRequest gt lt soapenv Body gt lt soapenv Envelope gt 16 5Search using parameter search chapter 7 4 lt xml version 1 0 encoding UTF 8 gt lt soapenv Envelope xmlns soapenv http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt lt soapenv Body gt lt GetUnitsReguest xmIns http xapsws owera com gt lt login xmlns gt lt username gt user lt username gt lt password gt pass lt password gt lt login gt lt unit xmins gt lt profile gt lt name gt Default lt name gt lt profile gt lt unittype gt lt name gt NPA201E lt name gt 34 lt unittype gt lt parameters gt lt parameterArray gt lt item gt lt name gt System X_OWERA COM Device MAC lt name gt lt value gt 00219401CA29 lt value gt lt flags gt EQ lt flags gt lt item gt lt parameterArray gt lt parameters gt lt unit gt lt GetUnitsRequest gt lt soapenv Body gt lt soapenv Envelope gt 35
3. Types and or Profiles Yes there can be a conflict that is when the explicitly stated Unit Types and or Profiles do no match the Login permissions In that case a SOAP Fault will be returned 3 3 Unit Id The Unit id is the unigue identifier in Fusion e g there can be only one Unit in Fusion for each Unit id The format of the Unit id varies according to the provisioning protocol Protocol Format Comment Example TR 069 lt 0UI gt OUI is a 6 digit hexadecimal number to identify 123456 Modelname lt ProductClass the organization 123456789012 lt SerialNumber gt ProductClass is often the model name of the device SerialNumber is most often the MAC address HTTP T lt SerialNumber gt SerialNumber is a unigue alfanumerical 123456HJK1234 FTP number If not universally unigue it should be prefix ed with a Product name The SHA 1 digest should be formatted as an alphanumerical upper case string To make sure you re on the right track your digest algorithm should convert Test into A94A8FESCCB19BA61C4C0873D391E987982FBBD3 7 3 4 Serial Number A unique value Some years ago the serial number was the only alternative to reference a unit except using the Unit id Over time Fusion have adapted to be able to reference a unit using any kind of unique value However changing the Fusion Web Services is something we are very reluctant to do since it most likely will cause all integrations to be un
4. be either AC AddChange or D Delete If omitted AC is default getUnitsReguest The flags can be either EO Egual or NE Not Egual LT Less Than LE Less or Egual GE Greater or Egual or GT Greater Than If omitted EO is default Optionally you can add another flag to indicate the type of comparison TEXT or NUMBER TEXT is default Examples EQ NUMBER or GT TEXT getUnitsResponse The flags can be either P Profile or U Unit Never omitted 3 6 Keyroot Each parameter that represents an attribute or property of the device always starts it s name with a Keyroot This Keyroot can be either Device Or InternetGatwayDevice depending upon the device Usually a device that can be or should be connected to public IP is a InternetGatewayDevice otherwise it is a Device This is not a rock solid rule and the best way to find out is to check the parameters defined in the Unit Type in Fusion Web or Fusion Shell Examples of parameter names Device DeviceInfo SerialNumber InternetGatewayDevice DeviceInfo SerialNumber 3 7 Exceptions In case the service for some reason fails it will throw an exception which will be shown as a SOAP Fault The goal is that this fault message should contain enough information to make it possible to correct the input to the service 3 8 Color codes Each input field is in blue color if it is reguired Optional input fields are green 3 9 XML The recommended way to m
5. value Comment Unit serialNumber 123456789012 Unit unittype name NPA201E Unit profile name Default Username This serial Number must be found in Fusion and should represent only one Unit We assume that the Serial Number we re searching for is defined in a Unit within this Unit Type We assume that the Unit is in Default Profile hence no profile move Unit unitId dd37cbd4 d4a3 3d66 8958 5d9cf30635f5 14 6 deleteUnit This service is relatively straight forward it simply deletes a Unit from Fusion The service does not support multiple deletes 6 1 case 1 delete a Unit known Unit id Example value Comment Unit Una ts 2 ol dd37cbd4 d4a3 3d66 This unit must be present in deleted true Will return true if unit was found and deleted If unit was not found it will return false 6 2 use case 2 delete a Unit unknown Unit id New in 2011 Release 2 The serial number value can be any value that uniguely identifies the unit password ip address username etc Object Example value Comment M Login password nel Password Unit serialNumber m This serial Number must be found in Fusion and should represent only one Unit Unit unittype name NPA2OIE We assume that the Serial Number we re searching for is defined in a Unit within this Unit Type deleted true Will return true if unit was found and deleted If unit was not found it will retur
6. R See chapter 3 5 on how to specify the flags You may repeat the same parameter in the search Two limitations 16 1 If you use a Parameter search you must also specify a Unit Type or a Profile 2 You cannot combine the value search and the parameter search 7 1 3 Preference Unit Type and Profile information will always be taken into account in all searches If not provided the search will be applied within the allowed Unit Types and Profiles The priority among the other search criteria are as follows 1 If Unit Id is detected in the input the search will be a unit id search The response will be O or 1 unit 2 If a Serial Number is detected in the input the search will be a value search The response will be 0 1 unique value or more units not unique and partial value 3 If a Parameter is detected in the input the search will be a parameter search 7 1 4 Return limit The result could range from O to 50 hits The 50 hits limit is specified to avoid a situation where your search hits thousands of Units and the response time goes sky rocketing To signal that more units were found than returned the output contains a boolean named moreUnits It is not feasible to actually return the number of units in an output field since that would hit the performance of the guery and it is not possible to return the next 50 units 50 100 To overcome this limitation use the getUnitIds service see next chapter 7 1 5 Partial se
7. Unit Parameter paramet 1 Device DeviceIn A Unit parameter name fo Uptime parame 1 A Unit parameter value parame 1 U The flag indicated that this is a Unit Parameter moreUnits No more units found 23 8 getUnitIds This methods is the cousin of the getUnits service The difference is this e no limitation on the result all unitIds that match the search will be returned e only unitId will be returned in the result higher performance for large result sets The idea of this unit is to be able to retrieve a list of unitIds To get more information about a certain unit you need to run the getUnits service 24 9 addOrChangeUnittype The methods mentioned so far in this document Unit methods are intended for integration between an Fusion customer requiring a limited standard integration It is then assumed that add change delete operations on Unittype Profile is something that will be done manually using Fusion Web or Fusion Shell However some customers will need a more tight integration since creating a Unittype Profile will be repeated by their customers In general this kind of integration will only be necessary with customer that is not an end customers that is Fusion will be part of another system which in turn will be sold to an end customer We recommend against using these methods if you re not this kind of customer because a tighter integration also will hurt more ever
8. a This example only show one Unit in return but there could be a list of up to 50 units in a list all complete with both unit parameters and profile parameters New for 2011 Release 2 No longer possible to use unit id in this search it will then be interpreted as a use case 1 search Object Cs Example value Comment Unit unittype name NPA201E The Unit Type must be present in Fusion parameter 0 name Device VoiceServi The parameter name must be ce 1 VoiceProfile present in the Unit Type l Line 1 SIP Aut NPA201E mentioned above hUserName Paramet ed NONI The value to search for must start with Joe parameter 0 ENKE Not Equal flag see chapter 3 5 This will turn the search into find all Units where AuthUserName do not start with Joe parameter 1 Device DeviceInfo The parameter name must be Uptime present in the Unit Type NPA201E mentioned above parameter 1 Represents in this case 24h 1440 minutes parameter 1 GT NUMBE Greater Than see chapter 3 5 This should prompt the search to only return the units with uptime higher than 24h Unit 0 unitId dd37cbd4 d4a3 The Unit id 3d66 8958 5d9cf30635 5 Unit 0 serialNumber 123456789012 The Unit s Serial Number 22 M K Ma Sege parameter 0 Device VoiceServi A Unit parameter name ce 1 VoiceProfile 1 Line 1 SIP Aut hUserName N D W paramet U The flag indicated that this is a
9. ake the correct XML SOAP reguests Web Services Reguests is to generate a Web Service Client based on the WSDL which is always supplied together with this document If you do not have the appropriate tools to generate the correct XML you may read the WSDL and check out the appendix which shows correct XML for some chosen services The input output shown in the examples are not supposed to be interpreted as XML tags although they do have almost the same name The difference can be uppercase lowercase is some cases The main idea with the input output is to show what kind of objects data the various services require 4 addOrChangeUnit add use case NB This chapter is mostly for adding devices not manufactured by Ping Communication For Ping Communication devices the adding of new devices is most likely already done through the use of the staging procedure This chapter focuses on add use cases This is the case where the Fusion database has no information whatsoever about the Unit It is not an add use case if you do not know the Unit id you must positively know that the unit is not found in the database If you do not know and run the service the effect will then be add or change That may not be problematic it depends on the context and what you are trying to do To add a Unit there are two pieces of information that is absolutely necessary Unit id Secret known as ACS password provisioning password The Unit id ha
10. an of course add as many parameters to the unit as you like for example information you gather from your customer Object Example value Comment Mn iu Unit unittype name NPA201E The Unit Type must be present in Fusion a Fusion Fusion Kos Uni 123456 Modelname This value must be unique 123456789012 within Fusion and correspond to the protocol it parameters 0 name InternetGatewayD The parameter name must be vice X OWERA defined within the COM Secret corresponding Unit Type in Fusion Unit parameters 0 value ASecretStoredInTh The actual value of the eDevice parameter This will be stored as a Unit Parameter Unit unitId 123456 Modelname The Unit Id 123456789012 11 5 addOrChangeUnit change use cases A Unit can be changed in many ways Add a Parameter Change a Parameter Delete a Parameter Change the Profile The only thing you cannot do with a Unit is to change it s connection to a Unit Type and you cannot change the Unit id If what you want is to move the Unit to a new Unit Type you will need to delete the Unit all together and add it into the new Unit Type To actually change the Unit id delete the Unit and add a new Unit 12 5 1 use case 2 change a Unit known Unit id When you change a unit you usually know the Unit id The Unit id is a universal key in Fusion so in this case you don t need any more information to identify the Unit The profil
11. arches To specify a partial id value we use a mix of SOL and Regexp syntax to avoid trouble using in XML x 0 or more characters of any kind e _ 1 character of any kind An example search criteria is Joe which would hit on any string that starts with Joe You can mix the usage of and _ as you like Escape usage of such special SQL characters by using In other words the search criteria Joe will return all strings that match Joe exactly 7 1 6 The result set The service always returns an array of Units This array can be O or more long Each unit in the array contains a Unit id Serial Number Profile Unit Type and a set of parameters If you are somewhat familiar with Fusion you would know that both the Profile and the Unit Type contains parameters each of it s own kind But these parameters are not returned in this service The reason They would clutter the result set with too much useless or confusing information Thus both Unit Type and Profile are represented in the result set only by their names But there is more to be said about the Profile because there is an interesting principle about Profiles and Units A Profile parameter is inherited by the Units unless overridden by a Unit parameter This is important because many of the parameters that a Unit holds is not located on the Unit level but found on the Profile level To make it simple for the user of this interface we decided to return all paramet
12. ch Documentation updated 21 Sep 11 Renaming from xAPS to Fusion 1 3 2 M Simonsen 14 Dec 11 Updating to 2012R1 removed last chapter SSL tips 1 4 3 M Simonsen 04 Apr 12 Revised edition removed OPP references rewrote some passages added XML appendix improved chapter 3 General stuff 2013R1 01 Mar 13 Updated to latest version 1 4 Acronyms and Abbreviations Explanation Auto Configuration Server Automatic Provisioning System Fusion Owera s eXtensible APS with advanced features such as Service Windows Job Control and Smart Groups Fusion Module The Fusion consists of several independently running Modules The Modules may run on separate hosts in the network North Side Common term describing the part of the Fusion which includes all Fusion Modules that provide management interfaces South Side Common term describing the part of the Fusion which includes all Fusion Modules that provide CPE communication protocols Core Common term describing the part of the Fusion which includes all Fusion Modules that provide neither management interfaces nor CPE communication protocols CPE Customer Premises Equipment Used in this document to refer to a single physical device Same as the term Device Fusion Employee of a Hosting Provider managing network Administrator infrastructure Typically the person deploying configuring and running the Fusion Fusion Operator Employee of a Hosting Virtual Provider managing th
13. done Therefore we simply treat Serial Number as a Unique Value when it comes to searches so searching for Serial Number lt customer id gt will work quite all right as long as the customer id is actually set on the correct unit 3 5 Parameter A parameter is a tuple of information which specify a certain attribute or property of a device or the Fusion The allowed parameter names are defined within a Unit Type in Fusion and cannot be created from these services The only thing that you can do is to read and write actual values to from the various units Parameter description Comment Example Name A name which uniquely identifies this Parameter Device DeviceInfo SerialNumber The Parameter name must be defined on the Unit Type in Fusion before used in any of these services Value The value could be a string up till 1024 characters Hello World The characters could be of any kind expect very exotic Remember to URL encode if necessary all values will be URL decoded on the server side Flags The flags is information to tell the server how to use AC the Parameter but can also be used by the client The flags in use depends upon the service addOrChangeUnitRequest The flags can be either AC AddChange or D Delete If omitted AC is default addOrChangeUnittypeRequest The flags can be either AC AddChange or D Delete If omitted AC is default addOrChangeProfileRequest The flags can
14. e provisioned deployment of CPEs through the Fusion Web Interface Fusion Data How the Fusion determines which Parameter values and other Model changes to send to CPEs Implemented as a database schema with additional processing logic on top in the various Fusion Modules Parameter Each individual configuration setting is represented in the Fusion Data Model as a Parameter A Parameter consists of aname and usually but not always a value Unit A dataset in the Fusion database consisting of Parameter values relating to a single CPE This dataset may extend beyond the Parameter values actually sent to the CPE as some Parameter values may only be useful or needed by the Fusion itself Also the dataset may represent only a subset of all the configurable settings in the CPE For these reasons it is important to distinguish the term Unit from the terms CPE and Device Profile Dataset stored in the Fusion containing Parameter values shared by multiple Units of the same Unit Type A Unit is always assigned to a single profile Multiple Profiles may be created for a Unit Type Unit Type Units that represent CPEs of the same model share a common definition of that CPE model named Unit Type The Unit Type definition is a list of Parameter names only as the Unit Type never contains any Parameter values values are stored in the Unit and or Profile TR 069 Industry standard provisioning protocol used by the Fusion to read and w
15. e is changed by simply setting the name of the Profile to something other than the existing Profile However the new Profile value must be defined in Fusion refer to chapter 3 1 The Parameters can take on various flags values as described in chapter 3 4 If you decide to add a Parameter use AC in case of deletion use D Omitting the flags value will be interpreted as AC Naturally you can add as many parameters as you like __ Object C Example value Comment MN mn pees ii n Unit unitId dd37cbd4 d4a3 3d66 This unit must be present in 8958 sa9er3le3ars Fusion Unit unittype name NPA201E The Unit Type must be present in Fusion Unit profile name NotDefault We assume that the Unit was previously in Default Profile This value will move the Unit to NotDefault Profile Unit unitId dd37cbd4 d4a3 3d66 8958 5d9cf30635f5 13 5 2 use case 3 change a Unit unknown Unit id If you only know the Serial Number and not the Unit id and you know that this Serial Number uniquely identifies the Unit since it s a MAC address or something similar then you can use the Serial Number The Unit object has a special field for a Serial Number to be used just in this case refer to chapter 3 4 Changing the profile and parameters is like the previous use case New in 2011 Release 2 The serial number value can be any value that uniquely identifies the unit password ip address username etc Object Example
16. ers both Profile and Unit 17 parameters in the list of parameters for each Unit The flags will be set to either P or U to show from where the parameter was taken 7 1 7 Miscellaneous If a Profile name is specified Unit Type name must also be specified The Profile and Unit Type objects are made with lists of parameters check with WSDL but they are never used populated The intention is to be able to provide services in the future which focuses on these concepts without breaking the existing interface Whether that will succeed remains to be seen 18 7 2 use case 1 search for a single Unit known Unit id Object LEvample value Comment an n See mie ee dd37cbd4 d4a3 This unit should be present in 3466 8958 Fusion 5d9cf30635f5 i unitId dd37cbd4 d4a3 The Unit id 3d66 8958 5d9cf30635 5 i serialNumber 123456789012 The Unit s Serial Number M i unittype name NPA201E The Unit s Unit Type i parameter 0 Device VoiceServi A Unit parameter name ce 1 VoiceProfile 1 Line 1 SIP Aut hUserName j parame A Unit parameter value j parame i The flag indicated that this is a Unit Parameter i paramet AR Device DeviceIn A Unit parameter name fo SerialNumber parame 1 123456789012 A Unit parameter value parame LI U The flag indicated that this is a Unit Parameter moreUnits No more units found 19 7 3 use case 2 search for a Unit s
17. file __ Object Example value Comment Default he name of the profile Will return the profile object but will include all data from Fusion not only the data changed if this is a change request in this call 28 13 deleteProfile The deletion of a profile is relatively simple Just keep in mind that you may need to delete Groups and Permissions and Units associated with this particular Profile first Profile Parameters will be deleted automatically Object Example value Comment Username Password Unittype name MobilePhone The name of the unittype Default The name of the profile isDeleted true Will return false if the delete operation in SQL did not return 1 row deleted 29 14 getProfiles getProfile will return all the Profile you are allowed to see If you specify a particular Profile you will only receive that one Object Example value Comment name of the unittype tServer URL parameter 0 Profile parameters 0 value http xaps com The value of th tr069 parameter 0 Profile parameters name Device Managemen Th 30 15 Redirection Troubleshooting The Fusion WS Server offers a redirection feature This is mostly meant for troubleshooting but could probably be useful in other cases as well The whole idea with redirecting is to be able to catch the XML to from the server and store it to a file This is important since the XML is often los
18. gs gt lt item gt lt item gt lt name gt System X_OWERA COM Device MAC lt name gt lt value gt 012345678902 lt value gt lt item gt lt parameterArray gt lt parameters gt lt unit gt lt AddOrChangeUnitRequest gt lt soapenv Body gt lt soapenv Envelope gt 16 3Search using unit id chapter 7 2 lt xml version 1 0 encoding UTF 8 gt lt soapenv Envelope xmlns soapenv http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt 33 lt soapenv Body gt lt GetUnitsRequest xmins http xapsws owera com gt lt login xmlns gt lt username gt user lt username gt lt password gt pass lt password gt lt login gt lt unit xmins gt lt unitId gt 002194 NPA201E 012345678901 lt unitId gt lt unit gt lt GetUnitsReguest gt lt soapenv Body gt lt soapenv Envelope gt 16 4Search using unigue value chapter 7 3 lt xml version 1 0 encoding UTF 8 gt lt soapenv Envelope xmlns soapenv http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt lt soapenv Body gt lt GetUnitsReguest xmins http xapsws owera com gt lt login xmlns gt lt username gt user lt username gt lt password gt pass lt password gt lt login gt lt unit xmins gt lt serialNumber gt ohHAII lt serialNumber gt
19. n false 15 7 getUnits 7 1 Introduction TMTOWTDI There s more than one way to do it or pronounced Tim Toady is a famous Perl slogan This slogan fits this service well There is a few limitations to the service but otherwise it s almost like anything you put into it will result in O or more Units 7 1 1 Searching for one single Unit You can retrieve information about a single Unit using one out these methods UnitId search Search for a single Unit using complete Unit id UniqueValue search Search for a single Unit using complete Serial Number or any other unique value for a unit 7 1 2 Searching for many Units The second group of searches are those which are expected to return O or more Units You can use one of these methods or combine the methods freely Simple search Search for many Units using Unit Type and or Profile Value search Search for many Units using partial Unit id or a partial value Parameter search Search for many Units using Parameters Specify search with one out of six kinds of operators specify as flags EQ Equals default NE Not Equals LT Less Than LE Less or Equals GE Greater or Equals GT Greater Than A parameter value can be of partial type see chapter 7 1 5 but only EQ and NE operators apply to partial values A parameter value can be NULL to symbolize the absence of this parameter A parameter can be interpreted as a special type specify as flags TEXT default NUMBE
20. name gt lt value gt freyrsSipUsername lt value gt lt flags gt AC lt flags gt lt item gt lt item gt lt name gt System X OWERA COM Secret lt name gt lt value gt 0123456789012345 lt value gt lt item gt lt parameterArray gt lt parameters gt lt unit gt lt AddOrChangeUnitReguest gt lt soapenv Body gt lt soapenv Envelope gt 32 16 2Change unit chapter 5 2 lt xml version 1 0 encoding UTF 8 gt lt soapenv Envelope xmlns soapenv http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt lt soapenv Body gt lt AddOrChangeUnitRequest xmlns http xapsws owera com gt lt login xmlns gt lt username gt user lt username gt lt password gt pass lt password gt lt login gt lt unit xmins gt lt serialNumber gt 012345678902 lt serialNumber gt lt profile gt lt name gt Default lt name gt lt profile gt lt unittype gt lt name gt NPA201E lt name gt lt unittype gt lt parameters gt lt parameterArray gt lt item gt lt name gt InternetGatewayDevice Services VoiceService 1 VoiceProfile 1 Line 1 SIP AuthPa ssword lt name gt lt value gt freyrsSipPassword lt value gt lt item gt lt item gt lt name gt InternetGatewayDevice Services VoiceService 1 VoiceProfile 1 Line 1 SIP AuthUs erName lt name gt lt value gt freyrsSipUsername lt value gt lt flags gt AC lt fla
21. on about add change delete Units or Unit Parameter 3 General stuff All the services are fairly equal when it comes to input to them Instead of repeating a lot throughout each section we ll gather information in this chapter that is considered recommended knowledge for all services 3 1 Login To access the services a login is reguired Logins are managed and created using Fusion Web or Fusion Shell The only user available at startup before any users are created is admin with the password xaps and this user will always have access to all parts of the system We expect the administrators of Fusion to change the admin password You can transmit the password in cleartext or as a digest using SHA 1 Using this last option and SSL should give you a secure service For each login there is set of permissions These permissions restrict which Unit Types and Profiles you can access The reason behind this schema is to able to offer a container feature of Fusion so that some users can access Unit Type A and B while others can access Unit Type C and D 3 2 Unit Type Profile A Unit Type and a Profile are concepts in Fusion to contain Units A Unit is always located within one and only one Profile and one Profile is located within one and only one Unit Type Many services reguire that the Unit Type and Profile are stated explicitly This may seem to be in conflict with the Login permissions since a Login implicitly also refers to Unit
22. ping communication Fusion Web Services User Manual 2013R1 2007 2012 Ping Communication Ping Communication Restricted 1 March 2013 Table of Contents 1 Document Introduction N l Bee EEE 1 1 Document EEE clan LME SL A E DA net ie as 1 2 DE Ment E GLS ri ren ar re ke ee 1 3 Document History a SIIKI WE 14 Acronyms and Abbreviations eer Konna S n n ET ET EE 3 General stuff 3 1 Login e 3 2 Unit Type Profile 3 3 Unit Id S ai 3 4 vin Number A unigue REINE een 4 addOrChangeUnit add use Basen en TI 4 1 use case 1 add Unit known Unit id secret EEE 5 addOrChangeUnit change use cases er EN 5 1 use case 2 change a Unit known Unit id ee esse tee 5 2 use case 3 change a Unit unknown Unit id Bass BEE N 6 deleteUnit 6 1 use case 1 delete a Unit known Unit id le 6 2 use case 2 delete a Unit unknown Unit id NT DEN VOTE Ae F CUES s masa ernennen 7 1 Introduction EE 21 1 Searching for one e single Unit ERN PER N EE E 7 1 2 Searching for ns Units wits are ai n aa mtn PIETINI L 7 1 3 Preference KaKa K ELN 7 1 4 Return Le SRE Re 7 7 1 5 Partial searche scies 7 1 6 The result set ee FIT Miscellaneous EE E 7 2 use case 1 search for a single Unit known Unit id 3 7 3 use case 2 ch for a Unit s using a parameter value 7 4 use case 3 ch for many Units using various criteria
23. rite configurations from and to the CPEs in addition to handle upgrades 2 Introduction Fusion Web Services is part of the North Side of Fusion and its sole purpose is to be a integration interface for other customer specific systems like a BSS or OSS or something else Fusion Web Services interface is designed with emphasis on a re usable object model Upon building a Web Service Client you will get the object model from the WSDL and it will be fairly compact The flip side of this re usability is that the content of each object in the services must be carefully documented hence this documentation So far there are nine services in this interface addOrChangeUnit deleteUnit getUnits addOrChangeUnittype deleteUnittype getUnittype addOrChangeProfile deleteProfile getProfile For most operators user only the first three methods are of interest The methods allows you to add or change a unit as well as the unit parameters Deletion of parameters is possible within the addOrChange service The addOrChangeUnit method is by far the most important when it comes to basic integration with another system The delete service is not crucial but there can perhaps be situations where you would like to control the existence of units from another system The last service is somewhat more important as it gives a possibility to get information about one or more units This information could then form the basis for a decisi
24. s already been described but the Secret has not since it s something that only matters if you re going to add a unit Without the secret there will be no communication between the device and Fusion and hence no provisioning since the communication is not secured The secret can be an alphanumerical string of any reasonable length It is important to understand that the secret that is added to Fusion using this service must match the secret that already exists in the device There is no room for generating a secret into Fusion but it must come from a file from the device factory Protocol Parameter name Example TR 069 lt Keyroot gt X OWERA COM Secret ASecretStoredInTheDevic HTTP TF lt Keyroot gt X OWERA COM Secret ASecretStoredInTheDevic TP With this two pieces of information in place the Fusion is ready to establish contact with the devices As already mentioned a Serial Number can be very useful as well so if that is an alternative add the Serial Number as a parameter 10 4 1 use case 1 add Unit known Unit id secret This is the use case where you have received a so called lot file with MAC addresses secrets and above all Unit ids A typical scenario would be that you make a registration page for your customers they supply the MAC address found on their device into the web page then the registration server checks with the Taiwan file and finds the Unit id and the secret You c
25. sure check the isDeleted flag in the output Object Example value Comment unittypeName MobilePhone The name of the unittype isDeleted true Will return false if the delete operation in SQL did not return 1 row deleted 26 11 getUnittypes getUnittypes will return all the Unit Types you are allowed to see If you specify a particular Unit Type you will only receive that one __ Object Example value Comment Username Login password Password Unittype name MobilePhone The name of the unittype Unittype matcherId 000000 The matcherId may be important if protocol is OPP Check with Owera in this case to set it correctly Unittype vendor Nokia The manufacturer of the phone Unittype protocol Can be TR 069 OPP or N A This decision will impact on which format is accepted in the unitIds within this unittype Unittype parameters 0 nam Device DeviceInf The name of the unittype o SerialNumber parameter Unittype parameters 0 value SAR The flag of the unittype parameter Must be R RW or X Additionally allowed S Serachable D Displayable in Fusion Web I Inspection A Always Read C Confidential 27 12 addOrChangeProfile Profile is a rather simple concept only requiring a name The ability to set common parameter values for all units within a profile is the most interesting aspect of a Profile Some may also find it useful to restrict permissions to a specific Pro
26. t when working with Web Service framework Comparing various XML output can be effective to pinpoint where things went wrong The URL to use for WS clients is http lt host gt lt port gt xapsws redirect The XML will be logged to xaps ws xml log or if otherwise configured in xaps ws logs properties Make sure to configure the correct URL to redirect to the FusionWS service in xaps ws properties 31 16 Appendix 16 1Add Change unit chapter 4 1 5 1 lt xml version 1 0 encoding UTF 8 gt lt soapenv Envelope xmlns soapenv http schemas xmlsoap org soap envelope xmlns xsd http www w3 org 2001 XMLSchema xmlns xsi http www w3 org 2001 XMLSchema instance gt lt soapenv Body gt lt AddOrChangeUnitRequest xmlns http xapsws owera com gt lt login xmlns gt lt username gt user lt username gt lt password gt pass lt password gt lt login gt lt unit xmins gt lt unitId gt 000000 TRO69TestClient 000000000001 lt unitId gt lt profile gt lt name gt Default lt name gt lt profile gt lt unittype gt lt name gt NPA201E lt name gt lt unittype gt lt parameters gt lt parameterArray gt lt item gt lt name gt InternetGatewayDevice Services VoiceService 1 VoiceProfile 1 Line 1 SIP AuthPa ssword lt name gt lt value gt freyrsSipPassword lt value gt lt item gt lt item gt lt name gt InternetGatewayDevice Services VoiceService 1 VoiceProfile 1 Line 1 SIP AuthUs erName lt
27. using a parameter value New for 2011 Release 2 The serialNumber does not really have to be a serialNumber Any unit parameter value will do e g ip adress mac address username etc If Unit Type name is omitted the search will be performed among all Unit Types If the serial number value supplied is not unique or even a partial value containing or _ the result may be more than 1 unit up until 50 However the response will contain the serial number if it exists in the same field This is done to avoid breaking the interface of the service Object Examplevalue Comment serialNumber 123456789012 Use any kind of unique value ip address mac address username password serialnumber 5 dd37cbd4 d4a3 The Unit id 3d66 8958 5d9cf30635f5 i serialNumber 123456789012 The Unit s Serial Number Bu unittype name NPA201E The Unit s Unit Type parameter Device VoiceServi A Unit parameter name ce 1 VoiceProfile 1 Line 1 SIP Aut hUserName parame e SIPUser A Unit parameter value paramet U The flag indicated that this is a Unit Parameter paramet A Device DeviceIn A Unit parameter name fo SerialNumber parame 123456789012 A Unit parameter value 20 Unit 0 parameter 1 flags The flag indicated that this is a Unit Parameter moreUnits No more units found 21 7 4 use case 3 search for many Units using various criteri
28. y time the these methods are subject to change This is not to say changes will happen freguently but it is unlikely that we ll be able to keep all these interfaces stable over years If you create a unittype using a login which is not an admin user the unittype will be created Obj ject Example value Comment LEE Login password ra xaps Password Unittype name MobilePhone The name of the unittype Unittype vendor Nokia The manufacturer of the phone Unittype protocol Can be TR 069 OPP or N A This decision will impact on which format is accepted in the unitIds within this unittype Will return the unittype object but will include all data from Fusion not only the data changed if this is a change request in this call 25 10 deleteUnittype The deletion of a Unit Type is intentionally difficult A Unit Type is the most basic concept in Fusion and many other concepts derive depend upon Unit Type So before a Unit Type can be deleted all other dependcies must be deleted Some things are deleted automatically by this service like Syslog Events Groups and Unit Type Parameters However Softwares Jobs and Permissions will not be deleted automatically these must be deleted via Fusion Shell or Fusion Web Profiles and Units must also be deleted separately but that can be done using these services The service is relatively simple to use If deletion fails it will usually return a SoapFault but to be 100
Download Pdf Manuals
Related Search