Vending Manager API

The Vending Manager API provides access to Vending Manager data maintained by Content Delivery Server. Use this API to create and manage bundles, campaigns, subscriber segments, and subscriber plans without going through the Vending Manager administration console interface.

The Vending Manager API is accessed through an XML-RPC (remote procedure call) implementation. XML-RPC enables your application to make remote procedure calls using HTTP for the transport and XML for data encoding. You can use XML-RPC with many different programming languages by using bindings that are available on the Internet.

For information on these classes and their methods and parameters, see the HTML output of the Javadoc tool at $CDS_HOME/javadoc/vendingapi/index.html.

12.1 General Process Flow

The Vending Manager API provides access to Vending Manager data, therefore, the first step in any application that uses this API must be to log in to the Vending Manager using the AuthenticationHandler.logUserIn method. The user name that is used to log in must be a valid Vending Manager administrator account, not a Customer Care Agent.

If the login is successful, an authorization key is returned. Use this authorization key in all subsequent calls for Vending Manager data. When the application completes all tasks, the final step is to log out of the Vending Manager using the AuthenticationHandler.logUserOut method.

12.2 Guidelines for Calls to XML-RPC Methods

XML-RPC calls follow certain conventions. The sample code in this section illustrates how to make the call and process the results for authenticating a user. The sample code is written in the Java programming language and uses the Apache XML-RPC client library. The code that you need to write might differ if you are using a different language or library.

Place the parameters for the method that you are calling in a hash table. Place the hash table in a vector.

...
// Create a vector to hold the request parameters
Vector<Hashtable> request = new Vector<Hashtable>();
 
// Create a Hashtable to hold the method specific parameters and add them.
Hashtable<String,Object> methodParams = new Hashtable<String,Object>();
methodParams.put("username", "user1");
methodParams.put("password", "cryptic1");
 
// Add the method specific parameters to the request.
request.addElement(methodParams);
...

To call a method, pass the name of the method and the vector that contains the parameters. A hash table is returned. The method call must include the name of the handler, for example, AuthenticationHandler.logUserIn.

...
// Generate the full method name. ( handlerName.methodName )
String methodName = "AuthenticationHandler.logUserIn";
// Send the request and get the response.
Hashtable response; 
response = (Hashtable) client.execute(methodName, request);
...

Verify that the method executed successfully by checking the response code that is included in the hash table that is returned. If an error occurred, a response message is also included in the hash table.

...
// Process the results: check to see if there was an error.
String responseCode = (String)response.get("responseCode");
if(!responseCode.equals(“success”)) {
   // There was an error. Find out the 'real cause'.
   String realCause = (String)response.get("responseErrorCode");
 
   System.out.println("Error: Operation failed with: " +realCause);
}
...

If the method executes successfully, extract the values that are returned in the hash table. If a method does not return any values, the hash table contains only the response code.

...
// Get the authKey from the request.
String authKey = (String)response.get("authKey");
...

12.3 Accessing Content Delivery Server

To obtain data from Content Delivery Server, your application must be able to communicate with Content Delivery Server. Work with your network administrator to ensure that the application can contact Content Delivery Server and that any required proxy or firewall is configured to allow this access.

In addition, Content Delivery Server must recognize that your client is authorized to make requests for data. The vendingApi.xml-rpc.trustedHosts property in the $CDS_HOME/deployment/deployment-name/conf/VSAdminConsole.properties file contains the list of hosts from which requests are accepted.

Set the vendingApi.xml-rpc.trustedHosts property to the host name or IP address of the host on which your application is located, whether it is on the same host as Content Delivery Server or on a different host. To accept requests from any host, leave the value blank. To accept requests from more than one host, separate the host names or IP addresses with a comma, for example: