Integrating Adobe DPS (2015) in WoodWing Enterprise

Info: Adobe AEM was formerly known as Adobe DPS (2015).

The functionality of uploading content from WoodWing Enterprise to Adobe Experience Manager (AEM) by using InDesign is provided through an Enterprise Server plug-in together with the use of Smart Connection plug-ins.

This article describes how to integrate Adobe AEM in WoodWing Enterprise.

Note: If you are looking for steps to integrate the Adobe Digital Publishing Suite, see Integrating Adobe DPS in Enterprise Server 9.

Compatibility

Publishing content from WoodWing Enterprise to Adobe AEM requires the following to be installed:

• InDesign CS6 or Adobe InDesign CC 2014, containing the latest version of the Adobe Digital Publishing plug-ins.
• Smart Connection CS6 for InDesign (v8.3.13 or higher) or Smart Connection CC 2014 for InDesign (v10.0.3 or higher)
• Enterprise Server 9.6 or higher

Steps to perform

Steps need to be performed to install the necessary software and to configure Enterprise Server.

Note: It is assumed here that: An Adobe subscription account for using Adobe AEM is available. Enterprise Server and Smart Connection are already installed and fully working. The installation is performed on a system with an instance of Enterprise Server in which Adobe AEM has not been integrated. If it has been integrated, some steps may have already been performed.

Adobe steps

1. Obtaining a unique Adobe AEM API key and secret

2. Creating a user role specific for the integration

3. Creating a Device Token and Device ID

Enterprise Server steps

4. Installing the crossdomain.xml file

5. Making the PHP ZIP Module available

6. Activating the Adobe AEM license

7. Installing and configuring the Enterprise Server plug-in

8. Setting up Enterprise Server Jobs

9. Setting up a Publication Channel

10. Setting up Multiple Device support

11. Registering Adobe AEM and the Publication Channels

12. Enabling the e-mail feature

13. Defining the Adobe article file format

14. Setting up Workflow Statuses

15. Making the "Upload Status" column available to Smart Connection users

16. Adding custom metadata

17. Adding custom metadata properties to dialog boxes

18. Testing Enterprise Server

19. Testing the upload to Adobe AEM

20. (Optional) Logging the communication with Adobe AEM

1. Obtaining a unique Adobe AEM API key and secret

Every Enterprise customer requires a unique Adobe AEM API key and secret from Adobe.

This can be obtained by sending an e-mail to wwds@adobe.com.

2. Creating a user role specific for the integration

Step 1. In the Adobe AEM Portal, create a role (specific for the integration) and grant the role to an Adobe ID.

Note: It is advised not to use an Adobe ID with a Master Admin role granted to it.

Step 2. E-mail the Adobe ID to wwds@adobe.com for whitelisting.

3. Creating a Device Token and Device ID

To connect Enterprise Server with Adobe AEM, a Device Token and Device ID are required.

Create these by using the Adobe AEX tool.

4. Installing the crossdomain.xml file

Creating the content for the publication is done in InDesign by using the Digital Publishing Tools panels which are part of Smart Connection for InDesign.Some of these panels (such as the Widget panel) need to receive information from and send information to Enterprise Server. This communication is established through the crossdomain.xml.

Step 1. Download the crossdomain.xml file from the software download page (click on either 'Enterprise Server Innovation' or 'Enterprise Server Maintenance').s

Step 2. Unzip the file and place it in the root of your server.

Example: /Applications/MAMP/htdocs/<server name> /var/www/html/<server name>

5. Making the PHP ZIP Module available

The Adobe DPS (2015) Server plug-in makes use of the ZIPArchive class of the PHP ZIP Module, which therefore needs to be installed.

• For Linux/Mac OS X: Compile PHP with ZIP support by using the --enable-zip configure option.

Note: If you have valid reasons not to (re)compile PHP, please use this alternative method. Show me When PHP is not compiled with the --enable-zip option, the Adobe DPS (2015) Server plug-in falls back on the Info-ZIP command line tools (zip and unzip). For Mac OS X these tools are pre-installed so no further steps are therefore needed. For Linux, make sure that these tools are installed: Step 1a. Open the Terminal and enter the following command: zip When you see the help page starting with Copyright (c) 1990-2008 Info-ZIP, then the ZIP tool is already installed and no further steps are needed. When you see an error: The program 'zip' is currently not installed, then the ZIP tool is missing. Continue with the next step. Step 1b. Enter the following command: sudo apt-get install zip

• For Windows: No installation is required; the ZIP extension is built into PHP (since PHP 5.3).

6. Activating the Adobe AEM license

In order for Smart Connection users to use the Digital Publishing Tools panels, activate the Digital Magazine license in Enterprise Server:

• Smart Connection CS6 for InDesign: activate the license named "Digital Magazine (8)"
• Smart Connection CC 2014 for InDesign: activate the license named "Digital Magazine (10)"

7. Installing and configuring the Enterprise Server plug-in

Step 1. Access the download page for the latest version of "Enterprise Server Innovation" or "Enterprise Maintenance", depending on the version used. The pages can be accessed from the Software Release page.

Step 2. Extract the file.

A folder named "AdobeDps2" is created.

Step 3. Place the folder in the following location:

<Enterprise Server path>/config/plugins

Step 4. In Enterprise Server, access the Server Plug-ins page.

Step 5. Locate the plug-in named Adobe AEM and verify that it is enabled, as indicated by the green Plugged In icon .

Note: In case it shows a different icon such as the Unplugged icon , click the icon to activate the plug-in.

Step 6. (Optional, only required when Adobe has informed you that they have changed their paths to the Adobe AEM Distribution Service.) Open the file <Enterprise Server path>/config/plugins/AdobeDps2/config.php in a plain-text editor and check that the following URLs have not been changed by Adobe during the beta phase:

• Authentication Server URL: https://ims-na1.adobelogin.com
• Authorization Server URL: https://authorization.publish.adobe.io
• Producer Server URL: https://pecs.publish.adobe.io
• Ingestion Server URL: https://ings.publish.adobe.io

Step 7. Test Enterprise Server by running the Server Plug-ins test on the Health Check page.

8. Setting up Enterprise Server Jobs

The actual process of uploading content to Adobe AEM is performed by Enterprise Server Jobs.

Step 1. Make sure that Enterprise Server Jobs are fully set up and configured.

Step 2. In Enterprise Server, access the Enterprise Server Job Config page.

Step 3. Verify that the Job named "AdobeDps2" is listed and active.

9. Setting up a Publication Channel

In Enterprise, uploading content to Adobe AEM is done through a Publication Channel.

Step 1. Set up a Publication Channel of type dps2 and Publish System Adobe AEM.

Step 2. Click Create.

An additional section named Adobe AEM appears as well as sections for creating Editions and Issues.

Filling out the Adobe AEM section

Note: The Project field is a read-only field and is automatically filled by Enterprise (this occurs at a later stage during the integration process).

Step 4. From the Default Article Access list, choose from the following options:

• Metered. Enables a user to preview an article for free, but only as long as the total number of free articles that can be viewed for that publication has not yet been reached. Once that total is reached, the user is prompted to purchase the publication or a subscription.

Note: Setting the total number of free articles is done in the account administration panel of Adobe AEM.

• Protected. Protects the story from sharing it through social media in the following ways:

• Viewing a representation of the story in a desktop browser.
• Sharing the story through Facebook, Adobe AEM, e-mail and by Copy Link.

Sharing is done by making a URL available:

• For unprotected stories, this URL links to a representation of the story which can be viewed in a supported desktop browser or on a smartphone or tablet.
• For protected stories, this URL links to the publication URL (a URL that contains information about the publication).

• Free. Makes the story available to all users for free.

Step 5. Select the check box Create Collections. This makes sure that when a layout is checked in, a Collection is automatically created when that Collection does not yet exist.

Creating Editions

Editions represent the output device that is published to. In Adobe AEM, output devices are of a generic type such as a smartphone or a tablet, and not for a specific device such as an iPhone 6 or Samsung Galaxy S4.

An Edition should therefore be created for each of these output device types.

Step 6. Create an Edition named phones and an Edition named tablets.

Creating Issues

Step 7. Create one or more Issues.

10. Setting up Multiple Device support

In the previous step, the output devices "phones" and "tablets" were defined in the form of Editions. For each of these devices, exact settings need to be defined such as width, height, the image quality to use, and so on.

Step 1. Decide for each type of output device (phone and tablet) which physical device is the main device to output content to.

Example: You might decide to target the iPhone 6 and the iPad Air 2 as the main devices to output content to.

This means that on these devices the content will fit exactly while on devices in which this content does not fully fit (because their dimensions are different), pillar boxes (vertical black bars to the left and right of the screen) or letter boxes (horizontal black bars at the top and bottom of the screen) are displayed.

Step 2. In Enterprise Server, access the Output Devices Maintenance page.

Figure: The Output Devices Maintenance page.

The devices "phones" and "tablets" are defined by default.

Step 2. Click phones to verify its settings and adjust them when necessary.

Step 3. Click Update.

Step 4. Click the Left Arrow icon to return to the Output Devices page.

Step 5. Repeat this process to verify the settings for tablets.

11. Registering Adobe AEM and the Publication Channels

This step will register the Issue in Enterprise Server with Adobe AEM and connect the Publication Channel to the Adobe Project.

Step 1. Access the Adobe AEM Maintenance page in Enterprise Server.

Step 2. Connect Enterprise Server to Adobe AEM by clicking Register.

Note: Should the registration process fail, test the Enterprise integration as explained in Testing Enterprise Server.

Step 3. On the page that appears, enter the following:

• The API key and Secretas received from Adobe (see 1. Obtaining a unique AEM API key and secret)
• The Device Token and Device ID as created by the Adobe AEX tool (see 3. Creating a Device Token and Device ID)

Step 4. click Register.

Step 5. On the Adobe AEM Maintenance page, click Assign Project for the Publication Channel that needs to be connected to its defined Adobe AEM Project.

Step 6. For the listed Publication Channel, click the link in the column named "Publication Channel". The Publication Channel Maintenance appears. Verify that the Project field is filled in.

12. Enabling the e-mail feature

When uploading content to Adobe AEM fails, an e-mail can be sent to inform the user who checked-in the layout in InDesign. This functionality needs to be configured and the e-mail address of the recipient  needs to be set.

Step 1. Configure Enterprise Server by following the steps in Configuring e-mail notifications in Enterprise Server 9.

Step 2. On the User Maintenance page for the user who checks in the layout, fill out an e-mail address in the E-mail field.

13. Defining the Adobe article file format

A page in an article is essentially an image with optionally interactive objects placed on top of it.

These background images can be exported in one of the following formats:

• JPEG. Default setting.
• PDF. Allows zooming in on the page.
• PNG. Ensures color consistency with any content placed on top of the background (see comment below).

In case a format other than JPEG needs to be used, follow these steps:

Step 1. In the configserver.php file, locate the SERVERFEATURES section.

Step 2. Add or enable the DPSFolioFormat ServerFeature:

new Feature( 'DPSFolioFormat', '<EditionID>, <format>;<EditionID>,<format>' ),

Step 3. Use the following values:

• EditionID: the ID of the Edition (device) to which the issue is assigned. Obtain this from the URL of the Edition Maintenance page.

Example: In the following example, the Edition ID is 45: http://<server path>/server/admin/hpeditions.php?id=45&publ=1&channelid=63

• format: the file format to use. Possible values: PDF or PNG. In case any other value or an empty value is used, the article is exported in JPEG format.

Example: new Feature( 'DPSFolioFormat', '23, PDF;28,PNG'),

14. Setting up Workflow Statuses

Uploading a story to Adobe AEM is done as a 2-step process:

1. The layout is turned into an Adobe article. This is done by checking in the layout with the "Create Adobe DPS Article" check box selected in the Check-in dialog box.

Figure: The "Create Adobe DPS Article check box (A) in the Check-in dialog box.

2. The Adobe article is uploaded to Adobe. This is done when the layout is assigned to a Workflow Status for which in Enterprise Server the "Ready for Publish" option is enabled. As the name implies, normally this option is enabled for a status that is used to indicate that the layout is ready for publishing. Assigning the Workflow Status can be done by saving the layout or by changing the properties of the layout.

Use of the "Ready for Publish" option within an Adobe AEM workflow

The "Ready for Publish" option of a Workflow Status is used within an Adobe AEM workflow for 2 purposes:

1. It triggers an upload of the most recent Adobe article to Adobe when a layout is assigned to the Workflow Status.

2. It controls the default state of the "Create Adobe DPS Article" check box in InDesign:

• When the option is enabled, the check box is selected by default
• When the option is not enabled, the check box is not selected by default

Example: Two Workflow Statuses exist: Status A with the "Ready to be published" option enabled and Status B with the "Ready to be published" option not enabled. When a user chooses Status A in the Check In dialog box, the "Create Adobe DPS Article" check box is automatically selected. When a user chooses Status B in the Check In dialog box, the "Create Adobe DPS Article" check box is automatically cleared.

Configuring the Workflow statuses

Do the following: 

• For each Workflow Status for which the created Adobe article needs to be uploaded to Adobe, enable the "Ready to be published" option.
• For all other Workflow Statuses for which no upload should be performed (such as when working on the content), disable the "Ready to be published" option.

Figure: The Workflow Maintenance page for layouts where the "Ready to be Published" option is set for the Workflow Status named "Ready".

15. Making the "Upload Status" column available to Smart Connection users

Uploading a layout to Adobe AEM is done in the background by Enterprise Server. The progress of this process can be verified in the "Upload Status" column in the Smart Connection panel in InDesign.

This column needs to be made available to Smart Connection users by configuring it in Enterprise Server. Do this by adding the "* Upload Status" column through the Dialog Setup page, as explained in Adding properties to the Smart Connection panel in InDesign and InCopy.

16. Adding custom metadata

When an InDesign user creates certain content such as adding a Slide Show or audio files, Enterprise needs to know which files are to be included. This is done by setting the "Intent" property of these files.

This property therefore needs to be made available.

Step 1. In Enterprise Server, access the Metadata Maintenance page.

Step 3. Scroll to the bottom of the page and click Add Custom Property. The Custom property page appears.

Step 4. Add the property:

Name: INTENT

Display Name: Intent

Assigned to: images

Description: Used for defining the intent with which an object is to be used.

Type: List

Default value: blank

Values:

Note: All values should be written in lower case.

• Blank. Add a blank value (by pressing Return) as a way for users to choose the option of 'none'.

• play audio. Used for images; it specifies that the image is to be displayed when an audio file is played. Multiple images in a Dossier can be assigned this intent. When a set of images is used, this results in an animated play progress. Multiple images are sorted by name.
• pause audio. Used for images; specifies that the image is to be displayed when an audio file is paused. Multiple images in a Dossier can be assigned this intent. When a set of images is used, this results in an animated pause progress. Multiple images are sorted by name.
• slideshow. Used for Slide Show Widgets; specifies that the Widget is to be used for creating a Slide Show with the use of the InDesign Slide Show panel.

Step 5. Click Update.

Step 6. Click the Left Arrow icon to return to the Metadata page.

17. Adding custom metadata properties to dialog boxes

The custom metadata property "Intent" that was added to Enterprise in the previous step needs to be made available to the user. This is done by adding it to the Workflow dialog boxes of the objects for which the properties are to be used.

Example: The property for setting the intent of a image needs to be added to the Properties dialog box of an image.

Step 1. In Enterprise Server, access the Dialog Setup page.

Step 2. In the Brand list, choose the Brand to which you want the properties to be available.

Step 3. Add the properties listed in the table below by doing the following:

Step 3a. From the Object Type list, choose the object listed in the Object Type column.

Step 3b. From the Action list, choose the action listed in the Action column.

Step 3c. At the bottom of the page, click Add Action Property. Options for adding a property appear.

Step 3d. (Optional) In the Order field, enter a number that defines the order in which the property should appear.

Step 3e. From the Property list, choose the property listed in the Property column of the table.

Step 3f. Select the check box for the option Editable and (optionally) for the option Multiple objects (requires Enterprise 9.2 or higher).

Step 3g. Click Add Action Property. The property is added and a new set of options appear for adding another property.

Step 3h. Repeat steps 3a to 3g until all properties in the table are added.

Object Type	Action	Property
Image	Create	*Intent (INTENT)
Image	Set Properties	*Intent (INTENT)
Other	Create	*Intent (INTENT)
Other	Set Properties	*Intent (INTENT)

Note: The custom property named 'Widget Manifest' does not need to be added to a dialog box; it is used internally by Enterprise Server only.

Step 4. (Optional) To enable users to automatically add an image or layout to a Dossier when the file is added to the system, also add the following properties:

Object Type	Action	Property
Image	Create	Dossier (DOSSIER)
Layout	Create	Dossier (DOSSIER)

18. Testing Enterprise Server

Step 1. In Enterprise Server, access the Health Check page.

Step 2. At the bottom of the page, click Clear All.

Step 3. Only select the Adobe AEM test.

Step 4. Click Test.

The test is executed and the result is displayed next to the test. It should display “OK”.

Note: If the test fails, an error is displayed together with instructions for solving it. Follow the instructions and then run the test once more.

19. Testing the upload to Adobe AEM

Step 1. In InDesign, check-in a layout to an Adobe AEM Publication Channel and to a Workflow Status for which the "Ready to be published" option is set.

Step 2. In Enterprise Server, verify on the Adobe AEM Maintenance page that a task has been created and is being queued or processed.

Step 3. In Adobe AEM, verify that the story appears in your Project.

20. (Optional) Logging the communication with Adobe AEM

Enterprise Server talks to the Adobe Publish Web services over HTTP. Log files can be created to inspect the data being sent and received. Requests and responses will be written to the server logging folder using the following name convention:

• <timestamp>_AdobeDps2_<service>_REST_Req.txt
• <timestamp>_AdobeDps2_<service>_REST_Resp.txt

IMPORTANT: Because of performance reasons, please make sure to disable this option when taking Enterprise into production.

To log the communication between Enterprise Server and Adobe AEM, perform the following steps:

Step 1. In the configserver.php file, locate the LOG_DPS_SERVICES option and set it to "true".

<Enterprise Server path>/config

// LOG_DPS_SERVICES:
//    Used for logging DPS Web services in the service log folder. 
//    When enabled, DPS requests fired by Enterprise Server to Adobe 
//    DPS Server and the corresponding responses are logged. 
//    Adobe DPS is a so called REST server. 
//    The REST services are logged in the service folder
//    (in OUTPUTDIRECTORY/soap) and have an AdobeDPS_ prefix 
//    and a .txt file extension. By default, this log feature 
//    is disabled. It can be temporarily enabled to
//    troubleshoot DPS traffic.
//    
define ('LOG_DPS_SERVICES', true);

Step 2. Enable error logging for Enterprise Server through the configserver.php file and set and set the DEBUGLEVEL option to "DEBUG". (See Logging Enterprise Server 9 activity.)

Document history

• 10 November 2016: Added step to test Enterprise Server after installing the Enterprise Server plug-in.