Skip To Content
ArcGIS Developer
Dashboard

Add Product

Description

License:

The use of this resource requires an ArcGIS GIS Server Advanced license and a Production Mapping or Defense Mapping server extension license.

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

ParameterDetails
productDefinition

(Required)

The JSON definition of a map product. More details are provided in the following section.

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:


[
  {
    "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 properties

The following are additional details about the properties of the map product specified in the productDefinition parameter:

PropertyDetails

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. Valid 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

The JSON 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 Defense Mapping or Production Mapping server extension product files.

Starting at ArcGIS Enterprise 11.2, there are additional properties that can be applied to the JSON :

  • extractionDatabase—The value overwrites the value for extractionDatabase at the map product level.
  • operationOverrides—The values in the key-value pairs of parameters overwrite the existing ones for the operation defined by the ID provided.
  • excludedOperations—The operations pertaining to the IDs provided are excluded.

The following JSON example includes three product versions: TRD_4_5, TRD_4_5_1, and TRD_4_6. The JSON for TRD_4_5 contains examples of the operation overrides and exclusions available at Enterprise 11.2:


"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 in JSON with three key-value pairs: name, type, and value. It provides values to the operation parameter 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.

To use a resource in the operation parameter, place brackets around its name. In the following example, the resource SheetID is defined, and the LayerProperties operation has a parameter named definition_query and the value is set to NRN = '[SheetID]'. At runtime, [SheetID] is replaced with the Sheet Identifier of the map being generated.


{
  "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.

dataExtraction

JSON that defines how the data will be extracted.

The following JSON syntax is an example of a data extraction operation in the array:


{
  "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 cartography database that is used as a starting schema for a job, then the feature dataset name must exist in the source.
  • The extraction is skipped when 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.


{
  "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:

  • 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 by JSON with the following parameters:


{
  "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 operation:


{
  "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.

Types of resources

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

ResourceTypeSyntaxDetails

Workspace

3

[<ResourceName>]\\<DatasetName>

The path to a dataset that this resource returns can be a table, feature class, or feature dataset.

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

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 Cartographic Information Model (CIM) path to the layout

Returns the layer's name

Returns the CIM path to a specific map in the layout

Returns the reference scaled of a specific map in the layout

Returns the extent of a specific map in the layout

Returns the spatial reference of a specific map in the layout

Returns the CIM path to a layer in a specific map in the layout

Returns the extent of a layer in a specific map in the layout

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

Value

1

[<ResourceName>]

Returns the value defined in the resource

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

Request example

The following is an example of the productDefinition parameter:


{
  "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:

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:


{
  "success" : <true | false>
}

JSON Response example

The following is an example of a response:


{
  "productName": "ExampleProduct",
  "success": true
}

JSON Response example

The following is an example of an error response:


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