The subscription API provides access to subscription methods from other systems.

The url for the APi is located at http://client.url/api/subscriptionapi.asmx

The service description is located at http://client.url/api/subscriptionapi.asmx?WSDL

All methods raise a soap exception if an error occurs. These will need to be handled by the client.

Methods

Method : SubscribeUser

This method subscribes a new user to your publication. Its uses the data contained in the sub & user classes to subscribe the user.

Return Value. A user_info class is returned. The user_info.guid value can used to identify the created user.

Method : SubscribeExistingUser

This method subscribes an existing user to your publication. It uses an existing unique user identifier the data contained in the sub & user classes to subscribe the user.

Return Value. None.

Method: IsSubscriberActive

This method checks if a user has a valid subscription.

Return Value: A boolean value is returned that identifies if a user has an active subscription or not.

Method: UpdateUser

This method updates the users details.

Return Value: true if the update was successful.

Method: GetUser

This method retrieves a user.

Return Value: returns a user_info class with the requested users details.

Method: UserExists

This method checks if a user exists.

Return Value: true if the user exists otherwise false.

Method: GetSubscriptionsForSubscriber

This method retrieves all the subscriptions a user is subscribed to.

Return Value: returns an array of user_subscription_info class with the requested subscription details. The array is order by subscription start date.

Method: GetSubscriptions

This method gets all subscriptions created for the publication specified.

Return Value: returns an array of subscription_info.

Method: GetWelcomeEmails

This method gets all Welcome Emails created for the publication.

Return Value: returns an array of email_info

Method: GetSubscribers

This method gets all subscribers for the publication specified.

Return Value: returns an array of User.

Method: GetIssues

This method returns a list of all the live issues for the given publication.

Returns an array of issues ordered by issue date.

Method : SubscribeUserToIssue

This method subscribes a new user to your publication. Its uses the data contained in the sub & user classes and the IssueID to subscribe the user.

The SubscripotionID in the sub class must be a subscription of fixed type to use this method.

You do not need to set the Start and End dates in the subscription class as these are calculated from the Issue.

Return Value. A user_info class is returned. The user_info.guid value can used to identify the created user.

Method : SubscribeExistingUserToIssue

This method subscribes a new user to your publication. Its uses the data contained in the sub & user classes and the IssueID to subscribe the user.

The SubscripotionID in the sub class must be a subscription of fixed type to use this method.

You do not need to set the Start and End dates in the subscription class as these are calculated from the Issue.

Return Value. None.

Classes

Class: subscription_info

This contains properties of the subscription for this publication. You can create or modify existing subscription using PAC.

Class: email_info

This contains properties of the email for this publication. You can create or modify existing emails using PAC.

Class: user_subscription_info

Class: user_info

This class contains the details of the user.

Class: issue

This class contains details of the live issues in your publication.

Example

This example uses the VS2008 “Add Web Reference” to generate C# proxy classes for the webservice. wsdl2perl, wsdl2java should produce similar proxy classes for Perl and Java.

Subscribing a user

The first step in using the subscription API is to create some subscriptions in PAC.

You can create date or issue based subscriptions in PAC. Contact Realview if you need help setting these up.

To get the subscription ID to pass to the SubscribeUser method you need to make a call to the GetSubscriptions method.

If you want to send an email after the subscription has completed then you will need to create an email in PAC. You can use the GetEmails method to get the email ID you would like to send.

realview.subscription.subscriptionapi subapi = new webservice_test.realview.subscription.subscriptionapi();

// create the user_info class and assign the properties

realview.subscription.user_info user = new webservice_test.realview.subscription.user_info();

user.emailaddress = "email@domain.com";

user.login = user.emailaddress;

user.password = "qwerty789";

user.first_name = "fergus";

user.last_name = "rourke";

user.status = 1;

// create the subscription_info class and assign properties

realview.subscription.user_subscription_info sub_info = new webservice_test.realview.subscription.user_subscription_info();

sub_info.StartDate = DateTime.Now.Date;

sub_info.SubscriptionStartOption = 2; // Start date will be publish date of currect issue.

sub_info.SendWelcomeEmail = true;

sub_info.WelcomeEmailID = 30; // ID retrieved from GetEmails()

sub_info.ID = 751; // ID retrieved from GetSubscriptions()

// Call the webservice to do the work

user = subapi.SubscribeUser(PID, sub_info, user);

// Do something with the returned user information.

do_something (user); 

Adding a subscription to an existing user.

To add a subscription to an existing subscriber you firstly need to see if that user exists in the Realview system. Call the GetUser() method to check if the user exists. Using the returned unique user identifier (user_guid) you then call SubscribeExistingUser() to add the subscription. If the user does not exist then you can subscribe the user using SubscribeUser().

This example user C# and Visual Studion 2008 with a Web Reference to the WSDL.

string email = "frourke@gmail.com";

realview.subscription.user_subscription_info sub = new realview.subscription.user_subscription_info();

sub.ID = 751;// 1836;

sub.StartDate = DateTime.Now.Date;

sub.SubscriptionStartOption = 1;

sub.SendWelcomeEmail = false;

//Guid PID = new Guid("A9891635-C672-48D2-9809-F636538DF02F");

Guid PID = new Guid("93AD2943-072F-4513-874A-221C5F12DD17");

realview.subscription.subscriptionapi api = new realview.subscription.subscriptionapi();

try

{

// find the user.

realview.subscription.user_info user = api.GetUser(PID, email); // throws error if the email is not found.

// add the subscription to the user we found.

api.SubscribeExistingUser(PID, user.user_guid, sub);

}

catch

{

// user was not found - create the user & subscribe them.

realview.subscription.user_info user = new realview.subscription.user_info();

user.Active = true;

user.emailaddress = "frourke@somemail.com";

user.first_name = "test";

user.last_name = "api";

user.login = "fergus";

user.Notify = false;

user.status = 1;

user.password = "mypwd";

user.user_guid = Guid.NewGuid();

// creatw the user & subscribe

api.SubscribeUser(PID, sub, user);

}