Configuring Studio 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 Studio Server.

Step 1. Make sure that Studio 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 Studio 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:

1. SubscriptionConfirmation. This message is sent when the Custom channel is created in Studio Server. It confirms that the endpoint is valid and can be used. This makes it possible for the endpoint to receive further messages.

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

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 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 Studio Server, access the Management Console for Studio.

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

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

Step 3c. Click Add channel.

Step 3d. 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 Studio and PSV classes.

• Custom data. 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.

Notes: Any type of text can be entered here. Be aware though that the receiving system should be able to recognize and process it. Data can for example be added as: A JWT token A JSON data structure A key value list Because of the sensitive nature of this data, added data will be displayed as placeholder text and not in a readable form. Editing added data is done by adding new custom data to an empty field which will then overwrite the existing custom data. The original data is never displayed.

• Maximum width and height for images in Assets. (See Optimizing images for publishing a Digital article in Studio) Assets 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 3e. 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 Working with Digital articles in Studio.)