Publish Service Definition

URL:: https://<root>/System/PublishingTools/GPServer/Publish Service Definition/submitJob
Methods:: GETPOST
Required Capability:: For federated servers - assigned either the publisher role or a custom role with the Publish server services privilege. For standalone servers - assigned the publisher role.
Version Introduced:: ??

Description

The Publish Service Definition operation publishes the service definition file (.sd) for a map, image, geocoding, or geoprocessing service to a federated or standalone ArcGIS Server. This operation is performed asynchronously and returns a jobID that allows publishers to access the job resource and poll for its status. When the operation is completed successfully, a service corresponding to the service configuration is published and the service definition file is deleted from the server.

This operation can also be used to do the following:

Assign specific portal item IDs to services published to a federated server
Modify the service configuration of a service before it is published
Overwrite a preexisting service with a new service definition

For more information on these workflows, see the Additional publishing workflows section below.

Publishing a service definition

A service definition is a portable file that contains all the information needed to publish a service, including the service configuration. The service configuration outlines a service’s properties (such as the service’s name and what folder the service is being published to), as well as any enabled capabilities and extensions.

Note

While the documentation refers to the Publish Service Definition operation resulting in a single service being published, the actual number of services published is dependent on the service configuration. For example, if this operation is used to publish the service definition for a map service, and its configuration shows that it has the WMS capability enabled, two services would be published: a map service and a WMS service. Similarly, if a map service’s service configuration has both the Feature and WFS capability enabled, three services would be published: a map service, a feature service, and a WFS service. Performing this operation to publish image and geoprocessing services may also result in multiple services published at once, depending on which capabilities are enabled in their service configurations.

For more information on service definition files, and how to save service definition files in ArcGIS Pro, see the following documentation: Introduction to saving service definitions

Prior to performing the Publish Service Definition operation, the service definition file must first be uploaded to ArcGIS Server.

Standard publishing workflow

Once the service definition file is uploaded to ArcGIS Server, copy the upload itemID returned as part of the upload operation’s response. For the Publish Service Definition operation, provide the upload itemID as input for the in_sdp_id parameter and submit the request.

Additional publishing workflows

In addition to the standard publishing workflow, publishers can use the Publish Service Definition operation to assign portal item IDs to services or modify the service configuration before the services are published, as well as overwrite the service definition for an already existing service.

The tabs below outline these workflows in more detail.

Assign portal item IDs

When the Publish Service Definition operation is performed on a federated server (such as the hosting server), a corresponding portal item is also created for the published service. Prior to publishing, publishers can set a prescribed portal item ID for the service using the in_publish_options parameter.

Setting prescribed portal item IDs can be beneficial for publishers who are publishing the same service to multiple portals and want the service to maintain the same item ID in each environment, or for publishers that are moving the service from one portal to another and wish to preserve the service’s item ID in the receiving portal.

To set a prescribed portal item ID for a service, publishers should include the portalProperties object for the in_publish_options parameter. The portalProperties object must include the following:

The preserveIDs property, set as true
A portalItems array, which must have an entry for each service in the service configuration. Each entry must include the portal item ID that will be assigned to the service, as well as the service type.

An example of the portalProperties object that assigns portal item IDs to a map service and a WMS service is shown below:

Use dark colors for code blocksCopy
{
  "portalProperties" : {
    "preserveIDs" : true,
    "portalItems" : [
      {
        "type" : "MapServer",
        "itemID" : "d5590eef6b7343e597da52ec4b940a98"
      },
      {
        "type" : "WMSServer",
        "itemID" : "b0625e1fe42c4be0ab0d407795b3af36"
      }
    ]
  }
}

Once inputs have been provided for the in_sdp_id and the in_publish_options parameter, submit the request. When published, the new portal item created for the service will use the prescribed item ID.

Modify the service configuration

The Publish Service Definition operation can be used to change aspects of the service configuration, such as the service’s name and folder to which it will be published, before publishing the service.

When a service definition file is uploaded to ArcGIS Server, publishers can view the service configuration file, which can be accessed by making a request of the following form:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/admin/uploads/<itemID>/serviceconfiguration.json?f=pjson

The service configuration can be copied from the above endpoint and used as input for the Publish Service Definition operation’s in_config_overwrite parameter. Publishers can then modify the values in the configuration JSON object before publishing.

If a service’s service configuration does not need to be changed, the in_config_overwrite parameter should be left empty.

Once inputs have been provided for the in_sdp_id and the in_config_overwrite parameter, submit the request. When published, the service will be created using the updated service configuration.

Overwriting an existing service

The Publish Service Definition operation can overwrite an existing service, allowing publishers to publish a new service with a modified service configuration while retaining the item ID and service URLs of the original service.

ArcGIS Enterprise 11.5 or later

At 11.5, publishers can now overwrite a published service without using the Overwrite tool in ArcGIS Pro. Publishers can create a new service definition file, upload it to ArcGIS Server, and then call the Publish Server Definition operation. To succesfully overwrite a preexisting service, publishers must include the overwrite property, set as true, as the input for the in_publish_options parameter. If a request to overwrite an existing service does not include the overwrite property, or if the overwrite property is set as false, the operation will fail.

ArcGIS Enterprise 11.4 or earlier

For organizations using a version of Enterprise at 11.4 or earlier, publishers can only overwrite an existing service using the Overwrite tool in ArcGIS Pro. To overwrite a service, publishers must perform the following steps:

Open the ArcGIS Pro project that contains the map that was published as a service
Choose the service that will be overwritten from the list of services available on the server
Using the Overwrite tool, make any necessary modifications to the service's configuration, such as modifying the item description, modifying the number of instances, or enabling capabilities or extensions
Choose to either Publish or Save as SD

After clicking Publish, ArcGIS Pro will create a new, overwriting service definition file that is uploaded to the server. It then calls the Publish Service Definition operation and overwrites the existing service.

After clicking Save as SD, publishers can choose to overwrite the service manually at a later time by uploading the service definition file and performing the standard publishing workflow. The publishers must use the service definition file generated from the Overwrite tool, as attempting to use a different file will cause the operation to fail.

Request parameters

Parameter Details

Parameter	Details
`in_sdp_id` (Required)	The upload `itemID` of the uploaded service definition file. Example Use dark colors for code blocksCopy `1 in_sdp_id=i029bb7ce-8fd3-4bb1-a823-2fc9936f9d5a`
`in_config_overwrite` (Optional)	The overwriting service configuration JSON. The information provided in this parameter will overwrite the service configuration information that was included with the service definition file when it was uploaded to ArcGIS Server, and the resulting service will be created using the new service configuration.
`in_publish_options` (Optional)	A set of additional options for the `Publish Service Definition` operation, such as assigning specific portal item IDs to a service before its published or specifying whether the service definition file will overwrite a preexisting service. For prescribed portal item IDs, this parameter must include a `portalProperties` object that includes the following: The `preserveIDs` property, set as `true` A `portalItems` array, which must have an entry for each service in the service configuration. Each entry must include the portal item ID that will be assigned to the service, as well as the service type. At 11.5, this parameter can also accept the `overwrite` property. The `overwrite` property designates the service definition file as overwriting a preexisting service. If publishers attempt to overwrite a preexisting service without including the `overwrite` property, or not setting the property as `true`, the operation will fail. Example 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 //Prescribed portal item IDs in_publish_options={ "portalProperties" : { "preserveIDs" : true, "portalItems" : [ { "type" : "MapServer", "itemID" : "d5590eef6b7343e597da52ec4b940a98" }, { "type" : "WMSServer", "itemID" : "b0625e1fe42c4be0ab0d407795b3af36" } ] } } //Overwrite service definition file in_publish_options={"overwrite": true}`
`returnZ` (Optional)	A Boolean that determines if z-values are included as part of the result. If `true`, z-values will be included in the results if the features have z-values. Otherwise, z-values will not be returned. The default is `false`. Values: `true` \| `false`
`returnM` (Optional)	A Boolean that determines if m-values are included in the results. If `true`, m-values will be included in the results if the features value has m-values. Otherwise, m-values will not be returned. The default is `false`. Values: `true` \| `false`
`returnTrueCurves` (Optional)	A Boolean that specifies whether true curves will be returned in the output geometries (`true`). When `false`, curves will be converted to densified polylines or polygons. The default value is `false`. Values: `true` \| `false`
`simplifyFeatures` (Optional)	A Boolean that specifies whether geometries should be simplified (`true`). Simplifying can siginificantly reduce the size of the response while fulfiling the accuracy needs for most analysis, espeically for complex and large geometries. The default value is `false`. Values: `true` \| `false`
`context` (Optional)	Additional settings that affect the result of the operation: `outSR` is the spatial reference of the output geometries. `processSR` is the spatial reference that the model will use to perform geometry operations. `extent` will only process features that overlap the specified extent. The output features will have an extent that is the same or larger than the `extent` value.
`f`	The response format. The default format is `html`. Values: `html` \| `json` \| `pjson`

in_sdp_id

(Required)

The upload itemID of the uploaded service definition file.

Example
Use dark colors for code blocksCopy
in_sdp_id=i029bb7ce-8fd3-4bb1-a823-2fc9936f9d5a

in_config_overwrite

(Optional)

The overwriting service configuration JSON. The information provided in this parameter will overwrite the service configuration information that was included with the service definition file when it was uploaded to ArcGIS Server, and the resulting service will be created using the new service configuration.

in_publish_options

(Optional)

A set of additional options for the Publish Service Definition operation, such as assigning specific portal item IDs to a service before its published or specifying whether the service definition file will overwrite a preexisting service.

For prescribed portal item IDs, this parameter must include a portalProperties object that includes the following:

The preserveIDs property, set as true
A portalItems array, which must have an entry for each service in the service configuration. Each entry must include the portal item ID that will be assigned to the service, as well as the service type.

At 11.5, this parameter can also accept the overwrite property. The overwrite property designates the service definition file as overwriting a preexisting service. If publishers attempt to overwrite a preexisting service without including the overwrite property, or not setting the property as true, the operation will fail.

Example
Use dark colors for code blocksCopy
//Prescribed portal item IDs
in_publish_options={
  "portalProperties" : {
    "preserveIDs" : true,
    "portalItems" : [
      {
        "type" : "MapServer",
        "itemID" : "d5590eef6b7343e597da52ec4b940a98"
      },
      {
        "type" : "WMSServer",
        "itemID" : "b0625e1fe42c4be0ab0d407795b3af36"
      }
    ]
  }
}

//Overwrite service definition file
in_publish_options={"overwrite": true}

returnZ

(Optional)

A Boolean that determines if z-values are included as part of the result. If true, z-values will be included in the results if the features have z-values. Otherwise, z-values will not be returned. The default is false.

Values: true | false

returnM

(Optional)

A Boolean that determines if m-values are included in the results. If true, m-values will be included in the results if the features value has m-values. Otherwise, m-values will not be returned. The default is false.

Values: true | false

returnTrueCurves

(Optional)

A Boolean that specifies whether true curves will be returned in the output geometries (true). When false, curves will be converted to densified polylines or polygons. The default value is false.

Values: true | false

simplifyFeatures

(Optional)

A Boolean that specifies whether geometries should be simplified (true). Simplifying can siginificantly reduce the size of the response while fulfiling the accuracy needs for most analysis, espeically for complex and large geometries. The default value is false.

Values: true | false

context

(Optional)

Additional settings that affect the result of the operation:

outSR is the spatial reference of the output geometries.
processSR is the spatial reference that the model will use to perform geometry operations.
extent will only process features that overlap the specified extent. The output features will have an extent that is the same or larger than the extent value.

f

The response format. The default format is html.

Values: html | json | pjson

Example usage

The following are sample requests (GET and POST) for the Publish Service Definition operation:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/System/PublishingTools/GPServer/Publish%20Service%20Definition/submitJob?in_spd_id=i029bb7ce-8fd3-4bb1-a823-2fc9936f9d5a&in_config_overwrite=&in_publish_options=&returnZ=false&returnM=false&returnTrueCurves=false&simplifyFeatures=true&context=&f=pjson

Use dark colors for code blocksCopy
POST /<context>/rest/services/System/PublishingTools/GPServer/Publish%20Service%20Definition/submitJob HTTP/1.1
Host: organization.example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

in_sdp_id=i029bb7ce-8fd3-4bb1-a823-2fc9936f9d5a&in_config_overwrite=&in_publish_options={"portalProperties": {"preserveIDs": true,"portalItems": [{"itemID": "d5590eef6b7343e597da52ec4b940a98","type": "MapServer"},{"itemID": "b0625e1fe42c4be0ab0d407795b3af36","type": "WMSServer"}]}}&returnZ=false&returnM=false&returnTrueCurves=false&simplifyFeatures=true&context=&f=pjson

JSON Response example

The tabbed sections below outline the workflow to review the Publish Service Definition job and view the out_result resource:

When the Publish Service Definition job request is submitted, the following JSON response is returned:

Use dark colors for code blocksCopy
{
  "jobId": " j417d7e8fc1544a8bb03574b5a5b151bb",
  "jobStatus": "esriJobSubmitted"
}

The value for jobId can be appended to a modified version of the request URL (shown below) to access the job resource:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/System/PublishingTools/GPServer/Publish%20Service%20Definition/jobs/j417d7e8fc1544a8bb03574b5a5b151bb?f=pjson

The job resource can be polled to check the status of the Publish Service Definition job. When the job is completed successfully, the following JSON response is returned:

Use dark colors for code blocksCopy
{
  "jobId": "j417d7e8fc1544a8bb03574b5a5b151bb",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "out_soap_svc_url": {
      "paramUrl": "results/out_soap_svc_url"
    },
    "out_rest_svc_url": {
      "paramUrl": "results/out_rest_svc_url"
    },
    "out_results": {
      "paramUrl": "results/out_results"
    }
  },
  "inputs": {
    "in_sdp_id": {
      "paramUrl": "inputs/in_sdp_id"
    },
    "in_config_overwrite": {
      "paramUrl": "inputs/in_config_overwrite"
    }
  },
  "messages": [
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Start Time: Wednesday, December 11, 2024 10:03:37 AM"
    },
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Getting server information (server folders, data stores, etc.)."
    },
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Validating service definition."
    },
    {
      "type": "esriJobMessageTypeWarning",
      "description": "WARNING 086222: Output directory in service definition is not set or is invalid. Using default output directory."
    },
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Creating the service."
    },
    {
      "type": "esriJobMessageTypeInformative",
      "description": "Succeeded at Wednesday, December 11, 2024 10:03:50 AM (Elapsed Time: 13.11 seconds)"
    }
  ]
}

The value for the out_results property's paramUrl can be appended to the job resource URL to access the out_results resource:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/System/PublishingTools/GPServer/Publish%20Service%20Definition/jobs/j417d7e8fc1544a8bb03574b5a5b151bb/results/out_results?f=pjson

The out_results resource returns the following JSON response:

Use dark colors for code blocksCopy
{
  "paramName": "out_results",
  "dataType": "GPString",
  "value": {
    "svcUrls": {
      "SOAPUrl": https://organization.example.com:6443/<context>/services/Demographics/MapServer
      "RESTUrl": https://organization.example.com:6443/<context>/rest/services/Demographics/MapServer
    },
    "svcConfigInfo": {
      "name": "Demographics",
      "type": "MapServer",
      "folder": ""
    }
  }
}

This resource returns service information such as the service’s name, type, and location, as well as the REST and SOAP service URLs.