Sharing Subscriptions


Sharing Subscriptions

One of the fine features of a hard copy newspaper (physical paper) is that it can be shared across the breakfast table. Doing the same with a digital/non-physical product is a bit more challenging. On the one hand you might want to offer your customers the same convenience of a shared family subscription, on the other hand you don't want one person buying a subscription and sharing it on a social media site or between all his/her friends.

Preventing shared logins in a technical manner is outside the scope of this document, and indeed outside the scope of the InfoSystems application, instead this document will highlight some of the options there are for sharing subscriptions in the first place.

Note
You can ofcourse share subscription by mapping in an external system, but managing the mapping at Infosoft gives your customer services personel a bit more information when conversing with the customer.

This section contains the following subsections:

Sharing Subscriptions using a login (lightweight approach)
Sharing Subscriptions using Customer Relations
Limiting the number of shared accounts

Generally speaking the system supports two types of sharing

User (or login) mapped to a subscription
Customer mapped to a Customer with a subscription

There a several approaches to each, but the general idea is the same. Either a user is somehow connected to a specific subscription (user based sharing) or a customer is connected to another customer with one or more subscriptions (customer relation sharing). The latter is most appropriate for families or companies, but it is more data/process heavy, as such is not recommended unless you have a specific reason/use case for connecting customers like that.

From the end user/consumers perspective the result is (more or less) the same regardless of which mapping type is used

Note
If authorizing via the INFO-Cweb API the ordinary authorization process will handle things for you and you don't have to worry about anything

The recommended flow is outlined by the following sequence diagram.

Figure 1: Conceptual flow for creating shared subscriptions

Sharing Subscriptions using a login (lightweight approach)

The subscription system currently supports two methods for doing user based sharing

Mapping to InfoSystems users
Mapping to external users

The integration is almost identical, however there are a bit more validation when the users are managed by the InfoSystems, and direct client support for the service staff to utilize. When the users are external the client is responsible for all validation and verification related to the user entity and the subscription system will just assume the identifier is correct/valid.

Note
INFO-Cweb currently supports user based sharing with users managed by the InfoSystems user system.

The following sections will outline the approach for mapping users and authorizing them. It is assumed that the initial subscription exists and that one user is already mapped as the owner of that subscription. Refer to this section for information of establishing this connection.

User based sharing and authorization

If using the InfoSystems user system, you should make sure that the user you are granting access too already exists. Either by verifying it using the UserGet method or by creating the user with the UserCreate method.
Map the user with the CreateSubscriptionUser request. The TitleCode and the CustomerNumber is the identification for the subscription that should be shared. Typically this would be the subscription being administered currently (i.e. this process is done by the owner of the subscription).
Fill out the UserName if you are using the InfoSystems user system, otherwise the ExternalUser field. Never both.
The Roles field is an optional string that can be used to provide client managed privileges or some such for the mapping. It is just a string field so anything could be stored here if needed.
The authorization process should be expanded to include a request to the method GetSubscriptionUserMappingsByUser. This will retrieve all subscriptions the user is connected to, and then each of these should be verified for access just as if it was the owner that logged in.
I.e. get the CustomerNumber and TitleCode for the desired publication and verify that the subscription in question is valid.
Refer to the section on How To Authorise a Subscription for suggestions on authorization.
For the InfoSystems user system there is an option to include the owner (IncludeCustomerUser) in the result effectively eliminating an extra request to figure out if the logged in user is an owner itself. The resulting Roles for such an entry will always be OWNER.
Limiting management of the mapped subscription can be done by parsing the Roles entry. Remember that if using the InfoSystems user system the owner of the subscription will always have the single role OWNER.

Establishing Subscription Ownership

When authorizing a user using the login/user sharing it is beneficial to not have two separate authorization flows, i.e. one for shared/invited accounts and one for owner accounts. To achieve this the user owning the subscription should be establish as such on the mapping.

There are two ways to do this, one requires the use of the InfoSystems user system and provides customer services with more information in the client application. Additionally it only requires the mapping to be done once for the customer and not once per his/her subscription.

The other method can be used regardless of which user system you have, and requires a mapping per subscription.

Important
Neither of the methods described in the following is as such required, but doing it like this will save you some work during the authorization process.

InfoSystems user mapped to a customer

While ordering a new subscription using OrderSubscription you can specify a mapping using the UserParameters property, which will then be applied during the import process.

Alternatively if you are connecting an existing user you can do so using ConnectCustomerAndUser

Both alternatives will map the user and the customer, so any subscription that the customer has the user will be mapped to.

External User mapped to subscription

For each subscription that the user is an owner of create a mapping to the subscription using the method CreateSubscriptionUser with a mapping from the customernumber and titlecode to the username, and optionally define a Role of OWNER to distinguish between the owner and other users.

You might have noticed that this process is essentially the same as creating a shared account.

Sharing Subscriptions using Customer Relations

The flow of sharing by using customer relations is similar to the user based flow (in fact the user based flow is implemented using relations behind the scenes). However there are more requirements to association using customers as a Customer is a more heavy weight entity than a user. Customers require a name, an address and even a user (externally or locally). The advantage is that sales and service personal now might be able to target these family members for up-sale or similar activities.

Tip
Infosoft recommends that you use user based sharing unless there is a specific requirement for customer based sharing.

For general information on relations refer to this section on relations

If you (or someone) have decided to use Customer Relation based sharing some preparation is required. Someone with access to the InfoSystems client application have to create a new RelationType where the reference is Subscription and the titlemode is Required. Name the type something like FAMILYMEMBER, SHAREDACCOUNT or similar. For the remainder of this section we will refer to this RelationType as FAMILYMEMBER.

Customer Relation based sharing and authorization

You should make sure that the invited customer already exists. If not create it using your preferred method for customer creation for instance using the CreateCustomer method.
Once the invited customer exists create a new relation on it referencing the subscription owner using the CreateCustomerRelation method. I.e something like the following example:
C#
ASP.NET
Copy
```
ICustomerRelationService service = new CustomerRelationServiceClient();
service.CreateCustomerRelation(new CustomerRelationRequest()
{
    CustomerNumber = INVITED_CUSTOMERS_CUSTOMERNUMBER,
    TitleCode = "TEST",
    RelationTypeCode = "FAMILYMEMBER",
    Reference = SUBSCRIPTION_OWNER_CUSTOMERNUMBER,
    Source = "INFOSOFT EXAMPLES",
});
```
No code example is currently available or this language may not be supported.
Its important that the relation is turned "the right way" because when authorizing the subscription for a shared account you only have that customer not the subscription owner.
An additional value can be used for anything you wish to add to the relation, such as a Role indicating administration rights or similar.
The authorization process should be expanded to include a request for the customers relations. Then for each relation of type FAMILYMEMBER where the title matches the one your are authentication, figure out if the target customer has a valid subscription for the publication.
In short; get the FAMILYMEMBER relation for your title and use the retrieved Reference as the CustomerNumber in the ordinary authorization flow.

Tip
Refer to the examples section for details on creating and retrieving customer relation

Limiting the number of shared accounts

Even though you want to allow sharing of subscriptions, its probably not feasible to allow an unlimited number of accounts for any given subscription.

Its possible to just decide on a number and limit the number of accounts to that number. However the InfoSystems offers a way for this limit to be customized on a subscription by subscription basis. This might be handy if the default account limit is 5 but a given family has 7 family members and you want to grant additional access to just that specific subscription.

Similarly this might be useful for providing account sharing in case of a company/organization subscription.

The mechanism for this limitation control is simply a field called SharedSubscriptionCount defined on each subscription. You can retrieve this using GetCustomerInformation, GetCustomerInformation or any of the methods that provides a InfoWebSubscription response.

The SharedSubscriptionCount is not verified in any cases by the web services so you have to verify this on your account sharing administration page.

Note
INFO-Cweb uses the SharedSubscriptionCount to determine the number of allowed accounts.

Important
You should consider what a value of 0 means for the SharedSubscriptionCount. It might mean sharing is disabled or a default should be used, that is up to the client to determine.

Other Resources

Relations

How to authorise a subscription

User register Introduction