XMPie Scripting Plugin SDK

Introduction

XMPie scripting plug-in is an extension to the Adobe InDesign scripting model. It allows a developer using InDesign scripting to affect XMPie related document properties, such as the plan reference, and to retrieve plan and ADOR information, in addition to the existing InDesign scripting features.

The scripting plug-in may be used both in desktop and server environments, with slightly varying capabilities. It is ideal for automating tasks that create and manipulate XMPie print documents. As opposed to the regular uProduce SDK, the scripting plug-in deals with the document template itself and not with the production functionality.

The scripting plug-in automates the following processes:

  1. The building of an XMPie template from a regular InDesign document, by attaching a plan and automatically adding ADOR objects.

  2. Converting other variable template formats to XMPie template, via constructing the InDesign document and adding the plan and ADOR objects associations. For example, using a combination of MS-Word scripting and InDesign/XMPie scripting you can convert a Word mail merge template to XMPie.

  3. Modifying a document template, including references to ADOR Objects, based on customization logic in a Web-To-Print application.

Use case

Assume that you are working with a graphic designer who does not own XMPie software. The designer is creating some static InDesign documents that you wish to automatically link to a data source or plan file and place ADORs or content objects into the design.

The designer can create the InDesign document and mark placeholders in the design where content objects should be placed. In the text, they can write the content object name surrounded by angle brackets (“<” and “>”). For example, the opening sentence in a mailer may look like this:

Hello <Salutation> <First Name>,

Thank you for registering to our upcoming event…

In this text there are two marks for content objects – <Salutation>, which will denote that person’s salutation (Mr, Miss, Mrs etc.), and <First Name> to refer to the person’s first name.

Once the document reaches you, you are supposed to link that document to a plan, and then associate each of the marks with a matching ADOR Object in the plan. You may have agreed on a set of variable names with the designer, or just built the plan based on their variables usage, or maybe knew which ADOR to use for each of the designer marks. In any case, you must now go through the design and tag each mark with the relevant ADOR objects of the plan.

The XMPie scripting plug-in can assist here, because it can automate the tagging process. In fact, using a combination of the plug-in and uProduce API you can automatically get from a state in which you receive the design to a state where you have the document ready for production on your uProduce server.

The following sections will go through installing the plug-in on the desktop, and writing the script to handle this task. The complete script and a sample document are available with the tech-note materials.

Installation

The XMPie Scripting Plugin is provided as a zipped folder. The plugin is provided for a specific InDesign version and must be installed on the correct InDesign version.

  1. Unzip the folder. You will find the XMPScriptingXXXX.apln plugin file and a folder of resources. (Where XXXX is the InDesign version that corresponds to the XMPie Scripting Plugin version.)

  1. Copy the plugin and resources folder to the XMPie plugins folder:

    • On the computer where InDesign and uCreate Print are installed:

      <install drive>:\Program Files\Adobe\Adobe InDesign XXXX\Plug-Ins\XMPie

    • On the uProduce production server(s):

      <install drive>:\Program Files\Adobe\Adobe InDesign Server XXXX\Plug-Ins\XMPie

  1. Add the XMPie Scripting Plugin license, as described below.

Licensing on the desktop

The XMPie Scripting Plugin is an optional extra which can be purchased from XMPie. The license needs to be installed on the desktop computer with Adobe InDesign and uCreate Print already installed.

  1. Open InDesign.

  2. From the Dynamic Content menu, select Help and then Activate license.

  3. In the License Key field, paste in the license key provided for the scripting plugin and click Activate.

Licensing on the server

The XMPie Scripting Plugin is an optional extra which can be purchased from XMPie. The license needs to be installed in the uProduce dashboard by an admin user.

  1. Browse to the uProduce dashboard and log in as an admin user.

  2. Click the Settings button, and select License Manager from the list of options on the left.

  3. In the License Key field, paste in the license key provided for the scripting plugin.

  4. Click the link to get an activation key.

  5. Your machine id and license key should be preset. Click Get Activation Key.

  6. Copy the activation key.

  7. Return to the uProduce dashboard, paste in the activation key and click the install button.

Create the script

While you can use any text editor to create the script, it is recommended to use the Adobe Extendscript Toolkit which is one of the applications available from the Adobe Creative Cloud subscription. This is the Adobe development environment for writing scripts. It is useful because you can select the Adobe InDesign application as the target application, and run the script, pause, continue and define breakpoints like you would expect from any IDE.

Sample script

The sample script documented here will do the following:

  1. Open the desired InDesign document.

  2. Link the document with a plan file.

  3. Associate all text content objects in the plan with the locations in the document text that matches their name.

  4. Export the document as a document package (DPKG).

Open the document in InDesign and associate it with the plan. At the top of the script write the following variables:

Copy 
var PlanFilePath = "/C/stuff/testPlan.plan";
var DocumentFilePath = "/C/stuff/testDocument.indd";
var targetFilePath = "/C/stuff";
var targetFileName = "testDocumentXMPie";

These variables set up various file references for the script. You will change them for the document that you wish to use the script with (alternatively you can find another method to get the required information).

Note that paths are defined using “Unix” style paths, as is the custom with Adobe scripting.

To open the document and associate it with a plan, write the following:

Copy 
var workDocument = app.open(File(DocumentFilePath));
workDocument.plan.filePath = File(PlanFilePath);

The first line opens the InDesign document, and saves the document reference to workDocument. The second line uses the plan property defined by the scripting plugin to set a reference to the plan file.

The next task is to go over all markups in the design and associate them with the plan ADOR Objects. For the sake of simplicity, we will assume that there are only text markups (for text ADOR Objects), and that the markup names fit the plan ADOR Objects. If the names do not fit, you can code in also some mapping method.

The code does this by iterating the plan ADOR Objects, looking for markups that fit that ADOR, and setting up the ADOR on those markups. Here is how it’s done:

Copy 
var planAdors = workDocument.plan.adors;
for (var i=0;i< planAdors.length;++i)
{
   var planAdor = planAdors [i];
   if (planAdor.objectType == ADORTypes.TEXTADOR)
   {
      app.findTextPreferences = NothingEnum.nothing;  
      app.findTextPreferences.findWhat = "<" + planAdor.name + ">";
      var textsToChangeToADOR = workDocument.findText ();
      for (var j=0;j<textsToChangeToADOR.length;++j)
          textsToChangeToADOR[j].adorName = planAdor.name;
      }
}

The first line retrieves the list of ADOR Objects from the plan, using the adors property of the now associated plan file. It then iterates it. For each ADOR object, it checks that its type is "text" by looking into its objectType property and checking if it is equal to a TEXTADOR which is a member of the ADORType enumeration.

For each text ADOR it uses the findText method of a document, which is a regular InDesign method. It looks for the text “<” + planAdor.name + “>”, which, for example, for the ADOR “FirstName” will look for “<FirstName>”.

The findText method returns a list of results, which are simply range objects in various text contents in the document. This list is iterated, and for each range object, its adorName value is set to the name of an ADOR Object in the plan. adorName property for text range objects is an XMPie property that allows setting an ADOR Object reference to it, or querying for it.

To finish the task, the document is saved as a DPKG. Make sure to save the document prior to exporting the dpkg because the exporting process will revert the document to its initial state:

Copy 
workDocument.Save();
app.createXmpiePackage (targetFileName,
          File(targetFilePath),
          XmpiePackageTypes.LAYOUT); app.activeDocument.close(SaveOptions.NO);

The second line uses the XMPie scripting function createXmpiePackage in order to create a DPKG. The first parameter is the target DPKG file name. The second parameter is the folder path in which the DPKG file is created. The third parameter is the package type which is set to XmpiePackageTypes.LAYOUT, which is a DPKG. You can also pack to CPKG, or XLIM document, as well as other possible XMPie packages.

The last line closes the document. Note that workDocument is no longer used. At this point, since the document is re-opened, it is invalid.

Scripting plugin capabilities review

We learned that you can get and set the plan object for a document, as well as iterate the ADOR objects over a plan. We associated text ranges with text ADOR objects and created an XMPie DPKG. All of these capabilities are added via the scripting plug-in.

The following provides a review of everything that you can do with the plugin. At the end of this document a complete reference is provided.

Document plan

An InDesign document object has a Plan property once the XMPie plug-in is installed. For XMPie documents this property will refer to the plan object. This plan may be either embedded, or a linked plan file. In either case you can use the Plan properties to iterate plan objects. The plan objects are available via 3 properties:

  • Plan ADOR Objects are available via plan.adors

  • Plan Variables are available via plan.variables

  • Plan fields (DB schema for recipient list are available via plan.planFields

In addition, the plan primary field name can be retrieved via the plan.primaryField property.

All these properties make it possible for a person to write general scripts that manipulate documents based on different plans. By using plan information queries one can write a script that, for example, assigns ADOR objects to a document in a pre-determined manner, as demonstrated by the example.

Document placeholders

Using scripting you can also query, add and modify document placeholders, which are the assignments of plans into a document.

Various objects that can potentially have ADOR assignments to them, such as boxes, or layers, or text ranges, have the property adorName once the plug-in is installed. Through this property you can both get and set an ADOR reference. If the property value is an empty string it means that this object is not affected by an ADOR. Objects that can have a Style ADOR affecting them own the property styleADORName (such as boxes and text ranges).

For example, a layer can be assigned a Visibility ADOR, hence the following is valid:

app.activeDocument.layers[0].adorName = “myVisibilityADOR”;

where myVisibilityADOR is a name of a visibility ADOR.

It is also possible to query the document for its ADOR objects based on types. For example, you can get all Graphic ADOR placeholders by calling the following function:

Document.findGraphicAdors()

To find a specific ADOR usage (myADORName):

Document.findGraphicAdors(myADORName)

The  return value is a list of page elements that either have Graphic ADOR Objects or Graphic ADOR Objects with a particular name.

Using similar methods, you can also find all usages of Visibility ADOR, as well as Object style ADOR Objects, with Document.findVisibilityAdors and Document.findStyleAdors.

Copy 
Document.findVisibilityAdors()
Document.findStyleAdors()

The method for finding characters Style ADOR Objects and Text ADOR Objects is slightly different, and goes through the InDesign method of findText.

To look for Text ADOR usages, use this code:

Copy 
app.findTextPreferences = NothingEnum.nothing;
app.findTextPreferences.adorName = "myADORName";
var textsToChangeToADOR = myDocument.findText();

The code sets up find preferences with the particular ADOR name for which we want to find usages, and then executes findText. In turn it will return a list of text ranges using this ADOR.

If you want to retrieve all texts that use ADOR Objects, set the adorName property of app.findTextPreferences to an empty string (“”).

The return values are text ranges, and you can check their adorName property to realize which ADOR Objects they use.

Using a similar method you can find Character Style ADOR usages. Instead of app.findTextPreferences.adorName = “myADORName”, use app.findTextPreferences.styleAdorName = “myStyleADORName”.

Package creation

Last but not least, you can create packages from an XMPie document that is currently the active document. The types of packages that you can create are the same as those that are available via the export option in the XMPie palette menu.

You do this using the createXmpiePackage method that the scripting plug-in adds to the application object. We used this method in the example script like this:

Copy 
app.createXmpiePackage (targetFileName, 
    File(targetFilePath), 
    XmpiePackageTypes.LAYOUT);

As demonstrated then, the first parameter designates the package name, and the second is the folder path in which to place the package. The third parameter denotes the package type, which can be one of the values in the XmpiePackageTypes enumerator:

  1. XmpiePackageTypes.CAMPAIGN – a CPKG, based on the InDesign template.

  2. XmpiePackageTypes.LAYOUT – a DPKG, based on the InDesign template.

  3. XmpiePackageTypes.PROOF – a Proof Set, for cases where the plan is embedded in the document. The Proof Set is generated based on the database link that is currently connected to the document, and the embedded plan.

  4. XmpiePackageTypes.WEBCAMPAIGN – a Web Campaign CPKG. To be used in Hosted eMedia solutions. Contains only embedded plan logic, without the document.

  5. XmpiePackageTypes.XLIM – a XLIM layout document representation of the InDesign document.

  6. XmpiePackageTypes.XLIMCAMPAIGN – a CPKG, based on a XLIM representation of the InDesign document.

  7. XmpiePackageTypes.XLIMLAYOUT – a DPKG, based on a XLIM representation of the InDesign document

Note that this method is available only with the desktop version of the scripting plug-in. So it is possible to execute a code that contains a call to it in uCreate Print environment, but not in uProduce.

Viewing the available commands and constructs

You can see which methods and objects exist in InDesign scripting model in general, and in particular what is added by XMPie, by using the Object Model Viewer of the Extendscript toolkit. When the application is open, press F1 to open the Object Model Viewer window, and select the latest InDesign version from the browser:

You can now review the various objects that are available by the scripting model. Note that both original and XMPie commands and objects exist, each with a reference and description.

How to run the script on the desktop

There are two ways to run the script with InDesign on the desktop:

  1. Use Extendscript Toolkit:

    1. Open the script with Extendscript Toolkit.

    1. Select InDesign as the application.

    1. Run the script.

  1. Use the InDesign Scripts panel:

    1. Open InDesign.

    1. From the Windows menu, select Utilities > Scripts.

    1. Right-click on the User Folder, and select Reveal in Explorer.

    1. Copy your script (JSX) file into the scripts folder and it will become visible in the Scripts panel.

    1. To run the script, double-click on the entry in the scripts panel.

You can also run scripts on the desktop version of InDesign through application interfaces such as AppleScript (on Macintosh) or COM Automation (on Windows).

How to run the script on the server

Running scripts on uProduce is possible on Pro editions of PersonalEffect where Adone InDesign Server is installed. Running scripts (with or without XMPie scripting commands) on the server can be done in three ways, which will be explained in this section:

  • 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 scripts directly on the InDesign server

As part of InDesign server infrastructure, you can direct calls for InDesign server through SOAP protocol. Provided that the XMPie scripting plug-in is installed, those calls may contain XMPie script commands. Discussing this option is outside of the scope of this document. Getting information about this option is possible via the InDesign Scripting SDK available from Adobe’s Web site - https://developer.adobe.com/indesign/.

Running scripts from customization dials

It is possible to run scripts as part of the customization behavior in uStore. Similarly, uProduce REST API and WSAPI users that use the customization feature can do the same. This allows you to extend the customization abilities beyond what is supported by XMPie ADOR Objects, and in fact customize a document to any extent that is available through InDesign scripting. By also having the ability to affect XMPie objects, through the XMPie scripting plug-in, the options are quite limitless.

As an example for why you would want to run scripts as part of the customization process, consider that you wish to provide a box that is colored based on a variable/customizable color value. If you allow for a large quantity of color values (like the full RGB or CMYK scale) you cannot do so with regular Style ADOR Objects, however it is possible to script such a change. With the XMPie scripting plug-in you can customize the identity of an ADOR affecting a certain image box.

Running scripts through Customization Dials is possible by using ADOR Objects (which are customized). To run a script in the beginning of the job, and thus customize the document for the production process, define two Text ADOR Objects in your plan:

  • InitialScriptFileName

  • InitialScriptParameter

You should mark them as 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). This script file should be placed adjacent to the InDesign document on uProduce. To achieve that, you can place that JSX file next to the document on the desktop environment, and once packed as DPKG or CPKG, 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).

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");

Note that in general those scripts DO NOT have to use the XMPie scripting plug-in commands, therefore you can use this option for customizing a document even though you are not in possession of the scripting plug-in. However, to be able to query and setup ADOR Objects in the document, or use any of the XMPie scripting commands, you must have the plugin installed.

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.

Running scripts from the Custom Output feature

The uProduce REST API and WSAPI provide a feature to allow custom outputs, that are not supported by the regular XMPie output formats. Since it is based on InDesign scripting it can also use the XMPie scripting plug-in added functionality, provided that the scripting plug-in is installed. Note that any actions adding ADOR Objects during the main running script (the per-record script) will not be affective, because the ADOR Objects value population phase is passed by then. Therefore, it only makes sense to either query ADOR Objects then, or set them up at the initial script.

XMPie Scripting plugin reference

The following provides reference to the constructs and methods added by the scripting plug-in.

Application object

The application object (available via app) has the following additions through the scripting plug-in:

CreateXmpiePackage method

Copy 
Application.createXmpiePackage(
           name: string ,
           parentFolder: File ,
           packageType: XmpiePackageTypes = XMPiePackageTypes.LAYOUT,
           exportFonts: Boolean = false)

Description

Exports the current document as one of 7 XMPie package types.

Return value

Nothing

Parameters

name: string, The name of the package to be created

parentFolder: File, The folder to contain the package

packageType: XmpiePackageTypes, The package type (Optional)

exportFonts: Boolean, Export fonts and agree to terms and conditions (Optional)

XmpiePackageTypes is an enumerator with the following possible values:

  1. XmpiePackageTypes.CAMPAIGN – a CPKG, based on the InDesign template

  2. XmpiePackageTypes.LAYOUT – a DPKG, based on the InDesign template

  3. XmpiePackageTypes.PROOF – a Proof Set, for cases where the plan is embedded in the document. The Proof Set is generated based on the database link that is currently connected to the document, and the embedded plan

  4. XmpiePackageTypes.WEBCAMPAIGN – a Web Campaign CPKG. To be used in hosted eMedia solutions. Contains only embedded plan logic, without the document.

  5. XmpiePackageTypes.XLIM – a XLIM layout document representation of the InDesign document.

  6. XmpiePackageTypes.XLIMCAMPAIGN – a CPKG, based on a XLIM representation of the InDesign document.

  7. XmpiePackageTypes.XLIMLAYOUT – a DPKG, based on a XLIM representation of the InDesign document

Note that this method is only available with the desktop version of the scripting plug-in.

findTextPreferences properties

Copy 
Application.findTextPreferences.styleAdorName: string
Application.findTextPreferences.adorName: string

Description

The styleAdorName and adorName properties of the findTextPreferences property of the application object set up ADOR placeholder search for a later Document.findText method call. styleAdorName should be set to a string value in order to look for text ranges with style ADOR references. Empty string value will set an all style ADOR placeholder search, while a non-empty value will look for a particular ADOR name. Similarly, adorName should be set to a string value to look for text ranges with text ADOR placeholder references. Make sure to call app.findTextPreferences = NothingEnum.nothing prior to setting the property to make sure all relevant search properties are nulled.

Document object

The document object has 3 methods added through the scripting plug-in, and a “Plan” property.

findGraphicAdors method

Document.findGraphicAdors(adorName:string = ””)

Description

findGraphicAdors retrieves graphic (image) placeholders. Passing empty string will retrieve all graphic placeholders. Passing a string will retrieve all placeholders where the ADOR object is used.

For each placeholder the object that contains them is retrieved, among other properties this object:

  1. ADOR name (Document.findGraphicAdors()[i]. adorName)

  2. Container ID (Document.findGraphicAdors()[i].id)

Return value

List of page items that contain graphic ADOR references

Parameters

adorName: string, Name of the ADOR Object that is being searched. If empty, will look for all Graphic ADOR placeholders.

findVisibilityAdors method

Document.findVisibilityAdors(adorName: string=””)

Description

findVisibilityAdors retrieves visibility placeholders. Passing empty string will retrieve all visibility placeholders. Passing a string will retrieve all placeholders where the ADOR object is used.

For each place holder the object that contains them (either spread or layer) is retrieved. The returned object will have the following information, among the regular properties:

  1. ADOR name (Document. findVisibilityAdors ()[i]. adorName)

  2. Container (spread or layer item) ID (Document. findVisibilityAdors ()[i].id)

  3. The layer name (if layer) (Document. findVisibilityAdors ()[i].name)

Return value

A list of layers and spreads that contain visibility ADOR references

Parameters

adorName: string, Name of the ADOR Object that is being searched. If empty, will look for all visibilty ADOR placeholders.

findStyleAdors method

Document.findStyleAdors(adorName:string = ””)

Description

findStyleAdors retrieves object style placeholders. Passing empty string will retrieve all object style placeholders. Passing a string will retrieve all placeholders where the ADOR object is used.

For each place holder the object that contains them is retrieved, among other properties this object:

  1. Style ADOR name (Document.findStyleAdors()[i]. styleAdorName)

  2. Container ID (Document.findStyleAdors()[i].id)

Return value

List of page items that contain object style ADOR references

Parameters

adorName: string, name of ADOR to look references for. If empty, will look for all object style ADOR placeholders.

Plan property

Document.plan

Description

The document plan property contains a reference to the plan object of the document. If it is an XMPie document it will be a none-null. The plan object information may be retrieved whether the plan is embedded or not.

The plan object has the following properties:

  • filePath: File

    Both set and get property for the plan file path (in case it is an external plan). Plan may be set up through this property.

  • ADOR Objects: ADOR Objects

    List of plan ADOR Objects. For each ADOR Object the following properties are available:

  • name: string, ADOR name

  • dial: bool, indication of Dial property

  • rule: string, plan expression for this ADOR Object

  • annotation: string, description for this ADOR Object

  • objectType: ADORTypes, type of ADOR. Can be one of:

    • ADORTypes.GRAPHICADOR - Graphic ADOR Object

    • ADORTypes.STYLEADOR - Style ADOR Object

    • ADORTypes.TABLEADOR - Table ADOR Object

    • ADORTypes.TEXTADOR - Text ADOR Object

    • ADORTypes.TEXTFILEADOR - Text file ADOR Object

    • ADORTypes.VISIBILITYADOR - Visibility ADOR Object

  • variables: Variables

    List of plan variables. For each variable the following properties are available:

    • name: string, Variable name

    • dial: bool, indication of Dial property

    • rule: string, plan expression for this variable

    • annotation: string, description for this ADOR Object

    • objectType: VariableObjectTypes, type of Variable. Can be one of:

      • VariableObjectTypes.BOOLEANVAR – Boolean

      • VariableObjectTypes.DATEVAR - Date

      • VariableObjectTypes.NUMBERVAR - Number

      • VariableObjectTypes.TEXTVAR - Text

  • PlanFields: PlanFields

    List of plan field, that is the recipient list schema fields. For each field the following properties are available:

    • name: string, field name

    • objectType: FieldObjectTypes, type of Variable. Can be one of:

      • FieldObjectTypes.BOOLEAN – Boolean

      • FieldObjectTypes.DATE - Date

      • FieldObjectTypes.NUMBER - Number

      • FieldObjectTypes.TEXT - Text

  • primaryField:string

    Name of primary field.

styleAdorName and adorName properties

Objects that can have placeholders will have adorName or styleAdorName properties. adorName is used to designate a reference to an ADOR object that is Visibility, Text or Image. styleAdorName is used to designate a Style ADOR. You can both get and set these properties, in order to query an ADOR reference, or attach an ADOR to an object. You can use these properties to set the following ADOR Objects:

  1. Visibility ADOR Objects (using the adorName property of a spread or a layer)

  2. Text ADOR/Text File ADOR (using the adorName property of a text range)

  3. Style ADOR (either text style or object style. Use the styleADORName property of either a box or a text range, accordingly)

  4. Graphic ADOR (using the adorName property of a graphic box)

Story object

Story objects (the objects in InDesign that represent a complete text content stream that uses one or more text frames to appear in) can have two extra properties, with the scripting plug-ins:

Story.suppressTrailingSpaces

A boolean value that determines whether trailing spaces are suppressed in case ADOR Objects are empty.

Story.suppressEmptyTables

A boolean value that determines whether table headers/footers are to be removed in case dynamic tables are empty.

Story.copyFitting

A boolean value that determines whether copy fitting will get a default value. Default values are overflow and font size.

Note that these properties are available only for the desktop version of the scripting plug-in.