How to Submit Services for Publication on GENESIS

Initial Setup

  1. Setup a “user” connection to the GENESIS Production environment in ArcCatalog, if you haven’t already, according to these instructions.
  2. Request access to the GENESIS Development ArcGIS Server so that you can test the publication, performance, look-and-feel, and functionality of your service before submitting it.
  3. Setup a “publisher” connection to the GENESIS Development environment in ArcCatalog, if you haven’t already, according to these instructions.
  4. Familiarize yourself with the GENESIS Development environment.

Building Your Service

The process for preparing different types of services varies. Depending on the type of service you are looking to prepare, follow the appropriate steps/advice below.

Map Services

  1. Familiarize yourself with building MXDs for the purpose of authoring map services, if you haven’t already. The documentation available on the Arcgis.com website is a good place to start.
  2. There are a number of technical and practical considerations you should make when making a map document to be published as a service. Many of these considerations have been combined into a “Best-Practices” document that includes further explanation, additional detail where necessary, etc.
  3. Build your MXD and review it according to the specifications. You can use this checklist if you like.
  4. Analyze the Map before attempting to go further. Correct any errors and try your best to resolve any warnings. If you don’t understand the errors/warnings, you should be able to read about them by right clicking and choosing Help.analyze-map

Image Services

  • Mosaic Datasets that reference data should be maintained in an enterprise geodatabase. The data they reference, however, should be on enterprise-class network storage
  • Raster Datasets should generally not be stored in an Enterprise Geodatabase until there is a transactional process that constantly changes it and file contention would be an issue. In this case, speak with the GENESIS Admin about where the best place is to store said data to be referenced in the image service.

Geoprocessing Services

  • Familiarize yourself with how to properly construct a geoprocessing service, how temporary data should be handled, and how to read inputs and return outputs.
  • Geoprocessing services should be developed to have a “test mode” where a Boolean input, defaulting to False when not provided, can be used to execute the task successfully with valid outputs and no unintended changes being made to back-end systems, such as data edits.
  • Generally, you will want to build your service using python only. Other command-line tools (such as compiled .Net exe tools) are allowable as well.
  • Third-party libraries must be included with your code in the submitted SD file inside the “v101” folder and referenced with local relative paths. The easiest way to do this is to build your code with the libraries in sub-folders of your source code folder and then add those folders into the SD file manually using 7-Zip (an SD file is a 7-Zip file).
  • Do not ever, under any circumstances write out data to the local server machine that the service is running on, temporary or not. That’s what the scratch workspace is for. If you need file storage, then its up to you to arrange for a file share to accommodate that and get the permissions setup correctly.
  • Keep in mind that your service should be stateless and assume that it will be run by multiple users simultaneously. Consider thread safety, race conditions, file locking, and file corruption issues that could occur if the service was triggered more than once at the same time. The ONLY exception to this rule is stack-trace logs that you may write out if (and only if) the code crashes. Do not store normal run-time logs, status logs, etc in this way. If you want to log anything, it should be either through the service output messages or in a database, or in a carefully constructed file share with thread/process-safe file naming to guarantee no file name conflicts.
  • Keep in mind that in the production environment, your GP service could be running/executing/triggered on any one of the many ArcGIS Servers that power GENESIS. You have no control of this, nor way of predicting this behavior. Interact with your GP service and its outputs only through the web service interface or a database that it reads/writes to.
  • The onus is on you to make sure the service can be published and will work in this environment using the development server to test it.

Geocode/Locator Services

  • Compound Locators are not supported.
  • Locators are best published as a file-based locator (.loc/.lox/.loc.xml file set)
  • File-based locators can be stored/referenced in a common shared location and should be provided to the GENESIS Admins prior to building the SD file for publication.

Other Service Types

Other service types are not routinely accepted for normal publication. Please consult with the GENESIS Admins if you need to publish any other type of service to address any special considerations that may be required.

Testing Your Service

  1. Familiarize yourself with how to publish a service in ArcGIS Desktop.
  2. Begin the service publication process. Choose the option to Publish a service, Save a service definition file,  or Overwrite an existing service depending on what you would like to do at this stage in your testing. When you are done, click Next.
    • Publishing directly is fine in some circumstances, but most of the time you will probably want to save
  3. When prompted, choose the connection to the GENESIS Development server that you created earlier. If the password wasn’t entered already or is no longer valid, you may get prompted to login at this point. You must provide a service name at this point: use the current date in YYYYMMDD format. If you chose to save a service definition, then you will have a slightly different dialog than the one below, which has another option of No available Connection. Choosing this option will not perform as many quality checks on the service and as such it is not recommended. When you are done, click Next.
    • For example: 20161202 for December 02, 2016. This format, which is the same format used in the production environment, is designed to minimize change disruption by allowing users/applications to reference a given version of a service without disruption when new versions are published.publish-services-2
  4. You will be prompted to select a folder to publish your service in. The folder you choose should be the “logical” name of your service, as will appear in it’s URL. If you have already created such a folder at some prior time, choose the option to Use existing folder and select it from the list. If you have not done this already, then choose the option to Create new folder and enter the folder name in the box provided. Note: The name of the folder must follow these rules:
    • The name may contain:
      • Uppercase letters
      • Lowercase letters
      • Digits
      • Underscores
    • The name must start with an Uppercase letter.
    • The name must be in the format: Some_Service_Name
      • Use underscores to separate words.
      • Capitalize all letters of words that are acronyms, and otherwise use title case.
    • If the service is in support of some application, and intended to be used more or less exclusively in that application, then the service name should be prefixed with the application short-name/acronym, and separated an underscore. Later when submitting, you will use a dash instead.
      • For example: APPNAME_Some_Service_Name
        publish-services-3
        When you are done, click Continue.
  5. For map services that do not have editing enabled through feature access, be sure to disable schema locking. Type “false” in the schemaLockingEnabled property field. It will be “true” by default. Click OK.
    schema-locking-disable
  6. Now enable any applicable Capabilities in the menu on the left (for example if a feature service is required, then enable Feature Access). This is important at this stage because the analyze command will perform additional checks to make sure those capabilities will work with your map.capabilities
  7. Click the Analyze button near the top-right to analyze your service. Correct any errors and try your best to resolve any warnings. Right clicking on the reported issues will give you options for resolving them. If you don’t understand the errors/warnings, you should be able to read about them by right clicking and choosing Help.
    • Warnings about data stored on UNC paths and about data reprojecting can generally be ignored, particularly if that is expected behavior.
    • In the GENESIS environment, data is never stored locally on the server machines. If you are referencing a data source that is not registered on the server, you should not register it on your own. Please consult with the GENESIS Admin first since your service may not function as intended and definitely will not in the production environment.
    • The Development EGDB/SDE environment can be (optionally) referenced in the development GENESIS ArcGIS Server, but never submit services for publication in GENESIS Production that reference the development EGDBs. Such connections will be blocked for security, performance, and system integrity reasons.
  8. Click the Publish button near the top-right to publish your service

Preparing your Service for Submission

Once the service has been tested in the development environment, including any capabilities that are required, then a service definition file (i.e. *.sd file) must be generated. The SD file is what you will submit for publication in GENESIS.

  1. Identify what the logical name of your service will be. You will use this name in step 3. This will be the name of the service folder that will be used in GENESIS when published. Note: The name of the folder must follow these rules:
    • The name may contain:
      • Uppercase letters
      • Lowercase letters
      • Digits
      • Underscores
      • Dashes
    • The name must start with an Uppercase letter.
    • The name must be in the format: Some_Service_Name
      • Use underscores to separate words.
      • Capitalize all letters of words that are acronyms, and otherwise use title case.
    • If the service is in support of some application, and intended to be used more or less exclusively in that application, then the service name should be prefixed with the application short-name/acronym, and separated by a dash.
      • For example: APPNAME-Some_Service_Name
      • Dashes are reserved for this purpose. Don’t use them otherwise.
  2. In some location where you personally store your service submissions, prepare a folder named in some way to uniquely identify this service submission for your own reference.
    • For example: Some_Service_Name 2016-12-07
  3. Inside this new folder, prepare another folder using the logical name you identified in step 1. Avoid storing anything but the .sd files for this particular submission in this folder.
    • For example: Some_Service_Name or APPNAME-Some_Service-Name
    • Note: You are permitted to uses dashes here if you have an APPNAME prefix. Its OK that this is different than the service folder you created in the dev environment that did not accept dashes.
  4. Use the tools in ArcGIS Desktop to prepare the SD file using the process above and selecting the option to Save a service definition file at the start of the wizard. When prompted to choose a location to save the service definition (i.e. the .sd file), choose the folder you created in step 3.
    • If you choose No available connection (which is not recommended), it is important that the option to Include data in the service definitions when publishing is  not enabled, or you will get errors and this process will fail, since we do not allow this in the GENESIS ArcGIS Server environments.
    • In the case of a geoprocessing service, you must add all tasks you wish to include in the service before submitting the SD file.
    • In the case of a geocode (i.e. locator) service, compound geocoders are not supported and cannot be used.
  5. Click the Stage button in the upper right of the Service Editor window to generate the .sd file.
  6. The .sd file will not be named correctly at this stage. To fix it, open the folder you created in step 3 and rename the .sd file to the following format: <Date>.<ServiceType>.sd
    • <Date> is the service release date as used above when testing in the dev server in YYYYMMDD format
    • <ServiceType> is one of:
      • MapServer
      • GPServer
      • ImageServer
      • GeocodeServer
    • Example:  C:\_LOCALdata\My Service Submissions\Some_Service_Name 2016-12-07\Some_Service_Name\20161207.MapServer.sd
  7. The folder created in step 3 is what you are going to submit. Make sure there is nothing in the folder except the .sd file for your service unless instructed otherwise by the GENESIS Admin.

Note: Naturally, some of these steps could be skipped, and you could put the file where-ever you like on your own machine. These steps are provided to help you prevent mistakes and to help streamline the submission process. Following these steps will reduce the chances of there being issues with your submission. Deviate from them at your own risk.

Submitting your Service

  1. Create a new submission folder in the dropbox by executing the this CMD script:
    • \\goa\apps\Genesis_Config\Dropbox\Create New Submission Folder.cmd
      • Simply copy this path, open your start menu, paste (CTRL+V) and hit enter.
      • Read the pop up dialog that opens, then click OK.
      • A new Explorer window will open. This is your submission folder. Leave this window open for now.
  2. Copy/Paste one or more service folders prepared earlier into the submission folder you just generated to make up a single submission.
  3. Send an email to the GENESIS Admin mailbox.
    • In the subject line, include the submission ID provided (i.e. the name of the submission folder you generated)
    • In the body, please include:
      1. the names of the services in your submission folder that you want published,
      2. if any specific service capabilities are required or must be disabled, and
      3. the security requirements/permissions requested. Options include:
        1. Public access,
        2. Public access, but completely hidden from the service directory, yet accessible to anyone with the URL,
        3. All GOA users, or
        4. Role-based security based on any combination of:
          • GOA security groups
          • GOA email distribution lists
          • one or more specific users.
  4. Close the “Submission folder” explorer window.

Last updated: February 13, 2020