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 describes additional properties for the map product 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.
`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 Enterprise11.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 is an example syntax of a data extraction operation in an array: 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 { "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 .dt2 raster file that gets extracted>" }, { "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 is only used when extracting a raster. The optional `includeDatasets` and `excludeDatasets` properties cannot be combined. Use one or the other. The following is an example of the dataExtraction 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 { "name": "RasterDataset", "type": 19, "id": "RasterDataset", "description": "Raster Dataset Extract", "parameters": [ { "name": "input_data", "value": "[ProductFiles]\\Elevation.gdb\\DEM" } { "name": "AOI", "value": "[AOILayer]\\Extent" } { "name": "buffer", "value": "2 kilometers" } { "name": "spatial_relationship", "value": "esriSpatialRelIntersects" } { "name": "DefinitionQuery", "value": "" } { "name": "includeDatasets", "value": "" } { "name": "excludeDatasets", "value": "" } ] } Note There are default operations available to extract map service layers and the raster, if one is defined. The two names `defaultMapExtraction` and `defaultRasterExtraction` are reserved for these default extraction operations, respectively. If they are not defined, they are automatically added at runtime. If they are defined, the following properties can be modified: `AOI` `buffer` `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>`	Returns the path to the correct grid `.xml` file in the product data files given the map name and AOI of the map product to create.
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.

Request example

The following is an example of the productDefinition parameter:

Use dark colors for code blocksCopy
{
  "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"
        }
      ]
    }
  ]
}

Example usage

The following URL is an example of the addProduct REST operation:

Use dark colors for code blocksCopy
https://machine.domain.com/server/rest/services/SampleService/TopographicProductionServer/addProduct?productDefinition=&raster=&ancillaryLayers=&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": [
    ]
  }
}