Using PHP to Access Broadworks over SOAP

First off, this topic is embarrassingly under-documented. developer.broadsoft.com was of very little help.  This document was slightly helpful in its explanation regarding the session ID, JSESSIONID  and how a unique connection relates to them but other than that it wasn't much help.  To get this to work I had to download asocisoapclient_rel14.0, figure out how to get it work, then capture its transactions with a broadworks platform using wireshark, then mimic what it did in PHP.

The asoscisoapclient is a valuable tool when attempting to get OCI over SOAP to work. Once you go through the painful process of getting it to work, you can take a capture while its executing and look at the communication between it and the webserver. To get asoscisoapclient to work i had to:
  1. Update JRE to 1.6.x
  2. Make sure the JAVA_HOME environment variable is set to something like "C:\Program Files\Java\jre6" (quotes included). This can be set by right clicking on "My Computer"->Properties->Advanced->Environemnt Variables. Look under system variables and make sure it is there. If it is not, add it. From a command line you can check to make sure it has been set properly by typing echo %JAVA_HOME% and seeing the path displayed. That path must have the java "bin" folder in it.
  3. Download asoscisoapclient
  4. Unzip it
  5. Open asoci soapclient_rel14.0\ASOCISoapClient\ociclient.config
    1. set userId
    2. set password
    3. set url to be http://theserver/webservice/services/ProvisioningService
    4. set runMode = Single
    5. set singleInputFile = input.xml
    6. set singleOutputFile = response.xml
  6.  Open a comand prompt
    1. change directory to where you unzipped the download. cd "C:\Documents and Settings\WIN_USERNAME\My Documents\Downloads\asoci
      soapclient_rel14.0\ASOCISoapClient"
    2. execute startociclient.bat ociclient.config
    3. The program will not be able to authenticate because the request it uses to login (LoginRequest) is depreciated. The LoginRequest14sp4 should now be used. I didn't bother editing and recompiling their code to make this change because I was able to see what I needed to without doing so.
    4. The program will show use the OCI commands but not the SOAP headers.

Now open wireshark, start a capture and execute the program. You should see http/xml packets go across your screen. The important thing that I learned from this is:
  1. What the soap envelope looks like. (I just copied it.)
  2. That unlike the soap envelop, the OCI command must be html encoded.
  3. HTTP POSTs must be used
  4. The server is capable of using HTTP/1.1 even though the program uses HTTP/1.0 because the server responds using the HTTP/1.1 protocol (which is important because it allows for persistent connections)
  5. The SOAPAction: "" header must be defined
Finally, to replicate this in PHP I tried and confirmed that both PEAR's Http_Request class and PHP's extension php_curl.dll will do the trick. Http_Request seemed to be a little neater while curl seemed to be a bit more configurable. I've heard that Http_Request is just a wrapper for curl although I haven't confirmed that. The important thing to remember is to use Http/1.1. If you don't and plan on ...say.. retrieving 1192 user records, your connection will close in the middle of things and you'll get only about the first 30. Another important thing to remember is that all transactions have to be done across the same connection. Just because you have a valid Session ID and JSESSIONID doesn't mean that you can drop the connection and then open up another using the same Sesseion ID and JSESSIONID and pick up where you left off. I've read that a single Session ID and JSESSIONID are valid for hours, maybe even days, so it sounds like the trick is just keeping the connection open. Finally and most importantly understand this... OCI over SOAP is very strict and rigid. The ErrorResponses often times are not helpful and in my case were down right misleading. I kept getting a response that said "REQUEST_TIMEOUT – The OCS, or the Provisioning Server through the
OCS, did not respond in a timely manner; the service may have received a RequestTimeoutException" which according to the little documentation that exists told me to "Verify that the Provisioning Server is running and
Verify that the OCS is communicating with the Provisioning Server". This sent me on a diagnostic tangent wondering if PHP was using multiple HTTP connections during a single script execution, leaving my requests that weren't on the initial connection to timeout. The real problem turned out to be a misplaced "&" in the OCI command. Somewhere in the process of html encoding and decoding the requests it got added where it shouldn't have been and caused about 3 hours of unnecessary, discouraging pain.

I will post my PHP class for accessing the broadworks platform when I finish it up. You can email blake.mckeeby@gmail.com and I can see if I can help although I am definitely no pro at this sort of thing.

Note:
Apparently you can put more than one OCI request inside a SOAP envelope but I haven't tried this yet. It isn't recommended to put more than 15 OCI requests in a single envelope.

2 comments:

Anonymous said...

Did you ever get anywhere with this? Trying to pull information from the broadsoft to set indicators on our phones

Unknown said...

Thanks for sharing great article about broadsoft services.
Broadsoft Service Providers




Post a Comment