Home

Welcome to Responsys Api Client !

This wiki is intended to help you understand the purpose and the actions that this client can make.

You will find functional, concepts and technical replies to your questions. If you need any more help, please feel free to ask in the repository issue section.

Overview

Our client helps you communicate to your dedicated Responsys system. It uses the Interact API provided by Oracle for a couple of recurrent common actions in order to integrate them easily into your back-end.

Important notes:

• Responsys is a private service which is based on a commercial contract. You cannot test it unless you have a demo account or a contract account. Please contact Oracle for further information.
• You will need your own credentials in order to use this Gem and to authenticate with your identity to the API.
• Your information are kept secret and will not be used to any third party.
• Please read the documentation before any action which would mess up your Responsys account.

Requirements:

• This client is using the Ruby power. It requires a Ruby 1.9 environment or newer.
• Enjoy !

Current supported concepts

The client is based upon the official documentation of Interact API v6.20. The same methods specifications are available inside the GEM.

But because the concepts in the API are not that straightforward, we tried to make it more user friendly by creating higher level objects that use these methods and make them more simple to use.

Interact API methods

Just a reminder of the concepts of the API. For further information, please refer to the documentation.

• Authentication [TODO]
• Folder [TODO]
• List Management

Client generic concepts

We're here to help you. Focus on your app and let us provide you nice simple objects to manipulate.

• Authentication
• Member

Integration

Responsys Api can be combined with Ruby scripts or Rails.

Example

A little bit of explanations if you want to know what's going on under the surface.

Scenario : say you want to know if a customer from a List has subscribed. You are working from your application or script, whatever it is.

1. Internal logic needs Responsys

We are : in your application, in your own newsletter subscription logic.

Your source code instanciate a built-in Member class. You pass it the description of your list with an Interact Object like this :

# Define the Member
member = Responsys::Member.new('[email protected]')

# The list you want to search in
list = Responsys::Api::Object::InteractObject.new("one_folder", "my_customers")

# Make a call to Responsys
puts member.subscribed?(list) ? "#{member.email} has subscribed to #{list.objectName}" : "An error happened"

Instanciating the objects defining the context does not make calls to the API. The call is only make at subscribed? method. We can continue to step 2 to understand how the GEM handles this.

2. Build request

We are : in the GEM bundled in your application.

You passed all the information to the GEM to build the request to Responsys.

The API is based on the SOAP protocol. According to its specification it which needs a bunch of things:

1. Authenticated session ID. If it's the first time you make a call, the built-in client will login to Responsys using your credentials. Read more about Authentication configuration.
2. Transform the parameters to the right expected representation.

3. Send SOAP request

We are : in the GEM bundled in your application.

We use the famous and helpful Savon GEM to make our request. It manages everything for us.

If you want to bypass our objects and directly use the API methods you can do it easily : Responsys::Api::Client.instance.api_method(:method, {parameter1: "value"})

• The first parameter is the alias of an API method listed in Responsys::Client::Client.instance.available_operations.
• The second one is the message of the request (SOAP body).

4. Let Interact API handles the request

We are : in Responsys Interact API system.

Couple of things done by the API :

• Check the Session ID passed in the request.
• Parse the body of the request and check that the WSDL specifications are respected.
• Execute the action if any.
• Return a response with result(s) / status.

5. Parse SOAP response

We are : back in the GEM in the application.

Savon handles the response, parses it. SOAP errors can be raised at this point.

The GEM extracts the response body to make it usable.

6. Return result(s)

We are : at the end of the client request process.

If you used one of our simplified objects, it should manage everything from the Responsys logic. Otherwise you'll have the raw body result(s) of the method you requested.

7. It will print...

We are : back at the origin.

[email protected] has subscribed to my_customers