The Content Studio Subscription Service gives the web site author the possibility to create powerful text or html based newsletters that automatically are sent out to subscribers according to a specific schedule.
By using a number of new Server Controls it is easy to build web pages where visitors can subscribe and unsubscribe to your newsletters or view their subscriptions.
Each type of subscription (ex. newsletters or price information) are located in their own categories that can be enabled or disabled by an administrator. When correctly set up, every newly created and published document will be sent out to all of the subscribers according to the subscription schedule. When a document has been sent out it will not be sent out again (risk for spam server) unless an administrator forces the document to be re-sent. Additionally, if there are documents in the category when it is set up for subscription, none of the existing documents will be sent out either.

Technical details

In Content Studio 5.2 and later versions the Subscription Service are implemented as an addition to the regular Event Actions subsystem. Five new events have been added to support this.

This event occurs when a document is published. This event is triggered synchronously when a document is published directly. However if the document is scheduled to be published later in time; this event is triggered asynchronously in the background when the Service Manager discovers that the document has been published recently.
This event is similar to the OnDocumentPublish event but it occurs when a document has been archived; i.e. its archive date has been reached.
This event is similar to the OnDocumentPublish event but it occurs when a document is no longer published but not archived; i.e. its publish date date has been set to a future time or the document has been set to be no longer published.
Occurs when the Service Manager has discovered that a document is about to be sent out for subscription. When this event a new job is added that will trigger the event handler that actually sends the document to its subscribers.
Occurs when an administrator tests the subscription functionality of a specific category and a specific document. This event adds a new job for the Service Manager and is carried out by the event handler. on event handler this event might not be implemented by that event handler.

The actual mail sending operation is implemented in a regular event actions asynchronous event handler. Such an event handler is included in Content Studio and will meet the needs of most users. When the Service Manager discovers a subscription job, it calls this implementation to actually carry out the mail sending operation.

Administrating subscriptions from the administrative interface

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.

The subscription properties tab
The subscription properties 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).
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
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=, PublicKeyToken=feea6d4abcd740d9
Normally this value should be left empty to use the built in event handler.
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.

Subscriber dialog
The subscribers dialog.

Sending test messages

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

Subscriber dialog
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.

The subscription schedule
The subscription schedule.

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.

The dynamic property editor dialog
The new advanced property editor dialog used to edit advanced settings.
Important advanced settings
Setting name Value Description
Optional setting that specifies if and what logger to use. (Used by the built in handler and handlers that inherits the SubscriptionEventHandlerBase)
ContentStudio.ServiceManager.Logging.ISysLogWriter A moniker (ex. "Mynamespace.Logging, MySyslogLogger" to an implementation of the ISysLogWriter interface.

The built in implementation of the event handler will log all of its events to the implementation of this interface. To use the built in file logger this value should be ContentStudio.ServiceManager.Logging.FileLogger, CSEventhandlers. If this setting is omitted or has an empty value no logging is performed.

If you specify the default logger you should set the ContentStudio.ServiceManager.Logging.FileLogger.Directory and ContentStudio.ServiceManager.Logging.FileLogger.FileName as well.

If this settings is empty or omitted no logger is used.

Optional settings that configures the built in file logger ContentStudio.ServiceManager.Logging.FileLogger
ContentStudio.ServiceManager.Logging.FileLogger.Directory The full path to the directory (ex. C:\temp\logging) on the server where the default file logger should save its log files. Used only if ContentStudio.ServiceManager.Logging.ISysLogWriter is specified. If not specified and the default file logger is specified the logger writes to the temp directory known to the Service Manager runtime account (i.e. NT Authority\Network Service). Do not forget to check that the Service Manager runtime account (i.e. NT Authority\Network Service) has permission to write to this directory.
ContentStudio.ServiceManager.Logging.FileLogger.FileName The name of the log file that the default file logger should use. If a file name is specified (ex MyLog.log) the logger will append data to this file rather that overwrite the current content.
If this setting is omitted a filename based on the current data and time is generated.
Optional settings that specifies how Content Studio documents are transformed into Html mail messages. (Used by the built in handler)
MultipartMailMessage.MailFormatSettings A comma separated list of the members in the MailFormatSettings enumeration. Default value is Default This setting regulates how Content Studio generates Html mail messages. See the documentation on this enumeration for more information on the individual settings.
Optional settings that specifies settings for the mail server used. (Used by the built in handler)
System.Net.Mail.SmtpClient.DeliveryMethod One of the members in the enumeration. Valid values are Network and Pickup Defines how the mail service sends the mails. The default value is Network and if Pickup is specified System.Net.Mail.SmtpClient.PickupDirectoryLocation must be specified as well.
System.Net.Mail.SmtpClient.PickupDirectoryLocation The directory on the server where the mail server fetches mails to be sent. Should only be specified if System.Net.Mail.SmtpClient.DeliveryMethod is Pickup
System.Net.Mail.SmtpClient.Port A SMTP port number to use. Default value is 25 Only used if System.Net.Mail.SmtpClient.DeliveryMethod is Network and the default port 25 cannot be used for some reason.
Optional settings that controls how mails are sent out. (Used by the built in handler)
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.RecipientFailRetryLimit Integer, default value is 5 Specifies the maximum number of times that the event handler should try to resend a message to a client when there is a non-fatal, temporary error.
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.SmtpFailureLimit Integer, default value is 2 Specifies the number of SMTP failures that is accepted before the handler stops and reports an error.
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.FailureRetryInterval Integer, default value is 5000 (milliseconds) Specifies the interval (in milliseconds) that the handler should wait before it tries to resend a failed message.
ContentStudio.Document.Subscription.EventHandler.MailSubscriptionHandler.MaxNumberOfAllowedFailedRecipients Integer, default value is 100 Specifies the max number of allowed failed recipients allowed before the event handler reports an error and stops.

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.
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.
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.
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

The dynamic property editor dialog
The subscription properties for document dialog.

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.
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.

Developing subscription documents

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.

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.
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
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.
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.
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.
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.