Java Web Service API Application Samples

The following Java samples illustrate how to use Version 2.0 of the Aculab Cloud Web Services API to invoke your outbound services and to manage your media files on the cloud.

All of the samples are thin application wrappers around functionality that is provided in a Common class library. This implements the web service requests and unwraps the JSON format responses.

Please note that in the interests of clarity these samples are short on the kind of error handling and diagnostic aspects that would typically be required in a live environment.

The Web Service API is documented here.

  • Where to Find Them
They are included in the Java UAS download package and located in <UAS install folder>\Samples\WSApplications.

Pre-built versions of all of these samples are provided in <UAS install folder>\Samples\WSApplications\bin.

  • How to Build Them
Each sample contains eclipse .project and .classpath files and an Ant build script file (build.xml). All the samples depend on the common.jar library for which the source is also provided.


  • How to Run Them
These samples are all console applications. Some require command line parameters to be supplied. Those that do describe the expected parameters below each sample description.

Samples that are designed to invoke an outbound service require that service to be registered with the cloud from Outbound Services.

Invoke an Outbound Service

A command line console application that simply invokes an outbound service that is currently registered on a cloud.
This application takes a number of command line options:

java -jar InvokeOutboundService.jar <cloudId> <cloudUsername> <outboundService> <outboundServicePassword>
[<outboundParameters> [<count>]] | [outboundParametersFilename];

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername = cloud account username
  • outboundService = the outbound service to invoke
  • outboundServicePassword = the outbound service password

    • followed by either:
  • outboundParameters = a single outbound parameters string that will be passed to the application followed optionally by
  • [count] = the number of invocations to make, all with the specified outboundParameters
    • or
  • outboundParametersFilename = the name of a file containing 1 or more outboundParameter strings, comma-separated
Note: outboundParameters, whether defined on the command line or in a file, must not contain characters carriage return, line feed or ^. Also, parameters defined in a file are not trimmed of leading and trailing spaces.

Note: a comma-separated file containing the application instance ids of the invoked services is written when they have all completed ("appInstances.csv").

Note: multiple call invocations are only supported on standard production cloud accounts or above.


e.g. java -jar InvokeOutboundService.jar 0-2-0 bob@acompany.com MyOutboundService 54321 sip:bill@bcompany.com 5

Invokes service MyOutboundService (with password 54321) 5 times
on cloud region 0-2-0 on account bob@acompany.com
and passes each invocation the outbound parameters: sip:bill@bcompany.com


e.g. java -jar InvokeOutboundService.jar 0-2-0 bob@acompany.com MyOutboundService 54321 outParams.csv

outParams.csv file contents:
    sip:bill@bcompany.com,sip:ben@bcompany.com,sip:lw@bcompany.com

Invokes service MyOutboundService (with password 54321) three times
on cloud region 0-2-0 on account bob@acompany.com
and passes each invocation one of the sip addresses from the outParams.csv file.



Get an Application Instance Result

A command line console application to query the cloud for the result of a UAS application instance, either inbound or outbound.

This application takes a number of command line options:

jav -jar GetApplicationInstanceResult.jar <cloudId> <cloudUsername:password> <applicationInstanceId> | <applicationInstanceIdsFileName>

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername:password = cloud account username and password

    • followed by either
  • applicationInstanceId = the unique id relating to a single invocation of an outbound or inbound application (e.g. 01f92d482e33a4ce.375315)
    • or
  • applicationInstanceIdsFileName = the name of a file containing 1 or more application instance id strings, comma-separated

e.g. java -jar GetApplicationInstanceResult.jar 0-2-0 bob@acompany.com:bobsPword 01f92d482e33a4ce.375315

This retrieves the application result from cloud region 0-2-0 on account
bob@acompany.com:bobsPword for application instance 01f92d482e33a4ce.375315.


e.g. java -jar GetApplicationInstanceResult.jar 0-2-0 bob@acompany.com:bobsPword appInstances.csv

appInstance.csv file contents:
    040880762e891fab.798,040880762e891fab.799,0408804b36f73ef5.809

This retrieves the application results from cloud region 0-2-0
on account bob@acompany.com:bobsPword
for all three application instances specified.

An applicationInstanceId can be obtained from a number of sources:
Note that there can be a delay of several seconds before the result data for a particular application instance becomes available on the cloud.



Manage Large Conferences

A command line console application that manages reservations on a specified cloud region for large conferences (see Conferencing Capabilities) using a specified account on that cloud.

Once the reservation has been made successfully, then, after the specified start time and for the duration specified, calls may be made to the conferenceRoom e.g. using the AddToConference UASApplication sample (specifying the conferenceRoom as a 4-digit pin).

This application takes a number of command line options:

java -jar ManageLargeConferences.jar <cloudId> <cloudUsername:password> <command>

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername:password= cloud account username:password
  • command= one of the following:
    • reserve
    • list
    • remove
    • extend
command arguments:
  • reserve conferenceRoom numberOfParties [startTime [minutesDuration]]
    where:
    • conferenceRoom = a conference room name consisting of alphanumeric characters only and must be unique on the chosen cloud
    • numberOfParties = the maximum number of parties to reserve for this conference. See Conferencing Capabilities for the allowable range.
    • startTime = the earliest start time of the conference (UTC) expressed as yyyy-MM-dd_HH:mm.
      (e.g. 2011-11-10_09:30 for 10th Nov 2011 09:30)
      This must be at least 5 minutes and at most 24 hours away.
      The conference can only be started after this time.
      (default 20 mins from now)
    • minutesDuration = the maximum duration of the conference in minutes
      (default 20 mins, allowable range 15-480)
  • list
    takes no arguments...
  • remove conferenceRoom
    where:
    • conferenceRoom = the name of the conference room to remove.
  • extend conferenceRoom additionalMinutes
    where:
    • conferenceRoom = the name of the conference room to extend.
    • additionalMinutes = the number of minutes by which to extend the conference.
      (allowable range 15-60 minutes)
e.g. java -jar ReserveLargeConference.jar 0-2-0 bob@acompany.com:bobspword reserve MyLargeConf1 120 2013-11-10-09-30 20

reserves a 20 minute conference "MyLargeConf1" for 120 parties
for 09:30 on 10th Nov 2013
on cloud region 0-2-0 (account bob@acompany.com:bobspswd)



Manage Media Files

A command line console application that provides access to the media file management facilities of the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar ManageMediaFiles.jar <cloudId> <cloudUsername:password> <command>

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername:password = cloud account username and password
  • command = one of the following:
    • upload localFilename cloudFilename
    • download cloudFilename localFilename
    • list localFilename [filespecPrefix]
    • delete filespecPrefix
    • rename cloudFilename newCloudFilename
filespecPrefix is an optional argument to the list command and a reqired argument to delete that specifies a filename prefix and can accept a trailing '*' wildcard. This matches all files with the filespec as a prefix. Note that this effectively means the command is applied recursively through all subfolders.

e.g.
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword upload c:/test/acuwelcome.wav /wavs/newacuwelcome.wav

java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword download /wavs/newacuwelcome.wav c:/test/newacuwelcome.wav

java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list *
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec*
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec* 0 1000
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword list /wavs/rec* 1000 1000

java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete *
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete /*
java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword delete /rec*

java -jar ManageMediaFiles.jar 0-2-0 bob@acompany.com:bobsPword rename /wavs/old/acuwelcome.wav /wavs/newacuwelcome.wav



Manage Reports

A command line console application that provides access to the report management facilities of the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar ManageReports.jar <cloudId> <cloudUsername:password> <command>

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername:password = cloud account username and password
  • command = one of the following:
    • start content from [to]
    • list listtype
    • cancel reportname
    • download reportname localfilename
    • delete reportname
and:
  • content = adr | cdr | err | cwp | full
  • from/to = YYYY-MM-DD_HH:MM:SS
    (to is optional and defaults to current time if omitted)
  • listtype = inprogress | completed
  • reportname = the name of the report to cancel, download or delete
  • localfilename = path and filename for the downloaded file
Note: this sample requests reports in JSON format. The web service also supports the CSV format, but that is not implemented in this sample.

e.g.
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword start cdr 2012-06-28_00:00:00

java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword start cdr
    2012-06-28_00:00:00 2012-06-29_00:00:00

java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword list inprogress

java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword list completed

java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword cancel
    0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json
java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword download
    0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json
.\myReport.json

java -jar ManageReports.jar 0-2-0 bob@acompany.com:bobsPword delete
    0-2-0_bob@acompany.com_cdr-adm_2012-06-28_00:00:00_2012-07-29_00:00:00.json



Manage Telephone Numbers

A console application that provides access to the telephone number management facilities of the Aculab Cloud Web Services API. It allows one or more telephone numbers to be purchased and can be configured to create corresponding inbound services for each new number based on an existing service.

This application takes a number of command line options:

java -jar ManageTelephoneNumbers.jar <cloudId> <cloudUsername:password> <command>

where:
  • cloudId = cloud region id (e.g. 0-2-0)
  • cloudUsername:password = cloud account username and password
  • command = one of the following:
    • listcountries
    • liststates "country"
    • listregions "country[:state]"
    • listnumbers ["country[:state]" ["region"]]
    • listregaddresses
    • delete number | numbersFile
    • purchase "country[:state]" "region" [quantity [allowpartial [baseonservice ["regaddress"]]]]
    • purchasedev "country[:state]" "region" [quantity [allowpartial [baseonservice ["regaddress"]]]]
and:
  • country = one of the returned country strings.
  • state = one of the returned state strings.
  • region = one of the returned region strings.
  • quantity = the quantity of telephone numbers to purchase. Defaults to 1.
  • allowpartial = (true/false) determines whether the request succeeds even if the requested quantity of telephone numbers are not available. Defaults to false.
  • baseonservice = the name of an existing inbound service (including the "sip:" prefix). If set then a new service will be created for each new number purchased, based on the settings within this service.
  • regaddress = the name of a regulation address that exists on the cloud account being used. Some countries require a regulation address to be specified.
  • number = a single inbound telephone number.
  • numbersFile = the name of a file containing 1 or more telephone numbers, comma-separated.
e.g.

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listcountries

Output:
Israel, Georgia, Mexico, Lithuania, United Kingdom, Netherlands, Croatia, Greece, Switzerland, Dominican Republic, Brazil, Romania, Czech Republic, El Salvador, Poland, South Africa, Luxembourg, Sweden, Germany, Peru, Puerto Rico, Hungary, Norway, Spain, Canada, Italy, Finland, United States, Slovenia, Ireland, Argentina, Cyprus, Australia, Vietnam, France, New Zealand, Latvia, Slovakia, Chile, Belgium, Japan, Bulgaria

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword liststates "Canada"

Output:
Ontario, Newfoundland And Labrador, Saskatchewan, Prince Edward Island, British Columbia, Nova Scotia, Quebec, Alberta, Manitoba, New Brunswick

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregions "France"

Output:
Orleans, Lyon, Sarcelles, Dreux, Strasbourg, Lille, Paris, Enghien-Les-Bains, Saint-Malo, Bourges, Avignon, Saint-Germain-En-Laye, Calais, Beziers, Le Raincy, Toulon, Belfort, La Roche-Sur Yon, Dunkerque, Saint-Etienne, Pau, Troyes, Reims, Tulle, Creteil, Vesoul, Nimes, Nice, Le Mans, Carhaix-Plouguer, Cergy, Clermont-Ferrand, Versailles, Vannes, Colmar, Corse, Amiens, Grenoble, Meaux, Poitiers, Angers, Evreux, Beauvais, Saint-Nazaire, Nancy, Aix-En-Provence, Le Havre, Auray, Blois, Mulhouse, Perpignan, Moissac, Cannes, Bobigny, Rennes, Bordeaux, Marseille, Boulogne-Billancourt, Limoges, Nanterre, Toulouse, Montpellier, Metz, Cholet, Dijon, Chalon-Sur-Saone, Saint-Quentin, Montauban, Caen, Corbeil-Essones, Niort, Chambery, Tours, Besancon, Rouen, Laval, Charleville-Mezieres, Brest, Annecy, Nantes, Arles

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregions "United States:Michigan"

Output:
Utica, Pontiac, Auburn Heights, Roseville, Ann Arbor, Grand Rapids, Flint, Detroit Zone 04, Detroit Zone 06, Detroit Zone 01, Detroit Zone 02, Detroit Zone 03, Commerce, Port Huron, Belleville, Howell, Trenton, Battle Creek, Romulus, Center Line, Troy, Royal Oak, Birmingham

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers

Output:
7890123: Stockholm, Sweden 2012-03-04 $3.0
0123456: Dallas, Texas, United States 2012-03-04 $3.0

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers "Sweden" "Stockholm"

Output:
7890123: Stockholm, Sweden 2012-03-04 $3.0

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listnumbers "United States:Texas" "Dallas"

Output:
0123456: Dallas, Texas, United States 2012-03-04 $3.0

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword listregaddresses

Output:
My French Place: Paris, France
My German Hideout: Berlin, Germany

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword delete 7890123

Output:
7890123 deleted

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword delete numbersToDelete.csv

Output:
7890123: deleted
1010202: not deleted (0300: Telephone number 1010202 does not belong to you.
see https://cloud.aculab.com/documents/cnws_errors?error=0300 for more information)

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "United States" "Dallas"

Output:
19725877455

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "United States:Texas" "Dallas"

Output:
19725877456

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 2

Output:
Purchased 2 of 2 numbers:
33249880328
33249880410

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 2 true sip:MyExistingService

Output:
Purchased 2 of 2 numbers:
33249880540 Created service sip:33249880540
33249880631 Created service sip:33249880631

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Sweden" "Stockholm" 3 true sip:MyExistingService

Output:
Purchased 2 of 3 numbers:
33249880740 Created service sip:33249880740
33249880752 Created service sip:33249880752

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "France" "Nantes" 3 false sip:MyExistingService "My French Place"

Output:
Purchased 3 of 3 numbers:
33249880765 Created service sip:33249880765
33249880766 Created service sip:33249880766
33249880767 Created service sip:33249880767

java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com:bobsPword purchase "Germany" "Mönchengladbach" 1 false "" "MyGermanAddress"

Output:
Purchased 3 of 3 numbers:
45249880768
45249880769
45249880770



Wake Up Call

A console application that invokes an OutboundReminder service (that runs the OutboundReminder UAS application) to make an outbound call and play a wake up call media file that has been uploaded to the cloud.

This application has a properties file (wakeUpCall.properties) controls the address/number that is called and which media file to play etc.