Integration with tropo's provisioning api
Since build 158, Rayo can be integrated with Tropo's Provisioning API. This integration basically lets you use the Provisioning API to create and remove rayo applications and to add/remove SIP addresses and phone numbers for your Rayo applications.
To install the provisioning API integration modules you should first have a Provisioning API installation running, and admin rights to it. This type of integration is normally oriented to on-premise deployments where you have Rayo and the provisioning API running in your own data center or a cloud provider like Amazon EC2. If you do not have a Provisioning API installation, please contact your Tropo customer support agent first and ask him about on-premise Tropo deployments.
When you execute some administrative operation like adding/removing applications or adding/removing addresses in the Provisioning API, the API sends a JMS notification into an ActiveMQ server. These notifications will be read by what we call an "agent" that is ixn charge of reading these notifications and updating the corresponding mappings in the Rayo storage.
Depending on whether your Rayo installation is clustered or not the agent will be slightly different.
To integrate your Rayo Cluster (gateway) with the Provisioning API you need to follow the steps below:
- Download the last version of the Rayo Provisioning Cassandra Agent and drop it into your gateway installation's WEB-INF/lib folder. This uses to be in /opt/voxeo/prism/rayo-gateway/WEB-INF/lib.
- Copy the agent configuration properties file - provisioning.properties into the WEB-INF folder.
- Update the properties file with the connection data of your ActiveMQ server, your rayo domain and the provisioning API's connection settings. Most of the properties do not need to be changed. However you should put special attention into the following ones:
| Property | Description |
|---|---|
| com.rayo.provisioning.jms.provider.url | Connection URL to your ActiveMQ server e.g. tcp://localhost:61616 |
| com.rayo.provisioning.jms.username | ActiveMQ username or blank if not needed |
| com.rayo.provisioning.jms.password | ActiveMQ password or blank if not needed |
| com.rayo.domain.name | Your rayo domain. This will be used to build sip addresses. e.g. apps.tropo.com |
| com.rayo.provisioning.api | The URL of the Rayo provisioning API. e.g. http://api.tropo.com/rest |
| com.rayo.provisioning.api.username | A Provisioning API username. This should be the same username that owns the different applications created via the Provisioning API command line. |
| com.rayo.provisioning.api.password | The password of the Provisioning APi username |
- Create your application using the Provisioning API. There are two very important things you need to remember when doing this:
4.1. The platform of your application has to be set to "rayo" 4.2. The VoiceURL of your application will be your application's Rayo JID
Here is an example:
curl -v -H "Content-Type: application/json" -X POST -d '{"name":"myapp", **"voiceUrl":"myapp@apps.rayo.com"**,"messagingUrl":"myapp@apps.rayo.com", **"platform":"rayo"**, "partition":"staging"}' username:password@api.tropo.com/rest/v1/applications
When running that command the following will happen:
- The provisioning API will create your application and send a notification to ActiveMQ
- The Rayo Agent will pick up the notification and check the platform attribute
- If the platform is not rayo, the notification is dropped.
- If the platform is set to rayo, the Rayo Agent will check the VoiceURL attribute to see if the application exists or not.
- Depending on the operation that you have executed the Rayo Agent will either create a new application, update it or remove it from the Rayo database. In the example above the application would have been created.
Sometimes you might be running Rayo on a single Prism server but you still might want to use or connect to an instance of a Provisioning API server. In this case the configuration steps are mainly the same but there are a couple of things that change, since on a single Rayo server we do not use Cassandra but a very simple routing properties file.
Nevertheless, the approach is very similar:
- Download the last version of the Rayo Provisioning Properties Agent and drop it into your Rayo installation's WEB-INF/lib folder. This uses to be in /opt/voxeo/prism/rayo/WEB-INF/lib.
- Copy the agent configuration properties file - provisioning.properties into the WEB-INF folder.
- From here you can follow the instructions in the clustered scenario.
Disconnecting your Rayo installation from the Provisioning API is as easy as removing the Rayo Agent's jar file. Either the cassandra agent or the properties based agent. Once you remove that jar from your WEB-INF/lib folder both Rayo and the Provisioning API become disconnected.