All priint:comet server API operations need a set of certain parameters to be executed. Most commands have some optional parameters not necessarily required to complete the operation. These parameters can be passed in the options string, thus we keep the API simple for general uses and flexible for special requirements - however somewhat at the cost of syntactic strength.
This document should help you to find options appropriate for your needs and explain how and where they can be used.
Options are passed as a list of key value pairs, elements separated by semicolons. A single option is a keword followed by colon and the value.
key:value;[key2:value;...]
The options string is parsed from left to right, latter statements therefore override former:
// width will be set to 534.0 String myoptions = "width:200.0;width:534.0;"
Some options are grouped and can either be set separately or in one pass:
// setting margins ... String myoptions = "margin-left:20.;margin-top:20.;margin-right:20.;margin-bottom:20."; // this would have the same effect myoptions = "margin:20.;";
The override rules apply for grouped options as well:
// this will set all margins to 20pt except for margin-left, which will be 40pt String myoptions = "margin:20.;margin-left:40."; // ... but in this case the margin option will override margin-left too: myoptions = "margin-left:40.;margin:20.;";
Most options expect a value of a certain type. These are the supported types:
| Type | Description |
| int | Integer |
| float | a floating point number. Decimal separator is a dot. |
| boolean | 0, !, false, off, no, none, nay, nope, omit, zero, dont, nothanks, never and skip (all case insensitive) will be interpreted as false, all other values as true . |
| String | Strings can but dont have to be enclosed in double quotes. Note: layer names (in the layers option) MUST be quoted. |
| Enums / Sets | Some options expect a string of a certain set. These values simply can be passed as a string (quoted or unquoted). |
xmlversion:3.0;content:tagged,plain;svg:bbox;svg-text:full;layers:+"visible",-"hidden";
| Keyword | Type | Remarks | Scope |
| userdata | string | path of the user / session data XML. | all operations |
| Keyword | Type | Remarks | Scope |
| page-scope | string | all, master or regular. Operate on all, only master or regular page items. This applies to nearly all commands, except for elements. |
xxGetCometGroups
xxGetElements xxGetPlaceHolders xxLoadPlaceholders xxSynncPlaceholders xxUpdatePlaceholders xxSetPlaceholderValue xxSetPlaceholderImage xxSetPlaceholderImagePath xxGetPreview xxGetPreviewOfClipping xxGeneratePDF createProductPreview createProductPDF createPDF |
| visibility | string | hidden, visible or all. Operate on all, only visible or only hidden page items. Just like page-scope this does not apply for element commands. |
|
| config-cache | boolean | true / yes or false / no. Allow client side config caching with SOAP connections. Requires PublishingServer 4.1.8 |
use |
| Keyword | Type | Remarks |
| require-native | boolean | require native document format (e.g. CC documents on a CC server), defaults to false. If set to true, this implies require-indd. |
| require-indd | boolean | Not yet supported
require indd document format, defaults to true. If set to false, import formats (such as w2ml, IDML) are imported and saved under the same path / document name with the extension .indd. All subsequent document operations (even, if the document is referred by the original path of the import file) then refer to the newly created InDesign® document.Currently this is always true, i.e.: other formats cannot be opened using the documentOpen scipting function. |
| auto-convert | boolean | auto convert outdated indd documents (e.g. convert CS6 documents to CC on an InDesign® CC Server), defaults to false. |
| Keyword | Type | Remarks | Scope |
| pages | int | number of pages to create. | documentCreate |
| pages-per-spread | int | number of pages per spread | |
| reshuffle | boolean | allow page reshuffle | spreadAddSpreads spreadMoveSpreads spreadDeleteSpreads pageAddPages pageMovePages pageDeletePages |
| Keyword | Type | Remarks | Scope |
| size | float [float] | page size in pt, either width height or one value for both settings |
documentCreate documentSetup execTemplate createProductPreview createProductPDF createPDF |
| width | float | page width in pt | |
| height | float | page height in pt | |
| margin | float | page margins | |
| margin-top | float | top margin | |
| margin-bottom | float | bottom margin | |
| margin-left | float | left margin | |
| margin-right | float | right margin | |
| margin-outer | float | outer margin | |
| margin-inner | float | inner margin | |
| margin-outsideright | float | outside right margin | |
| margin-insideleft | float | inside left margin | |
| bleed | float | page / spread bleed | |
| bleed-top | float | top bleed | |
| bleed-bottom | float | bottom bleed | |
| bleed-left | float | left bleed | |
| bleed-right | float | right bleed | |
| bleed-inner | float | inner bleed | |
| bleed-outer | float | outer bleed | |
| bleed-insideleft | float | inside left bleed | |
| bleed-outsideright | float | outside right bleed | |
| slug | float | page / spread slug | |
| slug-top | float | top slug | |
| slug-bottom | float | bottom slug | |
| slug-left | float | left slug | |
| slug-right | float | right slug | |
| slug-inner | float | inner slug | |
| slug-outer | float | outer slug | |
| slug-insideleft | float | inside left slug | |
| slug-outsideright | float | outside right slug |
| Keyword | Type | Remarks | Scope |
| offset | float [float] | build offset x / y from left / top | execTemplate createProductPreview createProductPDF |
| offset-x | float | build offset x from left of page | |
| offset-y | float | build offset y from top of page |
| Keyword | Type | Remarks | Scope |
| layer | string | name of the target layer | execTemplate pagePlaceTemplate spreadPlaceTemplate pageBuild pageBuildAt spreadBuild spreadBuildAt cometGroupInsertBefore cometGroupInsertAfter cometGroupReplaceGroup createProductPreview createProductPDF createPDF |
| snap-to-grid | boolean | snap to the next grid position | execTemplate pagePlaceTemplate spreadPlaceTemplate cometGroupInsertBefore cometGroupInsertAfter cometGroupReplaceGroup |
| snap-to-template | boolean | snap to the next page element | |
| auto-load | boolean | load content after inserting templates, default: true | |
| check-pagetype | boolean | check the page type when determining the correct template, default: true | |
| build-prescript | int | use this prescript when building |
execTemplate pagePlaceTemplate spreadPlaceTemplate xxBuild xxBuildAt |
| build-pageitem | int | use this template when building | |
| prefer-existing-pages | boolean | prefer existing pages when building, default: true | |
| prefer-default-pageitem | boolean | prefer the default template when building, default: false | |
| skip-empty-templates | boolean | skip products, when no template is provided (i.e.: no error will be thrown in that case), default: false | |
| localize-masteritems | boolean | localize masteritems, default: false | |
| auto-detect-type | boolean | auto detect type of source frame, when set to true content of text frames will be inserted instead of inlining. Default: false | |
| apply-master | boolean | Apply masterpage as determined by the page template to pages (and following), default: true (for apply-master) and false (for apply-following) This also affects pageSetTemplateID and spreadSetTemplateID |
|
| apply-following | boolean | ||
| allow-doubles | boolean | Allow duplicate products, default: true | xxBuild xxBuildAt documentSetItems |
| build-snippet-matches | string | [since v4.0.5, R8410] Prefer Comet snippets instead of building the products by templates. Snippets can be found by their document ID (or path, if no document ID is defined), by their template ID and/or by their product IDs. Any combination of the three IDs is allowed. (But not every combination is sensefull!). Valid otptions: Never Combination of document, template, product strict (abbreviation for document-template-product) tolerant (abbreviation for template-product) fallback-allowed (Snippet too large? Use the template after all.) Default : Never Example : build_snippet-matches=tolerant, fallback-allowed |
xxBuild |
| image-pos | string | Image placement, valid options: top-left, topleft top-center[ed], topcenter[ed] top-right, topright middle-left, middleleft middel, center[ed] middle-right, middleright bottom-left, bottomleft bottom-center[ed], bottomcenter[ed] bottom-right Default: centered. |
elementSetImage elementSetImagePath |
| image-scale | string | Image scaling, valid options: none or any valid combination of fit-Frame, fitFrame (Take care on the upper case F!) fit-Content, fitContent (Take care on the upper case C!) fit-content-width, fitcontentwidth fit-content-height, fitcontentheight fit-frame-width, fitframewidth fit-frame-height, fitframeheight best best-centered, bestcentered Default: none (means 'place like existing') |
| Keyword | Type | Remarks | Scope |
| combine-groups | boolean | combine CometGroups, i.e. also include subgroups, default true | deleteCometGroup xxMoveCometGroup cometGroupResolveGroup cometGroupJoinGroups |
| Keyword | Type | Remarks | Scope |
| format | string | image file format: jpeg | png | tiff | gif | png |
spreadGetPreview spreadGetPreviewOfClipping pageGetPreview pageGetPreviewOfClipping cometGroupGetPreviews elementGetPreview spreadGetCometGroupsPreview spreadGetElementsPreview createProductPreview adapterCreatePreview |
| scale | float | scaling x / y | |
| scale-x | float | scaling x | |
| scale-y | float | scaling y | |
| greek-below | float | greek text below given font size (pt) | |
| transparency | string | transparency quality: low | medium | high | maximum | |
| quality | string | quality: low | good | great | excellent | |
| encoding | string | jpeg encoding: baseline | progressive | |
| color-space | string | color space: rgb | cmyk | lab | gray | |
| antialiasing | boolean | antialiasing, default true | |
| fullres | boolean | draw full resolution graphics, default true | |
| add-alpha | boolean | Add alpha channel, default: depends on the image format (see above):
|
|
| palette | boolean | (TIFF, GIFF): exact/adaptive | win | mac | web | none | |
| interlaced | boolean | GIF only, default true | |
| combine-groups | boolean | combine CometGroups, cometGroupGetPreviews only, default true | |
| layers | string | layers to include in preview, see description below | |
| extract | boolean | extract element or comet groups, i.e.: show only content of the given entity or inluce other frames. Default:
|
|
| compression | int | png only: image compression, default: 5 |
| Keyword | Type | Remarks | Scope |
| xmlschema | boolean | Include XML Schema reference and namespaces, default true |
documentGetSpreads xxGetCometGroups xxGetPlaceholders xxGetElements |
| xmlindent | boolean | Add linebreaks and indentations, default false | |
| xmlversion | float | 2.9 or 3.0. The old 2.9 format is deprecated and is provided for compatibility reason only. Default: 3.0 | |
| content | string | list of text export formats, valid formats are plain, tagged or tagged-raw | |
| svg | string | options for svg export: full | bbox | none | |
| svg-group | string | options for CometGroups svg exports | |
| svg-frame | string | options for frames / elements svg exports | |
| svg-text | string | options for text / paragraphs svg exports | |
| placeholders | boolean | include placeholder tags in text export | |
| eval-sync | boolean | evaluate sync states of placeholders before export | |
| mark-changes | boolean | mark placeholder changes, not yet supported | |
| combine-groups | boolean | combine CometGroups, default true | |
| oversets | boolean | calculate and include text overset / underset, default true | |
| calc-sizes | boolean | Calculate sizes of groups or elements, all, relative and / or absolute. Default: false |
|
| calc-sizes-rel | boolean | ||
| calc-sizes-abs | boolean | ||
| size-checktrans | boolean | check transparency when calculating sizes, default: true | |
| size-checkmargins | boolean | check page margins when calculating sizes, default: true | |
| size-allowholes | boolean | allow holes when calculating sizes, default: true | |
| size-useclips | boolean | use image clipping paths when calculating sizes, default: true | |
| size-ignore-overlaps | boolean | ignore overlaps when calculating sizes. Default: false | |
| layers | string | layers to include in XML, see description below | |
| function-variables | boolean | include function variable definitions in placeholders.xml, default=false |
| Keyword | Type | Remarks | Scope |
| package-fonts | boolean | Include fonts in the document package, default true | documentGetPackage |
| package-images | boolean | Include images in the document package, default true | |
| package-color-profiles | boolean | Include color profiles in the document package, default true | |
| package-hidden-layers | boolean | Include fonts, images and color profiles of hidden layers in the document package, default true | |
| package-ignore-errors | boolean | Ignore document preflight errors, default true | |
| package-report | boolean | Include instructions, default true | |
| package-include-idml | boolean | Include IDML in the document package (only available from CC 2014), default false | |
| package-include-pdf | boolean | Include PDF in the document package (only available from CC 2014), default false | |
| package-pdf-profile | string | Name of the PDF profile to use when including PDF, default empty | |
| package-folder-name | string | Name of the document package folder, default document name | |
| package-document-name | string | Name of the packaged document, default original document name |
The layers option is a comma seperated list of names of layers to show or hide, the option applies to XMLs, PDFs and previews. By default the document preferences are used, this is the status the document was last saved in InDesign® Desktop and first opened in InDesign® Server.
Each list elements starts with the operator + (show) or - (hide), followed by a layername in double quotes or the wildcard * (all layers), see the examples below.
Examples:
// Show all layers layers:+*; // show none layers:-*; // show default and some more layers:+"layer-to-show-1",+"layer-to-show-2"; // show default and some less layers:-"layer-to-hide-1",+"layer-to-hide-2"; // show specific layers only layers:-*,+"layer-to-show-1",+"layer-to-show-2"; // show all but ... layers:+*,-"layer-to-hide-1",-"layer-to-hide-2";
There are some more options for internal use only. You shouldn't use them, but maybe you will stumble accross them when reading API logfiles:
| Keyword | Type | Remarks | Scope |
| move-absolute | boolean | x / y coordinates are absolute | several (if not all) |
| move-relative | boolean | x / y coordinates are relative | |
| documentId | string | the CometServer documentID of the current document | |
| session | string | Session ID | |
| internal-2ndrun | boolean | internal, failover handling |
When reading the logs you will also notice that there is some more information passed along with the options string. This is part of the priint:comet server / InDesign® Server protocol and subject to change without notice.