Saturday, July 20, 2013

First steps with the Java UCI API to access a starface PBX

In my last Starface related blog post i have shown how to configure the UCI API of the starface PBX in eclipse. Today i want to show you how to use the API to access data and functions in the starface PBX.

The first step to access data on the starface PBX is to create an UciProxy Object. The proxy object manages the connection to the PBX in the background. The proxy object is really handy, because it reestablish the connection automatically in the background if the connection to the PBX has been lost. The proxy object can use different transport methods to access the PBX. Here is an example for a connection without callback over HTTP.


   //Create a Ucpransportfactory to access the starface PBX over the HTTP protocol.
   UcpTransportFactory ucpTransportFactory = new HttpUcpTransportFactory("YOURSTARFACE", 80, false);
   //Create a UciProxyFactory with the above created Transportfactory.
   UciProxyFactory uciProxyFactory = UciProxyFactory.createWithTransportFactory(ucpTransportFactory);
   //Create a proxy with the given credentials
   uciProxy = uciProxyFactory.createUciProxy("0001", "PASSWORD");
   //Establish the connection to the starface PBX
   uciProxy.connect();

Please replace "YOURSTARFACE", "0001" and "PASSWORD" with the host name, your user id and your password.

The next step is to create a so called  "Request Object". Every access able function in the starface PBX is handled by this objects. Here is a list of all Request Objects and their use:

Request Object Use
UciCallListRequests Get and manipulate the call list
UciCallRequests start and end telephone calls or get the state of your telephone
UciFaxListRequests Get and manipulate the list of your faxes or get the transmission report of a fax.
UciFaxRequests Send new Faxes
UciFunctionKeyRequests Get manipulate and press the function keys of your telephone
UciGroupRequests Get and set Group settings
UciPhoneRequests Manage your phones or set your primary phone
UciRedirectRequests Change the redirect settings of your telephones
UciUserStateRequests Get and set your avatar and manipulate your presence awareness status.
UciVoicemailListRequests Get and manipulate the list of your voice mails

And here is the code to access your call list and write all inbound calls to the console.

   // Get a CallListRequest Object to access the calllist
   UciCallListRequests requests = uciProxy.getRequests(UciCallListRequests.class);
   // Get the inbound calllist for the lastday with no group calls,
   // ordered by startTime Ascending. If there are more then 1000
   // entries only the the first 1000 will be retrieved.
   CallList callList = requests.getCallList(new Date(), new Date(new Date().getTime() - 86400000),
     CallListEntryDirection.INBOUND, null, GroupRestriction.NON_GROUP,
     CallListEntryProperties.startTime, OrderDirection.ASCENDING, 0, 1000);
   // Create date and timeformater
   DateFormat df = SimpleDateFormat.getDateInstance();
   DateFormat tf = SimpleDateFormat.getTimeInstance();
   // Iterate through the callist entries and print every entry to
   // standard out.
   for (CallListEntry entry : callList.getEntries()) {
    System.out.println(entry.getId() + "/" + entry.getCalledNumber() + "/" + entry.getCallerNumber() + "/"
      + df.format(entry.getStartTime()) + " " + tf.format(entry.getStartTime()) + "/"
      + entry.getDuration());
   }

So you can see that the UCI API is very easy to use and with only a few lines of code you can access many information's in your PBX which are normally only available in the web interface. In the next post in the starface series i will show you how to get notifications about events occurring in the PBX. So stay tuned.

7 comments:

  1. Hallo,

    mir gefällt ihr Blog gut, jedoch habe ich zu diesem Beitrag eine Frage. Sobald ich das soweit anwende und versuche die Anruferliste auszugeben, wird nichts zurück gegeben, bzw. in der Console steht nur

    DEBUG Incoming RPC return value: {countOffset=0, orderDirection="ASCENDING", countLimit=500, resultRestriction="", totalCount=0, startAfter=Mon Sep 30 11:11:24 CEST 2013, groupRestriction="NON_GROUP", entries=[], startBefore=Thu Oct 10 11:11:24 CEST 2013, orderProperty="startTime", directionRestriction=""} from [...]

    totalCount=0 heißt für mich, dass es keine Rückgabewerte gibt, aber in diesem Zeitraum sind auf jeden Fall Telefonate getätigt worden. Wissen Sie hier weiter?

    Danke & Grüße
    Christian

    ReplyDelete
    Replies
    1. Okay, habe es jetzt geschafft, indem das Datum von 1970 bis heute genommen wird. Dabei erhalte ich 9 von ca. 13.000 Ergebnisse. Gibt es eine die Personen auf "alle" zu beschränken, statt nur eine Gruppenbeschränkung durchzuführen? Über die Weboberfläche kann ich mir alle anzeigen lassen, jedoch über den direkten Java UCI Zugriff nur 9.

      Delete
  2. Hallo!

    Bist du sicher, dass du den richtighen Datumsbereich verwendest. Bei mir funktioniert das nämlich einwandfrei. Kannst du den Debug Sending RPC Request posten?

    ReplyDelete
    Replies
    1. Hallo,

      DEBUG Sending RPC request: ucp.v22.requests.callList.getCallList(Fri Oct 11 13:23:00 CEST 2013, Thu Jan 01 01:00:02 CET 1970, "", "", "", "startTime", "ASCENDING", 0, 1000) to http:// ...

      Ich habe parallel dazu auch den Starface Democlienten getestet (starface-uci-democlient-java-2.2.0) und alle Einschränkungen durchprobiert doch komme immer nur auf maximal 9 Einträge. Mit der Weboberfläche hingegen funktioniert es aber tadellos.

      Alles was ich eigentlich möchte ist nur mit einem Klick die Verbindungsdaten zu exportieren und in Excel weiterverarbeiten ohne täglich das Web-Interface zu öffnen was einiges mehr an Zeit kostet.

      Weißt du, ob es noch eine andere Möglichkeit gibt, wie z.B. per MySQL direkt auf die Datenbank zuzugreifen?

      Danke vorab für die Antwort.

      Delete
  3. Dein Request sieht soweit richtig aus. Eine Frage, du weißt aber schon, dass du über diese API Methode nur die Anruferliste deines Benutzers bekommst. Um eine vollständige Anruferliste zu bekommen, müsstest du dich mit allen Benutzern anmelden und für jeden Benutzer die Daten exportieren.

    ReplyDelete
  4. Das wusste ich bisher nicht. Bin ich auch nicht von ausgegangen, da ich im Webinterface auch alle Daten über meine Benutzerkennung erhalte. Vielen Dank für die Aufklärung.

    ReplyDelete
  5. Hello,

    is it possible to connect using https port 443 instead of 80? How to make a call to https://???/xml-rpc?

    Thank you,
    Martin

    UcpTransportFactory ucpTransportFactory;
    ucpTransportFactory = new HttpUcpTransportFactory(Inet4Address.getLocalHost().getHostAddress(), 8181, SERVER_HOST, 443, false, null, null);
    final UciProxyFactory uciProxyFactory = UciProxyFactory.createWithTransportFactory(ucpTransportFactory);
    uciProxy = uciProxyFactory.createUciProxy(UCI_LOGIN_ID, UCI_PASSWORD);
    uciProxy.connect();

    Trace log:

    14:45:44,544 DEBUG openTransportAndAttach: Connecting to UCP server...
    14:45:44,613 DEBUG Sending RPC request: ucp.v30.requests.connection.login() to http://8x.xxx.xxx.x4:443/xml-rpc...
    14:45:44,772 DEBUG Could not send XML-RPC call over HTTP
    org.apache.commons.httpclient.ProtocolException: The server 8x.xxx.xxx.x4 failed to respond with a valid HTTP response
    at org.apache.commons.httpclient.HttpMethodBase.readStatusLine(HttpMethodBase.java:1987)

    14:45:44,777 ERROR onConnectionFailed: Connecting to UCP server failed.
    de.starface.integration.uci.v30.client.UcpConnectionFailedException: Failure during xml-rpc call.
    at de.starface.integration.uci.v30.client.impl.UcpConnectionManager.attach(UcpConnectionManager.java:366)

    Caused by: de.starface.com.rpc.RpcException: Could not send XML-RPC call over http
    at de.starface.com.rpc.xmlrpc.http.HttpXmlRpcOutgoingRequestProcessor.processRequest(HttpXmlRpcOutgoingRequestProcessor.java:155)

    ReplyDelete

ad