Add Product

URL:: https://<root>/<serviceName>/TopographicProductionServer/addProduct
Methods:: POST
Required Capability:: Requires an ArcGIS GIS Server Advanced license and a Production Mapping or Defense Mapping server extension license
Version Introduced:: 10.9

Description

The addProduct operation adds a definition of a map product to the Topographic Production Service resource that can be used to generate a map.

Request parameters

Parameter Details

Parameter	Details
`productDefinition` (Required)	The JSON definition of a map product.
`raster` (Optional)	The path to a raster on disk (server path) or the URL of an image service.
`ancillaryLayers` (Optional)	A JSON array of additional layers to include in the final product. Syntax: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 [ { "layer": "<URL of the layer>", "featureClass": "<name of the feature class to extract to>", "map": "<name of the map the layer will be inserted into>", "layerIndex": "<insertion index of the layer>" }, ... ]` Note This parameter supports services located in the same portal site as the server object extension (SOE) or services that are publicly available. The `featureClass` , `map` , and `layerIndex` properties in the array are optional. If the dataset is identifiable from the feature service, it is not necessary to provide the `featureClass` property. The default values are `0` for `layerIndex` and `BaseMap` for `map` .

productDefinition

(Required)

The JSON definition of a map product.

raster

(Optional)

The path to a raster on disk (server path) or the URL of an image service.

ancillaryLayers

(Optional)

A JSON array of additional layers to include in the final product. Syntax:

Use dark colors for code blocksCopy
[
	{
		"layer": "<URL of the layer>",
		"featureClass": "<name of the feature class to extract to>",
		"map": "<name of the map the layer will be inserted into>",
		"layerIndex": "<insertion index of the layer>"
	},
	...
]

productDefinition properties

The following table provides additional details about each property in the JSON of a map product definition. This definition is specified in the productDefinition parameter:

Property	Details
`version`	Indicates the serialization version, currently at version 0.
`name`	The name of the product. It must be unique in the map service.
`type`	Indicates the product type. Accepted values include `MTM`, `TM`, `JOG`, `CTM`, and `Custom` .
`gridType`	Indicates the type of grid XML to use when running grid operations. This must match the first part of the .xml file's name. For example, if the .xml file is titled `USTopo24_BaseMap.xml`, then the `gridType` value must be `USTopo24`. The .xml files must also be in a folder named GridTemplates that is located where the product files are installed.
`description`	Describes the type of map product being produced.
`sheetIDField`	The field name that identifies the area of interest (AOI) for which the product is generated. This must be a field that exists on the features used to define the AOI.
`productVersions`	An array of versions for this product. A version is a JSON with two properties, `name` and `template` . The template can be a path to a local layout template or the file name of a template installed with the ArcGIS Defense Mapping or ArcGIS Production Mapping server extension product files. Starting at ArcGIS Enterprise 11.2, the following properties can be applied: `extractionDatabase` —Overwrites the `extractionDatabase` value at the map product level. `operationOverrides` —Overwrites the values in the `parameters` key-value pairs for the operation with the specified ID. `excludedOperations` —Excludes the operations associated with the specified IDs. The following example includes three product versions: TRD_4_5, TRD_4_5_1, and TRD_4_6. The TRD_4_5 product version shows `operationOverrides` and `excludedOperations` available at Enterprise11.2: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 "productVersions": [ { "name": "TRD_4_5", "template": "MTM50_Layout.pagx" "extractionDatabase": "", "operationOverrides": [ { "id": "26C62049-A11F-4D5B-BC80-00CF3597555C", "parameters": [ { "name": "input_map", "value": "Map" }, ] }, ] "excludedOperations": [ "45B62049-A11F-4D5B-BC80-00CF3597555C", ... ] }, { "name": "TRD_4_5_1", "template": "MTM50_Layout.pagx" }, { "name": "TRD_4_6", "template": "MTM50_Layout.pagx" } ]
`resources`	Resources are defined with three key-value pairs: `name`, `type`, and `value` . The `operations` parameter uses the defined resources at run time. The following is a list of available resources: `1`—The Value resource returns values that are set in the map product JSON. It allows defined values to be referenced in multiple operations. `2`—The Layer resource returns details about a layer. `3`—The Workspace resource returns the path to a dataset. `4`—The GridLocator resource returns the path to a grid XML for a specified map using the AOI when the map product is created. `6`—The Layout resource returns details about a layout. `7`—The ProductFiles resource returns the path to a file in the installed product files. It works with custom product files and the file name must be unique across installed product files. `9`—The JobResource resource returns details about a job that is currently running. `10`—The PackageResource resource returns details about how an output is packaged. To use a resource, place brackets around its name. In the following example, the resource `SheetID` is defined, and the `LayerProperties` operation has a parameter named `definition_query` with the value set to `NRN = '[SheetID]'` . At runtime, `[SheetID]` is replaced with the Sheet Identifier of the map being generated. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 { "resources": [ { "name": "SheetID", "type": 1, "value": "" }, ... ], "operations": [ { "name": "LayerProperties", "type": 12, "description": "Update Layer in Map", "parameters": [ { "name": "in_layer", "value": "ASG_Layer" }, { "name": "definition_query", "value": "NRN = '[SheetID]'" }, ... ] } ] }` These are predefined resources known to the server object extension (SOE). The values of these resources are left blank in the JSON definition and the SOE sets the value at runtime. For example, the `SourceWorkspace` resource is set at runtime with the data from the map service. You can review map product definitions included with the Defense Mapping or Production Mapping product files for examples of how resources are used. Learn more about resource types
`dataExtraction`	Defines how the data will be extracted. The following JSON provides additional details about the syntax of a data extraction operation: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 { "name": "<name the operation>", "type": 19, "id": "<GUID or unique string>", "description": "", "featureDataset": "<optional name of the feature dataset to which the data is extracted>", "disabled": <true \| false>, "parameters": [ { "name": "input_data", "value": "<file path to workspace connection \| product file \| feature service URL \| map service URL \| raster service URL>" }, { "name": "AOI", "value": "<the string representation of an extent (space delimited) \| JSON geometry \| None>" }, { "name": "spatial_relationship", "value": "<...>" }, { "name": "buffer", "value": "<the buffer value and unit of measurement>" }, { "name": "fileName", "value": "<the name of the raster file that gets extracted>" }, { "name": "fileExtension", "value": "<the extension for the raster format that the final output should be in>" }, { "name": "definitionQuery", "value": "<a valid Where clause for all of the tables in the input_data parameter value>" }, { "name": "includeDatasets", "value": "<a comma-delimited list of datasets to extract>" }, { "name": "excludeDatasets", "value": "<a comma-delimited list of datasets to exclude from extraction>" } ] } Note For `featureDataset`, the default is the feature dataset defined for the product. If the name does not exist in the cartography database that is used as a starting schema for a job, then the feature dataset name must exist in the source. Extraction is skipped if the value for `disabled` is `false` . If the `AOI` parameter value is `None`, then no AOI is used to filter the data that is extracted. The `spatial_relationship` parameter value must be a string that matches the enumeration value in `esriSpatialRelEnum` . The `esriSpatialRelRelation` value is not supported. The `fileName` parameter can only be used when extracting a raster. The `fileExtension` parameter can only be used when extracting a raster and supports the following formats: `.dat` `.dt2` `.img` `.jp2` `.tif` `.mrf` `.crf` Formats that don't support the pixel type to store elevation values, such as `.jpg` and `.png`, and other unsupported formats will error out during extraction. If the `fileExtension` parameter is missing, extracted digital elevation models (DEMs) and image service rasters will default to `.img`, while `.dt2` and `.tif` extractions default to the file format of the input raster. If multiple `.dt2` files are created, a parent folder is created to contain them. The optional `includeDatasets` and `excludeDatasets` parameters cannot be combined. Use one or the other. A `rasterFunction` parameter can be added to process a configured raster function template after the raster is extracted. This parameter is not in the map product definition included with the product files and cannot be used when extracting a map or data. Use dark colors for code blocksCopy `1 2 3 4 { "name": "rasterFunction", "value": "<name of the configured raster function template>" }` The following dataExtraction operation example extracts a raster: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 { "name": "RasterDataset", "type": 19, "id": "RasterDataset", "description": "Raster Dataset Extract", "disabled": "false", "parameters": [ { "name": "input_data", "value": "[ProductFiles]\\Elevation.gdb\\DEM" } { "name": "AOI", "value": "[AOILayer]\\Extent" } { "name": "buffer", "value": "2 kilometers" } { "name": "fileName", "value": "MyRaster" }, { "name": "fileExtension", "value": ".tif" }, { "name": "spatial_relationship", "value": "esriSpatialRelIntersects" } { "name": "DefinitionQuery", "value": "" } { "name": "includeDatasets", "value": "" } { "name": "excludeDatasets", "value": "" } ] } Note There are two default `dataExtraction` operations. The first, `defaultMapExtraction`, extracts map service layers, while the other, `defaultRasterExtraction`, extracts a raster, if one is defined. The names `defaultMapExtraction` and `defaultRasterExtraction` are reserved for these default extraction operations. The following parameters for the two default operations can be modified: `AOI` `buffer` `fileName` `fileExtension` `definitionQuery` `includeDatasets` `excludeDatasets` `disabled`
`operations`	An operation is typically a geoprocessing operation, but there are also other types of operations. Operation types are predefined by the app so that it can optimize the order in which the operations are performed. The following is a list of available types: `1`—A custom operation that allows custom geoprocessing script tools to be run. `2`—The ASG operation creates adjoining sheets guide data. `3`—The EGB operation creates elevation guide band data. `4`—The Grid operation creates grids for a map. `5`—The PMI operation populates map sheet information. `6`—The Anno operation converts labels to annotations. `7`—The CreateMask operation creates polygon masks for features. `8`—The ApplyMask operation applies layer masking properties to a map. `9`—The Contours operation creates contour features. `10`—The FeatureOffset operation applies offsets to features. `11`—The MapResource operation updates data sources in the map. `12`—The LayerProperties operation sets map layer properties. `20`—The SelectionOperation operation uses an expression to select features to which a list of field-value pairs are applied. An operation is defined with the following syntax: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 { "name": "<the name of the operation>", "type": <the value indicating the type of operation>, "description": "<the string describing the operation>", "parameters": [ { "name": "<name of operation>", "value": "<value of parameter>" } ] }` Example MapResource operation: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 { "name": "MapResource", "type": 11, "description": "Update BaseMap DataSources", "parameters": [ { "name": "in_map", "value": "BaseMap" } ] }` Refer to the map product definitions in the Defense Mapping product files to learn more about how operations are used.
`postProcessing`	A JSON array of custom operations that are run after files for a map product have been created.
`outputPackage`	Defines the structure for the zipped file that is exported.

Types of resources

The following table provides more details about the types of resources:

Resource	Type	Syntax	Details
Value	1	`[<ResourceName>]`	Returns the value defined in the resource.
Layer	2	`[<ResourceName>]\\Name` `[<ResourceName>]\\Uri` `[<ResourceName>]\\Extent`	Returns the layer's name. Returns the Cartographic Information Model (CIM) path to the layer. Returns a string that represents the extent of the layer.
Workspace	3	`[<ResourceName>]\\<DatasetName>`	The path to a dataset that this resource returns can be a table, feature class, or feature dataset.
GridLocator	4	`[<ResourceName>]\\<MapName>` `[<ResourceName>]\\<MapName>\\Transformation\\<name of transformation>` `[<ResourceName>]\\<MapName>\\Transformation\\Log`	Returns the path to the appropriate grid `.xml` file in the product data files given the map name and AOI of the map product to create. Changes the projection of the AOI to WGS 84 GCS to avoid errors that can occur when the AOI is adjacent to the edge of a Universal Transverse Mercator (UTM) zone and a projection other than WGS 84 GCS is used. Provides log information about each transformation available for the given AOI so that you can identify which transformation to use. Note The `GridType` value in the log information should inform you which transformation to use. Zipper/Left/Right—AOI is across two UTM zones Dual—AOI is in one zone but within a certain distance of another Single—AOI is in one zone and not within a certain distance of another
Layout	6	`[<ResourceName>]\\Name` `[<ResourceName>]\\Uri` `[<ResourceName>]\\Name` `[<ResourceName>]\\<MapName>\\Uri` `[<ResourceName>]\\<MapName>\\ReferenceScale` `[<ResourceName>]\\<MapName>\\Extent` `[<ResourceName>]\\<MapName>\\SpatialReference` `[<ResourceName>]\\<MapName>\\<LayerName>\\Uri` `[<ResourceName>]\\<MapName>\\<LayerName>\\Extent`	Returns the layout's name. Returns the CIM path to the layout. Returns the layer's name. Returns the CIM path to a map in the layout. Returns the reference scaled of a map in the layout. Returns the extent of a map in the layout. Returns the spatial reference of a map in the layout. Returns the CIM path to a layer in a map in the layout. Returns the extent of a layer in a map in the layout.
ProductFiles	7	`[ProductFiles]\\<FileName>`	Returns the path to the file name in the product files.
JobResource	9	`[Job]\\Project` `[Job]\\Id` `[Job]\\Name` `[Job]\\User` `[Job]\\HasErrors` `[Job]\\HasWarnings` `[Job]\\Messages`	Returns the path to the ArcGIS Pro project that the job created. Returns the job's ID. Returns the job's name. Returns the name of the person who submitted the job. Returns `true` if the job has errors. Returns `true` if the job has warnings. Returns all of the job's messages.
PackageResource	10	`[Package]\\Project` `[Package]\\Database` `[Package]\\Output` `[Package]\\InputTemplate` `[Package]\\Raster` `[Package]\\Archive` `[Package]\\StagingDirectory` `[Package]\\OutputDirectory` `[Package]\\PackageName` `[Package]\\OutputPackage`	Returns the path to the .aprx file. Returns the path to database associated with the project file. Returns the path to the exported output file. Returns the path to the layout template that is used in the project. Returns the path to the raster file used in the project. Returns the path to the archive file. Returns the path to the staging folder where output files are staged before they are packaged. Returns the path to the output directory. Returns the name of the output package. Returns the path to the final output package that will be available through the public service URL.

Example usage

Add a map product definition to the service using the addProduct REST operation.

Request URL and parameters:

Use dark colors for code blocksCopy
https://machine.domain.com/server/rest/services/SampleService/TopographicProductionServer/addProduct

Use dark colors for code blocksCopy
productDefinition=
{
  "version": 0,
  "name": "ExampleProduct",
  "type": "MTM",
  "gridType": "TM50",
  "description": "Test Masking Product",
  "sheetIDField": "NRN",
  "featureDataset": "BM",
  "extractionDatabase": "MTM.gdb",
  "scale": "1:50,000",
  "productVersions": [
    {
      "name": "TRD_4_5",
      "template": "MTM50_Layout.pagx"
    }
  ],
  "resources": [
    {
      "name": "SourceWorkspace",
      "type": 3,
      "value": ""
    },
    {
      "name": "AOILayer",
      "type": 2,
      "value": ""
    },
    {
      "name": "SheetID",
      "type": 1,
      "value": ""
    },
    {
      "name": "Layout",
      "type": 6,
      "value": ""
    },
    {
      "name": "ProductFiles",
      "type": 7,
      "value": ""
    }
  ],
  "dataExtraction": [
    {
      "name": "MapService",
      "type": 19,
      "id": "MapService",
      "description": "Test extract from Map Service",
      "parameters": [
        {
          "name": "input_data",
          "value": "https://machinename.esri.com/server/rest/services/PostGreTest/MapServer"
        },
        {
          "name": "AOI",
          "value": "[AOILayer]\\Extent"
        },
        {
          "name": "buffer",
          "value": "5 kilometers"
        },
        {
          "name": "spatial_relationship",
          "value": "esriSpatialRelIntersects"
        },
        {
          "name": "DefinitionQuery",
          "value": ""
        },
        {
          "name": "includeDatasets",
          "value": ""
        },
        {
          "name": "excludedDatasets",
          "value": ""
        }
      ]
    }
  ],
  "operations": [
    {
      "name": "MapResource",
      "type": 11,
      "id": "62C3FFDE-F2C9-401E-9F57-50BECC3E15AP",
      "description": "Update BaseMap DataSources",
      "parameters": [
        {
          "name": "in_map",
          "value": "BaseMap"
        }
      ]
    },
    {
      "name": "Grid",
      "type": 4,
      "id": "22C3FFDE-F4C9-401E-9F57-50BRCC3E15GN",
      "description": "BaseMap Grid",
      "toolName": "MakeGridsAndGraticulesLayer_topographic",
      "validation": 2,
      "properties": {
        "type": "PropertySet",
        "propertySetItems" : [
          "AddOutputToMap",
          "BaseMap"
        ]
      },
      "parameters": [
        {
          "name": "in_grid_xml",
          "value": "[GridLocator]\\BaseMap"
        },
        {
          "name": "area_of_interest",
          "value": "[AOILayer]"
        },
        {
          "name": "target_feature_dataset",
          "value": "[SourceWorkspace]\\BM_GRD"
        },
        {
          "name": "out_layer_name",
          "value": "BMGrid"
        },
        {
          "name": "grid_name",
          "value": "BMGrid"
        },
        {
          "name": "configure_layout",
          "value": "CONFIGURE_LAYOUT"
        },
        {
          "name": "layout",
          "value": "[Layout]"
        },
        {
          "name": "map_frame",
          "value": "BaseMap Map Frame"
        }
      ]
    },
    {
      "name": "CreateMasks",
      "type": 7,
      "id": "35C3FFRF-F2C9-401E-9F57-30BECC3E15KF",
      "description": "Create Masks for Base Map",
      "toolName": "MakeMasksFromRules_topographic",
      "validation": 2,
      "properties" : {
        "type" : "PropertySet",
        "propertySetItems" : [
          "MapName",
          "BaseMap"
        ]
      },
      "parameters": [
        {
          "name": "in_map",
          "value": "BaseMap"
        },
        {
          "name": "rule_file",
          "value": "[ProductFiles]\\MTM_Basemap_Masking_Rules.xml"
        },
        {
          "name": "out_feature_dataset",
          "value": "[SourceWorkspace]\\Masks"
        }
      ]
    },
    {
      "name": "ApplyMasks",
      "type": 7,
      "id": "93C3FFDE-F2C9-401K-9F57-50BRCC3E15RW",
      "description": "Apply Masks for Base Map",
      "toolName": "ApplyMasksFromRules_topographic",
      "validation": 2,
      "properties" : {
        "type" : "PropertySet",
        "propertySetItems" : [
          "MapName",
          "BaseMap"
        ]
      },
      "parameters": [
        {
          "name": "in_map",
          "value": "BaseMap"
        },
        {
          "name": "rule_file",
          "value": "[ProductFiles]\\MTM_Basemap_Masking_Rules.xml"
        },
        {
          "name": "in_feature_dataset",
          "value": "[SourceWorkspace]\\Masks"
        }
      ]
    }
  ]
}
raster=https://servermachine.domain.com/server/rest/services/DEM/ImageServer
ancillaryLayers=
{
	"layer": "https://servermachine.domain.com/server/rest/services/SampleWorldCities/MapServer/1",
	"featureClass": "",
	"map": "BaseMap",
	"layerIndex": "0"
}
f=json

JSON Response syntax

The following is the syntax of a response:

Use dark colors for code blocksCopy
{
  "success" : <true | false>
}

JSON Response example

The following is an example response when the product is added successfully:

Use dark colors for code blocksCopy
{
  "productName": "ExampleProduct",
  "success": true
}

The following is an example error response:

Use dark colors for code blocksCopy
{
  "error": {
    "code": -2147211754,
    "message": "Map product ExampleProduct already exists. Map product names must be unique.",
    "details": [
    ]
  }
}