Prerequisites

The REST Demo requires a Linux system with OpenJDK 11. The JAVA_HOME shell environment variable should be set to the base directory of the OpenJDK installation.

The REST Demo is deployed on Rhino TAS. The REST Demo installer can install Rhino automatically (recommended), or you can install it manually. If installing Rhino manually, use Rhino SDK 3.0.0.0 or later.

Important The REST Demo requires access to Metaswitch Artifactory servers. Please contact Metaswitch for a username and password.

Licensing

A license file is required to run Rhino, the Sentinel SIP components and the Metaswitch Call Notification API used in the demo.

The REST demo package includes a license file (rest-demo-license.license) that is valid for two months from the release of the REST demo.

Important Contact Metaswitch if you require a new license file.

If you allow the installer to install Rhino automatically, it will prompt you for the location of the license file.

If you prefer to set up Rhino manually, then you need to install the license file prior to installing the demo.

Installation

Prepare the REST Demo package

download Download the Rhino REST API Demonstration

Important The REST Demo requires access to Metaswitch Artifactory servers. Please contact Metaswitch for a username and password.

The REST demo package contains an installer program that guides you through the installation process, and downloads the other components needed to run the demo.

After downloading, extract the REST Demo zip file. This will create the rest-demo-sdk directory. In this directory there is an installer that guides you through the following steps:

  1. You may optionally take the demo offline. The installer will download all additional components so that installation can continue later without accessing the network.

  2. You can choose to install the Rhino TAS SDK, if you don’t have it already.

  3. Source code for the REST Demo modules is extracted and built.

  4. Finally the REST Demo components are deployed and configured in the Rhino TAS instance specified in (2).

Tip The installer captures full logging from the various tools that it uses, and writes these logs into the rest-demo-sdk/build/target/log directory. This can be helpful when debugging issues.
Note Before installing, if the host requires a proxy to access Artifactory then it must be configured in sdk.properties. sdk.properties can be found in the top-level directory of the unzipped package. Find the section marked with # Proxy settings and change it to the following: 
# Proxy settings
#
sdk.http.proxyHost=<proxy hostname here>
sdk.http.proxyPort=<proxy port here>
sdk.https.proxyHost<proxy hostname here>
sdk.https.proxyPort=<proxy port here>
#
# These properties are used for both http and https.
sdk.http.nonProxyHosts=localhost|127.0.0.1

Install the REST Demo modules

1

Start the installer

Run the installer command in the build/bin directory of the extracted REST Demo SDK.

$ cd rest-demo-sdk
$ build/bin/installer

The installer first initialises its environment, showing output similar to the following:

Initialising the SDK ...
Retrieving Installer dependencies ... done.

The installer may prompt for Artifactory credentials, which should have been supplied to you by Metaswitch.

2

Prompting for information

The installer will prompt the user for some configuration values. A value inside square brackets, if present, is the default answer for that question. Pressing the Enter key without entering any value will use the default value. If the default isn’t present, the prompt will be repeated. In subsequent runs of the installer, the defaults will reflect the values that the user has previously entered.

Explanations of all of the questions the installer will ask are laid out over the next few steps. Note that some of the questions will only appear under certain circumstances, so not all of them will be seen in a given installer run.

3

Taking the SDK offline

The installer asks if the SDK should be taken offline.

You can optionally take the SDK offline by creating a local repository. This will take several minutes depending on connection speed, but will make subsequent retrievals much faster and remove the need for an internet connection.
Do you want to take the SDK offline? y/[N] >

If the user presses the Enter key then the default of N is applied by the installer. This means that the SDK remains online, and will connect to the Metaswitch Ivy repositories on an as-needs basis. Answering yes will create a local Ivy repository that includes all of the remote artifacts required to build the SDK.

The user is then presented with progress information related to the downloading of artifacts necessary to take the SDK offline. This process can take around 10 minutes.

4

Basic SDK Questions

The values provided in this step are used in SLEE component identifiers and Ivy artifacts created when the REST Demo modules are built below.

Your organization's name, e.g. Rocket Communications Inc.
sdk.component.vendor [UNSET] >

This value will be used for the vendor portion of the SLEE Component ID for all SLEE components published by the SDK.

sdk.component.version [1.0] >

This value will be used for the version portion of the SLEE Component ID for all SLEE components published by the SDK.

The name of the platform operator, e.g. Rocket.
sdk.platform.operator.name [UNSET] >

The name of the platform operator for the system. It is used extensively throughout configuration profiles.

An Ivy organization field, recommended lower case with no whitespace e.g. "rocket".
sdk.ivy.org [UNSET] >

This value is used as the org value for all Ivy artifacts created by the SDK.

sdk.ivy.publish.revision [1.0.0] >

This value is used as the base of the revision value for all Ivy artifacts created by the SDK. Additional letters and numbers will be appended to it to identify specific releases, snapshots and milestones when an artifact is actually published.

5

Installing Rhino

You can either have the installer set up a Rhino SDK for you or point it at an existing Rhino installation, SDK or production.
Note: If you want to use an existing Rhino installation it has to be running and a proper license has to be installed when finishing the installation after the configuration. Also make sure that you have adjusted the memory settings and created a tcapsim-gt-table.txt file as detailed in the documentation.
Set up a Rhino SDK installation automatically? y/[N] >

If the installer needs to set up a new Rhino SDK installation, it will prompt for a license file.

Enter the path to your Rhino license file > /home/restdemo/rest-demo-sdk/opencloud.license

The Rhino TAS SDK will be installed and started in the background.

If the user instructs the installer to use an existing Rhino TAS, the path to the Rhino client directory must be entered.

Enter the path to your Rhino client directory > /home/restdemo/RhinoSDK

If the Rhino TAS installation is a production version, then additional information is required to complete configuration.

You can either have the installer deploy against Rhino SDK or production.
Does the specified client point to a production installation? y/[N] >

If Yes is selected, the installer prompts for details of the cluster nodes and hosts. Otherwise, the user enters the host that Rhino TAS SDK is installed on.

The host your Rhino SDK is installed on.
Rhino host [localhost] >

6

Review settings

Once the basic SDK configuration questions have been answered, the user is provided the opportunity to review, and if happy, accept the settings.

Tip Settings are saved to disk, so that they can be read later. 
Review settings
***************


Basic SDK properties
====================

  sdk.component.vendor: Rocket Communications Inc
  sdk.component.version: 1.0
  sdk.platform.operator.name: Rocket
  sdk.ivy.org: rocket
  sdk.ivy.publish.revision: 1.0.0


Rhino settings
==============

  Deploy Rhino: Yes
  License location: /home/restdemo/rest-demo-sdk/opencloud.license

Accept these values? [Y]/n > y

Updating file sdk.properties
Updating file sdk.properties

Configuration changes written.

If the user presses the n key then the questions are asked again. Note that the list of configuration files that have been modified are printed out by the configuration portion.

7

Create deployment modules

Next, the installer prompts the user to create and build the REST demo modules. These include Sentinel-SIP features and REST API RA Types used by those features to communicate with an external API server.

This creates the rest-demo-modules directory and builds the demo modules, ready for deployment in Rhino. This must be done the first time the installer runs. If this step has already been done in a previous installer run, it can be safely skipped.

Create REST Demo Modules
========================


You can optionally create & build the demo REST RA and Call Notification API feature modules. This will create the "rest-demo-modules" directory and build the modules it contains. These modules will be deployed automatically by the installer. If the "rest-demo-modules" directory already exists, it will be deleted before being recreated and rebuilt.
Delete & rebuild REST demo modules? [Y]/n >

The user is then asked to confirm:

Review settings
***************


Create REST Demo Modules
========================

  Create & build REST demo modules: Yes

Accept these values? [Y]/n > y

Building the modules will take a few minutes.

Creating module rest-demo-modules ...done.
Building REST Demo modules; this is going to take a while ...
done.

Configuration changes written.
Creating deployment module deploy-rest-demo ...done.

8

Deployment

The installer can now deploy the REST Demo features into Rhino. It will prompt the user to confirm whether to proceed with the installation:

Install now? [Y]/n >

Installation can be deferred to a later time by entering n here. The installer will exit, saving the settings that were entered. These settings will be used automatically on the next installer run.

Otherwise, the installer proceeds with deploying the REST Demo modules into Rhino. This may take around 10-15 minutes.

Installing Rhino ...done.
Starting Rhino in the background ...done.


Installing List CDRs tool ...done.
Publishing deployment module deploy-rest-demo ...done.
Deploying; this is going to take a while ...done.
Binding; this is going to take a while ...done.
Configuring; this is going to take a while ...done.

Installation completed successfully in 11 minutes and 14 seconds. Rhino has been left running to finish applying configuration changes.

The configuration has been saved to the file /home/restdemo/rest-demo-sdk/install.properties. This file can be used to re-run the installation non-interactively with the same settings.

The installation is now complete.

When the installer completes, the Rhino TAS will be running with Sentinel SIP and the call notification features described in Demo Architecture and Implementation.

Directory Structure

The contents of the rest-demo-sdk directory are as follows:

Name Description 
build/

Directory containing the installer and Ant scripts for building and deploying SDK components.

 
rest-demo-modules/

Directory containing:

  • API modules for generating SLEE RA Types based on an OpenAPI specification of an example "Call Notification" API (based on the OMA Call Notification API)

  • An RA module that generates the implementation of a SLEE Resource Adaptor supporting the demo APIs

  • Sentinel-SIP feature modules that make use of the demo Call Notification API to direct SIP calls

 
test-suite/

Directory containing a test suite that simulates some example SIP call scenarios, showing the demo features making REST calls to a simulated HTTP server. See Running the Test Suite below.

 
run-tests

A script that runs the tests in the test-suite directory.

 
rhino-sdk/

Directory containing the Rhino TAS SDK that was created by the installer (if requested).

 
build.xml, sdk.properties, deps.properties

Ant build and properties files for building the project. Should not need to be modified.

 
ivy.properties, release.properties

Dynamically-generated properties files for resolving the various components deployed by the demo. Automatically recreated when building or deploying REST demo modules.

Running the Test Suite

The test-suite directory contains integration tests that demonstrate various scenarios using the demo Call Notification API. The test scenarios simulate a SIP node (e.g. an S-CSCF) sending calls to Rhino, and an HTTP server that responds to the REST requests sent by the Sentinel-SIP features running in Rhino.

To run the tests, first run the installer as above, then run the run-tests script. This runs all scenarios in the test suite, and logs the call flows as they are performed.

See Demo Call Flow Scenarios for more information on the test scenarios.

Previous page Next page