Scripting on the Server

Server requirements

Only Pro editions of PersonalEffect include the Adobe InDesign Server which is required to run InDesign scripts. Therefore, InDesign scripts cannot be run on XLIM-only servers.

Licensing the server

The ability to use InDesign scripts on the XMPie server requires an optional license that can be purchased from XMPie. The Advanced Output Control license needs to be installed in the uProduce dashboard by an admin user.

Browse to the uProduce dashboard and log in as an admin user.
Click the Settings button and select License Manager from the list of options on the left.
In the License Key field, paste in the license key provided for the scripting plugin.
Click the link to get an activation key.
Your machine id and license key should be preset. Click Get Activation Key.
Copy the activation key.
Return to the uProduce dashboard, paste in the activation key and click the install button.

Copying or packing the script for the server

On the uProduce server, InDesign scripts file should be in the InDesign document's "Resources" folder. The location of the Resources folder is based on the Account ID, Campaign ID and Document ID on the server. For example: C:\XMPie\XMPieData\00\000\000\Resources

To avoid mistakes it is recommended to package the script file in the Document Package (DPKG) or Campaign Package (CPKG) that you upload to the uProduce Dashboard. To do achieve this:

Save or copy your JSX script file next to the InDesign document in the desktop environment,
Select Export Package from the Dynamic Content menu and select a relevant package type.
uCreate Print will automatically pack the JSX file with the document (it simply scans all JSX files placed next to the document and packs them).
When the package is uploaded to uProduce, the script file is automatically saved to the correct location.

Options for running a script on the server

Running InDesign scripts on the server can be done in any of three ways:

Directly with InDesign server, via its port
As part of customization dials
As part of the "Custom Output" feature

Each method fits a different scenario, but all are common in being able to execute InDesign scripts.

Running directly on InDesign server

As part of the Adobe InDesign Server infrastructure, you can direct calls to InDesign server through the SOAP protocol. Discussing this option is outside of the scope of this document. Information about this method is available from the InDesign Scripting SDK from Adobe’s Web site:

https://helpx.adobe.com/au/indesign/using/indesign-server.html

Running from Customization Dials

It is possible to run scripts as part of the content object customization behavior in uStore. Similarly, uProduce REST API can also use the content object customization feature to run InDesign scripts. This allows you to extend the customization capabilities beyond what is supported by XMPie content objects, and in fact customize a document to any extent that is available through InDesign scripting.

Note: When running InDesign scripts via customization dials, uProduce will automatically disable global caching for the job. The reason for this behavior is that the script may change design elements and there is no guarantee that they will be consistent among jobs.

An example for why you might want to run scripts as part of the customization process, could be that you wish to color a box based on a variable/customizable color value. Using a regular Style content object requires you to define each possible color in the InDesign swatches panel. If you want to allow for a large number of color values (like the full RGB or CMYK scale) this would be an overwhelming task. However, it is possible to script the color change.

It is possible to run scripts at the start or end of the XMPie production process by setting the appropriate name of the ADOR or content object that you use as the customization dial.

InitialScriptFileName and InitialScriptParameter

Scripts that run at the start will be run immediately after the document is opened by uProduce and before any other XMPie tasks. Modifications performed by this script can affect the output generated for all recipients in the job.

Optionally, a second script can be run after the XMPie production and before the InDesign document is closed. The purpose of this script file is to perform cleanup operations if needed.

To run a script in the beginning of the job, define two Text content objects in your plan:

InitialScriptFileName
InitialScriptParameter

You should set them as campaign dials to make them visible as customization options in uStore. The customization value for InitialScriptFileName provides a script file (JSX) name reference (like myscript.jsx).

You can provide a parameter to the script, with which you can further parameterize the customization (other than the choice of customization script). You can later get the parameter in the script by using this code:

var custParams = app.scriptArgs.getValue("CUST_PARAMS");

FinalScriptFileName and FinalScriptParameter

If you also wish to have a cleanup method, once the job finishes, for any actions carried out in the initial script you can define the following:

FinalScriptFileName
FinalScriptParameter

Similarly to the "Initial" scripts, the FinalScriptFileName denotes a name of a script file, and FinalScriptParameter is a parameter that can be passed to it for further parameterizing the cleanup action.

Setting customization dials via uStore

After creating the script file and packaging it to the uProduce server, add the dynamic document to uStore in the usual way.

On the customization step of the dynamic document setup, you will need to add the specially named content objects to the customization step. You can use any of the standard uStore dial features. For example, you can set and hide the required values, or show your customer/shopper a user control that allows them to select the file name and/or parameters to send to the script.

For our color selector example, the customization step could allow the customer to select a color and the value of the color be passed to the script in the InitialScriptParameter dial while the InitialScriptFileName dial is preset with the name of your script file and hidden from the customer.

Setting customization dials via API

If using the uProduce REST API, you have full control over the job ticket and can set customization dials to set the required script name and parameters.

Running from the Custom Output feature

The uProduce REST API provides a feature to allow custom output types from InDesign, that are not available in the list of XMPie output formats. This is enabled by using InDesign scripting to export or save the required document format instead of using the XMPie output mechanism. Since this offers another method to run an InDesign script, there is also the opportunity to use the script to make other structural changes to the document during the process.

Note that accessing the custom output feature requires the use of the API and is not accessible via the uProduce dashboard or uStore.

Custom output provides two options for running InDesign scripts:

Per-record scripting – the ability to run InDesign scripts on a per-record or recipient basis after the XMPie personalization takes place. This enables you to manipulate the document further than XMPie's personalization allows. For instance, you could add elements to the page based on the amount of space left by a dynamic table.
Script creates output – the XMPie production engine does not emit any Print output files. Instead, you can use the script to export or save any kind of output that InDesign supports. You can do this on a per-record basis or create batch output by emitting the output in a finalization script.

The XMPie infrastructure automatically provides the script with information such as the following:

Output folder – in which the produced files are to be placed.
Recipient information – to create personalized manipulations.
State information – a simple pass-through string, to allow the script to maintain its state between the production runs.

As with other output formats, you can still use "Job Start" and "Job End" scripts. This becomes valuable if you require some initialization or cleanup. Another possible use is to create batch output through the script, such as a single PostScript output for all recipients, instead of a single per‐record kind of output. In this case, use the "Job Start" or "InitScriptFile" script to generate a header, the Per‐Record or "RecordScriptFile" script to provide the recipient code, and the "Job End" or "FinalScriptFile" script to finalize the PostScript code.

Using custom output

To use the custom output production, follow these steps:

Create the RecordScriptFile that will be run for each recipient. The script should assume that it is running after the XMPie personalization has already taken place. Any modifications that the script makes to the document will not be maintained for the next recipient.
Write an application using the uProduce REST API to submit a custom output job. The JobTicket Output Format should be set to "CustomScripting" using the Output Format ENUM.
Add the InDesignScripting object to the JobTicket Output to set the location of the scripts to be run:
1. InitScriptFile (optional) – run once at the beginning of the job after opening the InDesign document and before any XMPie document analysis begins. This script allows you to modify the document for purposes of this specific job.
2. RecordScriptFile – run for each record in the recipient range, after the XMPie population and composition takes place, and instead of the XMPie output creation stage.
3. FinalScriptFile (optional) – run once at the end of the job for any clean up required.

If needed it is also possible to pass user data to the script by using the ScriptUserData parameter of the InDesignScripting object.

Script parameters

The InitScriptFile and FinalScriptFile scripts allow you to take advantage of special parameters beyond the regular InDesign scripting variables and functions available to any InDesign scripting. The following paragraphs describe which parameters are available to these scripts, and how to retrieve them.

InitScriptFile and FinalScriptFile parameters

These scripts may use the following parameters:

User data – all scripts may pass state data with the ScriptUserData parameter. This parameter is a string, initially passed by the job ticket, but it may be modified by the scripts.

To get the userData parameter, use the following code:

var userData = app.scriptArgs.getValue("UserData");

To set the userData parameter, use the following code:

app.scriptArgs.setValue("UserData",userData);

This state information can help you to accumulate data. For instance, to provide a total number of pages for the job to display on each page, you can accumulate the number of pages in the state user data information.

Output folder – to use the uProduce "Post Production" services, such as compression and copying to destination, place the output files in the output folder, designated by the OutputFolder Parameter. Note that this parameter is an absolute path to the folder.

To get the OutputFolder parameter, use the following code:

var outputFolder = app.scriptArgs.getValue("OutputFolder");

Output file name – For the InitScriptFile and FinalScriptFile scripts, The OutputFileName parameter value is simply the Job Ticket output file name, as set by the FileName object of the JobTicket Output object.

To get the OutputFileName parameter, use the following code:

var outputFileName = app.scriptArgs.getValue("OutputFileName");

Note that if not set, the Output file name will be the same as the uProduce document name.

Job ID –the ID of the Job associated with this production. This ID may be retrieved through the JobID parameter.

To get the JobID parameter, use the following code:

var jobID = app.scriptArgs.getValue("JobID");

RecordScriptFile Parameters

The RecordScriptFile script can not only use the parameters available to the InitScriptFile and FinalScriptFile scripts, but also some other parameters, which make sense in the context of a particular recipient. This section describes the additional parameters available to the RecordScriptFile: Recipient information, Recipient Record Number, Total visible page count and Output file name.

Note that the Output file name parameter has a slightly different meaning in the context of the Per‐Record script, compared to its meaning in the context of the Job Start (InitScriptFile) and Job End (FinalScriptFile) scripts.

Recipient information – the scripts can use the recipient ADOR values to create personalized customizations. To access the recipient information, use the RecipientInformation parameter as follows:

var recipientInformation = app.scriptArgs.getValue("RecipientInformation");

The RecipientInformation parameter value is a string in an XML format.

A typical recipient information XML string looks like this:
Copy
```
<root>
    <fields count="5">
        <field name="First Name" type="Text">Jane</field>
        <field name="Last Name" type="Text">THOMPSON</field>
        <field name="e-mail" type="Text">jane@net.com</field>
        <field name="Favorite Color" type="Graphic">
            c:\testAssets\Silver.eps
        </field>
        <field name="XMPieRURL" type="Link">
            http://friendly_domain.com/friendly_folder/Jane
        </field>
    </fields>
</root>
```
The root "root" node contains a single "fields" node, with a single attribute named "count", providing the ADORs (fields) count. Each ADOR is designated by a single "field" node, where its text designates the value. Each field has two attributes: "name", which has the ADOR name; and "type", which has the ADOR type. Depending on the available ADORs, the types can be any of the following:
- Text
- Graphic
- Link
- Style
- Tabular
- Visibility
- TextFile
Note that the values of Graphic ADORs and TextFile ADORs are absolute paths.

A table ADOR value is actually another "fields" structure, similar to the form of the root "fields" structure.

InDesign scripting has XML support, so it is fairly easy to access the recipient information. To use XML support with the recipient information XML, use the following code:
Copy
```
var recipientInformation = app.scriptArgs.getValue("RecipientInformation");
var aRoot = new XML(recipientInformation);
```
You can then use XPath methods to retrieve recipient information values. For example:

If you want the fields count (other than using the "count" attribute), you can use the following script:

var fieldsCount = thisRecipientXML.fields.@count;

To get the name of the first field:

var fieldName = thisRecipientXML.fields.field[0].@name;

In this example, to get the second Hobby in the Hobbies table:

var secondHobby = thisRecipientXML.fields.field.(@name == "Hobbies").fields[1].field.(@name == "Hobby")

Recipient record number – to get the current record number, out of the recipients for this batch, use RecipientRecord parameter:

var recipientRecord = app.scriptArgs.getValue("RecipientRecord");

Note that if you are using this parameter in batch production, this is the record number in this particular batch, and not out of all batches.

Total visible page count – to get the number of pages available to this particular recipient, use the DocumentInstancePageCount parameter. This number may change through the usage of visibility ADORs on spreads, OR the Autoflow handling of overflow text.

Note that in the case of visibility spreads, the invisible spreads are moved by the XMPie production code to the end of the document. As such, in the document provided to the script, visible pages are from 0…DocumentInstancePageCount-1 indexes, and invisible pages are from DocumentInstancePageCount to the page count of the document minus 1. Note that particularly when exporting a multi‐page output, it is recommended to export just the visible pages.

The following shows a code example for retrieving the page count:

var pageCount = app.scriptArgs.getValue("DocumentInstancePageCount");

Output file name – the output file name parameter in the Per‐Record script is a bit different from the Output file name parameter in the Job Start and Job End scripts.

Here it simulates a per‐record output production scenario.

The name has the following structure:

<Base File Name> + _r + <Record Index>

For example:

MyDocument_r00001

Where base file name is the name set by the JobTicket Web Service SetOutputFileName method.

If you are using the File Name ADOR option in the Job Ticket, the name will be different: it will be the same as the value of the File Name ADOR for this recipient.

To access the file name parameter, use the following code:

var outputFileName = app.scriptArgs.getValue("OutputFileName");

Once retrieving the output file name, you can now use it in combination with the output folder to create a personalized output. For instance, the following code creates a PDF from the current document:
Copy
```
var thisDocument = app.documents.item(app.documents.length-1);
thisDocument.exportFile(
    ExportFormat.pdfType,
    File( app.scriptArgs.getValue("OutputFolder") + app.scriptArgs.getValue("OutputFileName") + ".pdf")
);
```
Important! Note a key element in this sample, which is how the document is being referred to:

var thisDocument = app.documents.item(app.documents.length-1);

While you would expect that there is just one document running in a single production, technical requirements of the XMPie solution may require more open documents than just the main production document. In order to make sure you have the right document get the reference to it by choosing the document which is the last on the documents list – as the example shows.

Using uProduce REST API to Submit a Job with Custom Output

Running Custom Production via uProduce REST API is not very different from running any output production job. The user simply creates a JobTicket object, sets the production parameters, and submits the JobTicket to production. Therefore, only the differences between regular production and Custom Output production are explained in this section.

Setting a Job for Custom Output Production

To enable Custom Output production, set the JobTicket Output Format to "CustomScripting".

Designating Script Paths

The file path to each script file is defined on the InDesignScripting object on the JobTicket Output object.

RecordScriptFile – the path to the script to be run for every recipient.
FinalScriptFile – the path to the script to be run at the end of the job.
InitScriptFile – the path to the script to be run at the beginning of the job.

Note that the values may be either:

File names – when the file is saved to the document's resources folder on the uProduce server or packaged and uploaded to the server as part of a document or campaign package file. Or,
Absolute paths as expressed as URLs. For example, the path to c:\userScripts\test.jsx should be: "file:///c|/userScripts/test.jsx".

Important! Note the 3 forward slashes and how a drive is defined. It is critical to define the URL in this manner, otherwise the script file will not be found.

Note that when using absolute paths, if you have a uProduce Cluster, that includes more than one uProduce production server, the path must be the same on all uProduce Servers, and the script must be installed on each Server.

Passing State Information

The scripts may use the UserData script parameter to retrieve and set state information.

The initial value of this parameter may be set via the ScriptUserData parameter of the InDesignScripting object in the JobTicket.

Error reporting

Sometimes you might want your script to fail production. For instance, if your script expects an even number of pages, but the document actually contains an odd number. In that case you would like to fail production and specify the reason for the failure.

To do that use the JavaScript throw command. For example:

throw("Odd number of pages is unsupported");

The code above will fail production and provide the message as a production error visible in the uProduce Job Center.

In addition to planned error conditions thrown as part of your script, any other coding errors that cause the script to fail will also be reported in the same way.

Each error message displays the script name and the parameter string. If available, the error description will be shown, or just the error code number if no description is available.