Subscription service

From the Content Studio administrative interface you enable subscription on a specific category by opening the properties dialog on a category and navigating to the new Subscription tab.

Activation subscriptions

By checking the Activated checkbox in the upper right corner of this dialog the category is set up for subscription. In order to be able to activate subscription for a category or change any subscription related properties the caller must have WriteContainer permission for that category, a permission normally given only to developers and administrators. Before you can save your data you must also set other important properties necessary for the subscriptions to work.

General properties

The upper section of the dialog contains some general properties:

Web site address

Specifies the address that the even handler should use when it finds the document that should be transformed to a mail message and sent out to the subscribers. This value is one of the url:s specified by the site administrator in the SiteURL and MultiHomedSiteURL web site wide settings. Normally there is only one alternative here that is pre-set by the system.

Presentation template

Specifies the presentation template to use when the handler generates the mail message from the document being sent out. This is relevant for EPT-documents only and the default value --- Auto --- indicates that the default presentation template should be used or that presentation templates are not relevant for this category (i.e. not an EPT category).

Sender

This is the mail address that will be used as sender of all subscription mail being sent out. Most mail (SMPT) servers does not accept mails without a sender.

Custom event handler

Specifies a custom implementation of the ICSAsyncEventHandler interface that will be called by the Service Manager when mails are sent out. A custom event handler might be necessary to use if the built in implementation does not meet the requirements. These event handlers are regular .NET assemblies that implements the ICSAsyncEventHandler interface, compiled as .DLL and are installed in the same directory as Content Studio server, CSServiceHost.exe or installed in the Global Assembly Cache (GAC).
The value of this property specifies the programmatic name of your event handler and can be written in several ways where the simplest form is Namespace.Class, Assembly name The complete format looks like: Namespace.Class, Assembly name, Version=value, Culture=value, PublicKeyToken=value

Examples

The first example is as simple as it gets where only the full name and the assembly name are given. The assembly name is normally the same as the name of the dll file minus the .dll extension.

MyEventHandlers.OnDocumentSubscription, MyEventHandlers

The second example is more specific an specifies that the event handler has been given a strong name and we also needs a specific version of the assembly to be loaded with a specific culture. This advanced type info is needed when your event handler assembly has been registered in the global assembly cache (GAC).

MyEventHandlers.OnDocumentSubscription, MyEventHandlers, Culture=neutral, Version=1.0.0.0, PublicKeyToken=feea6d4abcd740d9

Normally this value should be left empty to use the built in event handler.

Timeout

When the event handler implements time out functionality this value can be the time (in seconds) that a mail sending job may take before interrupted and considered an error by the Service Manager. The default value 0 (zero) should indicates no time out value. The current implementation of the built in event handler does not implement time outs and in this case; the value should always be zero.

Viewing subscribers

By hitting the "Subscribers" link you can view a list of all subscribers of the category. This list supports paging and displays both activated and not activated subscribers and from this list an administrator can add new subscribers by either hitting the "New subscriber" button or simply right-click somewhere in the list. By default new subscribers are not activated by default, which indicates by the icon with the stop sign. The administrator can easily activate or deactivate a single subscriber by just right-click on a subscriber and select the appropriate command in the context menu that appears. Deleting subscribers is done in exactly the same way.

Sending test messages

The Test send functionality is available for activated subscriptions only and displays the Test send dialog

From this dialog you can select any of the documents in the category and enter the address of one receiver. When you close the dialog by pressing the Send button Content Studio informs you that a test mail job has been created. Provided that the event handler supports sending test mails (the built in default provider support this) the mail is sent as soon as the Service Manager finds the job. Since this procedure is carried out in the same way as the regular send operations you can test that the whole chain is working.

Working with the schedule

The schedule part of the main dialog is used to specify when mail messages should be sent out to subscribers but you can also specify that no schedule should be used. It that case any new published document will be sent out to subscribers within just a few minutes or as long that it takes for the Service Manager and the mail server to send them out. The subscription administrative interface only supports one schedule but within this schedule you can specify as many occurrences you like during the day and you can specify any combination of weekdays. However, for practical reasons, most users find that one or two deliveries during work days are sufficient. For example you might want to send mail when the mail server is not busy with regular traffic; in this case 03:00 (03.00 AM) might be a good option.

Advanced settings

The advanced settings can be reached by hitting the "Advanced properties" dialog that displays the new Dynamic property editor.

The advanced properties are used to send information to the implementation of the subscription event handler. The built in event handler (which can be replaced by a third-party implementation) uses a number of settings related to Html mail rendering, logging and mail server settings. A brief summary of these properties are listed in the table below.

Properties for outgoing mails

Server name or IP:

Specifies the name or IP address of the SMPT (mail) server that the event handler uses when it sends out the mail messages to the subscribers.

Authentication method:

Specifies whether and how the event handler authenticates to the mail server. Not all mail server requires authentication. There are three different methods supported.

Anonymous

Mail messages are sent anonymously and no authentication is required. This is the default value. Some mail servers might allow non-authenticated clients to send messages locally but prohibits relaying (outside the local network) if not authenticated. For this reason always test subscriptions both with external and internal messages.

Windows

Messages are sent using the Service Manager's own credentials i.e. NT AUTHORITY\Network Service). Not all mail servers supports this authentication method but is supported with Microsoft Exchange. Windows authentication cannot be used between server (i.e. the mail server is located on a remote computer) unless both computers (Web server and mail server) are members of the same Active Directory. Windows authentication (also known as integrated authentication) is very safe and robust since no passwords are stored and transmitted over the network.

Basic

This is the standard method of authentication supported by most mail servers. Use this method as a last resort only since credentials are sent in clear text to the mail server. The credentials are stored encrypted in the database and by default only the Service Manager (i.e. sessions in Content Studio that has the ServiceQueueAdmin global group right set) can read this information in clear text. Also, this information is readable only on the web server that stored them in the first place. If Content Studio is moved or restored to another server all subscription credentials are lost and must be entered again. A future version of Content Studio might include a tool that can copy and restore these credentials. Also Basic authentication is not supported if Content Studio is set up to run as a web farm and mail credentials are saved or read on different servers.

User data:

Only available when Basic authentication is used. By click this link a dialog is displayed where one can enter user credentials for Basic authentication. If specified the username and a symbolic password is displayed in the textboxes below this link. The password is not stored somewhere in the Html code, what is shown is just a dummy value to give the impression of a password.

Viewing subscription properties for a document

This new dialog displays the subscription related properties for a document. You can reach this dialog by right-clicking a document in the document list in the Content Studio administrative interface and select the Properties option.  This displays the document properties dialog which has a button "Subscription properties" that brings this dialog up.

In this dialog you can determine whether subscription is enabled for the document's category and the current subscription status for the document. The following status values are available for any document:

Will not be sent or already sent

This is the status of document that are not subject to subscription. This is true also for documents that existed in a category before subscription was enabled on that category. Also this is the status given to all existing documents in a category when subscription is turned off.

Will be sent after publishing

The document is not published yet but will be scheduled for subscription as soon it has been published. This can occur when:

• the document is approved and published
• an approved document that is not yet published (its publish date is greater than the current date or it has not yet been marked published).

Will be sent according to the schedule

The document is published and will soon be scheduled. No job has yet been created for the document.

• the document has been saved but not yet approved and published.
• an approved document that is not yet published (its publish date is greater than the current date or it has not yet been marked published).

Queued or in progress

A job has been created and will be executed when scheduled - or the job is currently executing.

Sent

The document has been sent to the subscribers and will normally not be sent again.

Invalid or an error has occurred

This status simply indicates that data could not be read properly.

Changing status of a document

By changing subscription status of a document you prevent a document from being sent or force a document to be sent out

Stop send

You can stop a document from being sent as long as it has not been scheduled or is in progress. If you stop a document from being sent its status will be set to Will not be sent or already sent and will not be sent out automatically again.

Force resend

Forces a document that is not meant to be sent out to be sent according to the schedule.

Send when published

Enables the document to be sent out as soon it is re-published. Such a document is normally never sent out again. A document is re-published if it

• was not marked as published (with-drawn) and later marked published.
• An archived document's archive date is changed so it is published again.
• The publish date of a document was been changed so that it is went un-published. The document is the re-published when the new publish date has been reached.

Any subscription system is worthless unless visitors can subscribe to your newsletters. Even though an administrator can manually add and remove subscribers this is, of course, very unpractical. For this reason the best way is to create a number of web pages that let the visitor accomplish these tasks. These pages can be developed from scratch by a skilful programmer using the Subscription API but it is much easier to use one or more of the server controls distributed with the product.

Any subscription system is useless unless visitors can subscribe to your newsletters. An administrator can manually add and remove subscribers but this is, of course, very unpractical. The best way to let visitors subscribe to your newsletters is to create a number of web pages that let the visitor accomplish this. These pages can be developed from scratch by a skilful programmer using the Subscription API but it is much easier to use the server controls distributed with the product.

SubscriptionManager

This control displays a list of categories a visitor can subscribe on. The subscriptions can either be activated directly or via a confirmation mail message. If you choose to require activation mails you must also develop a confirmation mail message document and a activation document. Activation mails using the built-in functionality requires that the SMTP settings are correctly configured. For more information about this control and how to configure it see the SubscriptionManager control documentation.

SubscriptionAction

This control when placed on a document performs an actions on a specific subscribers subscription when the page is loaded. These actions are; remove, activate and deactivate the subscription. The subscription is identified by a very long and unique identifier

SubscriptionRemover

This control displays a list of all categories that a specific user has subscriber to. A visitor can check all subscriptions to remove and have them removed. The control supports sending a confirmation mail message containing a link to a page that contains the SubscriptionAction control set to remove passed in subscriptions. Confirmation mails using the built-in functionality requires that the SMTP settings are correctly configured. For more information about this control and how to configure it see the SubscriptionRemover control documentation.

SubscriptionMarker

This control us primarily used on pages used as regular subscription mail or confirmation mail messages. The control inserts a marker that will be replaced with the actual user data when the confirmation mail is sent out.

SubscriptionLink

This control inserts a link with subscription identifier data in regular subscription mail or a confirmation mail message. The generated link contains one or more query string elements needed by the SubscriptionAction control. When the mail is sent out the mail handler inserts the correct link with the unique subscription data for the subscriber.

SubscribableCategoryCheckBox

This control displays a checkbox representing a subscribable category. When added to a page, the developer can select the category to use from a list of categories that are enabled for subscription. The SubscriptionManage and SubscriptionRemover controls make extensively use of this control. Use this control when you develop your own subscription applications.