Setting up InDesign Server Automation in Studio Server

Content for a publication is generated by various team members using different applications: Studio, and Studio for InDesign and InCopy.

When users work on a file that is placed on a layout such as an article or an image, they can view a preview of the layout on which that file is placed to verify the end result.

However, generating a new preview of the layout that shows the changes that the user made is an action that is performed by InDesign and involves opening the layout and saving it back to Studio Server. Especially for users of InCopy and Studio this is not very practical: it would be time consuming, require InDesign skills and additional InDesign licenses.

Additional tasks that are performed by InDesign (such as generating thumbnails or PDFs, typically done when a file is saved) can also be very time consuming. Instead of manually performing these tasks by using the InDesign client they can be automated by implementing InDesign Server Automation.

Handing off the process to InDesign Server

When a large InDesign Server farm with plenty capacity is available, the tasks of generating previews, thumbnails, or PDFs can best be handled by the InDesign Server instances of that farm. This way, all users have an updated layout preview available shortly after the edited file is saved and waiting times for tasks such as checking-in a layout in InDesign is much reduced.

When to offload?

You would not offload tasks to InDesign Server when:

• Insufficient capacity exists on an InDesign Server farm or no InDesign Server farm is installed at all.
• InDesign client runs on a fast machine and is connected to a fast LAN.

You would offload tasks to InDesign Server when:

• InDesign client runs on a slow machine or runs on a remote location.
• Layouts are very frequently saved or article or layouts are always automatically saved to Studio Server instead of saving them locall\.
• Layouts have many pages (such as books) and/or vary for many Editions.
• PDF (or EPS) files must be provided for layout versions (for all Workflow Statuses).
• Previews and PDF files should be produced or updated on every applicable status update. If InDesign Server is not used, updates are only done when layouts are created or saved by the InDesign client.
• Previews and PDF files should be produced or updated when an article or image that is placed on the layout is updated. If InDesign Server is not used, updates are only done when layouts are created or saved by the InDesign client.

How it works

The process is as follows:

• The machine running idsjobindex.php is continuously watching the InDesign Server Job queue.

• It will try to match jobs with InDesign Server instances. A match will be made when the job is still TODO and when an InDesign Server instance is available that matches the min/max versions specified for the job.

• When a match could be made, the InDesign Server Dispatcher will start the InDesign Server Job Processor. The processor runs on another PHP process and is started by the dispatcher with the help of cURL.

• Like the dispatcher, the processor runs within the idsjobindex.php module. It receives the InDesign Server instance and the job to process through its URL. In other words: you only have to configure the dispatcher which will start the processors for you.

• The processor will run the InDesign Server job and wait for InDesign Server to complete. Once completed it will update the job with a new status, script logging and/or error information.

• When a layout file is opened for editing by an end user at the time the job is started while the job wants to update the layout, it will fail and put the job into a 'Locked' status.

• When the layout is checked-in again, the job status will be set to 'Replanned' again.

• When there is no InDesign Server instance found for a job, the status will also be set to 'Unavailable'.

• When the scheduler is at end of life time (after 1 minute) it will check which of the jobs with status 'Unavailable' can be set back into the 'Replanned' status.

• When jobs fail for other reasons they may be retried up to 3 times. When all have failed, the Error status will change to 'Fatal' to indicate that the job will not be executed anymore.

• When successful, the job status will be set to 'Completed'.

Identifying actions that are triggered by the InDesign Server Automation

Info: This feature requires Studio Server 10.72.0 or higher.

When an action is run by the InDesign Server Automation, there may be a need by other processes to know that it was triggered by that system.

For this purpose, a label with key scriptName and value indesignserverjob.jsx is added at the beginning of each script that is run by the InDesign Server Automation:

app.insertLabel("scriptName", app.scriptArgs.get("indesignserverjob.jsx"));

Event listeners and other InDesign Server scripts can read the label using the app.extractLabel("scriptName")call.

Just before the script ends or when the job fails, the label is cleared by setting it to an empty string.

Installation and configuration

Info: Performing the described steps requires direct server access. Depending upon how your system is hosted and the level of access you have to that system, coordination may be required with your Partner or WoodWing Support team. For a full overview of the steps that need to be done by WoodWing and how to request them, see WoodWing Cloud - Change management.

To make use of the InDesign Server Automation feature, perform the following steps.

1. Enable the Studio Server plug-in
2. Install and configure InDesign Servers
3. Install a Scheduler
4. Configure the Scheduler for the InDesign Server Job Dispatcher
5. Configure preview and output generation
6. Configure when the InDesign Server Automation should not be triggered

Step 1. Enabling the Studio Server plug-in

The feature is provided by an Studio Server plug-in named InDesign Server Automation which is shipped with Studio Server. Enable this plug-in on the Server Plug-in page in Studio Server by clicking its icon.

Access this page by doing the following:

In Studio Server, click Server Plug-ins in the Maintenance menu or on the Home page.

Step 2. Installing and configuring InDesign Servers

Make sure that InDesign Servers are installed and configured in Studio Server. See Configuring the Studio Server instance for InDesign Server to log in to.

Step 3. Installing a Scheduler

Step 1. Make sure that cURL is installed.

Step 2. Use a scheduler of your choice.

• CronniX for macOS. CronniX is a GUI for Crontab and makes its configuration a little easier. Crontab is pre-installed on macOS. CronniX can be downloaded from https://code.google.com/archive/p/cronnix/.

Note: Alternatively, you can skip the CronniX installation and use Crontab directly, but then please follow the configuration instructions written for Linux.

• Task Scheduler for Windows. Task Scheduler is pre-installed for Windows. No further action is therefore needed.

• Crontab for Linux. Crontab is pre-installed for Linux. Therefore, there is no further action needed.

Step 4. Configuring the Scheduler for the InDesign Server Job Dispatcher

Step 5. Configuring preview and output generation

The generation of preview files and output files can be configured on the following levels:

• Per client type: InDesign or InDesign Server
• For local or remote clients

Preview and output generation is triggered when:

• An article, image, Layout Module or spreadsheet that is placed on a layout is saved to Studio Server.
• A layout is saved to Studio Server in a status for which the Output option is enabled while the configured processing tasks differ between InDesign client and InDesign Server (see the CLIENTFEATURES option below).
• The status for a layout is changed (for example through Set Properties) into a status for which the Output option is enabled.

Setting up this environment involves various configuration steps in Studio Server.

Step 1. Open the configserver.php file (recommended: config_overrule.php file) for your Studio Server installation.

Step 2. In the Remote users section, define which client users should be treated as remote users or local users.

Step 2a. Define the IP addresses of the users who should be treated as a remote user under the INCLUDE option (for details about defining these addresses see below):

define( 'REMOTE_LOCATIONS_INCLUDE', serialize( array(
)));

Step 2b. Define the IP addresses of the users who should be treated as a local user under the EXCLUDE option (for details about defining these addresses see below):

define( 'REMOTE_LOCATIONS_EXCLUDE', serialize( array(
))); 

Defining IP addresses

Use any of the following notations:

define( 'REMOTE_LOCATIONS_INCLUDE', serialize( array(
'192.0.0.1'
)));

define( 'REMOTE_LOCATIONS_INCLUDE', serialize( array(
'192.268.0.1',
'2001:db8::/64'
)));

Step 3. In the CLIENTFEATURES section, define which processing tasks need to be performed by InDesign and which by InDesign Server.

This is done by configuring two arrays: one for InDesign client and one for InDesign Server. In each array, define the processing tasks (if any) that need to be performed. (For a list of tasks that can be added, see the end of this step.)

define ('CLIENTFEATURES', serialize(array(
	'InDesign' => array(
		'local' => array(
			new Feature( 'XXX' ), 
		),
		'remote' => array(
			new Feature( 'XXX' ), 
		),
	),
	'InDesign Server' => array(
		'default' => array(
			new Feature( 'XXX' ),
		),
		'IDS_AUTOMATION' => array(
			new Feature( 'XXX' ),
			new Feature( 'YYY' ),
		),
	),
)));

The following arrays are used:

• For InDesign client:
• local. Controls the features at client level.
• remote. Controls the features at client level based on included or excluded IP addresses (see step 2 above).

• For InDesign Server:
• default. Controls the features used for fallback InDesign Server automations for all InDesign Server custom jobs where no array is defined.
• IDS_AUTOMATION. Controls the features used for the InDesign Server Automation job type (required for native InDesign Server integration).

Note: When the exact same configuration is made under 'local', 'remote' and 'IDS_AUTOMATION', layout save operations will never trigger InDesign Server Automation. However, changing placed content in Studio or InCopy will still trigger it.

define ('CLIENTFEATURES', serialize(array(
	'InDesign' => array(
		'local' => array(
			new Feature( 'CreatePagePreview' ), 
		),
		'remote' => array(
		),
	),
	'InDesign Server' => array(
		'default' => array(
			new Feature( 'CreatePagePreview' ),
		),
		'IDS_AUTOMATION' => array(
			new Feature( 'CreatePagePreview' ),
			new Feature( 'CreatePagePDFOnProduce', '[Press Quality]' ),
		),
	),
)));

Use any of the following features:

new Feature( 'CreatePageEPS' ),

new Feature( 'CreatePageEPSOnProduce' ),

new Feature( 'CreatePagePDF' ),

new Feature( 'CreatePagePDFOnProduce',  '[Press Quality]' ),                

new Feature( 'CreatePagePreview' ),

new Feature( 'CreatePagePreview' ),                 

new Feature( 'PagePreviewQuality', 4),             

new Feature( 'PagePreviewResolution', 200),

new Feature( 'FullResolutionGraphics'),

Step 6. Configuring when the InDesign Server Automation should not be triggered

The scenarios in which Studio Server triggers the InDesign Server automation (such as changing the Workflow status of an object or checking-in a layout without changing the Workflow status) can also occur when other systems such as MadeToPrint, Journal Designer, Claro, and Smart Mover interact with Studio Server.

However, triggering an InDesign Server Automation job by those systems is typically not desired.

Objects can therefore be prevented from being processed by the InDesign Server Automation feature in one of the following scenarios:

• When an object is assigned to a specific Workflow Status
• When a layout is created or changed by a planning tool

Skipping automation based on Workflow Status

In this scenario the automation is skipped when an object such as a layout or article is assigned to a specific Workflow Status.

This method can be used for the following types of objects:

• Articles
• Images
• Layouts
• Layout templates
• Layout Modules
• Layout Module templates
• Spreadsheets

Note: This option only appears when the Studio Server plug-in named 'InDesign Server Automation' is enabled.

Figure: The 'Skip InDesign Server Automation' option for Workflow statuses.

Setting the Workflow status is done on the Workflow Maintenance page.

Skipping pages created or changed by a planning tool

In this scenario, any layout that is created or changed by a planning tool is ignored by the InDesign Server automation.

Configure this by defining the following option:

• File: config.php file (recommended: config_overrule.php file)
• Name of option: IDSA_PLANNED_PAGES_PROCESSING
  
• Possible values:
• true - An InDesign Server Job is created for the InDesign Server Automation to process pages that are created or changed by the Planning tool.
• false - No InDesign Server Job is created; pages that are created or changed by the Planning tool are not processed by the InDesign Server Automation.
• Default setting: false.
• Example:

define ( 'IDSA_PLANNED_PAGES_PROCESSING', false );

Starting InDesign Server

When starting InDesign Server, make sure to include the 'previews' argument so that previews are generated when images are placed.

Note: When leaving out this argument, placed images may appear as gray boxes.

Revisions

• 12 November 2026: Added section 'Identifying actions that are triggered by the InDesign Server Automation'.
• 21 October 2024: Updated section 'When to offload?' by adding 2 bullets about offloading previews and PDF files.