Web Service Application Samples

Get an Application Instance Result


Sample Name: GetApplicationInstanceResult

A command line console application that provides access to application instance results using the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar GetApplicationInstanceResult.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <applicationInstanceId>|<applicationInstanceIdsFileName>

where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • 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
An applicationInstanceId can be obtained from a number of sources:
  • using the service_start and service_status web services (see the Start a REST Outbound Service sample)
  • using the report_start web service (see the Manage Reports sample)
  • using the Management Console ADRs page for the UAS on which the instance ran
Note: there can be a delay of several seconds before the result data for a particular application instance becomes available on the cloud.

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 (apiAccessKey=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 (apiAccessKey=bobsPword) for all three application instances specified.



Interrupt a REST API Application


Sample Name: InterruptRESTApplication

A command line console application to interrupt one or more REST application instances that are currently running on Aculab Cloud.

This application takes a number of command line options:

java -jar InterruptRESTApplication.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <applicationInstanceId>|<applicationInstanceIdsFileName> [redirectPage [redirectMethod]]

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • applicationInstanceId = the unique id relating to a single instance of an outbound or inbound REST application (e.g. 01f92d482e33a4ce.375315)
  • applicationInstanceIdsFileName = the name of a file containing 1 or more REST application instance ids, comma-separated
  • redirectPage = an optional page to which the application will be redirected by the interrupt. If no redirectPage is specified then following the interrupt the REST application will call the final page and end.
  • redirectMethod = the method used to access the redirectPage, GET or POST. Default is GET.

e.g.

java -jar InterruptRESTApplication.jar 0-2-0 bob@acompany.com bobsPword 01f92d482e33a4ce.375315

This interrupts the application instance 01f92d482e33a4ce.375315 on cloud 0-2-0 on account bob@acompany.com bobsPword


e.g.

java -jar InterruptRESTApplication.jar 0-2-0 bob@acompany.com bobsPword appInstances.csv

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

This interrupts the three specified REST application instances on cloud 0-2-0 on account bob@acompany.com bobsPword


e.g.

java -jar InterruptRESTApplication.jar 0-2-0 bob@acompany.com bobsPword 01f92d482e33a4ce.375315 http://rest.acompany.com/AppInterruptHandler.aspx

This interrupts the application instance 01f92d482e33a4ce.375315 on cloud 0-2-0 on account bob@acompany.com bobsPword. The application will be redirected to the specified page following the interrupt.



Lookup a Telephone Number


Sample Name: NumberLookup

A command line console application that provides access to the number lookup facility of the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar NumberLookup.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • check <phoneNumber>
where:
  • phoneNumber = the phone number to check, in international format.


e.g. To lookup a telephone number that exists:

    java -jar NumberLookup.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ check 17344124733

Output:

    Looking up 17344124733...

    Country: United States of America (US)
    Type: Landline
    Carrier: United States Cellular Corp. (U.S. Cellular)


e.g. To lookup a telephone number that does not exist:

    java -jar NumberLookup.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ check 441111111111

Output:

    Looking up 441111111111...

    Phone number not found


Manage Conferences


Sample Name: ManageConferences

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

This application takes a number of command line options:

java -jar ManageConferences.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • reserve <conferenceName> <maxParticipants> [<divertToService> [<startTime> [<minutesDuration>]]]
    • unreserve <reservationToken>|<conferenceName>
    • extend <reservationToken>|<conferenceName> <additionalMinutes>
    • listconferences [<conferenceType>]
    • listparticipants <conferenceName>
    • setparticipantoptions <conferenceName> <participantId> <mute> <enableDtmf>
    • ejectparticipant <conferenceName> <participantId>
where:
  • reservationToken = the reservation token as returned by the reserve command.
  • conferenceName = a conference name consisting of alphanumeric characters only and must be unique on the chosen cloud.
  • conferenceType = 'active' or 'reserved'.
  • participantId = the id of a conference participant as returned by the listParticipants command.
  • mute = 'true' or 't' to mute the participant. Any other value to unmute.
  • enableDtmf = 'true' or 't' to enable DTMF key actions for the participant. Any other value to disable DTMF actions.
  • maxParticipants = the maximum number of parties to reserve for a conference.
  • divertToService = the name of an inbound service on the cloud to which participants will be diverted when they call a conference before it has started. "" just busies the call (defaults to "").
  • startTime = the earliest start time of the conference (UTC) in the ISO 8601 format yyyy-mm-ddThh:mm:ss (e.g. 2019-02-13T11:22:02). The time is rounded down to the nearest minute. This must be at least 5 minutes and at most 24 hours away. The conference can only be started after this time. Default is 20 mins from now.
  • minutesDuration = the maximum duration of the conference in minutes Default is 20 mins, allowable range 15-480.
  • additionalMinutes = the number of minutes by which to extend the conference. Allowable range is 15-60 minutes.
Note: Output is sorted in ascending order by conference name or participant id.

Examples:

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd listconferences
java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd listconferences active
java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd listconferences reserved

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd listparticipants MyConf1

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd setparticipantoptions MyConf1 01234567a1b1c1c1.12345x0 true true

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd ejectparticipant MyConf1 01234567a1b1c1c1.12345x0

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd reserve MyConf1 60
java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd reserve MyConf2 60 null 2014-11-11T09:30:00 60
java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd reserve MyConf3 60 PlayHoldingMusic 2014-11-12T09:30:00

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd unreserve MyConf1

java -jar ManageConferences.jar 0-2-0 bob@acompany.com bobspswd extend MyConf1 20



Manage Files


Sample Name: ManageFiles

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

This application takes a number of command line options:

java -jar ManageFiles.jar [--wsserver <webServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • upload <fileType> <localFilename> <cloudFilename> [<encrypted> [<timeToLive> [<contentType>]]]
    • upload_multiple <fileType> <localFileList> <cloudFoldername> [<encrypted> [<timeToLive> [<contentType>]]]
    • download <fileType> <cloudFilename> <localFilename>
    • file_list | list <fileType> <cloudFileSpec> [<startAfter> [<count> [<from> [<to>]]]]
    • folder_list <fileType> <cloudFoldername> [<prefix> [<startAfter> [<count> [<from> [<to>]]]]]
    • delete <fileType> <cloudFileSpec> [<from> [<to>]]
    • rename <fileType> <cloudFilename> <newCloudFilename>

where:
  • fileType = the file type ("media", "rest" or "msg_media"). upload and rename only support "media" and "msg_media".
  • localFilename = the name of a file on the local file system.
  • cloudFilename = the name of a file on the cloud file store. For upload from a file listing this is a path on the cloud media file store where the files will be uploaded.
  • localFileList = the name of a file containing a list of names of one or more media files on the local file system, one per line.
  • cloudFoldername = a path to a folder on one of the cloud file stores.
  • prefix = a prefix that is to match any folders or files within a folder. This cannot contain '/' characters. If prefix is set to a single asterisk character or a single dot character, then all folders or files within a folder will be matched (the default).
  • newCloudFilename = the name of the renamed file on the cloud file store.
  • cloudFilespec = a specification of files on the chosen cloud file store. This can be either the name of a single file, a partial file path with a trailing asterisk, a single asterisk character or a single dot character. If cloudFileSpec is set to a partial file path with a trailing asterisk, this specifies all files that start with that file path. If cloudFileSpec is set to a single asterisk or a single dot character, then this specifies all files on the cloud file store.
  • encrypted = 'true' or 't' to specify that the file(s) being uploaded is encrypted (case-insensitive) or 'false' or 'f' for non-encrypted files. The default is 'false'.
  • timeToLive = the lifetime of the uploaded file(s). This is a time period expressed as a number followed by a units character - one of D or d for days, H or h for hours, M or m for minutes, or U for unlimited (e.g. 24H is 24hours).
  • contentType = the content type (also called the MIME type) of the uploaded file(s) (e.g. "image/jpeg"). If not specified this is derived from the filename extension. Set it here if it needs to be overridden. If specified for upload_multiple all the files must be the same type.
  • startAfter = if listing a large number of files, this specifies the last filename in the previous file list after which to list more files. It is the name of a file on the media, message media or rest logs cloud file store including path or "-" to list from the start. If specified this should be the filename from the previous list which has its startafter property set. If this is specified as an integer, it is used as the DEPRECATED startpos argument.
  • count = the maximum number of files to list. The default is 10000. The maximum this can be set to is 10000.
  • from = list/delete only files after the UTC date and time specified in the ISO 8601 format yyyy-mm-ddThh:mm:ss (e.g. 2019-02-13T11:22:02).
  • to = list/delete only files before the UTC date and time specified in the ISO 8601 format yyyy-mm-ddThh:mm:ss (e.g. 2019-02-13T11:23:02).
Note: When running this sample and supplying a single asterisk character as a command line argument, java.exe will attempt to replace the asterisk with a list of jar files located in your working directory. To stop this from happening, you can encapsulate the asterisk in quotes (e.g. "*"). Alternatively, certain parameters (e.g. cloudFileSpec and prefix) allow you to supply a single dot character instead.

Examples:

java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ upload media c:\test\welcome.wav /wavs/welcome.wav
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ upload msg_media c:\test\banner1.png /banners/banner1.png
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ upload media c:\test\encrypted\welcomeE.wav /wavs/encrypted/welcome.wav true
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ upload media c:\test\tempWelcome.wav /wavs/tempwelcome.wav f 16H
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ upload_multiple media "C:\test\my_uploads.txt" my_cloud_files/wavs/ true 30m

java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ download media /recordings/recording1.wav c:\test\recordings\recording1.wav
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ download mms_media /received/1423/1876278.png c:\test\1423\1876278.png
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ download rest /2019/02/07/rest_12_19_35_058d242936dcc5f9.47610.log c:\test\restapi\logs\2019_02_07\rest_12_19_35_058d242936dcc5f9.47610.log

java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media .
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media /recordings/*
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ folder_list msg_media recordings/
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media archive/* - 5
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media archive/* archive/rec119.wav 7
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media faxs/received/* - 5 2019-02-02T12:00:00
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list media /faxs/received/* - 10000 2019-02-02T12:00:00 2019-02-03T16:00:00
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ file_list rest /2019/02/*

java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete media /recordings/2019_01_03_19924.wav
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete media /recordings/*
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete media /recordings/* 2019-02-02T12:00:00 2019-02-03T16:00:00
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete rest /2019/02/07/rest_12_19_35_058d242936dcc5f9.47610.log
java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete rest /2019/02/*

java -jar ManageFiles.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ rename media /wavs/old/prompt1.wav /wavs/prompt1.wav



Manage SMS and MMS Messages


Sample Name: ManageMessages

A command line console application that provides access to the SMS and MMS facilities of the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar ManageMessages.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • sendsms|send <to>|<tosFileName> <from> <content> [<statusPage> [<requestDeliveryReport> [<alphanumericId>]]]
    • sendmms <to>|<tosFileName> <from> <msgMediaList> [<content> [<statusPage> [<requestDeliveryReport> [<alphanumericId>]]]]
    • status <messageId> [<messageId> ...]
    • cancel <messageId> [<messageId> ...]
    • blockedto <toNumber>
    • blockedfrom <fromNumber>
where:

  • to = the number of the phone to which the message will be sent. This must be a full international number without any leading +.
  • tosFileName = the name of a file containing 1 or more to strings, comma-separated.
  • from = the number from which the message will be sent. This must be one of your numbers. This must be a full international number without any leading +.
  • content = the textual content of your message. Required when sending SMS, optional when sending MMS.
  • msgMediaList = a comma separated list of message media files to include in the message.
  • statusPage = the URL of a web page to which message status updates will be sent. Default is "" meaning that no updates will be sent.
  • requestDeliveryReport = true or false. true to request a delivery report. Note that the carrier must support delivery reports otherwise the send will fail. Default is false.
  • messageId = the message ID to act on, as returned by the send command. More than one may be specified.
  • toNumber = a mobile number. The returned list will contain all your numbers which are blocked for sending to this number.
  • fromNumber = one of your numbers. The returned list will contain all mobile numbers which this number is blocked for sending to.
  • alphanumericId = the string to replace the from field with.

Note: a comma-separated file ("MessageRefs.csv") containing the message references of the sent message parts is written by the send command.

Examples:

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword sendsms 441098654321 441098123456 "A useful text message."

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword sendsms 441098654321 441098123456 "A useful text message." http://sms.acompany.com/InMessageHandler

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword sendsms 441098654321 441098123456 "A useful text message." http://sms.acompany.com/InMessageHandler true

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword sendsms targets.csv 441098123456 "A useful text message."


java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword sendmms 441098654321 441098654321 Aculab.png "A message with a logo."


java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword status 2e891aea_0.1366641192.77831

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword status 2e891aea_0.1366641192.77831 2e891aea_0.1366641192.77832 2e891aea_0.1366641192.77833


java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword cancel 2e891aea_0.1366641192.77831

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword cancel 2e891aea_0.1366641192.77831 2e891aea_0.1366641192.77832 2e891aea_0.1366641192.77833


java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword blockedto 441098654321

java -jar ManageMessages.jar 0-2-0 bob@acompany.com bobsPword blockedfrom 441098123456




Monitor Recordings


Sample Name: MonitorRecordings

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

This application takes a number of command line options:

java -jar MonitorRecordings.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>
where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • list <applicationInstanceId>
    • download <recording> <localfilename>
where:

  • applicationInstanceId = the id that identifies the application instance for which to retrieve a list of monitor recordings from the cloud.
  • recording = the name of the monitor recording file on the cloud.
  • localfilename = the path and filename for the downloaded file.


Examples:
java -jar MonitorRecordings.jar 0-2-0 bob@acompany.com bobsPword list 0123456789abcdef.12345

java -jar MonitorRecordings.jar 0-2-0 bob@acompany.com bobsPword download 2014-05-14/0123456789abcdef.12345.6543/150994965_NRCH_NORMAL(200).wav .\myRecording1.wav



Manage Reports


Sample Name: ManageReports

A 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 [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> command

where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region Id (e.g. 0-2-0 for EU-West, 1-2-0 for US-East)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • start <content> <from> [<to>]
    • list <listtype>
    • cancel <reportname>
    • download <reportname> <localfilename>
    • delete <reportname>
where:

  • content = adr | cdr | fdr | msg | err | csr
  • from/to = UTC date and time specified in the ISO 8601 format yyyy-mm-ddThh:mm:ss (e.g. 2019-02-13T11:22:02). to is optional and defaults to the current UTC time.
  • listtype = inprogress | completed
  • reportname = the name of the report to cancel, download or delete.
  • localfilename = path and filename for the downloaded file.
Note: Reports are generated as comma-separated value files.

Examples:

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

java -jar ManageReports.jar 0-2-0 bob@acompany.com bobsPword start cdr 2012-06-28T00:00:00 2012-06-29T00: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.csv

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.csv .\myReport.csv

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.csv



Manage Services


Sample Name: ManageServices

A console application that provides access to the Inbound Service Management, Outbound Service Management and Outbound Queue Management facilities of the Aculab Cloud Web Services API. This sample allows you to run a number of commands that give the ability to list, read, write, modify and delete service configurations; list and purge outbound service queues; and retrieve service configuration schemas. The final result of running a command successfully is written to stdout or (If the 'dstFilename' argument is set (Only applicable to the schema, read, write and modify commands)) saved to file. All other text is written to stderr.
This application takes a number of command line options:

java -jar ManageServices.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • list <direction>
    • schema <direction> [<dstFilename>]
    • read <direction> <serviceName> [<dstFilename>]
    • write <direction> <serviceName> <srcFilename> [<dstFilename>]
    • modify <direction> <serviceName> <srcFilename> [<dstFilename>]
    • delete <direction> <serviceName>
    • outbound_queues
    • outbound_queue_info <serviceName> [<servicePassword>]
    • outbound_purge_queue <serviceName> [<servicePassword>]
where:

  • direction = The direction of the service. Either 'inbound' or 'outbound'.
  • serviceName = The name of the service.
  • servicePassword = The service password found in the outbound service configuration. When set, the value supplied for the apiAccessKey is ignored and the cloud server will perform authentication using the service password instead.
  • srcFilename = The name of a file on the local file system containing a full or partial configuration of a service. The contents of the file must be JSON formatted. When running the 'write' command, this is the configuration that you want to create/replace your service with. When running the 'modify' command, this is the configuration that you want to modify your existing service with. When writing an inbound service, you can set this argument to "-" if you do not wish to specify a configuration file (Resulting in a service configuration being written with all its options set to default values).
  • dstFilename = The name of a file on the local file system to dump the service configuration schema (If using the schema command) or the configuration of a service (If using the read, write and modify commands). The contents of the file will be saved as JSON formatted data. If the file already exists, it will be overwritten. If omitted, the schema/configuration is written to stdout.


e.g.

List all inbound services:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ list inbound



e.g.

Retrieve an inbound schema and dump it to file:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ schema inbound C:\MyCloudServices\MyInboundSchema.json



e.g.

Retrieve an outbound schema and print it to stdout:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ schema outbound



e.g.

Read an outbound service configuration and dump it to file:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ read outbound MyOutboundService1 C:\MyCloudServices\MyOutboundService1.json



e.g.

Create an inbound service with all options set to default values and dump the new configuration to file:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ write inbound MyInboundService2 - C:\MyCloudServices\MyInboundService2.json



e.g.

Create an outbound service and dump the new configuration to file:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ write outbound MyOutboundService2 C:\MyCloudServices\MySimpleOutboundRestCfg.json C:\MyCloudServices\MyOutboundService2.json



e.g.

Modify an existing outbound service and dump the modified configuration to file:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ modify outbound MyOutboundService2 C:\MyCloudServices\MySimpleOutboundUASCfg.json C:\MyCloudServices\MyOutboundService2.json



e.g.

Delete an inbound service:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete inbound MyInboundService2



e.g.

Retrieve the queue information for all outbound services that have queued service starts:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ outbound_queues



e.g.

Retrieve the queue information for a specific outbound service:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ outbound_queue_info MyTestServiceE



e.g.

Purge the queue for a specific outbound service:

java -jar ManageServices.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ outbound_purge_queue MyTestServiceD



Manage Inbound Telephone Numbers


Sample Name: ManageTelephoneNumbers

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 [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region (e.g. 0-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • listcountries [<telNoType>]
    • liststates "<country>"
    • listregions "<country>[:<state>]" [<telNoType>]
    • listnumbers ["<country>[:<state>]" ["<region>" [<telNoType>]]]
    • listregaddresses
    • delete <number> | <numbersFile>
    • purchase "<country>[:<state>]" "<region>" [<quantity> [<allowpartial> [<baseonservice> ["<regaddress>" [<telNoType>]]]]]
    • purchasedev "<country>[:<state>]" "<region>" [<quantity> [<allowpartial> [<baseonservice> ["<regaddress>" [<telNoType>]]]]]
where:

  • telNoType = one of the telephone number types: geographic, national, mobile or tollfree.
  • 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
Examples:

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

Output:
Israel,Netherlands,Portugal,Mexico,United Kingdom,Colombia,Greece,Thailand, Dominican Republic,Brazil,Romania,Czech Republic,El Salvador,Poland,South Africa, Austria,Sweden,Germany,Peru,Puerto Rico,Hungary,Norway,Spain,Canada,Italy,New Zealand, Denmark,Finland,United States,Malaysia,Ireland,Argentina,Cyprus,Turkey,Australia,Slovenia, Panama,France,Bahrain,Slovakia,Chile,Belgium,Japan,South Korea,Bulgaria

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

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

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

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

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

Output:
Berrien Springs / 269,Beaverton / 989,Fulton / 269,Harrison / 989,Coloma / 269,Gagetown / 989,Rankin / 810,Milano / 734,Caseville / 989,Saginaw / 989,Clarkston / 248,Pinckney / 734,Detroit Zone 03 / 313,Ann Arbor / 734,Trufant / 616,Linden / 810,Imlay City / 810,Temperance / 734,Fenton / 810,Manistee / 231,Dexter / 734,Cadillac / 231,Elk Rapids / 231,Avoca / 810,Capac / 810,Plymouth / 734,Milford White Lake / 248,Davison / 810,Holly / 248,Alto / 616,Port Huron / 810,Romeo / 586,Lexington / 810,Mayville / 989,Detroit Zone 05 / 313,Bridgman / 269,Rockford / 616,Gladwin / 989,Detroit Zone 02 / 313,Yale / 810,Flushing / 810,Almont / 810,South Lyon / 248,Pontiac / 248,Wayland / 269,Trenton / 734,Fife Lake / 231,Clare / 989,Dutton / 616,Lake Orion / 248,Traverse City / 231,Grant / 231,Newaygo / 231,Williamsbg / 231,Cass City / 989,Holland / 616,Flat Rock / 734,Caledonia / 616,Auburn Heights / 248,Athens / 269,Saranac / 616,Hastings / 269,Plainwell / 269,Battle Creek / 269,New Boston / 734,Howell / 517,Detroit Zone 06 / 313,Rochester / 248,Kalkaska / 231,Gregory / 734,Washington / 586,Utica / 586,Greenville / 616,Richland / 269,Buchanan / 269,Ionia / 616,Warren / 586,Whitmore Lake / 734,Hartland / 810,Flint / 810,Bad Axe / 989,Armada / 586,Sebewaing / 989,Auburn / 989,Coleman / 989,Kingston / 989,Midland / 989,Ubly / 989,Northville / 248,Dryden / 810,Cheboygan / 231,Eau Claire / 269,Freeland / 989,Otsego / 269,Ada / 616,Clio Mount Morris / 810,Sparta / 616,Belding / 616,Ellsworth / 231,East Tawas / 989,Middleville / 269,Sawyer / 269,Commerce / 248,Reed City / 231,Dorr / 616,Applegate / 810,Jamestown / 616,Wayne / 734,Willis / 734,Grand Haven / 616,Southfield / 248,Birch Run / 989,Oscoda / 989,Bellevue / 269,Wolverine / 231,West Bloomfield / 248,Freeport / 616,Zeeland / 616,Otisville / 810,Erie / 734,Mount Clemens / 586,Alden / 231,Beulah / 231,Chelsea / 734,Standish / 989,Byron Center / 616,Jeddo / 810,Birmingham / 248,Fairgrove / 989,Royal Oak / 248,Petoskey / 231,Monroe / 734,Farmington / 248,Benton Harbor / 269,Grand Rapids / 616,Akron / 989,Frankfort / 231,Hudsonville / 616,Bay City / 989,Center Line / 586,Rockwood / 734,New Haven / 586,Columbiaville / 810,Roseville / 586,Memphis / 810,Saline / 734,Detroit Zone 01 / 313,Kalamazoo / 269,Romulus / 734,Oxford / 248,Farwell / 989,Drayton Plains / 248,Walled Lake / 248,Ortonville / 248,Vicksburg / 269,Algonac / 810,Wyandotte / 734,Grand Blanc / 810,Boyne City / 231,Marine City / 810,New Baltimore / 586,Belleville / 734,Ypsilanti / 734,Carleton / 734,Richmond / 586,St Joseph / 269,Detroit Zone 04 / 313,Lapeer / 810,Vassar / 989,St Clair / 810,Troy / 248,Rosebush / 989,Niles / 269,Watervliet / 269,Fremont / 231,Baroda / 269,Big Rapids / 231,Cedar Springs / 616,Lowell / 616,Brighton / 810

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

Output:
7890123: Purchased 02 Jul 2019 for $1.00. Sweden, Stockholm / 8. Geographic.
0123456: Purchased 02 Jul 2019 for $1.00. United States, Texas, Dallas / 972. Geographic.
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com bobsPword listnumbers "Sweden" "Stockholm / 8"

Output:
7890123: Purchased 02 Jul 2019 for $1.00. Sweden, Stockholm / 8. Geographic.
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com bobsPword listnumbers "United States:Texas" "Dallas / 972"

Output:
0123456: Purchased 02 Jul 2019 for $1.00. United States, Texas, Dallas / 972. Geographic.
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com bobsPword listregaddresses

Output:
My French Place: Paris / 1, France
My German Hideout: Berlin / 30, 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 - Failed to delete. Error code 0300. Telephone number 1010202 doesn't belong to you.
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com bobsPword purchase "United States" "Dallas / 972"

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

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

Output:
Purchased 2 of 2 numbers:
33249880328
33249880410
java -jar ManageTelephoneNumbers.jar 0-2-0 bob@acompany.com bobsPword purchase "Sweden" "Stockholm / 8" 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 / 8" 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 / 2" 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


Security Tools


Sample Name: SecurityTools

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

This application takes a number of command line options:

java -jar SecurityTools.jar [--wsserver <cloudWebServerAddress>] [--protocol tls10|tls11|tls12] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • protocol = The protocol to support. By default, the wrappers will use the latest available protocols. For diagnostic purposes you can specify your own protocol to support.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • protocol_check

e.g.

To check what the latest available protocol is:

java -jar SecurityTools.jar 0-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ protocol_check



e.g.

To check if the TLSv1.0 protocol is available:

java -jar SecurityTools.jar --protocol tls10 0-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ protocol_check



Start a REST Outbound Service


Sample Name: StartRESTOutbound

A command line console application that starts an outbound service that is currently configured on a cloud region to run a REST API application.

The telephone number to call, the originating number and user-specified outboundParameters to be passed to a single service instance can be supplied on the command line. Multiple instances can be started by specifying the name of the file that contains a set of these parameters for each instance (comma-separated).

This application takes a number of command line options:

java -jar StartRESTOutbound.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <outboundService> <outboundServicePassword> <to>[;<from>[;<token>[;<outboundParameters>[;<extraSIPHeaders>]]]] | <csvFilename>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • outboundService = the outbound service to start
  • outboundServicePassword = the outbound service password
  • followed by either:
    • to = the destination of the outbound call
    • from = optional - the origin of the outbound call
    • token = optional - a user-defined token string to send to the first page of the application
    • outboundParameters = optional - a single outbound parameters string to send to the first page of the application
    • extraSIPHeaders = optional - A comma-separated list of name:value pairs of extra SIP Headers to send in the initial outbound call request
    or
    • csvFilename = the name of a file containing 1 or more to;from;token;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 ^. Comma-delimited parameters defined in a file are trimmed of leading and trailing spaces.

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

e.g.

java -jar StartRESTOutbound.jar 1-2-0 bob@acompany.com BobsOutboundRESTService 1912 "443069990123;443069999876;mytoken;"

Starts a single instance of BobsOutboundRESTService.
The outbound destination is 443069990123.
The calling number is 443069999876.
It is passed the token: "mytoken".

e.g.

java -jar StartRESTOutbound.jar 1-2-0 bob@acompany.com BobsOutboundRESTService 1912 targets.csv

where:
targets.csv contains:
443069990123;443069999876;;,sip:bill@bcompany.com;;;user defined info

Starts two instances of BobsOutboundRESTService.
The first outbound destination is 443069990123.
and the calling number is 443069999876.
The second outbound destination is sip:bill@bcompany.com.
The originating address or token are not specified.



Start a UAS Outbound Service


Sample Name: StartUASOutbound

A command line console application that starts an outbound service that is currently configured on a cloud region to run an application on a UAS.

The telephone number to call, the originating number and user-specified outboundParameters to be passed to a single service instance can be supplied on the command line. Multiple invocations can be made by specifying a count on the command line. In this case all invocations will receive the same outboundParameters.

Alternatively a file of comma-separated outboundParameter strings can be supplied on the command line. One invocation will be made with each outboundParameter specified.

This application takes a number of command line options:

java -jar StartUASOutbound.java [--wsserver <cloudWebServerAddress>] <cloudId> <username> <outboundService> <outboundServicePassword> [<outboundParameters> [<count>]] | <csvFilename> [<delimiterToUse>]

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • outboundService = the outbound service to start
  • 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, each being passed the specified outboundParameters
    or
    • csvFilename = the name of a file containing 1 or more outboundParameter strings, comma-separated
    • delimiterToUse = a delimiter character to use in the call to the web service to delimit the outboundParameter strings (default is ;)
Note: outboundParameters, whether defined on the command line or in a file, must not contain characters carriage return, line feed or ^. Comma-delimited parameters defined in a file are 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 StartUASOutbound.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 StartUASOutbound.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.



Text Translation


Sample Name: TextTranslation

A console application that provides access to the text translation facilities of the Aculab Cloud Web Services API. Use the 'translate' command to translate some text from one language to another. Use the 'languages' command to list all languages that the text can be translated to.

Getting Java applications to read and display UTF-8 characters in a Command Prompt window can be problematic. It is recommended that you specify UTF-8 encoding (I.e. Adding '-Dfile.encoding=UTF-8' to the command line string. See examples 2, 3 & 4) to ensure UTF-8 characters are read from text files correctly. If you have issues displaying UTF-8 characters, try running the 'chcp 65001' command prior to running the sample or, alternatively, try redirecting the output to file (See example 4).

This application takes a number of command line options:

java [-Dfile.encoding=UTF-8] -jar TextTranslation.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • languages
    • translate <sourceLanguageCode> <targetLanguageCode> <filename>
where:
  • sourceLanguageCode = The language of the text that is to be translated. The language must be specified using one of the supported codes (Use the 'languages' command to see all available languages and their codes). If you do not know the language, specify a dash character to have the server auto detect it.
  • targetLanguageCode = The language that the text will be translated to. The language must be specified using one of the supported codes (Use the 'languages' command to see all available languages and their codes).
  • filename = A UTF-8 encoded file containing text that is to be translated.


Example 1:

  List all available languages and their codes:

    java -jar TextTranslation.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ languages


Example 2:

  Translate some text from English to French:

    java -Dfile.encoding=UTF-8 -jar TextTranslation.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ translate en fr my_question.txt
  If the text in my_question.txt is "How are you?", then the output will be:

    Translated text from 'English' to 'French':
    Comment vas-tu?


Example 3:

  Translate some text from an unknown language to English:

    java -Dfile.encoding=UTF-8 -jar TextTranslation.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ translate - en their_answer.txt
  If the text in their_answer.txt is "Je vais bien, merci.", then the output will be:

    Translated text from 'French' (Detected) to 'English':
    I'm doing well, thanks.


Example 4:

  Translate some text from an unknown language to English and redirect the output to a text file:

    java -Dfile.encoding=UTF-8 -jar TextTranslation.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ translate - en their_answer.txt > translated.txt


Voice Biometrics


Sample Name: VoiceBiometrics

A command line console application that provides access to the voice biometrics facilities of the Aculab Cloud Web Services APIs. It shows how to use the UserGroup and UserGroupKey APIs and the User API to supply a single audio file containing voice data to register, update and verify a user.


User API usage:

    java -jar VoiceBiometrics.jar [--wsserver <cloudWebServerAddress>] [--method <httpRequestMethod>] user <cloudId> <username> <command>


UserGroup API usage:

    java -jar VoiceBiometrics.jar [--wsserver <cloudWebServerAddress>] userGroup <cloudId> <username> <apiAccessKey> <command>


UserGroupKey API usage:

    java -jar VoiceBiometrics.jar [--wsserver <cloudWebServerAddress>] userGroupKey <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • httpRequestMethod = PUT, POST or GET. The method used to make one of the requests that supply audio data. When using PUT and POST the audio file is supplied in the request body while for GET, the request returns a url on which a websocket is opened and the audio file streamed to it. The default is to use POST.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key


For API 'user', command can be one of the following:

    register <userId> <userGroupKey> <audioFilename>

    update <userId> <userGroupKey> <audioFilename>

    update <userId> <userGroupKey> <audioFilename>

    verify <userId> <userGroupKey> <audioFilename> [<sensitivity> [<textDependent> [enablePAD]]]

    stats <userId> <userGroupKey>

    exists <userId> <userGroupKey>

    delete <userId> <userGroupKey>


For API 'userGroup', command can be one of the following:

    list

    create <userGroupName>

    delete <userGroupName>


For API 'userGroupKey', command can be one of the following:

    list <userGroupName>

    create <userGroupName>

    modify <userGroupKey> <keyEnabled> [<retainData>]

    delete <userGroupKey>


where:
  • userId = a user-defined Id that uniquely identifies the user.
  • userGroupName = The name of a user group that will contain user registrations.
  • userGroupKey = An access key from the user group with which this user will be associated.
  • audioFilename = The name of the audio file to process. For PUT and POST, if the string starts with "http:" or "https:" the name is assumed to be a url from which to download the audio data. For register and update using POST it can be a comma-delimited list.
  • sensitivity = The sensitivity of the biometric analysis. Range is -10.0 to 10.0. Default is 0.0. Positive values decrease confidence, negative values increase confidence.
  • textDependent = By default this is true, meaning all audio data supplied to register, update and verify must contain the same spoken phrase. Set this to false to allow any phrase to be used to register, update and verify.
  • enabledPAD = Enable presentation attack detection (PAD). Presentation attacks may be encountered when voice data is supplied that has been covertly obtained from the user, synthesized or replayed. When PAD is enabled, and an attack is detected, extra information is returned identifying the type of attack. PAD is disabled by default.
  • keyEnabled = true to enable the key or false to disable it.
  • retainData = true to retain biometric and transaction data for all transactions using key.


Examples:

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com register Bob ak-3FHfDbq7e-g9QaOGwyv6C9 BobPhrase1a.wav

java -jar VoiceBiometrics.jar --method GET user 1-2-0 bob@acompany.com register Bill27645 ak-3FHfDbq7e-g9QaOGwyv6C9 BillPhraseAlawa.wav

java -jar VoiceBiometrics.jar --method GET user 1-2-0 bob@acompany.com register Bill27645 ak-3FHfDbq7e-g9QaOGwyv6C9 BillPhraseAlawa.wav,BillPhraseAlawb.wav

java -jar VoiceBiometrics.jar --method GET user 1-2-0 bob@acompany.com register Bill27645 ak-3FHfDbq7e-g9QaOGwyv6C9 BillPhraseAlawa.wav,BillPhraseAlawNoSpeech.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com register Bob ak-3FHfDbq7e-g9QaOGwyv6C9 https://my.wav.files.com/get_wav?filename=BobPhrase1a.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com register Bob ak-3FHfDbq7e-g9QaOGwyv6C9 https://my.wav.files.com/get_wav?filename=BobPhrase1a.wav,https://my.wav.files.com/get_wav?filename=BobPhrase1b.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com register Bob ak-3FHfDbq7e-g9QaOGwyv6C9 https://my.wav.files.com/get_wav?filename=BobPhrase1a.wav,https://my.wav.files.com/get_wav?filename=BobPhrase1NoSpeech.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com update Bob ak-3FHfDbq7e-g9QaOGwyv6C9 BobPhrase1b.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com verify Bob ak-3FHfDbq7e-g9QaOGwyv6C9 BobPhrase1c.wav

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com verify Bob ak-3FHfDbq7e-g9QaOGwyv6C9 BobPhrase2a.wav 2.0 false true

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com stats Bob ak-3FHfDbq7e-g9QaOGwyv6C9

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com exists Bob ak-3FHfDbq7e-g9QaOGwyv6C9

java -jar VoiceBiometrics.jar user 1-2-0 bob@acompany.com delete Bob ak-3FHfDbq7e-g9QaOGwyv6C9

java -jar VoiceBiometrics.jar usergroup 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ list

java -jar VoiceBiometrics.jar usergroup 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ create BobsCompany

java -jar VoiceBiometrics.jar usergroup 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete BobsCompany

java -jar VoiceBiometrics.jar usergroupkey 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ list BobsCompany

java -jar VoiceBiometrics.jar usergroupkey 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ create BobsCompany

java -jar VoiceBiometrics.jar usergroupkey 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ modify ak-ksxh4hiLdNEwGdEKd3osOH false

java -jar VoiceBiometrics.jar usergroupkey 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ modify ak-ksxh4hiLdNEwGdEKd3osOH true true

java -jar VoiceBiometrics.jar usergroupkey 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ delete ak-ksxh4hiLdNEwGdEKd3osOH



WebRTC Client Tools


Sample Name: WebRTCClientTools

A console application that provides access to the WebRTC client facilities of the Aculab Cloud Web Services API.

This application takes a number of command line options:

java -jar WebRTCClientTools.jar [--wsserver <cloudWebServerAddress>] <cloudId> <username> <apiAccessKey> <command>

where:
  • cloudWebServerAddress = The address of the cloud web server. By default the wrappers call web services on https://ws-<cloudId>.aculabcloud.net. In certain circumstances you may need to use a different address which you can set here.
  • cloudId = cloud region id (e.g. 1-2-0)
  • username = cloud account username
  • apiAccessKey = cloud API Access key
  • command = one of the following:
    • generate_token <clientId> <timeToLive>
    • list_registered_clients
where:

  • clientId = the client id of the WebRTC client that will be registered. This is the same as the clientId used when creating the WebRTC client.
  • timeToLive = The time, in seconds, that the token is valid for. This must be between 600 and 86400 inclusive. The default is 3600 (1 hour).


e.g.

To generate a token that is valid for 1 hour:

java -jar WebRTCClientTools.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ generate_token MyClient1234



e.g.

To generate a token that is valid for 2 hours:

java -jar WebRTCClientTools.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ generate_token AnotherClient 7200



e.g.

To list registered clients:

java -jar WebRTCClientTools.jar 1-2-0 bob@acompany.com 6b4UmwoOPxjeI2M76aebfQ list_registered_clients