Configuring Content Station Aurora for publishing to a custom Publish Channel

Publishing to a custom channel involves publishing the Story in a particular file format to a location where it is picked up and processed in some way. Many different ways of using this exist, but one way would be to publish the Story to a Web CMS environment.

This article describes how to set up a custom channel using an example written in PHP and how to publish it.

Before you start

Before you start, it is recommended to first test the general process of publishing to digital channels in Enterprise Server.

Step 1. Make sure that Enterprise Server jobs are set up including a job queue processor.

Note: It is not needed to set up one of the available default Server Jobs, the publishing process makes use of a user-initiated Server Job.

Step 2. Open any Digital article, click Publish and use the option Send via e-mail to send the article to yourself. Should this not work, troubleshoot this first.

How it works

Every custom channel is configured with an 'endpoint' that Content Station sends messages to when the Story is published.

These messages are sent through the Amazon Simple Notification System, which means that the endpoint needs to be able to accept messages in this format.

Every endpoint will receive 2 types of messages:

• SubscriptionConfirmation. This message is sent when creating the Custom channel is created in Enterprise Server. It confirms that the endpoint is valid and can be used. This allows the endpoint to receive further messages.
• Notification. This message is sent each time a Story is published to the Custom channel. It contains the id, name and an URL of the article, which in this example is downloaded and placed into a folder. In theory an endpoint can do anything it wants to with an article.

Properties

Users can add properties to a Story which can be used by the custom channel to correctly process and categorize the Story.

Component IDs vs embedded HTML

When publishing a story to a custom publication channel such as a Web CMS, any Social or Video component that is present in the story is injected into the article JSON as an HTML snippet.

However, having the HTML snippet only available for these two component types makes the publishing process complex and inconsistent.

This behavior is therefore changed by adding the component ID to the published HTML and PSV files as a separate tag (named data-component-id). This makes it possible for custom integrations to extract specific parts, for example a complete Hero component or a Social component.

This change applies to the following versions and time frames:

• From 2 October 2019 to 30 November 2019: 
• The component ID and embedded HTML options are available in Content Station 11.48 and higher.

• From 1 December 2019: 
• The embedded HTML option is removed and not available for any version of Content Station.
• The component ID option is available in Content Station 11.48 and higher.

How to use it

The following process is used to receive messages on this example:

custom-channel-2.0.1.zip (800Kb, February 2019)

Info: Using this sample project requires PHP version 5.5.0 or higher (needed by the AWS PHP SDK).

Step 1. Place the example project on a Web server or any other place where it can be hosted and accessed publicly.

Note: Set the public folder as your document root. When simply copying and pasting the project to your document root, all endpoints have to be prepended with '/public'.

IMPORTANT: A directory named '/public/stories' is needed where articles can be downloaded to and read from by this example; the code will not work when this directory cannot be read or written to.

Step 2. Run './composer.phar install' and resolve any missing dependencies.

Step 3. Set up the Custom channel by following the steps below.

Step 3a. In Enterprise Server, access the Management Console for Content Station.

Show me how

Click Integrations > Content Station

Step 3b. In the menu, choose Publish Channels.

The Publish Channels page appears showing all Brands. When selecting a Brand, all Publication Channels for that Brand appear.

Step 3c. From the Channel list at the top of the page, make sure that Custom channel is selected.

Step 3d. Click Add Channel.

Step 3e. Fill out the details.

Note: Your changes are automatically saved.

• Name: The name you want to give this channel. This name will appear in the list of Publish channels that the user can choose from.
• Target name: The name of the type of target you want to publish to. The user interface will group channels with the same Target name in the Publish dialog.
• Endpoint URL: The URL that SNS messages will be posted to. This needs to link to the /story/add endpoint located on the public host mentioned in step 1.

Note: When custom data is added (see below), the endpoint needs to use HTTPS and needs to be able to verify the origin of the SNS message (see the Amazon documentation Verifying the Signatures of Amazon SNS Messages).

• Reference images by ID only (actual images will not be sent). Select this option when only a reference to any images in the story need to be included, not the actual images.
• Export formats. Choose the format into which you want to export the story: JSON, HTML or PSV.

Note: The PSV format is the recommended format. This file, based on Prism and with the extension .psv, contains the structure, properties, content, design and related files of the Story. For more information, see the documentation on idealliance.org. For information about the mapping between the Digital article components and the prism fields, see Mapping between Digital article components in Content Station Aurora and PSV classes.

• Custom data. (Requires Content Station 11.15 or higher) Use this option to add additional data that is required for the channel to publish the story. A typical example would be to include authentication or security information.

• Maximum width and height for Elvis images. (Requires Content Station 11.49 or higher, see Optimizing images for publishing a Digital article in Content Station Aurora) Elvis images that are published to a digital channel and which have a format bigger than 2500 x 2500 pixels are automatically downsized to that format. To change this format, set a custom width and/or height.

Step 3f. Click outside any of the fields to have the channel automatically created.

Step 4. Create a Story in the Digital editor and publish it to the custom channel. (See .)

Document history

• 16 October 2019: Updated step 3e in section 'How to use it' by adding 'Maximum width and height for Elvis images'.
• 7 October 2019: Added section 'Component IDs vs embedded HTML'.