DEVELOPERS BLOG

Starter Guide for making Web Services calls to Good Control (GC)

webservices_gc_1

Good Control (GC) has web services API calls that let you administer the system as well as manage devices. Like BlackBerry Enterprise Server (BES), SOAP has been the default API, though a more recent REST API has been added. For this starter guide I will focus on the SOAP API calls, and I will use the popular SOAPUI app (https://www.soapui.org/) on my Windows desktop to show how you can connect and invoke API calls.

My goal is to be able to invoke a SOAP call, that brings up my user record on my GC.

Recipe Overview:

  • Download SoapUI (or use any SOAP compatible tool or plugin your like, there are lots for chrome/firefox etc).
  • Update SoapUI to use TLS 1.2 in order for it to connect to GC
  • Configure SoapUI project to point to your GC.

Downloading SoapUI

Download SOAPUI from https://www.soapui.org/.  I'm going to use the latest rev, 5.2.1.

Update SoapUI to use TLS 1.2

Once installed, you will need to update it to use TLS1.2 in order to connect to GC.

  • Download the unlimited strength JRE policy jars from Oracle here: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html
  • Go to the install location of SOAPUI, for me on 64bit Windows 8.1 it was: C:Program FilesSmartBearSoapUI-5.2.x
  • Edit using a text editor this file: C:Program FilesSmartBearSoapUI-5.2.xinsoapui.bat
  • Find the set JAVA_OPTS= string and add following parameters to the end of the line:
    -Dsoapui.https.protocols=TLSv1.2,TLSv1,TLSv1.1 -Dsoapui.https.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA256
  • Install the unlimited strength JRE policy jars you downloaded (ie: jce_policy-8.zip), by extracting the zip files, and replacing the similarly name files in SoapUI here: C:Program FilesSmartBearSoapUI-5.2.xjrelibsecurity

Now run SoapUI, and using the steps listed here in the Good public knowledge base.

http://goodpkb.force.com/PublicKnowledgeBase/articles/Answer/4027/?q=soapui&l=en_US&fs=Search&pn=1

  1. Next, open SoapUI and create a new project (File->New SoapUI Project). Give the project a name. For the initial WSDL, point it to the GD WSDL on the Good Control server(<GD install directory>docsgc.wsdl, e.g. c:gooddocsgc.wsdl).The SoapUI tool will create a project and operations based on those definited in gc.wsdl.
  2. Double-click the SoapUI project to bring up the project configuration.
  3. Select the WS-Security Configurations tab.
  4. In the WS-Security Configurations, select the Outgoing WS-Security Configurations tab.
  5. Click the '+' icon to add a new Outgoing WS-Security Configurations, then give the new config a name. Your new configuration should appear in the table.
  6. Underneath the table of Outgoing WS-Security configurations, click the '+' in the lower left-hand tab to create a new WSS entry.
  7. Choose "Username" from the dropdown list.
    webservices_gc_2
  8. In the username entry, add your GC username and password. Note: make sure you specify the domain in the format: domain\username . Make sure 'Add Nonce' and 'Add Created' are both checked.
  9. For Password Type, choose PasswordText from the list.
  10. Save the project to record your changes.
  11. In the project window, scroll down to the operation GetUser. Expand GetUser and double-click 'Request 1'.
  12. In the request window, select 'Authentication and Security-related settings' in the lower left (it may be represented as '…' based on the size of the window on the screen).
  13. Under Outgoing WSS, select the entry you added in step 10.
  14. In the xml view of the SOAP request, replace the '?' in <urn:stringId>?</urn:stringId> with the stringId (the exchange email address) of a GC user.
  15. In the drop down box at the top of the request window, choose [add new endpoint…] to add a new GC web services endpoint, e.g. https://<GC hostname>/gc/services/GCService. If you are testing on the GC server itself, you can specify https://localhost/gc/services/GCService. Select the new endpoint.
  16. Click the green submit button to send the SOAP request to the server.
  17. You should receive a SOAP response containing the corresponding user data for the stringId you sent as a parameter in the SOAP request.

Now that you have GetUser working, try out the others, adding the same authentication and connection URL.

For more information on GC web services start here pdf: https://community.good.com/docs/DOC-3604