@vertigis/viewer-spec 59.5.0 → 59.6.0

package/messaging/registry/printing.d.ts

@@ -1,6 +1,9 @@
 import type Viewpoint from "@arcgis/core/Viewpoint";
 import type Extent from "@arcgis/core/geometry/Extent";
+import type Point from "@arcgis/core/geometry/Point.js";
 import type SpatialReference from "@arcgis/core/geometry/SpatialReference";
+import type { BasemapJson } from "@vertigis/arcgis-extensions/json/BasemapJson.js";
+import type { OperationalLayerJson } from "@vertigis/arcgis-extensions/json/OperationalLayerJson.js";
 import type { PortalItemLike } from "@vertigis/arcgis-extensions/utilities/portal";
 import type { Command } from "../Command.js";
 import { CommandRegistry } from "../CommandRegistry.js";
@@ -12,12 +15,742 @@ import type { MapsLike } from "../common.js";
  */
 export type JobParameters = Record<string, unknown>;
 /**
- * The export formats allowed for the layout print.
+ * Available print output formats (printing gen2).
  */
-export type LayoutExportFormats = "AIX" | "BMP" | "MF" | "EPS" | "GIF" | "JPG" | "PDF" | "PNG" | "PNG32" | "SVG" | "SVGZ" | "TGA" | "TIFF";
+export declare const printOutputFormats: readonly ["AIX", "BMP", "EMF", "EPS", "GIF", "JPG", "PDF", "PNG", "PNG32", "SVG", "SVGZ", "TGA", "TIFF"];
 /**
- * The arguments required by the printing.run command when printing with ArcGIS
- * Pro layouts.
+ * Represents the print output format type (printing gen2). Note: Output format
+ * is ignored and PDF is used automatically if more than one page is exported.
+ */
+export type PrintOutputFormat = (typeof printOutputFormats)[number];
+/**
+ * Represents a print spatial reference.
+ */
+export interface PrintSpatialReference {
+    /**
+     * WKID.
+     */
+    wkid?: number;
+    /**
+     * Latest WKID.
+     */
+    latestWkid?: number;
+    /**
+     * WKT String.
+     */
+    wkt?: string;
+}
+/**
+ * Represents the print extent.
+ */
+export interface PrintExtent {
+    /**
+     * Xmin value.
+     */
+    xmin: number;
+    /**
+     * Ymin value.
+     */
+    ymin: number;
+    /**
+     * Xmax value.
+     */
+    xmax: number;
+    /**
+     * Ymax value.
+     */
+    ymax: number;
+    /**
+     * Center point.
+     */
+    center?: Point;
+    /**
+     * Spatial reference.
+     */
+    spatialReference: PrintSpatialReference;
+}
+/**
+ * Represents the map options.
+ */
+export interface MapOptions {
+    /**
+     * Defines the extent of the map to be printed. The spatial reference of the
+     * extent object is optional; when it is not provided, it is assumed to be
+     * in the map's spatial reference. When the aspect ratio of the map extent
+     * is different than the size of the map on the output page or the
+     * ExportWebMap:ExportOptions:outputSize, you might notice more features on
+     * the output map.
+     */
+    extent: PrintExtent;
+    /**
+     * The map scale at which you want your map to be exported. When scale is
+     * used, it takes precedence over the extent, but the output map is drawn at
+     * the requested scale centered on the center of the extent.
+     */
+    scale?: number;
+    /**
+     * The spatial reference of the map. The order of preference when
+     * spatialReference is missing is as follows:
+     *
+     * - ExportWebMap:MapOptions.extent.spatialReference
+     * - ExportWebMap:BaseMap.baseMapLayers.spatialReference
+     * - Map template's spatial reference.
+     */
+    spatialReference?: PrintSpatialReference;
+    /**
+     * This represents the number of degrees by which the map frame will be
+     * rotated, measured counterclockwise from the north. To rotate clockwise,
+     * use a negative value.
+     */
+    rotation?: number;
+}
+/**
+ * Represents the export options.
+ */
+export interface ExportOptions {
+    /**
+     * The resolution in dots per inch. The default is 96 dpi.
+     */
+    dpi?: number;
+    /**
+     * Size of the map in pixels. The size must be defined when an empty string
+     * or MAP_ONLY (without quotation marks) is passed in as a value to the
+     * layout_template parameter. If layout_template is not specified as
+     * MAP_ONLY or an empty string, the map frame with the name WEBMAP_MAP_FRAME
+     * of the referenced DEFAULT layout portal item in layout_template print
+     * parameter takes precedence over outputSize.
+     */
+    outputSize?: number[];
+}
+/**
+ * Represents the legend options.
+ */
+export interface LegendOptions {
+    /**
+     * Specifies if the legend of all operational layers should be added to the
+     * layout. If true, operationalLayers can be undefined. Note: this is no
+     * ESRI standard property and only works with VertiGIS Studio Printing
+     * Engine.
+     */
+    operationalLayersAutoSet?: boolean;
+    /**
+     * Specifies the operational layers whose legends will be added to the
+     * layout.
+     */
+    operationalLayers?: {
+        /**
+         * String representing the ID of the layer. The ID must be unique and
+         * must match the layer's ID in the operationalLayers element where the
+         * operational layer is defined.
+         */
+        id: string;
+        /**
+         * An array of sublayers whose element types are string or number and
+         * contextual to the operational layer type. For example, for a map
+         * service layer, it must be a number; for a WMS layer, it must be a
+         * string. It is recommended that you specify subLayerIds values for
+         * operational layers that have sublayers. Once omitted, in the case of
+         * map service and WMS layers, legends from all sublayers are added to
+         * the legend element on the layout. For feature or graphics layers, the
+         * sublayers property does not need to be set.
+         */
+        subLayerIds?: string[] | number[];
+    }[];
+}
+/**
+ * Represents the layout options.
+ */
+export interface LayoutOptions {
+    /**
+     * Specifies properties of a legend element on the layout.
+     */
+    legendOptions?: LegendOptions;
+    /**
+     * Dynamic text elements as array of name-value pairs. Applies for all
+     * layout page types. Sets the values of layout function fields for all
+     * layouts containing the specified functions fields. Values must be
+     * strings. Function fields of type string and additionally of type image
+     * can also be set when using additionalSettings:dynamicElements. Function
+     * field values can be applied individually for specific layout page types
+     * by using:
+     *
+     * - AdditionalSettings:page:dynamicElements.
+     * - AdditionalSettings:pageCover:dynamicElements.
+     * - AdditionalSettings:pageOverview:dynamicElements.
+     * - AdditionalSettings:pageLegend:dynamicElements.
+     */
+    customTextElements?: unknown;
+}
+/**
+ * Represents the export web map as defined by ESRI in
+ * https://enterprise.arcgis.com/en/server/latest/publish-services/windows/exportwebmap-specification.htm.
+ */
+export interface ExportWebMap {
+    /**
+     * The object mapOptions is required and defines map display properties.
+     */
+    mapOptions: MapOptions;
+    /**
+     * This object specifies settings for the output map.
+     */
+    exportOptions?: ExportOptions;
+    /**
+     * This defines settings for different available page layout elements and is
+     * only needed when an available layout template is chosen. Page layout
+     * elements include well-known VertiGIS Studios function fields and custom
+     * text elements.
+     */
+    layoutOptions?: LayoutOptions;
+    /**
+     * The operationalLayers list contains all the operational layers to be
+     * displayed in the map. The order of the array defines the order of the
+     * layers in the map. The type of each layer is defined by the URL resource
+     * response. If the resource cannot be determined from the URL, the type
+     * property defines the type. For example, a WMS layer requires that you
+     * specify "type": "wms". There are some properties common to all types of
+     * operational layers, while others are specific to each type of operational
+     * layer.
+     *
+     * In case of secured layers, specify the token in a layer definition. A
+     * user name and password are not supported as part of the URL.
+     */
+    operationalLayers?: OperationalLayerJson[];
+    /**
+     * The map contains one baseMap, which has a title, and a baseMapLayers
+     * property that contains an ordered list of baseMapLayers. Each
+     * baseMapLayer must be in the same spatial reference and tiling scheme.
+     * When there is a baseMap, it defines the map's spatial reference.
+     */
+    baseMap?: BasemapJson;
+}
+/**
+ * Represents an additional export web map.
+ */
+export interface AdditionalExportWebMap {
+    /**
+     * Name of the additional map frame in the layout. Well-known additional map
+     * frame names are 'OVERVIEW' for the overview map and
+     * 'WEBMAP_MAP_FRAME_PAGE_OVERVIEW' for the overview page map. For a custom
+     * additional web frame name use the map frame name as defined in the
+     * layout. For fetching the available map frames for layouts or layout
+     * packages use the 'Get Layout Template Info Task'.
+     */
+    name: string;
+    /**
+     * The export web map properties.
+     */
+    Map_As_JSON: ExportWebMap;
+}
+/**
+ * Represents the portal authentication settings.
+ */
+export interface PortalAuthentication {
+    /**
+     * Whether the access to an ArcGIS Online / ArcGIS Enterprise organization
+     * is anonymous. If anonymous is true, no token is required.
+     */
+    anonymous: boolean;
+    /**
+     * URL of an ArcGIS Enterprise or ArcGIS Online organization. If not
+     * defined, ArcGIS Online access is assumed.
+     */
+    portal_url: string;
+    /**
+     * Access token. Required for non-anonymous access.
+     */
+    token?: string;
+    /**
+     * Access token referer. Required for non-anonymous access if the token was
+     * created with the ESRI 'Generate Token Service'.
+     */
+    referer?: string;
+}
+/**
+ * Represents the layer objects selection Settings.
+ */
+export interface Selection {
+    /**
+     * Layer object IDs.
+     */
+    oidList: number[];
+    /**
+     * Web map layer ID.
+     */
+    layerId: string;
+    /**
+     * Whether the default object selection graphics should be visible for
+     * selected objects. If 'true' or not defined, the ArcGIS default object
+     * selection graphics are used. If 'false', object selection graphics are
+     * expected in the export web map request parameter (e.g. operational layer
+     * with custom renderer for selected objects, or pre-defined selection
+     * geometries with custom renderer in feature collections).
+     */
+    visible: boolean;
+}
+/**
+ * Represents the time interval units.
+ */
+export type IntervalUnits = "MILLISECONDS" | "SECONDS" | "MINUTES" | "HOURS" | "DAYS" | "WEEKS" | "MONTHS" | "YEARS" | "DECADES" | "CENTURIES";
+/**
+ * Represents the time series settings.
+ */
+export interface TimeSeries {
+    /**
+     * Maximum count of time series PDF documents within the returned ZIP
+     * archive. If not set, no limit for time series PDF document exports is
+     * used. Depending on the client and the execution environment and the
+     * template- / map properties, the clients should always define a suitable
+     * value.
+     */
+    maxCount?: number;
+    /**
+     * Client time zone information. Default is UTC.
+     */
+    timeZone?: {
+        /**
+         * Offset in hours to UTC without daylight saving time (DST).
+         */
+        utcOffset: number;
+        /**
+         * Timezone name. Used for the time function field.
+         */
+        name: string;
+    };
+    /**
+     * Human-readable date time pattern in ESRI format:
+     * https://pro.arcgis.com/en/pro-app/latest/help/data/tables/format-numeric-and-date-fields.htm.
+     * Used for the time function field. Default is 'yyyy-MM-dd hh:mm:ss'.
+     */
+    datetimePattern?: string;
+    /**
+     * Export interval in milliseconds or in other interval units if defined.
+     * Requires a single export time in the array with a time range > 0. If
+     * defined, an export is triggered for each interval starting at the time
+     * range <startTime> and stopping at <endTime>. If no main map with one or
+     * more visible time-aware operational layers is available for exporting, or
+     * if the defined interval does not fit into the specified time range, this
+     * property is ignored.
+     */
+    interval?: number;
+    /**
+     * Export interval units. Requires a defined interval. Default is
+     * MILLISECONDS.
+     */
+    intervalUnits?: IntervalUnits;
+    /**
+     * Export Times. Triggers an export for each defined export time. Export
+     * time in milliseconds UTC. Requires at least one entry.
+     */
+    times: number[][];
+}
+/**
+ * Represents the range settings.
+ */
+export interface Range {
+    /**
+     * Start value.
+     */
+    start: number;
+    /**
+     * End value.
+     */
+    end: number;
+    /**
+     * Whether the start value is included in the value range.
+     */
+    includeStart: boolean;
+    /**
+     * Whether the end value is included in the value range.
+     */
+    includeEnd: boolean;
+}
+/**
+ * Represents the range series settings.
+ */
+export interface RangeSeries {
+    /**
+     * Maximum count of value range series pages per PDF document. If not set,
+     * no limit for value range series PDF page exports is used. Depending on
+     * the client and the execution environment and the template- / map
+     * properties, the clients should always define a suitable value.
+     */
+    maxCount?: number;
+    /**
+     * Export interval in integer or float. Requires a single export value range
+     * in the array with a value range extent > 0. If defined, an export is
+     * triggered for each interval starting at the value range <start> and
+     * stopping at <end>. If no main map with one or more visible z-aware layers
+     * is available for exporting, or if the defined interval does not fit into
+     * the specified value range span, this property is ignored.
+     */
+    interval?: number;
+    /**
+     * Export value ranges. Triggers an export for each defined export value
+     * range. Requires at least one entry.
+     */
+    ranges: Range[];
+}
+/**
+ * Represents the table data selection mode.
+ */
+export type DataSelectionMode = "All" | "InExtent" | "SelectedAll" | "SelectedInExtent";
+/**
+ * Represents the attribute table settings.
+ */
+export interface AttributeTable {
+    /**
+     * Name of attribute table.
+     */
+    name: string;
+    /**
+     * ID of the map layer used as data source.
+     */
+    layerId: string;
+    /**
+     * Data selection mode.
+     */
+    mode: DataSelectionMode;
+    /**
+     * List of table fields to show in the table.
+     */
+    fields: string[];
+}
+/**
+ * Represents the geo transformation in the settings.
+ */
+export interface GeoTransformation {
+    /**
+     * WKID.
+     */
+    wkid: number;
+    /**
+     * Name.
+     */
+    name: string;
+}
+/**
+ * Represents the dynamic element type.
+ */
+export type DynamicElementType = "string" | "image";
+/**
+ * Represents a dynamic element. A dynamic element can be a custom text element
+ * (type: string) or a custom image element (type: image).
+ */
+export interface DynamicElement {
+    /**
+     * Type.
+     */
+    type: DynamicElementType;
+    /**
+     * Name.
+     */
+    name: string;
+    /**
+     * Value.
+     */
+    value: string;
+}
+/**
+ * Represents the default page settings. The properties match the index info
+ * page properties as received by the VertiGIS Printing Engine as response of an
+ * 'Get Index Info Task'.
+ */
+export interface Page {
+    /**
+     * Page scale.
+     */
+    scale: number;
+    /**
+     * Page rotation.
+     */
+    rotation?: number;
+    /**
+     * Page centerpoint x-coordinate.
+     */
+    centerX?: number;
+    /**
+     * Page centerpoint y-coordinate.
+     */
+    centerY?: number;
+    /**
+     * Projected page geometry. An array of geometry points according to the
+     * ESRI specification.
+     */
+    geometry?: number[][];
+    /**
+     * Spatial reference of the projected page geometry.
+     */
+    spatialReference?: PrintSpatialReference;
+    /**
+     * Output spatial reference of the projected page geometry for export.
+     */
+    spatialReferenceOut?: PrintSpatialReference;
+    /**
+     * Transformation name for projecting the page geometry between the
+     * projected page geometry spatial reference and the output spatial
+     * reference.
+     */
+    transformationName?: string;
+    /**
+     * Transformation WKT string for projecting the page geometry between the
+     * projected page geometry spatial reference and the output spatial
+     * reference.
+     */
+    transformationString?: string;
+    /**
+     * Dynamic elements of the default page additionally to the dynamic text
+     * elements in exportWebMap:layoutOptions:customTextElement and the dynamic
+     * elements in additionalSettings. These elements take precedence over the
+     * elements in exportWebMap:layoutOptions:customTextElement and the elements
+     * in addtional Settings root, if they have the same type and name.
+     */
+    dynamicElements?: DynamicElement[];
+    /**
+     * Layer objects selections of the default Page additionally to the Layer
+     * objects selections in additionalSettings.
+     */
+    selection?: Selection;
+}
+/**
+ * Represents the seamless page settings.
+ */
+export interface PageSeamless {
+    /**
+     * Page scale.
+     */
+    scale: number;
+    /**
+     * Index line or polygon geometry. An array of geometry points according to
+     * the ESRI array specification. Excepted geometries are a polyline with
+     * CENTER LEFT and CENTER RIGHT coordinates or a rectangle with BOTTOM LEFT,
+     * TOP LEFT, TOP RIGHT, BOTTOM RIGHT coordinates or a complex polygon with
+     * arbitrary vertices. A polyline geometry defines the delta, the current
+     * template's mapframe width should be updated with. A rectangle or complex
+     * polygon geometry defines an arbitrary extent, for the current template's
+     * mapframe. For complex polygons the extent is defined by the polygon's
+     * bounding box. For complex polygons geometry rotation can not be
+     * considered.
+     */
+    geometry?: number[][];
+    /**
+     * Spatial reference.
+     */
+    spatialReference: PrintSpatialReference;
+}
+/**
+ * Represents the cover page settings.
+ */
+export interface PageCover {
+    /**
+     * Whether the cover page is visible.
+     */
+    visible?: boolean;
+    /**
+     * Dynamic elements of the cover page additionally to the dynamic text
+     * elements in exportWebMap:layoutOptions:customTextElement and the dynamic
+     * elements in additionalSettings. These elements take precedence over the
+     * elements in exportWebMap:layoutOptions:customTextElement and the elements
+     * in addtional settings root, if they have the same type and name.
+     */
+    dynamicElements?: DynamicElement[];
+}
+/**
+ * Represents the overview page settings.
+ */
+export interface PageOverview {
+    /**
+     * Whether the overview page is visible.
+     */
+    visible?: boolean;
+    /**
+     * Dynamic elements of the overview page additionally to the dynamic text
+     * elements in exportWebMap:layoutOptions:customTextElement and the dynamic
+     * elements in additionalSettings. These elements take precedence over the
+     * elements in exportWebMap:layoutOptions:customTextElement and the elements
+     * in addtional settings root, if they have the same type and name.
+     */
+    dynamicElements?: DynamicElement[];
+    /**
+     * Page graphics settings.
+     */
+    pageGraphics?: {
+        /**
+         * Whether the page graphics are visible.
+         */
+        visible?: boolean;
+        /**
+         * Page stroke RGB color according to the ESRI RGB color specification.
+         */
+        colorStroke: number[];
+        /**
+         * Page fill RGB color according to the ESRI RGB color specification.
+         */
+        colorFill: number[];
+    };
+    /**
+     * Page overlap graphics settings.
+     */
+    pageGraphicsOverlap?: {
+        /**
+         * Whether the page overlap fill graphics are visible.
+         */
+        visibleFill?: boolean;
+        /**
+         * Page overlap fill RGB Color according to the ESRI RGB color
+         * specification.
+         */
+        colorFill?: number[];
+    };
+    /**
+     * Page graphics index settings.
+     */
+    pageGraphicsIndex?: {
+        /**
+         * Whether the index line graphics is visible.
+         */
+        visibleStroke?: boolean;
+        /**
+         * Whether the page number annotations are visible.
+         */
+        visibleAnnotation?: boolean;
+        /**
+         * Index line stroke RGB color according to the ESRI RGB color
+         * specification.
+         */
+        colorStroke?: number[];
+        /**
+         * Page number annotations RGB color according to the ESRI RGB color
+         * specification.
+         */
+        colorAnnotation?: number[];
+    };
+}
+/**
+ * Represents the legend page settings.
+ */
+export interface PageLegend {
+    /**
+     * Whether the legend page is visible.
+     */
+    visible?: boolean;
+    /**
+     * Dynamic elements of the legend page additionally to the dynamic text
+     * elements in exportWebMap:layoutOptions:customTextElement and the dynamic
+     * elements in additionalSettings. These elements take precedence over the
+     * elements in exportWebMap:layoutOptions:customTextElement and the elements
+     * in addtional settings root, if they have the same type and name.
+     */
+    dynamicElements?: DynamicElement[];
+    /**
+     * Whether the legend items of dynamic layers, organized in composite layers
+     * on root level, should be exported in seperate legend pages. Legend items
+     * are seperated if this value is set to 'true'. This might result in
+     * additional legend page exports.
+     */
+    layerCompositeExport?: boolean;
+    /**
+     * Whether the legend items of visible layers should only be exported if
+     * related features are visible in the print extent. If not defined, the
+     * value from the layout's default legend item (ArcGIS Pro: 'Only show
+     * feature visible in the map extent') is used.
+     */
+    itemsAutoVisibility?: boolean;
+}
+/**
+ * Represents the additional settings.
+ */
+export interface AdditionalSettings {
+    /**
+     * Authentication for layout or layout package portal item access.
+     */
+    authentication?: PortalAuthentication;
+    /**
+     * Security settings.
+     */
+    security?: {
+        /**
+         * AES-128 encrypted password to secure resulting PDF documents. Clients
+         * must use shared AES crypto key for password encryption.
+         */
+        outputPassword: string;
+    };
+    /**
+     * Default seamless page settings for prints with layout or layout packages.
+     * Mandatory for a seamless page print.
+     */
+    seamless?: PageSeamless;
+    /**
+     * Default series pages settings for prints with layout or layout packages.
+     * Mandatory for unprojected or projected spatial series pages prints.
+     */
+    pages?: Page[];
+    /**
+     * Cover page settings for prints with layout packages.
+     */
+    pageCover?: PageCover;
+    /**
+     * Overview page settings for prints with layout packages.
+     */
+    pageOverview?: PageOverview;
+    /**
+     * Legend page settings for prints with layout packages.
+     */
+    pageLegend?: PageLegend;
+    /**
+     * Layer objects selections.
+     */
+    selection?: Selection;
+    /**
+     * Series time settings for time-aware layers.
+     */
+    timeSeries?: TimeSeries;
+    /**
+     * Series range settings for range/z-aware layers.
+     */
+    rangeSeries?: RangeSeries;
+    /**
+     * Attribute tables settings.
+     */
+    attributeTables?: AttributeTable[];
+    /**
+     * Geo transformations for prints with layout or layout packages. Geo
+     * transformations used for maps to avoid spatial displacement between
+     * operational layers and basemap layers if they have incompatible
+     * underlying geographic coordinate systems. These geo transformations are
+     * added to all maps in the request. They are ignored if no geo
+     * transformation is necessary. Also see:
+     * https://developers.arcgis.com/rest/services-reference/enterprise/pdf/gtf_pdf_11.1.pdf.
+     */
+    geoTransforms?: GeoTransformation[];
+    /**
+     * Dynamic elements additionally to the dynamic text elements in the
+     * ExportWebMap:LayoutOptions:customTextElement. These elements take
+     * precedence over the elements in
+     * ExportWebMap:LayoutOptions:customTextElement, if they have the same type
+     * and name.
+     */
+    dynamicElements?: DynamicElement[];
+}
+/**
+ * Prepared print job arguments (printing gen2).
+ */
+export interface PreparedPrintJobArgs {
+    /**
+     * Export web map.
+     */
+    webMap?: ExportWebMap;
+    /**
+     * Additional settings.
+     */
+    additionalSettings?: AdditionalSettings;
+    /**
+     * Additional export web maps.
+     */
+    additionalWebMaps?: AdditionalExportWebMap[];
+}
+/**
+ * The arguments required by the printing.run command when printing with
+ * VertiGIS Studio ArcGIS Pro layouts or -layout packages (printing gen2).
  */
 export interface RunLayoutPrintArgs extends RunPrintArgsBase {
     /**
@@ -25,13 +758,13 @@ export interface RunLayoutPrintArgs extends RunPrintArgsBase {
      */
     layoutId: string;
     /**
-     * The export format of the layout print.
+     * The print output format.
      */
-    exportFormat?: LayoutExportFormats;
+    outputFormat?: PrintOutputFormat;
 }
 /**
  * The arguments required by the printing.run command when printing with
- * templates.
+ * templates (printing gen1).
  */
 export interface RunPrintArgs extends RunPrintArgsBase {
     /**
@@ -148,6 +881,10 @@ export interface PrintPreparingEventArgs extends PrintEventArgsBase {
  * Arguments for the printing.print-prepared event.
  */
 export interface PrintPreparedEventArgs extends PrintEventArgsBase {
+    /**
+     * The print job arguments.
+     */
+    printJobArgs?: PreparedPrintJobArgs;
 }
 /**
  * Arguments for the printing.print-started event.