Map Services User Guide Using and Creating Map Services
USDA Forest Service Geospatial Technology Applications Center Enterprise GIS
Geospatial Management Office 2/1/2018
Map Services User Guide
Table of Contents
1 Overview ...... 7
1.1 What are Map Services? ...... 7
1.2 Process Overview ...... 8
1.3 Roles ...... 8
1.3.1 National Data Center ArcGIS Server Administrator ...... 9
1.3.2 Data Center Map Service Administrator ...... 9
1.3.3 Local Map Service Point of Contact (POC) ...... 10
1.4 Types of GIS Web Services ...... 11
1.4.1 Map Services ...... 11
1.4.2 Feature Services ...... 13
1.4.3 Geoprocessing Services ...... 14
1.5 ArcGIS Online...... 15
1.6 Benefits and Limitations of Using GIS Web Services ...... 15
1.6.1 Considerations for Using GIS Web Services ...... 15
1.6.2 Considerations for Using Geoprocessing Services ...... 16
1.7 Guidelines for Use of GIS Web Services for Developers ...... 17
2 Preparing Data & Authoring Map Documents ...... 18
2.1 Content Governance...... 18
2.1.1 Map and Feature Services ...... 18
2.1.2 Geoprocessing Services ...... 18
2.2 Connecting to Data in the Enterprise Environment ...... 19
2.2.1 SDE ...... 20
2.2.2 File Based Data (EFS) ...... 20
2.2.3 Database Schema Locking ...... 21
2.3 Choosing the Right Projection for Your Data ...... 22
EGIS US Forest Service Page 2 Map Services User Guide 2.3.1 Dynamic Map Service Coordinate System ...... 22
2.3.2 Tiled/Cached Map Service Coordinate System ...... 23
2.4 Authoring the Map Document ...... 24
2.4.1 Map Service Planning ...... 24
2.4.2 Scale Dependent Rendering ...... 25
2.4.3 Symbology ...... 26
2.4.4 Labeling ...... 26
2.4.5 Definition Queries ...... 26
2.4.6 Unused Layers and Data Frames ...... 26
2.5 Map Document Properties Guidelines ...... 26
2.5.1 Assumptions ...... 27
2.5.2 Enter Map Document Properties ...... 27
2.5.3 Enter Data Frame Description ...... 28
2.5.4 Choose Data Frame Projection Properties ...... 28
2.5.5 Choose Data Frame Extent...... 29
2.5.6 Enter Layer Properties ...... 29
2.6 Authoring Resources for Geoprocessing Services ...... 29
2.7 Naming and Filing Conventions ...... 30
2.7.1 Map Document Naming Convention ...... 30
2.7.2 Naming Convention Examples ...... 31
2.7.3 Map Document Filing Location ...... 31
2.7.4 Geoprocessing Toolbox and Map Document Naming Convention ...... 32
2.7.5 Geoprocessing Toolbox and Map Document Filing Location ...... 32
2.8 Submit the Map Document for Optimizing and Publishing ...... 32
3 Publish and Administer GIS Web Services ...... 33
3.1 Roles and Permissions ...... 33
EGIS US Forest Service Page 3 Map Services User Guide 3.2 Map Services Publication Coordination...... 34
3.2.1 Map Services Publication Timing ...... 34
3.2.2 Map Services Version Management ...... 34
3.2.3 Map Services Organization and Cleanup ...... 34
3.3 Optimizing and Publishing the Map Document...... 35
3.3.1 Projections for Map Services ...... 36
3.3.2 Verify the Initial Extent of the Map ...... 36
3.3.3 Analyze the Map Document ...... 36
3.3.4 Preview as a Map Service ...... 36
3.3.5 Process for Updating the Map Service ...... 36
3.4 Login to Server Manager ...... 37
3.5 GIS Web Service Creation Wizard ...... 37
3.6 GIS Web Service Filing and Naming Conventions ...... 38
3.7 Map Service Capabilities ...... 38
3.8 Feature Service Considerations ...... 39
3.8.1 Data Source and Database Configuration ...... 39
3.8.2 Preparing Data for Offline Use ...... 39
3.8.3 Publishing Procedures for Web and Mobile ...... 40
3.8.4 Securing Feature Services ...... 41
3.8.5 Authoring ArcGIS Online Map for Offline Use ...... 41
3.9 Geoprocessing Service Considerations ...... 42
3.9.1 Folder Structure and Filing Location ...... 42
3.9.2 Output Directory and the Scratch Workspace ...... 42
3.10 Cached Map Service Considerations ...... 42
3.11 Make GIS Web Services Available on ArcGIS Online ...... 43
3.11.1 Roles & Responsibilities ...... 43
EGIS US Forest Service Page 4 Map Services User Guide 3.12 Make GIS Web Services Available on Data.gov ...... 43
3.13 Notify the Local Map Service POC after Successful Service Publication ...... 44
3.14 Map Service Maintenance and Monitoring ...... 44
3.14.1 Roles & Responsibilities ...... 44
3.14.2 Daily, Weekly, and Monthly Reports...... 44
4 Using GIS Web Services ...... 46
4.2 What is a GIS Web Service? ...... 46
4.3 Finding GIS Web Services ...... 47
4.3.1 ArcGIS Online ...... 47
4.3.2 How to Find a GIS Web Service on AGOL ...... 47
4.3.3 How to Find a GIS Web Service using the REST URL ...... 48
4.3.4 How GIS Web Services are Organized ...... 48
4.4 Map Viewer Client Applications ...... 48
4.4.1 ESRI ArcGIS Desktop Programs ...... 48
4.4.2 Other 3rd party programs ...... 50
4.4.3 Web based map viewers ...... 50
4.5 Using Map Services with Dynamic Layers Enabled ...... 53
4.5.1 How to Use Map Services with Dynamic Layers Enabled ...... 53
4.6 Using Feature Services ...... 54
4.6.1 How to Use Feature Services ...... 54
4.7 Using Map Services with Different Coordinate Systems ...... 55
4.7.1 Dynamic Map Services with Different Coordinate Systems ...... 56
4.7.2 Tiled Map Services with Different Coordinate Systems ...... 56
5 Using GIS Web Services for Application Developers ...... 57
5.2 Standard Forest Service Hosting Environments ...... 57
5.3 Development Process ...... 58
EGIS US Forest Service Page 5 Map Services User Guide 5.3.1 New GIS Services ...... 58
5.3.2 Existing GIS Services ...... 58
5.4 Testing ...... 58
5.5 Production ...... 58
5.6 Types of Available GIS Web Services ...... 59
5.7 Tips for Using Enterprise GIS Web Services in Applications ...... 59
5.7.1 Best Practices and Patterns ...... 59
5.8 Accessing GIS Web Services across Different Hosting Environments ...... 59
EGIS US Forest Service Page 6 Map Services User Guide 1 Overview
The Enterprise GIS (EGIS) Team, in cooperation with the Geospatial Management Office (GMO) and the Chiefs Information Office (CIO) has implemented ESRI’s ArcGIS Server at the Forest Service Virtual Data Center (VDC). This user guide describes what map services are, how to use them and outlines the process used to publish map services at the VDC.
The guide covers nationally standard map services created from data that is available in the Enterprise Data Warehouse (EDW) and the process used by local units to publish project level data as map services. It is intended to document and communicate the roles, responsibilities, processes, procedures, for daily operations. It is for use by those creating and maintaining standard national level map services as well as GIS staff at local units who wish to publish and use map services.
Finding, viewing and using GIS web services is a distinctly different topic from that of creating the services and this document is divided into two sections to cover both topics. Users only interested in finding and using available map services may want to skip the “Creating Map Services” section and focus on the “Using GIS Web Services” section. The “Using GIS Web Services” section gives an overview and describes the Forest Service ArcGIS Online website and the Forest Service Map Service Viewer, which can be used to view map services in a web based application. Also note that this user guide is supplemented with free interactive web based training modules which are available on the National Geospatial Training webpage.
This document does not cover the system architecture, server procurement, software installation, security and operations and maintenance of the ArcGIS Server installations in the VDC. That type of information is found in the ArcGIS Server Administrators Daily Operations Guide. This document does not cover the development and hosting of web based applications.
1.1 What are Map Services?
The term “map service” can have a broad definition. One can think of a map service as being a “web-based feed of GIS data”. Map services are often used as a component in web-based interactive mapping applications. In our case, local GIS staff can create and prepare resources such as data and map documents then publish them as map services which can be viewed in a variety of map viewing client applications such as ArcGIS Online, ArcMap, ArcExplorer or other custom web based applications. The map service should not be confused with map viewing application. You can think of the data, the map service and the viewing application as three distinct components that can be mixed and matched in a variety of configurations. For the purposes of this document, we will refer to map services as being a specific type of GIS Service that is created using ESRI’s ArcGIS Server software.
EGIS US Forest Service Page 7 Map Services User Guide
Data and Map Documents Map Viewing Client Map Services Applications
1.2 Process Overview
There are several stages in the process of publishing and using GIS services:
1. Data Preparation – includes items such as data migration, data stewardship, attribute linking.
2. Authoring Map Documents or Toolboxes– identifying data sources, connecting to data, map optimization, symbology, scale dependent rendering, labeling and other cartographic tasks. Also includes validation and map document descriptive properties for metadata.
3. Publishing and Administering GIS Services – includes the process followed by the Map Service Administrator and local unit publishers using ArcGIS desktop to publish a GIS web service at the VDC.
4. Cataloging – adding the GIS web service to ArcGIS Online and Data.gov so that it is discoverable and available to other users.
5. Finding and Using GIS Web Services – includes discovering available GIS web services and using them in a map viewing client application such as ArcGIS Online, ArcMap, ArcExplorer, the web-based Forest Service Map Service Viewer or other applications.
Each of these stages is covered in more detail in the subsequent sections of this document.
1.3 Roles
Each stage in the process of creating a map service has procedures to be carried out by roles at both the national level and at the local unit level. The local unit has the role of identifying business needs, stewarding data and creating map documents for publication, and publishing map services if local unit individuals are identified and given publisher permissions, while data center operations has the roles of publishing and administering the national map services and the systems they run on. At the national level there are two primary roles that have been filled by Data Center Operational staff to support map services.
EGIS US Forest Service Page 8 Map Services User Guide 1.3.1 National Data Center ArcGIS Server Administrator
The Data Center ArcGIS Server Administrator has the role of ensuring that ArcGIS Server installations at the VDC are configured, optimized and scaled to support the Agencies required map services. This includes items such as ensuring access to standard data sources in the VDC such as EDW, SDE and EFS.
This role includes items such as architecture design, system monitoring and coordination with CIO on service request submission. ArcGIS Server Administrator does not have responsibility for items such as determining data content, data publication standards, data sources or creation of map services.
1.3.2 Data Center Map Service Administrator
The Data Center Map Service Administrator (MSA) manages the national level GIS web services at the EDW data center and coordinates the publication of local services at the regional and unit level. The Data Center MSA oversees publication, management and cataloging of all GIS web services created at the VDC. The Data Center MSA also has the responsibility to ensure that the processes used to publish GIS web services are meeting the needs of the Agency and that they are updated as needed and made available to users. This role works with GIS specialists at the region and local level to ensure their requested GIS web services are published and that file structure, naming conventions and indexing guidelines are in place.
ArcGIS Server can support the granularity of permissions required to enable multiple units to create and administer GIS web services specific to their unit. The individual(s) identified by local units can work with the Data Center MSA to obtain the necessary permissions to publish local unit level map services as needed. The Data Center MSA will coordinate with the unit’s regional ArcGIS Online Administrator to determine which individual(s) from local units in their regions will have publisher permissions. Local units also have the option to continue going through the Data Center MSA for publishing of local unit map services. The Data Center MSA will create the following types of GIS web services:
National level dynamic map services using data from the EDW National level feature services using data from the EDW National level cached map services using data from the EDW EDW approved geoprocessing services to support data extract and data download from the EDW Local organizational unit dynamic map services (in conjunction with Local MS POC) Local organizational unit feature services (in conjunction with Local MS POC) Local organizational unit cached map services (in conjunction with Local MS POC) Specialized geoprocessing services for use by web mapping application developers requiring geoprocessing functionality in their applications
EGIS US Forest Service Page 9 Map Services User Guide Stages in the Process of Creating Map or Feature Services
Data Center Business Map Map Publishing and ArcGIS Data Cataloging Needs Document Document Administering Server Stewardship Map Services Identification Authoring Optimization Map Services System Admin
Non- EDW Shared - Local Shared - Local Shared - Local Local Unit or Local MS POC and MS POC and MS POC and ArcGIS Server Role Local Unit Local Unit Map Service Map/Feature Map Service Map Service Map Service Administrator POC Services Administrator Administrator Administrator
Enterprise Data National Enterprise Warehouse Level EDW Data Map Service Map Service Map Service Map Service ArcGIS Server Role Content Map/Feature Warehouse Administrator Administrator Administrator Administrator Administrator Governance Services Operations Board
Stages in the Process of Creating Geoprocessing Services
Data Center Author Publishing Business Troubleshooting, ArcGIS Data Model, and Cataloging Needs Testing, Server Stewardship Toolbox, Administering GP Services Identification Reconfiguring System and Scripts GP Services Admin
Non - EDW Shared - Web or Web Web Application ArcGIS Map Service Map Service Roles Application Local Unit Local Unit Application Developer and Server Administrator Administrator GP Developer Map Service Administrator Services Administrator
Enterprise National Data Enterprise ArcGIS Level EDW Warehouse Data Map Service Map Service Map Service Map Service Role Server GP Content Warehouse Administrator Administrator Administrator Administrator Administrator Services Governance Operations Board
1.3.3 Local Map Service Point of Contact (POC)
A Local Map Service POC serves as the single point of contact identified by the organizational unit to work with unit staff to publish map documents as map services. The Local Map Service POC works with the Data Center Map Service Administrator to optimize and publish map documents as map services. It may typically be a Forest GIS Coordinator or GIS Specialist. This role works with local unit staff to determine business needs for local project level map services and works with local data stewards to prepare data and map documents at the VDC to be published as map services. The Local Map Service POC also acts as a point of contact working with the Data Center Map Service Administrator to optimize map documents for publication,
EGIS US Forest Service Page 10 Map Services User Guide provide descriptive indexing information for cataloging and ensures guidelines are followed. The role is responsible for working with forest staff to ensure data being published is approved and appropriate for publication as a map service.
Local Unit Staff Local Map Service Administrator
Map Services POC
Publishes Map Prepares Data and Services or Map Documents, works with Local Publishes Map MS POC Services
1.4 Types of GIS Web Services
ArcGIS Server supports hosting a variety of GIS web services. GIS services are created from GIS resources (i.e. a map, globe, locator, or geoprocessing toolbox) that are accessible by the ArcGIS Server. Once published these GIS resources are accessible as a GIS service for use by client applications. Client applications use the GIS web services to do GIS work on the ArcGIS Server and retrieve the results in common formats such as images or text. The deployment of ArcGIS Server at the VDC supports publishing and using three GIS services: map, feature, and geoprocessing services.
1.4.1 Map Services
Map services can be created and configured in a variety of ways to meet the needs of the Agency. Most map services will have some of the properties listed below which are combined in any number of ways to meet specific needs.
EDW vs. Non-EDW
EDW map services are to be built upon standard data which has been approved by the EDW Content Governance Board and are created and administered by the Data Center Map Service Administrator.
EGIS US Forest Service Page 11 Map Services User Guide Non-EDW or local map services are those created by local units from project level data to meet the needs of that unit. These can be national, regional or forest level in extent and include any services other than the approved EDW services.
Fsweb vs. www
Fsweb map services are those that are available only on the Forest Service internal network. This is also commonly referred to as Www map services are those that are available to the public on the internet or www. This is also commonly referred to as ArcX.
Cached vs. Dynamic
A cached map service is a series of raster image tiles which have been created from vector data in order to improve the performance of a map service. Cached map services are created by the Map Service Administrator or by local units with publishing privileges. In many cases, cached map services are not required. A dynamic map service does not use a cache but creates map images on the fly based on vector data.
Map Service vs. Feature Service
A map service is a specific type of ArcGIS Server GIS service that is designed to expose maps, features, and attribute data to client applications via SOAP, REST, KML, or OGC WMS interfaces. A feature service is a specific type of ArcGIS Server GIS service that allows serving of features over the Internet and provides the symbology to use when displaying the features. Clients can execute queries to get features and perform edits that can be applied to the server. For more information about feature services including how to use in ArcGIS Online and ArcGIS Desktop refer to the Using Feature Services topic under section four – “Using GIS Web Services”.
A Basic Map Service vs. Map Service with Dynamic Layers Enabled
A basic map service is a standard map service with dynamic layers disabled. This means that users will have no control over the symbology, layer ordering, and appearance in ArcGIS Online and other client applications. A map service with dynamic layers enabled is a map service that allows clients to dynamically change layer appearance, layer order, and scale dependency. Determining which layers will appear in a map, layer symbol styles, layer order and position, labeling, and scale dependent rendering are all possible with dynamic layers. For more information about map services with dynamic layers enabled including how to use in ArcGIS Online and ArcGIS Desktop refer to the Using Map Services with Dynamic Layers Enabled topic under section four – “Using GIS Web Services”.
EGIS US Forest Service Page 12 Map Services User Guide For further detail about dynamic layers, refer to help topics in ESRI’s ArcGIS Server documentation:
About dynamic layers
Map Service vs. Geoprocessing Service
A map service is a specific type of ArcGIS Server GIS service that is designed to expose maps, features, and attribute data to client applications via SOAP, REST, KML, or OGC WMS interfaces. A geoprocessing service is a specific type of ArcGIS Server GIS service that is designed to make geoprocessing tasks accessible to client applications. Executing tasks in a geoprocessing service uses resources on the GIS server to execute the task.
Single Layer vs. Themed
A single layer map service is created from a map document that only contains one map layer. It is designed to be used together with other data sources or displayed on top of other pre-made base maps. A themed or multi-layer map service is created from a map document that contains several layers that are all published at once as a single map service. Keep in mind that a themed map service containing several layers can still be displayed on top of other premade base maps, and does not necessarily need to contain lots of background/base reference data.
WMS and KML
A Web Mapping Service (WMS) is an open standard for the publication of geospatial web services and it is also a format or capability of ESRI map services. Keyhole Mark-Up Language (KML) is a type of XML that can be used to display map services in Google Earth and is a capability supported by ESRI map services. Both WMS and KML capability will be enabled by default on most map services.
For more detail and information about map services refer to help topics in ESRI’s ArcGIS Server documentation:
What is a map service?
1.4.2 Feature Services
Feature services serve features over the Internet and provide the symbology to use when displaying the features. Clients can execute queries to get features and perform edits that can be applied to the server. When using feature services in ArcGIS desktop, users can change symbols, apply custom labeling, access attribute tables, and use the individual layers in geoprocessing models and scripts.
EGIS US Forest Service Page 13 Map Services User Guide Here at the Forest Service we now have the capability to publish feature services from enterprise SDE data housed in the EDW with the query option enabled. We do not allow editing of feature services published from data within the EDW as this is the agency publication geodatabase. However, editable feature services can be created from any of the transactional SDE geodatabase environments within the data center (e.g., GDB01A, GDB02A, etc.). Forest Service units and regions can work with the Map Service Administrator (Nathan Robbins) to create feature services with editing functionality enabled for web or mobile data collection or navigation.
The Data Center MSA is responsible for governing what feature services are published. Feature services are published at the data center under three target scenarios:
1. To support EDW operations and users 2. To support field data collection using Collector for ArcGIS on mobile devices (For more information about taking maps offline in Collector refer to the help topics in ESRI’s documentation: How to take maps offline) 3. When the requests of local units for feature services become nationally relevant as evaluated by the MSA
In order for feature services to be published in the VDC environment, all data within the map document must come from an Enterprise SDE database that has been configured properly. For more information on how to configure the data and publish these types of services refer to section 3.7 Feature Service Considerations.
For further detail about feature services refer to help topics in ESRI’s ArcGIS Server documentation:
What is a feature service?
1.4.3 Geoprocessing Services
Geoprocessing enables automating GIS tasks and performing spatial analysis and modeling. A geoprocessing service contains tasks that can be accessed by client applications. These services are created by publishing geoprocessing toolboxes or map documents containing tool layers. Tasks executed via a geoprocessing service on a client application use resources on the server hosting the geoprocessing service. Geoprocessing services are accessible in a variety of applications both on the desktop (ArcGIS desktop, ArcGIS Explorer) and in custom web applications.
The Data Center Map Service Administrator is responsible for governing what geoprocessing services are published. Geoprocessing services are published at the data center under three target scenarios:
1. To support EDW operations and users 2. To support web mapping applications developed by the Agency’s national program areas
EGIS US Forest Service Page 14 Map Services User Guide 3. When the requests of local units for geoprocessing services become nationally relevant as evaluated by the Map Service Administrator
For further detail about geoprocessing services refer to help topics in ESRI’s ArcGIS Server documentation:
What is a geoprocessing service?
1.5 ArcGIS Online
Map services created by the Agency can be viewed in ArcGIS Online maps and applications. The US Forest Service is using ArcGIS Online to share maps, data, and applications for use by internal Forest Service employees, other federal agencies, and the public. Users can find and use map services published by the Agency, together with their own data, to create web maps and mashups. For more information about the US Forest Service ArcGIS Online site see the US Forest Service AGOL topic under section four – “Using GIS Web Services”.
1.6 Benefits and Limitations of Using GIS Web Services
This implementation of ArcGIS Server at the VDC focuses on supporting map services, feature services, and geoprocessing services. There are other types of GIS web services such as geodata services that support geodatabase replication, extraction, and executing queries in the geodatabase over a private intranet or over the public internet. ArcGIS Server at the VDC currently focuses on map services, feature services, and geoprocessing services. Other types of GIS web services will be added in future implementations of ArcGIS Server.
1.6.1 Considerations for Using GIS Web Services
Agency standard data is available in several formats to meet a variety of needs. Some users may connect to data in SDE to meet their needs while others may need to have a local copy of a unit’s data on the Enterprise File System (EFS). Still others may be able to utilize a map service to meet their needs. There are several factors that go into the decision of when to use a map service vs. an SDE connection or local data on the EFS (also referred to as the T drive).
As mentioned above, this implementation of ArcGIS Server at the VDC includes support for map services and feature services. While the standard map services are best used as a read only display of data for users who are making or using a map, map services with dynamic layers enabled and feature services allow more flexibility in the symbology and display. The symbology and display of standard map services are determined by the creator at the time a map service is published. Users of standard map services cannot change the symbology being used or the scale dependent rendering that has been set in ArcMap at the time the map service was created. Dynamic layers and feature services provide more display options to users.
Map services also require a network connection in order to function. Users require an intranet connection in order to use map services which have been published internally on the fs network and will require a connection to the www in order to use any map services that have been published on the internet.
EGIS US Forest Service Page 15 Map Services User Guide For users who need access to standardized display of standard data, map services may be the best option. EDW map services offer a convenient way for many users to access and display standard data that has been aggregated, linked and published. Raw transactional GIS data can be linked to tabular attribute information and published as map services that non GIS users can view and use on the web. In this way, map services help GIS technology become integrated into Agency business processes.
The real power of map services is that they allow non-GIS users to interact with map data over the web in order to conduct their business. Map services bridge the gap between complex GIS technology and Agency business processes. Use of map services will reduce the need for all users to use ArcMap and SDE in Citrix for access and display of standard data. Map services support the enterprise data model as they are centrally managed and made available to users. Map services are published centrally and can easily be accessed by many users. Multiple users can simultaneously access and use map services. Any updates to underlying data contributing to published map services are immediately available to users. Map services can easily be loaded directly into ArcGIS programs like ArcMap and ArcCatalog. These services can be used with other maps and data (i.e., local maps and data) to facilitate project development. Many map services are created from data that has already been linked to attribute data and appropriately symbolized for a variety of display purposes. Users are able to incorporate map service information into their projects immediately. Map services with dynamic layers enabled allow end users to change symbol style, scale dependent rendering, and layer order. This prevents the creation of additional duplicate map services with slightly different symbol styles or properties. Feature services allow end users to have access to underlying features and symbology without requiring the client to do all the work of processing as it is done by the ArcGIS Server behind the scenes. These services also allow multiple users to edit features in various environments, including Web, desktop, and mobile applications.
1.6.2 Considerations for Using Geoprocessing Services
This implementation of ArcGIS Server at the VDC includes support for geoprocessing services. Geoprocessing services provide a powerful way for exposing rich GIS functionality in web applications and ArcGIS desktop clients without needing to develop the functionality from scratch. In this way GIS tasks and analysis can be accessed by a greater variety of users not just expert GIS users. Geoprocessing services published at the VDC are limited to supporting the business needs of the EDW as well as web application developers requiring the use of geoprocessing services in their mapping applications.
The real power of geoprocessing services is that they give non-GIS users access to GIS tasks and analysis over the web in order to conduct their business.
EGIS US Forest Service Page 16 Map Services User Guide Geoprocessing services help bridge the gap between complex GIS technology and Agency business processes. Use of geoprocessing services will reduce the need for all users to use ArcMap and SDE in Citrix for GIS tasks and analysis. Geoprocessing services support the enterprise data model as they are centrally managed and made available to many users. Multiple users can simultaneously access and use geoprocessing services. Geoprocessing services can be used easily in ArcGIS programs like ArcMap and ArcGIS Explorer as well as in custom web mapping applications. Geoprocessing services enable access to download EDW datasets from a web browser. For example, standard Agency data are available for download through a geoprocessing service published at the VDC. This geoprocessing service will allow users to extract standard EDW data into commonly used GIS formats for use on their local computers using the standard FS Map Service Map Viewer.
1.7 Guidelines for Use of GIS Web Services for Developers
This document and the effort to implement GIS web services(map, feature, and geoprocessing services) at the VDC, focuses mostly on the GIS web services themselves rather than on the development, implementation and hosting of web based applications that display and use GIS web services. In many cases, applications that use GIS web services are very separate from ArcGIS Server Installations. There is a large variety of development approaches, and technology platforms that can be used to develop web-based map applications and many of them have specific provisioning requirements and configurations which makes it difficult to mix them all under one environment. For this reason, guidelines for the development, implementation and hosting of web based applications using GIS web services is covered briefly in Section 5 entitled “Using GIS Web Services for Application Developers”.
EGIS US Forest Service Page 17 Map Services User Guide 2 Preparing Data & Authoring Map Documents
This section describes the process of authoring and designing resources for national-level (or EDW approved) and local unit-level (or non-EDW approved) map and feature services and further defines the responsibilities of the Local Map Service POC and Map Service Administrator (MSA) in this process. Also described in this section is the process for authoring and publishing geoprocessing services to support EDW operations, national web mapping applications, and geoprocessing services evaluated as nationally relevant for the Agency.
ArcGIS Server has been configured at the VDC so that data and map documents can be published directly from their existing standard locations in SDE and EFS. GIS staff working with these data and resources will need standard access to Citrix, SDE and their EFS folders at the VDC.
Topics described in this section consist of: content governance, data connections, authoring map documents, and optimizing map document.
2.1 Content Governance
Various mechanisms exist to help the content governance of map and geoprocessing services published using ArcGIS Server at the VDC.
2.1.1 Map and Feature Services
The EDW Content Governance Board determines what data content is published as standard national EDW map and feature services. At local units, the decision to publish data as map or features services and the determination of which content to publish should be made by line staff. The process and implications of creating a map or feature service is similar to that of posting a shapefile, coverage, or map to the fsweb or www. It is the responsibility of the Local Map Service POC to work with line staff to ensure that all published content is approved.
2.1.2 Geoprocessing Services
The Data Center Map Service Administrator governs publishing geoprocessing services at the VDC. The following criteria are used to govern the geoprocessing services published at the data center:
1. Does the geoprocessing service support EDW operations and users? 2. Does the geoprocessing service support web mapping applications developed by the Agency’s national program areas? 3. If a local unit requests a geoprocessing service is the service nationally relevant for use with nationally available data by users across the agency?
Geoprocessing services that meet at least one of these criteria will be published at the data center by the Map Service Administrator.
EGIS US Forest Service Page 18 Map Services User Guide 2.2 Connecting to Data in the Enterprise Environment
All map documents that will be published as map or feature services must be created in Citrix at the VDC using ArcMap. It is the responsibility of the Local Map Service POC or MSA (depending on the map service ownership—national or local level) to make sure that all resources used to create the maps are available while working in Citrix at the VDC.
Map documents must be opened using UNC (universal naming convention) paths. Failure to open map documents using UNC paths will prevent the map document from being successfully published to ArcGIS Server. Following is the correct UNC path for the T drive.
\\usda.net\FS
Connect to Folder in ArcCatalog as shown below to create a connection to the UNC path for the T drive.
Geoprocessing services that use a source map document must also be created in Citrix at the VDC using ArcMap. It is the responsibility of the Web Application Developer or the MSA to author map documents used for geoprocessing services.
Map source data for both map and geoprocessing services is typically referenced from SDE (Spatial Data Engine) or the EFS (Enterprise File System) at the VDC. Below are general source data SDE and EFS connection guidelines in the GIS services creation process.
EGIS US Forest Service Page 19 Map Services User Guide 2.2.1 SDE
When authoring map documents for map or feature services, there are two ways to connect to SDE source data within Citrix at the VDC—using a local unit-level SDE connection, and using a national EDW SDE connection.
Local Unit-Level SDE Connection: To access organizational unit SDE data connections at the data center view the predefined database direct connections using aliases within the following location in the EFS:
\\usda.net\FS\FS\Reference\GeoTool\agency\AG4SDatabaseConnection
Example connection for the LOGIN_GISDBWEBSERVICES user to Region 9 Chippewa National Forest SDE geodatabase 03a schema:
S_R09_CNF.sde
If a connection to your organizational unit SDE data already exists, you may use that connection to add SDE data to your map document. If a connection does not exist, contact the MSA at 801- 975-3730, or [email protected]. A connection will be created for your organizational unit SDE data, which you may then use to add SDE data to your map document.
Using these SDE database connection files that have already been created for the login_gisdbwebservices user will give ArcGIS Server access to the data which is necessary for successfully publishing unit and project level map or feature services that contain SDE data. ArcGIS Server has been configured to have access to both the EFS structure for storing and filing map documents and GIS data as well as access to the data within the Oracle SDE database. It is important to use the specified connection files and filing locations so that ArcGIS Server has access to the map documents and data to successfully publish a map or feature service.
National EDW SDE Connection: To connect to national level SDE data from the Enterprise Data Warehouse (EDW) as the LOGIN_EDWWEBSERVICES user, use the following SDE direct connection file:
\\usda.net\FS\FS\Reference\GeoTool\agency\AG4SDatabaseConnection\EDW.sde
2.2.2 File Based Data (EFS)
The Enterprise File System (EFS) is used to store file-based GIS data used in active work sessions with Citrix at the VDC. The EFS is commonly mapped and referenced as the T drive. Map documents used for publishing map or geoprocessing services can reference both national and unit level file-based source data from the EFS. The best format for storing file-based data is in ESRI’s file geodatabase format. Although it is technically possible to publish GIS web services referencing data in shapefiles or personal geodatabases (mdb), GIS web services will perform best when using data stored in file geodatabases.
EGIS US Forest Service Page 20 Map Services User Guide The location for storing map data used in GIS services will follow the established EFS file structure guidelines as described in the following EGIS documentation: Description of the Data Center File Structure including Best Practices
EFS data must be added to the map document using UNC paths.
\\usda.net\FS
Example file paths to GIS data in the EFS are as follows:
National - \\usda.net\FS\FS\Reference\GIS\USA\Data\ Forest Library - \\usda.net\FS\FS\Reference\GIS\R06_Siu\Data Forest Project - \\usda.net\FS\FS\NFS\Siuslaw\Project\LowerAlseaEA\GIS\Data
Reference the data in the map document using relative paths as opposed to absolute paths to ensure that the map or geoprocessing service will have access to the data. Relative paths are used by opening the map document properties from ArcMap and setting the data source options to store relative paths to the data.
2.2.3 Database Schema Locking
The geodatabase format is the primary data storage type for map services published at the VDC. EDW map services use data from an SDE geodatabase. Forest Service organizational units publish non-EDW map services using data from their unit's SDE data or from file geodatabases located on the EFS.
By default ArcGIS Server map services use schema locking to prevent modifications to the source dataset schemas while the service is running. As a general rule we typically disable schema locking on all our map services at the VDC. This allows updates to source dataset schemas even while the map services are running. However, it is recommended that the schemas are updated only when the service is idle. If the schema is updated when the service is under load, users of the map service may experience unexpected behavior such as layers and fields missing, queries failing, and service unavailability. Changes to the schema of the dataset need to be carefully planned; permanently removing datasets may leave the map services in an inconsistent state.
Schema changes to a geodatabase generally include the following:
Adding or deleting a feature class Adding, deleting, or modifying field names Altering database rules Changing database types Adding, modifying , or deleting domains Adding or modifying topologies or geometric networks
Even if SDE data is being used in a map service, the data can still be edited in ArcGIS. Editing, adding, and deleting features and feature attributes is still allowed while the map service uses
EGIS US Forest Service Page 21 Map Services User Guide the data. Edits to the data's features and feature attributes are reflected in the map service automatically.
The way to know one or more map services are placing a lock on an SDE geodatabase is to verify the user that is accessing the data. ArcGIS server uses a read-only database user account to access data in SDE (read and write access if the data is enabled for editing a feature service). For EDW map services the database user ID is login_edwwebservices. For local organizational units the database user account name is login_gisdbwebservices.
If changes to the geodatabase can’t be applied due to one or more map service locking the database, please notify the MSA. The MSA will stop the necessary map services to remove the lock. The MSA will not restart the map services until receiving notification that the changes to the geodatabase are complete.
For more information about schema locking, refer to ESRI’s help documentation listed below:
Disabling schema locking on a map service Schema locking
2.3 Choosing the Right Projection for Your Data
Most map services will be displayed in the WGS 1984 Web Mercator (Auxiliary Sphere) projection so that they can be used together with other pre-created basemaps. To achieve the best overall performance for your services you will need to re-project all your data to Web Mercator. But if projecting the data is not feasible, you can leave it in its standard native projection and change your data frame to Web Mercator and apply any datum transformations necessary. Using this method, projecting on the fly will occur in the MSD in the ArcGIS input folder, which will be more efficient and yield better performance than having the application perform the projection on the fly if the map service itself is not in Web Mercator.
2.3.1 Dynamic Map Service Coordinate System
You can keep your data in its native projection. As outlined above, always set your data frame projection to Web Mercator so projection on the fly does not happen in the application. Always avoid using data in many different projections. For more information see this ESRI doc.
To achieve the best performance with dynamic services, project your data to Web Mercator. If this is not possible, set the projection of your data frame to Web Mercator. Note, if you plan to add many data layers in your map document where each data layer is in a different projection, you can still use your map document to create a map service, however you will notice a performance decrease in your map service. The reason for the performance decrease is because every layer within the map is re-projecting on the fly with every map service request. Projection on the fly can happen in two instances.
1. Within the MXD: When projection on the fly happens within the MXD, the re-projection happens on every single layer in the map with every map request. This is a lot of work and can negatively impact performance.
EGIS US Forest Service Page 22 Map Services User Guide 2. Within the map service: When the projection on the fly happens at the map service level only the resulting output map is re-projected. This re projection happens once for the entire map per request and is therefore much faster than MXD projection on the fly.
2.3.2 Tiled/Cached Map Service Coordinate System
The following section is mainly a reference for the Map Service Administrator and the ArcGIS Server Administrator who may be creating cached map services. Most map services will not require a cache and the following section is provided as an informational reference only.
Projection on the fly does not work with cached map services. So for those map services that you are going to cache (all basemaps and some of your operational layers), you need to change the projection of the map to the projection of the other services you are going to mash up with (e.g. WGS 84 Web Mercator Auxiliary Sphere). If you will be overlaying your cache with another cache, you should use the same coordinate system for both. In this case you would pay the price for projecting on the fly within the MXD, which would slow down your cache creation but you would get the great performance of a cached map service on each map service request. If you are building a very large cached map service, you should consider extracting your data to a file geodatabase just for the cache creation. A file geodatabase on the EFS is going to give you the best performance for cache creation. When you create this copy of the data for cache creation, you can project it to the coordinate system of your map service (e.g. WGS 84 Web Mercator Auxiliary Sphere).
The best practice for creating a map service cache would be to follow the Google / Bing / ESRI ArcGIS online tiling scheme which use the WGS 1984 Web Mercator Auxiliary Sphere projection. The advantage of following the Google / Bing tiling scheme is standardization. This tiling scheme is well-known and widely used. Online mapping services such as Google, Bing and ArcGIS online maps use the WGS 1984 Web Mercator Auxiliary Sphere projection. Whether you love the Mercator projection or hate it, it is now customary in Web maps designed for mass consumption. In the end, simplicity of math (you can fit the world on a square at the smallest scale) determined the way most Internet users expect to see the world.
There are some subtle performance advantages to the Google / Bing tiling scheme. Because the tiles are only 256 x 256 pixels, less tile area falls outside the periphery of the map. This means you have to send less data across the wire. The smaller tiles also enhance the perception of the map loading faster, compared with waiting for the 512 x 512 “chunks” of map to appear.
If you will be creating a nationwide tiled map service with the web Mercator coordinate system then refer to the topic ESRI guidelines to create Bing / Google map tiling scheme.
If you will be creating a tiled service with any other coordinate then refer to the topic ESRI guidelines how to create ArcGIS Server map tiles / caches.
Another tip to follow when building a large map cache is to consider extracting your data to a file geodatabase for the cache creation. When you create a copy of the data for cache creation, you
EGIS US Forest Service Page 23 Map Services User Guide can project it to the coordinate system of your map service but keep the source data’s original map projection. The best tool for creating a copy is the Extract Data Wizard in ArcMap.
2.4 Authoring the Map Document
It is important to plan carefully when authoring the MXD that will be published as a map service. Common practices for authoring map documents used in the desktop environment don’t always perform well when published to the GIS server and used in a web mapping application. To help author the map document in the best way for publishing as a map service it is good to share as map service and analyze the map document while constructing the MXD. To access this choose File > Share As > Service > Publish Service from the main menu. Refer to the section Optimize the Map Document for help using this method. The following are several best practices to consider when authoring an MXD to help achieve the best performance and web mapping experience.
2.4.1 Map Service Planning
Since map services will be used at multiple scale levels and viewed layered on top of or under other map services it is essential to plan how the map service will ultimately be used and which layers are needed for communicating the purpose of the map service. Designing a map document with this in mind will ensure optimal appearance and performance of the published map service.
The first step is to identify how the map service will be used. Will it be mashed up with other map services? Will it be used against a basemap map service or will it be used by itself in ArcMap? Answers to these questions help guide the design and construction of the MXD that will be published as a map service including labeling, symbology, and scale dependent rendering.
The second step is to identify the operational and basemap layers in a map document to be published as a map service. The operational (or thematic) layers are layers focused on a specific item of interest. The operational layers overlay on top of the basemap layers. The basemap layers are reference layers that provide needed setting and context for the operational layers. The basemap layers are less focused and change infrequently. They can be used in a variety of maps providing context for various operational layers. In contrast, operational layers have a specific theme and audience and are more subject to frequent change than basemap layers. Some examples of basemap layers would be contour lines, forest and grassland administrative boundaries, and roads. Flight hazards, fire history, and soil samples are all examples of operational data layers.
After identifying the basemaps layers and the operational layers as well as how the map service will be used decide whether the basemap layers are necessary in the final map service. For example, if the map service is planned to be overlaid on a topographic basemap then there wouldn’t be a need to include features common on a topographic map in your map document such as contour lines, streets, or hill shading since those features would be displayed in the basemap map service. In addition, if there are Forest Service layers in the EDW that are
EGIS US Forest Service Page 24 Map Services User Guide needed as base layers for your map service, consider mashing up the EDW map services with your operation layers service. For example, rather than adding Forest Service boundaries to your map service overlay the EDW Forest Service Boundaries map service with yours. If you need to change the symbology of the EDW map service you can do that in ArcGIS Online now since we have enabled dynamic layers on all EDW map services. For more information about map services with dynamic layers enabled including how to use in ArcGIS Online and ArcGIS Desktop refer to the Using Map Services with Dynamic Layers Enabled topic under section four – “Using GIS Web Services”.
Removing unneeded layers helps improve map service performance. Choose to separate the basemap layers and operational layers into two separate map documents (MXDs). Each MXD would then be published as two separate map services that could be added together in a web application or within an ArcMap session. Mashing up or blending together two or more map services with a small, focused set of layers usually performs better than one map service with dozens of layers.
For more information about map document design and planning see the following resources below: ESRI ArcGIS Server Online Help: Map Service Planning Map Document Design Approach: The Map Sandwich Map Document Design Consideration: Map Authoring Considerations
2.4.2 Scale Dependent Rendering
Traditional paper maps focus on one set scale level at which the map is viewed. In contrast map services are used at multiple scales with each scale displaying varying levels of detail. Consequently it is important for map services that each layer in the map document turns on and off as the scale of the map increases and decreases. Before authoring the map document, establish the scale levels at which the map service will be viewed. With these established map scales the map document can be structured with group layers, each group layer representing a predetermined scale range. In this way the map document becomes a container for multiple maps at varying scale levels. Each group layer or “map” would contain essentially the same features but symbolized in a way that displays best at the group layer’s scale range. Once all the group layers are authored as intended and scale ranges set, test the map by zooming in and out to verify that the group layers turn on and off as desired. For a more readable map reorganize the map document by feature type (i.e. roads, streams, forests, cities, etc.) so each group layer represents a feature type.
For more information on authoring the map document with scale dependent layers consult the following article from ESRI’s Mapping Center blog:
Working with layers and scale ranges: Tips for organizing the Table of Contents
EGIS US Forest Service Page 25 Map Services User Guide 2.4.3 Symbology
Complex, multi-layered symbology takes longer to draw. Avoid using symbology that contains multiple layers, complicated dash patterns, hash lines, or outlines. Instead use simple point, line, and fill symbols where possible. You can also use the ESRI_Optimized style, which contains both line and fill symbols that are designed to perform better while still maintaining a visual appearance similar to their counterparts in the default ESRI style.
2.4.4 Labeling
Labeling takes time for the computer to decide where each label should be placed. Use the standard label engine if you are creating a dynamic map service. Using the maplex label engine is not recommended unless you are caching your service. Simplify labels so they avoid using halos, offsets, and other labeling effects which can negatively affect performance of the map service. For optimal performance, convert labels to annotation stored in either SDE or in a file geodatabase. Set scale-dependent rendering for labels so that labels only draw at the scales you need them to show up. Often labels do not need to be shown at smaller scales so you can turn them off when zoomed out by setting the scale dependency.
2.4.5 Definition Queries
Use definition queries for layers in the map document to filter out extraneous data that isn’t vital for the map service. For example if a national streams feature class is used in a map document but the map service will only be used in a local geographic region a definition query can be set on the streams feature class that only draws features for the area of interest used in the map service.
2.4.6 Unused Layers and Data Frames
Remove stale, unused layers and data frames from the map document that aren’t essential for the map service. Check the page layout view as well for any extra data frames or graphics that aren’t needed for the final map service and remove these elements for best performance.
Refer to the ESRI help topic, “Map authoring considerations for ArcGIS Server”, for more tips and best practices.
2.5 Map Document Properties Guidelines
An important step in the map service creation process is to fully describe your map—or provide detailed map metadata—appropriately so that users can learn more about the data published in the map service. It’s recommended that the MSA and Local Map Service POC enter metadata in the map document. The focus of this section is to describe how to enter metadata associated with a map document.
EGIS US Forest Service Page 26 Map Services User Guide 2.5.1 Assumptions
The assumption is that the map document is open in Citrix at the VDC, contains fully prepared data layers, is set to an appropriate default display scale, and is ready to be published as a map service.
2.5.2 Enter Map Document Properties
Access the Map Document Properties dialog by going to File > Document Properties from ArcMap's main menu. Below are descriptions and guidance for each field.
1. Title: Enter the name of the map document. This title follows the same naming conventions used for the map document file name and the map service name. For details on the naming convention consult the topic Map Document Naming and Filing Conventions. This property is used in the title for the map service metadata. 2. Summary: The resource type represented by the map service (e.g. Streams, Roads, Administrative Forest Boundaries). 3. Description: Use this field for other descriptive information that describes the map service. Display scales, symbology descriptions, and labeling rules are examples of information that would be appropriate to use for this property. In addition, the REST URL for the map service displays this text in the Service Description heading. 4. Author: Enter the map author. The author is the unit and program owner that created the map document (e.g. San Bernardino National Forest – Recreation where San Bernardino NF is the unit and Recreation is the program owner). The property is to be spelled out in full as opposed to using abbreviations. The author displays as the originator in the map service metadata. Do not use this to specify an individual’s name or active directory user name. 5. Credits: Map service metadata available to users in the REST URL contains a copyright text property. This copyright text is taken from the credits property on the data frame properties dialog in ArcMap. Use this property for adding the agency data disclaimer as listed below.
The USDA Forest Service makes no warranty, expressed or implied, including the warranties of merchantability and fitness for a particular purpose, nor assumes any legal liability or responsibility for the accuracy, reliability, completeness or utility of these geospatial data, or for the improper or incorrect use of these geospatial data. These geospatial data and related maps or graphics are not legal documents and are not intended to be used as such. The data and maps may not be used to determine title, ownership, legal descriptions or boundaries, legal jurisdiction, or restrictions that may be in place on either public or private land. Natural hazards may or may not be depicted on the data and maps, and land users should exercise due caution. The data are dynamic and may change over time. The user is responsible to verify the limitations of the geospatial data and to use the data accordingly.
EGIS US Forest Service Page 27 Map Services User Guide 6. Tags: Enter common keywords that a user could use to search for this map service (e.g., national forest, Utah, land ownership). Make sure to place a space between keywords. 7. Pathnames: Always check this on so all data sources in the map document are referenced using relative paths. ArcGIS Server can only access data sources at the VDC referenced using relative paths.
2.5.3 Enter Data Frame Description
In addition to the general map document properties, filling in the data frame properties is also helpful to users. The data frame properties are used when displaying services in the ArcGIS REST Services Directory, in ArcGIS Online, and in Data.gov.
1. Name: Give a concise, descriptive name for the map document's data frame. This name is also used in the map service metadata to help identify the map service. 2. Description: The data frame description consists of readable, complete sentences that describe the content and purpose of the map service. This description is listed under the map document title for each map service. It is also displayed when viewing the metadata details for the map service as the map service abstract. In addition, the REST URL for the map service displays this text in the Description heading. The description should follow a similar formula based on whether the service is published on the www (FSGISX02) or on the fsweb (ArcN). Be sure that any description or summary of the service describes the service and what is included in the service.
FSGISX02 map service: “A map service on the www that depicts…” ArcN map service: “A map service on the fsweb that depicts…” 3. Credits: Optional field that can be used to add additional disclaimers or credit information.
2.5.4 Choose Data Frame Projection Properties
Verify the coordinate system in the map data frame is Web Mercator (Auxiliary Sphere). Note, you can set the coordinate system in the map data frame to a different coordinate system that you prefer but as per the projection guidelines the performance will decrease when a map service is created. Web Mercator is the standard web projection used in AGOL.
1. Click View | Data Frame Properties from ArcMap’s main menu to access the Data Frame Properties dialog. 2. Click Coordinate System tab. 3. Expand the Layers menu. 4. Verify all the layers are in same coordinate system. Verify WGS 1984 Web Mercator (Auxiliary Sphere) projection is selected for the data frame. Select an appropriate datum transformation if necessary. 5. Click OK.
EGIS US Forest Service Page 28 Map Services User Guide 2.5.5 Choose Data Frame Extent
Set the default display or the initial extent of the map appropriately. The initial extent of the map is used to define initial extent in ArcGIS Online. It is also used by the home default extent functionality which appears between the plus and minus in the navigation buttons on the top left section of the AGOL map. The zoom-to functionality zooms to the initial spatial extent of the map service.
1. Click View | Data Frame Properties from ArcMap’s main menu to access the Data Frame Properties dialog. 2. Click Data Frame tab. 3. Choose the option other. 4. Click Specify Extent. 5. Choose Current Visible Extent. 6. Click OK.
2.5.6 Enter Layer Properties
Consider taking time to document the map layers included in the map document that will be included in the final map service. Doing so will improve the map service’s usability. There are several properties for each map layer that can be considered for helping users better understand the data and the map’s purpose. The following properties can be found by looking at a map layer’s properties within ArcMap.
General Tab – Layer name, layer description, credits Field Tab – primary display field, field aliases, turn off unnecessary fields Symbology Tab – names of color swatches
2.6 Authoring Resources for Geoprocessing Services
It is the role of the web application developer to author required resources before requesting to publish a geoprocessing service at the data center. For EDW geoprocessing services the MSA is responsible to author any necessary resources. Geoprocessing services are published using one of two resources:
1. A toolbox where each tool or model in the toolbox becomes a geoprocessing service task. 2. A map document that has one or more geoprocessing tool layers. Each tool layer becomes a task in the geoprocessing service.
In general, author geoprocessing service resources following ESRI’s best practices. Authoring a geoprocessing service involves authoring the tasks within the service. Model Builder and Python scripts can be used to author geoprocessing services and tasks. Prior to ArcGIS 10.1, geoprocessing tasks were required to have Feature Set data types to input features in geoprocessing tasks, and Record Sets to input tables. In addition, prior to 10.1, intermediate data variables had to be explicitly set in Model Builder and it was strongly recommended that all
EGIS US Forest Service Page 29 Map Services User Guide outputs be written to the geoprocessing scratch workspace environment using the convention %scratchworkspace% in the output path. At 10.1 and later versions you are no longer required to specify these conventions. You only need to specify an Input mode of User defined value for an input feature or table parameter. When authoring tools, models, and scripts use relative paths to reference data or other resources necessary for the geoprocessing service.
Refer to ESRI’s performance tips for geoprocessing services for additional information on how to create these types of resources.
If a map document containing tool layers is used with a geoprocessing service the same considerations apply to authoring these map documents as they apply to authoring map documents for publishing as map services. Follow the listed recommendations for map service planning and map document authoring when authoring a map document containing tool layers.
2.7 Naming and Filing Conventions
All map documents and the corresponding map service share the same name. There are two main categories of map documents that determine the naming convention used when creating map documents:
EDW map documents –these contain Enterprise Data Warehouse (EDW) content and will be published as authorized map services for the EDW Non-EDW map documents –these are created at the unit, project, regional, or forest- level and will be published for use by local organizational units
The name and file structure cannot describe all aspects of a map service and additional descriptive components are stored in the MXDs which are used by ArcGIS Online and Data.gov to provide index and search capabilities. For example, information about the source of the data, how the data has been transformed, and how it is symbolized is not referenced in the naming convention or file structure. This other information should be entered in the MXD as map document properties. In this way this other information will be available as metadata when published as a map service.
2.7.1 Map Document Naming Convention
The name of map documents to be published as map services consists of three parts:
1. Publishing Unit – The organizational unit that creates and owns the map document and map service. Map services published by the EDW use the prefix “EDW”. Local organizational units follow the standard unit, region, or forest code prefixed with “r” and the region’s two-character code. For example 04mlfspd which is the code for the Sanpete Ranger District in the Manti-Lasal National Forest in region 4. 2. Resource Type or Project Name– The map theme or focus of the dataset(s) used in the map document when one main resource type is identifiable. When multiple resource types are used in a unit level project the project or application name is used. The resource type or project name should be capitalized following the upper camel case convention where the first letter for each word in the name is capitalized.
EGIS US Forest Service Page 30 Map Services User Guide 3. Version Number – A numerical indicator specifying the version number of the map document and map service. This indicator distinguishes between map documents containing the same dataset but symbolized differently.
These parts are combined in the following format where each part is separated by an underscore character:
2.7.2 Naming Convention Examples
The following examples illustrate the naming conventions for EDW and non-EDW map documents. For example, if the Data Center Map Service Administrator was creating a map service of roads from a roads layer in the EDW, it would be named as follows:
EDW_Roads_01
This name indicates that the map document and map service is based on data published in EDW, contains roads, and is the first version of this map service. Another example:
EDW_NationalBasemap_01
This example name indicates that the map document and map service is the first version of a national basemap using data from the EDW.
An example of a non-EDW map document would be the following:
r04mlfspd_Trails_02
This example name indicates that the map document and map service is the second version of a trails dataset published by the Sanpete ranger district in the Manti-Lasal National Forest in region 4.
r02_Streams_01
This example name indicates the map document and map service is the first version of a streams dataset published by region 2.
r05anf_RedRiver_01
This example name indicates the map document and map service is the first version of the Red River project for the Angeles National Forest in region 5.
2.7.3 Map Document Filing Location
Save the MXD in a location based on established EFS filing conventions. Example file paths in the EFS are as follows:
National - \\usda.net\FS\FS\Reference\GeoTool\agency\MapService
EGIS US Forest Service Page 31 Map Services User Guide Forest Library - \\usda.net\FS\FS\Reference\Geotool\R06_Siuslaw\MapService Forest Project - \\usda.net\FS\FS\NFS\Siuslaw\Project\LowerAlseaEA\GIS Program - \\usda.net\FS\FS\R02\Program\5100Fire\GIS\DispatchBoundaries
See the following link for more detail: Description of the Data Center File Structure including Best Practices.
2.7.4 Geoprocessing Toolbox and Map Document Naming Convention
Toolboxes and map documents used to publish geoprocessing services should follow the same naming conventions specified for map documents published as map services. If a map document is used as a geoprocessing result map service the name of the map document and geoprocessing toolbox should match.
2.7.5 Geoprocessing Toolbox and Map Document Filing Location
Toolboxes, scripts, and map documents that are used to publish geoprocessing services should be bundled together in one folder. This tool share folder should then be filed in a folder called “Geoprocessing” within the unit’s map service folder on the EFS. Please create the folder if the geoprocessing folder doesn’t already exist. Example file paths in the EFS are as follows:
National - \\usda.net\FS\FS\Reference\GeoTool\agency\MapService\Geoprocessing Forest Library - \\usda.net\FS\FS\Reference\Geotool\R06_Siuslaw\MapService\Geoprocessing Forest Project - \\usda.net\FS\FS\NFS\Siuslaw\Project\LowerAlseaEA\GIS\MapService\Geoprocessing
2.8 Submit the Map Document for Optimizing and Publishing
After authoring the map document (MXD) the Local Map Service POC saves the completed map document for optimizing and publishing as a map service. The MSA will handle all map service requests by email. Once the map document is prepared the Local Map Service POC sends a map service request to the MSA at the following email address:
Email: [email protected]
The map service request includes the EFS UNC path to the location of the map document, whether the service should be published internally or externally, and when the service is needed. The MSA then reviews the map document properties, data source locations, naming conventions, and works with the Local Map Service POC to optimize the document for publishing as a map service. The MSA follows up with the Local Map Service POC to make sure all info is available to publish the map service as requested. Since the MSA may not have write access to the folder where the map document is saved, the POC will be required to make any necessary changes prior to publishing. If the POC or someone the POC has designated has access to publish directly to the server, the POC will have full responsibility to ensure that map document property and optimization guidelines are followed.
EGIS US Forest Service Page 32 Map Services User Guide 3 Publish and Administer GIS Web Services
Publishing GIS resources as a GIS web service (map or geoprocessing) follows these main steps: publish the GIS web service to the GIS server, register the GIS web service with ArcGIS Online and Data.gov to make the service accessible and discoverable, and monitor and maintain the GIS web service. This section focuses on these steps that the MSA and other unit level publishers will take when publishing and administering GIS web services in the data center.
ArcGIS Server can support the granularity of permissions required to enable multiple units to create and administer GIS web services specific to their unit. The individual(s) identified by local units can work with the Data Center MSA to obtain the necessary permissions to publish local unit level map services as needed. The Data Center MSA will coordinate with the unit’s regional ArcGIS Online Administrator to determine which individual(s) from local units in their regions will have publisher permissions. Local units also have the option to continue going through the Data Center MSA for publishing and administration of local unit map services.
3.1 Roles and Permissions
The roles and permissions necessary for publishing and administering GIS web services are defined as listed in the overview and creating map service topics listed above. Refer to those topics for further detail.
FS Author. The MSA must have FS Author permissions to any national-level EDW (Enterprise Data Warehouse) directories that contain data, map documents, or any other associated resources that will be used to create GIS web services on the EFS at the VDC (Note: Follow the same procedure as described above).
ArcGIS Admin Group. The MSA must have ArcGIS Admin Role permissions to publish and manage GIS web services using ArcGIS Server Manager or ArcGIS Desktop in the Citrix environment.
ArcGIS Publisher Group. The local unit publishers must have ArcGIS Publisher Role Group permissions to publish and manage GIS web services using ArcGIS Server Manager or ArcGIS Desktop in the Citrix environment. Steps to get ArcGIS Publisher Role Group permissions are as follows:
1. Submit a detailed request to the MSA at [email protected]. 2. The MSA will coordinate with the Local Map Service POC and regional ArcGIS Online Administrator to determine if the request will be approved and authorized. 3. The MSA will work with the ArcGIS Server Administrator to place the approved individual(s) in the appropriate ArcGIS Server Publisher Role. 4. The MSA will contact the new unit level publisher to provide the necessary details for getting access to the appropriate servers for publishing map documents.
EGIS US Forest Service Page 33 Map Services User Guide AGOL Admin Group. The MSA and local unit publishers must have at least AGOL USFS Content Manger permissions to register and index GIS web services in ArcGIS Online. Please refer to the AGOL custom role functionality document for further information on which roles have the ability to register items such as map services. 3.2 Map Services Publication Coordination
The MSA publishes national level EDW map services for the agency to the internal and external ArcGIS Servers. There are nearly 2000 map, feature, image, and geoprocessing services published as of March 6, 2017. 1649 of these services are non-EDW. A complete list of services published can be found in the Monthly Enterprise Map Services Program Report.
3.2.1 Map Services Publication Timing
With so many different local unit level publishers potentially publishing or updating services at the same time, it is important to coordinate the timing of publication. Web services are most utilized by internal and external users during the day between the hours of 9 and 3. Because of this, it is recommended that publication or re-publication happens either before or after that time. This will help to alleviate bottlenecks and free up resources for the map services to perform at their peak optimal level.
3.2.2 Map Services Version Management
The naming convention best practices in section 2.7.2 outline what map services should be named. When creating additional map service versions with a slightly different view and purpose, it is best to name them with 01, 02, 03, etc, at the end of the service name. With the recent updates to AGOL and use of dynamic layers for map services, different views of the same service can often be avoided. AGOL offers many ways to filter and symbolize the layers such that you can have just one map service with different views depending on purpose; this is very important as each service consumes some resources on the servers whether it is being used or not, so minimizing service proliferation is key to overall system performance.
3.2.3 Map Services Organization and Cleanup
At times a project requires an internal map service to be created first on ArcN. Once the project has approvals to go public, the service is then published on an external instance such as FSGISX02. When this happens, in addition to going through the proper governance procedures, the publisher should perform cleanup and organization of the folders and services on the servers so that only the current most recent map services are kept. If any services are no longer needed, such as those on ArcN, the publisher should delete them or work with the MSA to have them removed. If it is agreeable to the project team, one optional best practice would be to go ahead and publish the service externally if it will eventually be public so that additional work to publish externally and clean up internal services can be avoided. This decision should be made by those involved to determine if the risk is low enough to have it exposed for a short time during project development.
EGIS US Forest Service Page 34 Map Services User Guide 3.3 Optimizing and Publishing the Map Document
The local Map Service POC and the MSA use ArcMap to optimize the map document for publishing as a map service. ArcMap provides a means to optimize ArcMap documents for publishing high performance map services to the GIS Server. Optimized map documents demonstrate improved performance under two main scenarios:
- Using dynamic map services in a web mapping application - Generating the cached map tiles for a cached map service
The publishing tools in ArcMap allow users to analyze and optimize a map document, preview the map service display, and publish to the server.
The main steps for optimizing and publishing the map document are as follows:
1. Go to Add GIS Server in ArcCatalog. 2. Specify Publish GIS services or Administer GIS services depending on the level of permission you have been granted. 3. Specify the server URL you want to connect to depending on which type of service you are publishing: a. http://ntcfsxopsx1299.usda.net:6080/arcgis/admin (arcn) - Internal map, feature, and geoprocessing services. b. http://ntcfsxopsx1300.usda.net:6080/arcgis/admin (fsgisn01) – Internal image services. c. http://ntcfsxopsx1262.usda.net:6080/arcgis/admin (fsgisx02) – External map, feature, and geoprocessing services. d. http://ntcfsxopsx1266.usda.net:6080/arcgis/admin (fsgisx03) – External image services. 4. Enter your active directory username following the usda\
EGIS US Forest Service Page 35 Map Services User Guide 12. Review errors and warnings. Errors must be resolved before the map can be published as a service. 13. Preview the map service to verify speed and performance. 14. Click Publish to publish the map service.
3.3.1 Projections for Map Services
Ensuring that all data in the map document is drawing in the same Web Mercator coordinate system is important for an extremely high performing optimized map service. If your data is not projected to Web Mercator, the next best thing is to set the data frame to Web Mercator. When a data layer is being projected on-the-fly the analyze tool will report a warning that this will negatively affect performance of the map service. Failure to resolve these types of warnings will not prevent publishing the map but it is highly recommended to resolve them since map services will draw faster when all data is using a common coordinate system. See ESRI Doc.
3.3.2 Verify the Initial Extent of the Map
Make sure the desired initial extent is set on the map before publishing as a service. This initial extent should cover the area of interest in the map document. Refer to the topic Choose Data Frame Extent under Map Document Properties for further information.
3.3.3 Analyze the Map Document
Analyzing the map document generates a report identifying all map errors and bottlenecks that will prevent optimal map service performance. These potential issues are listed as three different types of messages: errors, warnings, and information.
Errors refer to unsupported functionality that must be resolved before publishing. Warnings refer to issues that affect drawing performance or appearance. You have the option of correcting or ignoring warnings. Ignoring warnings does not prohibit publishing. Information messages display information about the map that is important to note.
3.3.4 Preview as a Map Service
After analyzing the map document and resolving any errors the map can be previewed using the preview tool prior to publishing. This preview simulates how the map will appear and perform when published as a map service and is useful for testing the map service performance. The time in the preview window shows the time it takes for the map to draw when a pan or zoom is performed on the map.
3.3.5 Process for Updating the Map Service
Changes to the underlying data referenced in the original MXD don’t require that the map service be republished. If changes are made to the MXD then the map service will need to be republished. When changes to the map document are made, notify the MSA that the map service needs to be republished, unless an authorized unit level publisher has been granted publisher role permissions on the servers.
EGIS US Forest Service Page 36 Map Services User Guide For further information on publishing map services consult the following ArcGIS help topics.
Publishing a map service
3.4 Login to Server Manager
Using an internet browser go to the Server Manager URL on the production environment machine for the server that will host the requested map, feature, geoprocessing, or image service.
Internal Map, Feature, and Geoprocessing Services (arcn)
http://ntcfsxopsx1299.usda.net:6080/arcgis/manager/
Internal Image Services (fsgisn01)
http://ntcfsxopsx1300.usda.net:6080/arcgis/manager/
External Map, Feature, and Geoprocessing Services (fsgisx02)
http://ntcfsxopsx1262.usda.net:6080/arcgis/manager/
External Image Services (fsgisx03)
http://ntcfsxopsx1266.usda.net:6080/arcgis/manager/
After the login screen displays, log in using the correct username and password. Enter your active directory username following the usda\
3.5 GIS Web Service Creation Wizard
The following instructions show how to publish a GIS web service using the Publish a GIS Resource wizard.
1. Log into Server Manager 2. Click the “Publish a map, globe, or other GIS resource as a service” link from the home page or alternatively click the “Publish a GIS Resource” link under the services tab on the left side of Server Manager 3. Choose the GIS resource to publish 4. Verify that the name of the GIS web service is correct 5. Verify that the GIS web service is published into the correct folder and click next 6. Verify that the necessary capabilities for the GIS web service are checked on and click next 7. Verify that the summary output for the GIS web service is correct and click finish
EGIS US Forest Service Page 37 Map Services User Guide 3.6 GIS Web Service Filing and Naming Conventions
GIS web services and corresponding map documents (MXD) all share the same name. The naming conventions for GIS web services match the naming conventions of map documents and resources used to publish GIS web services. These naming conventions are covered in the topic Naming and Filing Conventions.
Although the naming conventions match across GIS web services and map documents, the filing convention for GIS web services is different than the filing conventions for the GIS web service’s associated resources. ArcGIS Server does not support a nested folder filing structure for storing published GIS web services. ArcGIS Server at the VDC provides a one-folder deep hierarchy for publishing GIS web services. Services will be organized based on whether they are authorized as authoritative GIS web services for the EDW or by which region the GIS web service owner is located. The folder names for each region will follow the Unit Name Standards for GIS:
r01 r02 r03 r04 …
For example, if the Okanogan-Wenatchee National Forest requested a map service showing travel management data for their forest, their map service would be published within the r06 folder on ArcGIS Server. GIS web services published for the EDW or by other units not organized by region will be published in a folder with their EGIS standard unit name code:
EDW nrs rmrs srs wo_nfs_gstc wo_nfs_rsac wo_nrm_iweb
3.7 Map Service Capabilities
When publishing map services additional capabilities can be turned on giving the map service functionality accessible by other applications. If needed, the Local Map Service POC should submit requests for specific service capabilities within their map service request they send to the MSA. By default the MSA will turn on the WMS and KML capabilities. A WMS enabled map service creates a service URL that is compliant with the Open Geospatial Consortium’s (OGC) Web Map Service (WMS) specification. KML enabled map services expose Keyhole Markup Language (KML) features that can be used in applications like Google Earth and ArcGIS Explorer. For further explanation on all map service capabilities consult the following help document:
EGIS US Forest Service Page 38 Map Services User Guide Map service capabilities
3.8 Feature Service Considerations
There are specific considerations for the MSA when publishing and maintaining feature services that are unique to this type of GIS web service.
3.8.1 Data Source and Database Configuration
For feature services, all data within a map document must come from an Enterprise SDE database connection. Each unit already has an Oracle database schema configured and set up with the appropriate user accounts. For units desiring to create feature services for online or offline editing, a Local Unit-Level SDE Connection must be created if it does not already exist: To access organizational unit SDE data connections at the data center work with the MSA to set up the predefined database direct connections within the following location in the EFS: \\usda.net\FS\FS\Reference\GeoTool\agency\AG4SDatabaseConnection
For more information on preparing feature services to be used for editing either online or offline in the ESRI Collector application, please refer to the following guidance documents:
ESRI Collector App Quick Start Guide Mobile Data Collection – Using Collector for ArcGIS
Feature classes or feature datasets must be created within the appropriate SDE schema with a login user that has necessary privileges to create data in the database. The login_gisdbwebservices user must be granted full read/write privileges on each feature class or feature dataset you intend to include in your editable feature service. This will allow the feature service to be edited on the web or on a mobile device.
3.8.2 Preparing Data for Offline Use
If the users of this feature service will be taking this data offline for editing on a mobile device, and you need this layer in your service, you will need to configure your data for Sync. All layers must be either versioned and contain a Global ID field or all nonversioned, archive enabled, and contain a Global ID field. If the layer participates in a relationship class or has attachments, the layer and related table or attachment must be related using a Global ID field as the primary key. You can use the Migrate Relationship Class geoprocessing tool to convert ObjectID-based relationship classes and attachments to use Global ID fields as the primary key.
Configuring your data this this way will allow you to download a copy of the data to a mobile device, make edits in the field while disconnected from a network, and then synchronize with the feature service when connectivity is available. For this workflow to work properly, VPN or FS wireless must be set up on the mobile device since the SDE database sits behind a firewall on the FS network.
EGIS US Forest Service Page 39 Map Services User Guide Editor tracking can also be turned on in the data prior to publishing the feature service. The DS domain user that is logged into a feature service will be recorded in the edited by field if security is enabled on the feature service. If the service is open to all and not secured, the generic login_gisdbwebservices user is recorded. So if you need to secure your feature service, and detailed editor tracking is required, refer to the securing feature services section below. The date and time that features are created or edited are recorded in create and edit date fields, respectively. These values are preserved when you sync with the feature service. All date values must be in the UTC format.
For more information about preparing data for offline use, refer to ESRI’s help documentation listed below:
Prepare data for offline use
The decision of whether to use nonversioned archive enabled data or versioned data depends entirely on your project workflow requirements. If your data participates in a topology or a network, then the data must be versioned. The other reason you may want to use versioned data is if you want to perform QA/QC on the data prior to submitting it to the default parent version. For more information on offline maps and versioned data workflows, refer to ESRI’s help documentation listed below:
Offline maps and versioned data
NOTE: In order for versioned data to work when publishing a feature service, you must publish the service using ArcGIS Desktop 10.3 or later. Version 10.3.1 is now available in Citrix.
3.8.3 Publishing Procedures for Web and Mobile
When you are ready to publish your feature service, you will need to publish to the internal ArcGIS Server, ArcN, and in the appropriate folder. At this time, we recommend publishing feature services to this instance of Server because we don’t yet have protocols in place for enabling security on our external instance. Publishing the feature service is done in the same manner map services are published. However, the feature access capability must be turned on and configured properly.
When authoring a feature service, you will need to choose the options that fit your particular situation. This depends on whether you will have only web editing workflows or offline read-only data or offline editable data workflows. If you have a map that will contain read-only reference data for offline use, then clients will only be querying the data. So only the query and sync capabilities will need to be turned on. If you have data in the map that you want users to be able to edit while offline and then synchronize changes when they have connectivity, enable the query, sync, create, update, and delete capabilities. If your feature service will not be taken offline, but will only be edited on the web, then do not enable the sync capability.
EGIS US Forest Service Page 40 Map Services User Guide 3.8.4 Securing Feature Services
In our current implementation of ArcGIS Server, token based security is used to lock down services to a specific group of users. To secure your feature service, work with the MSA to define a list of users that need to have access to edit the data. When securing feature services published on ArcN, there are three options to consider: Completely open to all FS users with no login required (editor tracking fields will not record the user name of the person doing the edits) Secured but open to all DS domain users after login (editor tracking fields will record user names) Secured and only open to a selected set of DS domain users within a custom role (editor tracking fields will record user names)
ArcGIS Server Manager is used to manage the DS users and add them to roles based on editing requirements. Roles can be created based on a group of users and then added to the security of a particular feature service. If the secured feature service is added to an AGOL map, then a login prompt will appear when opening the map even if you are already logged into AGOL. You will need to enter your DS username and password into this dialog in order to go further. This is the same username you use to log in to the Citrix environment.
3.8.5 Authoring ArcGIS Online Map for Offline Use
When an editable feature service is added to a web map, the web map can be seen in Collector. If no editable feature services exist in the map, Collector will not display it.
To author a map for offline use, the AGOL map must contain the following elements: All feature layers in the map are sync-enabled. These can be hosted feature layers or ArcGIS 10.2.2 Server or later feature services. For details on using hosted feature layers, see Allow offline editing in the ArcGIS Online help. For details on using ArcGIS Server feature services, see Preparing data for offline use and Tutorial: Setting up feature service data for offline use in the ArcGIS for Server documentation. (Optional) ArcGIS 10.2.2 Server or later tiled map services with export tiles enabled. See Allow clients to export cache tiles in the ArcGIS for Server documentation for more information. An Esri basemap enabled for offline use or your own ArcGIS 10.2.2 Server or later tiled map service with export enabled. Esri basemaps that are enabled for offline use can be found in the Tiled Basemaps group. For details on enabling export of tiled map services, see Allow clients to export cache tiles in the ArcGIS for Server documentation.
The Forest Service has a couple of tiled basemap map services that have been enabled for offline use. These basemaps can be found in the rest services directory. The basemaps contain relevant forest service data such as wilderness areas, forest boundaries, and quads. https://apps.fs.usda.gov/arcx/rest/services/wo_nfs_gstc/GSTC_TravelAccessBasemap_01/Map Server https://apps.fs.usda.gov/arcx/rest/services/EDW/EDW_FSTopo_01/MapServer More basemaps coming soon
EGIS US Forest Service Page 41 Map Services User Guide 3.9 Geoprocessing Service Considerations
There are specific considerations for the MSA when publishing and maintaining geoprocessing services that are unique to this type of GIS web service.
3.9.1 Folder Structure and Filing Location
Resources used to create geoprocessing services need to be stored together following ESRI’s best practice for bundling together geoprocessing resources (scripts, models, toolboxes, and map documents). To publish a geoprocessing service the MSA uses the tool share location containing the necessary toolbox or map document within the Geoprocessing folder found in each unit’s MapService folder on the EFS. The geoprocessing location for EDW geoprocessing services is as follows:
\\usda.net\FS\FS\Reference\GeoTool\agency\MapService\Geoprocessing
3.9.2 Output Directory and the Scratch Workspace
Outputs for geoprocessing services are stored in ArcGIS Server’s built-in jobs directory. This directory is located in the arcgisjobs directory of an ArcGIS Server instance. For each task executed within a geoprocessing service, ArcGIS Server creates a folder named with the task’s unique job ID. Within the task’s folder is stored a scratch folder. Within this scratch folder is stored intermediate and output data used in the geoprocessing script or model. This jobs directory is cleaned by ArcGIS Server on a regular schedule. Prior to ArcGIS 10.1, geoprocessing tasks were required to have Feature Set data types to input features in geoprocessing tasks, and Record Sets to input tables. In addition, prior to 10.1, intermediate data variables had to be explicitly set in Model Builder and it was strongly recommended that all outputs be written to the geoprocessing scratch workspace environment using the convention %scratchworkspace% in the output path. At 10.1 and later versions you are no longer required to specify these conventions. You only need to specify an Input mode of User defined value for an input feature or table parameter. When authoring tools, models, and scripts use relative paths to reference data or other resources necessary for the geoprocessing service.
3.10 Cached Map Service Considerations
Cached or tiled map services are created and updated on the service instance of ArcGIS Server. Standard EDW cached map services will follow the ArcGIS Online/Google Maps/Bing maps tiling scheme. Tiles for these caches are generated and stored at the following EFS locations:
\\usda.net\FS\FS\Reference\Server\arcn\arcgisserver\directories\arcgiscache \\usda.net\FS\FS\Reference\Server\fsgisn01\arcgisserver\directories\arcgiscache \\usda.net\FS\FS\Reference\Server\fsgisx02\arcgisserver\directories\arcgiscache \\usda.net\FS\FS\Reference\Server\fsgisx03\arcgisserver\directories\arcgiscache When a cache is created and ready to use, a matching service is created on either the internal or external instances of ArcGIS Server with the cache directory pointing to the EFS storage
EGIS US Forest Service Page 42 Map Services User Guide location where the cached map service tiles are stored. This matching map service will automatically detect the tiles and will display as a cached map service. When a map cache needs to be updated, the matching service published on either the internal or external instance needs to first be stopped to ensure the caching process isn’t interrupted.
3.11 Make GIS Web Services Available on ArcGIS Online
The US Forest Service now has many groups on ArcGIS Online. Please refer to the USFS ArcGIS Online Guidance for more information on groups. There are a few groups created to register national map services: one group shows GIS web services available to the public on the www, the other group shows GIS web services available internally to Forest Service employees on the fsweb. Both groups are administered with a generic admin account USFSAGOLAdmin. GIS web services published on the www are added to the public U.S. Forest Service Enterprise Content ArcGIS Online group. They are also designated as “authoritative content”. Enterprise web services published for internal use on the fsweb are added to the private US Forest Service – Internal ArcGIS Online group.
3.11.1 Roles & Responsibilities
If a map service contains Forest Service data, is in the EDW or RDW, approved for public use, and published on ArcX or FSGISX01, then the MSA has the role to register this service on Data.gov and on AGOL. These entries on AGOL are shared with ‘Everyone’ so they will be discoverable by the public. If a map service does not contain Forest Service data (such as EPA layers), is in the EDW, and approved for www on ArcX, then the MSA does not register this service on Data.gov or on AGOL.
If EDW map services are approved only for internal use and published on ArcN, they are registered in AGOL by the MSA and shared only with the Forest Service – Internal group. These map services are not registered in Data.gov.
If a unit or region publishes a public facing map service in FSGISX02 or FSGISX03 they can register this service on AGOL and share it with ‘Everyone’. It is the role of the regional AGOL Administrators to manage all of the content for the units within their region on AGOL. The MSA does not register unit/region level non EDW services on Data.gov or on AGOL at this time. If a unit or region publishes internal map services on ArcN, the AGOL Administrator can register these services on AGOL and share them with internal groups and use them in AGOL apps that are shared with internal groups.
3.12 Make GIS Web Services Available on Data.gov
The US Forest Service public map services showing authoritative agency data are registered on Data.gov. An ArcGIS Open Data site, which is currently available at https://enterprisecontent- usfs.opendata.arcgis.com/, contains all the authoritative agency data sets and utilized by data.gov to automatically harvest assets into the data.gov repository. In the meantime, the MSA has the role to manually update all entries in the USDA organization on catalog.data.gov to comply with metadata standards. The MSA also has the role to add other resource types to the
EGIS US Forest Service Page 43 Map Services User Guide registered entries on Data.gov including links to feature services, feature class metadata xml files, shapefile and geodatabase download ZIP files, KML files, and links to APIs.
3.13 Notify the Local Map Service POC after Successful Service Publication
After a GIS web service is successfully published to ArcGIS Server and registered in ArcGIS Online, the MSA will notify the Local Map Service POC that the GIS web service is ready and available for use. If the map service has been published for a local unit, it is the responsibility of the Regional AGOL Administrators to register and manage their own content on AGOL.
3.14 Map Service Maintenance and Monitoring
3.14.1 Roles & Responsibilities
Enterprise Operations Center monitors the hardware that ArcGIS Server is using at the data center. They send notifications to the ArcGIS Server Administrator when CPU and memory usage is high or if one or more GIS servers are down.
The ASA performs routine maintenance of the GIS servers to ensure they are running and configured correctly. When notified by the EOC the ASA investigates performance issues on the GIS servers using performance management tools and tunes the servers' performance.
The MSA assists the ASA to ensure that the GIS servers are running and configured properly. The MSA checks daily to ensure that map services are available and discoverable on the FS Map Service Viewer, Data.gov, and from the FS groups on ArcGIS Online. The MSA maintains an up-to-date inventory of the number of GIS services published at the data center. The MSA also ensures that map service entries on the FS ArcGIS Online groups are current. Adding and maintaining records in Data.gov is currently a manual process. In a future implementation of ArcGIS Online maintaining records will be automated on a regular schedule. The monitoring work of the MSA includes identifying and fixing broken map services where the underlying data or map document has been moved. The MSA uses the 3rd party tools and python scripts for monitoring and administering map services.
3.14.2 Daily, Weekly, and Monthly Reports
Every week and month the MSA generates reports and statistics on the status of the GIS web services at the data center. Click to see the Monthly Enterprise Map Services Program Report and the Map Service Usage Statistics. These reports and stats include the following information:
How many GIS web services are published at the data center? How many services running are EDW map services? How many services running are non-EDW map services? How many map services are available on Data.gov and on AGOL? How much use did the servers receive over a month's time? How many people are using GIS web services? How many export map requests are being performed on GIS web services?
EGIS US Forest Service Page 44 Map Services User Guide How long did it take on average to draw a map service? How many transactions were performed on each map service? What was the total busy time for individual map services? What are the most popular EDW map and feature services?
These reports will be used for capacity planning for planning future hardware and software deployments to support increased demand for GIS web services.
EGIS US Forest Service Page 45 Map Services User Guide 4 Using GIS Web Services
This chapter describes how to find GIS web services that have been created by the Forest Service and discusses a few ways they can be viewed and used in ArcMap and web-based applications to complete some common tasks. This chapter also describes how you can use feature services and map services with dynamic layers enabled in AGOL and ArcGIS Desktop to view available map services or customize the application to meet your project specific needs.
This chapter also includes a short discussion on best practices and limitations for the use of GIS web services as well as providing guidelines on when to use GIS web services rather than other data sources. A general overview and description of GIS web services and their implementation in the Forest Service is included in the “Overview” section of this document and should be considered a required supplement to this “Using GIS Web Services” section. Also note that there is a free web-based training module on the use of map services available in on the National Geospatial training website.
4.2 What is a GIS Web Service?
A GIS web service represents a GIS resource, (e.g. map, toolbox, geodatabase), on the server that is made available to client applications. Through GIS web services, these resources are easily shared over an organization’s intranet or over the internet. GIS web services provide the same view of a GIS resource to all who access the service without needing to install extra GIS software. GIS web services are often used as a component in web-based interactive mapping applications. There are many types of GIS web services based on which GIS resource is used to create the service. The US Forest Service focuses on publishing map, feature, and geoprocessing services. For more information about these types of services refer to the section, “Type of GIS Web Services”.
In the US Forest Service a Local Map Service POC can create and prepare resources, such as data and map documents, then publish them as map services which can be viewed in a variety of map viewing client applications. For example, if a Local Map Service POC publishes a map service of forest planning management areas, this map service can be viewed by others in ArcMap, ArcGIS Online or other web-based map viewing applications.
GIS web services should not be confused with the map viewing application. A GIS web service is not tied to any single map viewing application and cannot be viewed on its own without the use of a map viewing application. You can think of the resources (data, map documents, or toolboxes), the GIS web service, and the map viewing client application as three distinct components that can be mixed and matched in a variety of configurations. It is also important to understand that GIS web services from a variety of sources can be used together with other GIS web services or local spatial data to create unique cartographic displays within a map viewing application. Users can think of the process of finding available GIS web services somewhat separately from the decision about what map viewing client application will be used.
EGIS US Forest Service Page 46 Map Services User Guide 4.3 Finding GIS Web Services
Individuals, Organizations and Government Agencies around the world are publishing GIS web services on a variety of resource topics. Some of these are obscure and difficult to find while others are readily discoverable in searchable indexes or map service catalogs.
A catalog of GIS web services generally organizes services by geographic area, keyword, data type, or resource application focus so that users can easily find the GIS web services they need for their work. In its basic form, a GIS web service catalog should contain service URLs that are used by map viewer client applications and metadata associated with each GIS web service. Additionally, good GIS web service catalogs have these main characteristics:
Well-organized Contain simple search mechanisms Enable users to preview map services Provide direct links to access the contents of a map service by automatically launching map viewer client applications like ArcMap and ArcGIS Online Make services available in multiple capabilities (i.e., ArcGIS Server map service, WMS, and KML)
GeoData.gov and ESRI’s ArcGIS Online are examples of the websites that contain GIS web service catalogs. The Remote Sensing Application Center (RSAC) also publishes a pdf catalog of available image services.
4.3.1 ArcGIS Online
The Forest Service ArcGIS Online Organization serves as a searchable web-based index of all GIS web services created in the Forest Service. The application makes map and geoprocessing services published by different groups and individuals within the agency all available in one central location. This includes standard map services of EDW data, map and geoprocessing services published by the Geospatial Technology Application Center (GTAC), and others. The application also provides a place for local units to share project level map services and make them discoverable to others.
4.3.2 How to Find a GIS Web Service on AGOL
The USFS ArcGIS Online Organization contains effective search mechanisms. Users can enter search criteria to locate GIS web services of interest when they log in and create a web map. They can enter search criteria related to keyword to easily find or check to see if map services they need for their work are available. They can search within the entire FS organization, within specific groups, on public sites, or on specific known GIS servers. GIS web services that meet the search criteria will be listed and available for them to use. Also, users can mash up other public data not published by the Forest Service with their map service.
EGIS US Forest Service Page 47 Map Services User Guide 4.3.3 How to Find a GIS Web Service using the REST URL
Since all map services have been published to a server, each map service has a URL or web link. The REST URL provides users with a URL associated with each map service so they can manually add a service to viewer clients. Click the links below for the services URL directories: Internal map, feature, and geoprocessing (gp) services: https://apps.fs.usda.gov/arcn/rest/services Internal image services: https://apps.fs.usda.gov/fsgisn01/rest/services External Enterprise map, feature, and gp services: https://apps.fs.usda.gov/arcx/rest/services External Enterprise RDW image services: https://apps.fs.usda.gov/fsgisx01/rest/services External unit level map, feature, and gp services: https://apps.fs.usda.gov/fsgisx02/rest/services External unit level image services: https://apps.fs.usda.gov/fsgisx03/rest/services
4.3.4 How GIS Web Services are Organized
A user can determine some details about a particular GIS web service based solely on the name of a service. For example, a GIS web service name will likely indicate whether it’s an approved EDW service, the application focus, and more. Section “Map Document Naming Conventions” outlines these naming conventions that guide how the services are organized.
Within the ArcGIS Server services directories, users can access a metadata description of each GIS web service that will include details like geographic extent, spatial reference, title, author, minimum and maximum scale, and more.
Some information related to a service will not always be available to a user unless they use the GIS web service in a client application and explore it. Specifically, viewing a map service in a viewer client will provide the user with the layer configuration, or how the layers in a map service are organized. Users can click on the View In link within each service description to open the service in a specific application such as ArcGIS Online or ArcMap.
4.4 Map Viewer Client Applications
Map viewer client applications enable users to view, interact with, and explore map services. The map viewer client application sends requests to the map service, and the map service returns a map based on the requests. Common map viewer client application requests to a map service include changing the display scale (i.e., zooming in and out), panning across a map, turning map layers off and on, and more. Common map viewer client applications include ESRI ArcGIS programs, other 3rd party programs, and custom and generic web-based viewer clients. These map viewer clients are described below.
4.4.1 ESRI ArcGIS Desktop Programs
The most common viewer clients used by GIS users are ArcGIS programs like ArcMap, ArcCatalog and ArcGIS Explorer.
EGIS US Forest Service Page 48 Map Services User Guide Steps for using GIS web services in ArcMap:
1. Create connection to ArcGIS Server. a. Open ArcMap in Citrix at the data center. b. Click the Add Data button. c. Click GIS Servers in the Look in: drop down menu. d. Double click Add ArcGIS Server. e. Select Use GIS Services, click next. f. Enter the Server URL i. Internal map, feature, and geoprocessing (gp) services: https://apps.fs.usda.gov/arcn/rest/services ii. Internal image services: https://apps.fs.usda.gov/fsgisn01/rest/services iii. External Enterprise map, feature, and gp services: https://apps.fs.usda.gov/arcx/rest/services iv. External Enterprise RDW image services: https://apps.fs.usda.gov/fsgisx01/rest/services v. External unit level map, feature, and gp services: https://apps.fs.usda.gov/fsgisx02/rest/services vi. External unit level image services: https://apps.fs.usda.gov/fsgisx03/rest/services g. Leave user name and password empty. Click Finish. h. ArcGIS Server connection is now created. 2. Using the ArcGIS Server connection. a. Login to ArcMap through Citrix at the data center. b. Create a new empty map. a. Click the Add Data button, and double click the ArcGIS Server connection created earlier. b. Navigate to the location of the map service created earlier. c. Select the map service you wish to view and click Add. d. The map service displays on screen. You can add any data from any location to be displayed with this map service.
Steps for using GIS web services in ArcCatalog:
1. Create Connection to ArcGIS Server. a. Open ArcCatalog. b. Expand GIS Servers. c. Double click Add ArcGIS server. d. Click the Use GIS Services radio button. e. Enter the server URL i. Internal map, feature, and geoprocessing (gp) services: https://apps.fs.usda.gov/arcn/rest/services ii. Internal image services: https://apps.fs.usda.gov/fsgisn01/rest/services iii. External Enterprise map, feature, and gp services: https://apps.fs.usda.gov/arcx/rest/services
EGIS US Forest Service Page 49 Map Services User Guide iv. External Enterprise RDW image services: https://apps.fs.usda.gov/fsgisx01/rest/services v. External unit level map, feature, and gp services: https://apps.fs.usda.gov/fsgisx02/rest/services vi. External unit level image services: https://apps.fs.usda.gov/fsgisx03/rest/services f. Leave username and password empty. g. Click on Finish. h. ArcGIS Server connection is now created. 2. Using the ArcGIS Server connection. a. Expand GIS Servers b. Click the connection made earlier. c. Navigate to the location of the map service. d. Click on Preview, and the service will display in the preview window.
4.4.2 Other 3rd party programs
Other 3rd party viewer clients programs include Google Earth, NASA World Wind, MapInfo, and most other GIS-related software programs used to view map services.
4.4.3 Web based map viewers
Custom web-based viewer clients have typically been developed for specific applications, and users are not able to add other GIS web services or modify the interface in any way. Examples of custom web-based map viewers include:
Forest Service Interactive Travel Map (https://apps.fs.usda.gov/TravelAccess/index.jsp) Forest Service Interactive Visitor Map (https://www.fs.fed.us/ivm)
Generic web-based viewer clients typically are not designed for a specific purpose, users add their own GIS web services (using service URLs), and may allow users to customize the interface. Users generally use generic viewer clients when they are interested in creating their own map, and sending colleagues or other interested individuals a map URL that will enable them to view the same map. Examples of generic web-based map viewers include:
ArcGIS.com (ArcGIS Online) Geodata.gov
Steps for using GIS web services on ArcGIS Online:
1. Open a web browser and navigate to U.S. Forest Service on ArcGIS Online. 2. Log into ArcGIS Online using your FS account. If you do not have an account created, you may go here to request one. 3. Click the “Map” tab along the top left. 4. Choose the “Add” drop-down and choose the appropriate option.
EGIS US Forest Service Page 50 Map Services User Guide
a. Search for Layers = layers already in AGOL (Authoritative EDW map or feature services are owned by USFSEnterpriseContent while national services with non-FS data published in the EDW are owned by USFSMapsandApps) i. Map services appear with a small map icon while feature services appear with a small yellow icon and red paper clip, as shown below.
b. Browse for ESRI Map Layers = ESRI layers available c. Add Layer from Web = the URL of your new map service d. Add Layer from File = csv, text, gpx, or json file with x, y coordinates e. Add Map Notes = Graphics or text added to your map 5. If you choose to Add Layer from Web, go to the appropriate ArcGIS REST Services Directory and find the desired map service. i. Internal map, feature, and geoprocessing (gp) services: https://apps.fs.usda.gov/arcn/rest/services ii. Internal image services: https://apps.fs.usda.gov/fsgisn01/rest/services iii. External Enterprise map, feature, and gp services: https://apps.fs.usda.gov/arcx/rest/services iv. External Enterprise RDW image services: https://apps.fs.usda.gov/fsgisx01/rest/services v. External unit level map, feature, and gp services: https://apps.fs.usda.gov/fsgisx02/rest/services vi. External unit level image services: https://apps.fs.usda.gov/fsgisx03/rest/services a. Copy and paste the URL into the Add Layer from Web dialog and click Add Layer.
EGIS US Forest Service Page 51 Map Services User Guide
6. Modify your map as necessary. a. Zoom to an appropriate scale. b. Order the layers in the map as desired. c. Change the Basemap. d. Change symbology or visible scale. e. Enable and configure popups.
7. Save your map by clicking the “Save” button along the top and choose “Save As”
a. Fill out the title, tags, and summary with as much detailed information as possible. Separate your unique tags with commas. 8. Your map will now be listed under “My Content”. You can modify it, delete it, or share it from here. (https://usfs.maps.arcgis.com/home/content.html). a. Select your map from the list by clicking the check-box to the left of the map name. b. Click the “Share” button above the list of your maps. c. Choose the groups with whom to share the map and click OK.
Note that those designated users can now view and search for your map. But just sharing a map to a group does not necessarily mean that only those group members can search for the map. Only those group members can actually access it and use it, but others could potentially find it in a search. If you have a data sensitivity issue, talk to the MSA to make sure the map is set up correctly.
9. Send collaborators a direct link, or add the link to a webpage:
Note that if you are sharing with members of the organization or collaborators outside the FS, they will need an ArcGIS Online account unless you share it with everyone (public).
a. Use the drop-down to the right of your map title to “Open in Map Viewer”.
EGIS US Forest Service Page 52 Map Services User Guide b. Click the Share link at the top of the map. c. Copy the “Link to this map” URL and paste it in your email or send to the web manager to add to a page. d. If you would like the map embedded in a webpage, click the “Embed in Website” button and choose the options you would like. Send the resulting code to the web manager. e. If you would like to create a web application such as a story map using your newly created map, click the “Make a Web Application” button. Templates and examples of various web applications are available.
4.5 Using Map Services with Dynamic Layers Enabled
At the Forest Service we have enabled dynamic layers on many map services on all server instances. This allows clients to dynamically change layer appearance and behavior in the map service. Determining which layers will appear in a map, layer symbology, layer order and position, labeling, and more, can be achieved on the server through the use of dynamic layers. In this way, dynamic layers can increase the amount of interaction that users are able to have with our map services.
4.5.1 How to Use Map Services with Dynamic Layers Enabled
Navigate to the EDW folder in the ArcGIS REST Services Directory for the appropriate instance: Internal map, feature, and geoprocessing (gp) services: https://apps.fs.usda.gov/arcn/rest/services Internal image services: https://apps.fs.usda.gov/fsgisn01/rest/services External Enterprise map, feature, and gp services: https://apps.fs.usda.gov/arcx/rest/services External Enterprise RDW image services: https://apps.fs.usda.gov/fsgisx01/rest/services External unit level map, feature, and gp services: https://apps.fs.usda.gov/fsgisx02/rest/services External unit level image services: https://apps.fs.usda.gov/fsgisx03/rest/services
You will see all the map services, which you can then click on to get the full URL. For those with dynamic layers enabled you will see Dynamic Legend and Dynamic All Layers links in the map service description of the ArcGIS REST Services Directory.
4.5.1.1 Dynamic Map Services in AGOL
To add a dynamic map service to AGOL simply create a web map and choose to add layer from the Web and copy paste the URL from the appropriate ArcGIS REST Services Directory (alternatively, you could search for a map service in the Organization. Authoritative EDW map services are owned by USFSEnterpriseContent.)
EGIS US Forest Service Page 53 Map Services User Guide After being added to your map you will have access to each individual layer in your service. You can enable and configure popups, change layer order, change symbol style, and change the visibility range.
To change the style of a layer in the map service, click on Change Style and modify the properties as you see fit. You can choose to show location only or you can choose an attribute to show symbols for.
4.5.1.2 Dynamic Map Services in ArcGIS Desktop
To use dynamic map services in ArcGIS Desktop, you can create a user connection to ArcGIS Server in ArcGIS for Desktop, and add the dynamic service to your mxd.
Map Services will be shown in the connection without a small gray box next the map image. Also, the type will indicate Map Service (Only if you are in ArcCatalog standalone).
4.6 Using Feature Services
Feature services allow us to serve features over the Internet and provide the symbology to use when displaying the features. Clients can execute queries to get features and perform edits that can be applied to the server.
4.6.1 How to Use Feature Services
If you go to the EDW_FEATURE folder in the ArcGIS REST Services Directory for ArcX (external ArcGIS Server Instance) at https://apps.fs.usda.gov/arcx/rest/services/EDW_FEATURE you will see the EDW map services that have had feature access capability enabled. For those with feature access enabled you will see the name of the map service followed by /FeatureServer. These feature services can be added to an ArcGIS Online map, ArcGIS Desktop, or any other third party application.
NOTE: The main EDW folder still contains the primary map services that should be used in most cases if feature access is not needed. These map services will eventually be pointed at File GDB Web Mercator data to increase speed and performance of the services. Feature access requires an ArcSDE Enterprise Geodatabase so we cannot enable feature access on the main File GDB services.
4.6.1.1 Feature Services in AGOL
To add a feature service to AGOL simply create a web map and choose to add layer from the Web. Go to the rest ArcGIS REST Services Directory EDW_FEATURE folder at
https://apps.fs.usda.gov/arcx/rest/services/EDW_FEATURE
Click the link for the feature services you want to add to your map and copy the full URL in the address bar (make sure to select the URL with (FeatureServer) in the name. Go back to your web map and paste this URL in the URL: field.
EGIS US Forest Service Page 54 Map Services User Guide After being added to the map you will have access to each individual layer in your service. You can enable and configure popups, change layer order, change symbol style, add labels, set visibility range, and more.
When adding layers to your map using the search for layers dialog, map services appear with a small map icon while feature services appear with a small yellow icon and red paper clip, as shown below.
4.6.1.2 Feature Services in ArcGIS Desktop
To use feature services in ArcGIS Desktop, you can create a user connection to ArcGIS Server in ArcGIS for Desktop, and add the feature service to your mxd.
Feature Services will be shown in the connection with a small gray box next the map image. Also, the type will indicate Feature Service (Only if you are in ArcCatalog standalone).
After being added to the map, you can open the attribute table, change symbol style, modify labeling, or add the layer to geoprocessing models and tools.
4.7 Using Map Services with Different Coordinate Systems
For the most part, map services will be viewed in the WGS84 Web Mercator (Auxiliary Sphere) projection without much trouble, however when combining multiple map services, it is important to be aware of the coordinate system and tiling scheme of the maps. As a general rule, tiled or cached map services, will not re-project, thus any combination that displays a tiled map service over a service in any other projection will not display. Dynamic services can always be re- projected to match the projection of the basemap.
EGIS US Forest Service Page 55 Map Services User Guide
Basemap Basemap Operational Layer Basemap Layer Basemap Layer Layer Layer
TILED TILED DYNAMIC DYNAMIC
Web Mercator Other Web Mercator Other TILED Y N Y N Web Mercator TILED N Must be the same N Must be the same Other DYNAMIC Y Y Y Y Web Mercator DYNAMIC Y Y Y Y Other Y = Overlay will draw on the map N = Overlay will NOT draw on the map
4.7.1 Dynamic Map Services with Different Coordinate Systems
It does not matter what type of map viewer client applications (e.g. ArcMap, AGOL) you use in consuming the dynamic map service. You can always overlay dynamic map services that are in different coordinate systems.
For example, consider the scenario using two dynamic map services each with a different coordinate system. If you try to overlay dynamic map service A (using the WGS 84 web Mercator projection) on top of the dynamic map service B (using an Albers projection) with any map viewer client applications (e.g. ArcMap, AGOL), both map services will display.
4.7.2 Tiled Map Services with Different Coordinate Systems
Despite the advantages associated with the tiled map service there are a few limitations. One limitation arises when overlaying a tiled map service A (WGS 84 Web Mercator) on another cached map service B (Albers) in a web based map viewer (e.g. AGOL). Under this scenario only the tiled map service B will display. However when combining these services in ArcMap both tiled map services can be successfully viewed because of the resampling feature in ArcMap.
Below is a simple matrix showing the different combinations:
A- Tiled Map Service (WGS 84 web Mercator) B- Tiled Map Service (Albers)
Map Viewer Client Applications Overlay combinations
ArcMap ...... A on B, B on A
EGIS US Forest Service Page 56 Map Services User Guide 5 Using GIS Web Services for Application Developers
This section provides a general overview for developing and publishing applications that utilize GIS web services at the Virtual Data Center (VDC). It also includes a description of the process for development, testing and production of the GIS web services themselves. This applies to any application that utilizes geospatial web services, whether they are ArcGIS REST / SOAP Services, ESRI map services used by ArcGIS Server applications, .NET web services using ArcGIS server objects, geoprocessing service, or any other web service technology connected to geospatial data. This document does not cover the use, licensing, and integration of the Google or Bing Map API’s.
If an application utilizes a new GIS web service this is created specifically for the application and uses data that is not yet in production, then this service should be stood up in each of the hosting environments: development (PHE), pre-production (PRP), and production (PROD). If an application utilizes existing GIS web services already available in production or external third party services, then there is no need to stand up these services in the development or pre- production environments. The application can point directly to the GIS web services in production during the application’s development and testing.
Applications running at the Virtual Data Center can use several types of GIS web services:
They can use existing Enterprise Data Warehouse map services that are created from authoritative sources, are national in extent and have been approved by the EDW Content Governance Board. They can use existing non-EDW map services that local units, service centers, research stations and national applications have published. These map services have not been approved by the EDW so the content, accuracy, and extent can vary greatly. They can use public map services created by third-party organizations such as ESRI for use by the general public. They can use new map services that have been created specifically for use in the application. They can use Enterprise Data Warehouse geoprocessing services that are created to support EDW operations. They can use new geoprocessing services that have been created specifically for use in an application.
5.2 Standard Forest Service Hosting Environments
Web applications using ArcGIS Server map services are hosted in the following environments.
PHE – Project hosting environment
Here the application is built and tested. Application-specific GIS web services are created and tested.
PRP – Pre-production environment
EGIS US Forest Service Page 57 Map Services User Guide Before being installed in production web applications and any custom GIS web services are tested here to ensure the application works as designed.
PROD –Production environment
After being tested in PHE and PRP applications are installed here. GIS web services used by the application are published at the data center in production. This environment is protected by a firewall and uses a reverse proxy.
5.3 Development Process
All application development should be done in the Project Hosting Environment (PHE). New GIS services must be stood up in PHE while existing internal or external third party GIS web services can be pointed to directly.
5.3.1 New GIS Services
Applications that utilize new GIS web services using data not available in production must setup those services in PHE for development. These GIS web services should be created in PHE using data located in the development environment so that they can be tested without potentially locking any production datasets. These services should be connected to independent instances that are not used by anyone else in development so as to not cause any data locking issues.
5.3.2 Existing GIS Services
Applications that will use existing GIS web services can simply point to the production services for development. Since the GIS web service is already established, it does not need to be stood up in the development or pre-production environments for development and testing. Existing third party GIS web services can also be used, as long as they are public facing and accessible from the PHE environment.
5.4 Testing
Once an application has been developed in the development environment, the application should be stood up in the pre-production environment for testing. As with the development environment, if an application is using an established GIS web service, the application can point directly to the production or third party GIS web service version. All applications that require a new GIS web service using data not available in production must have test versions of those GIS web services stood up in pre-production that do not point to any production data.
5.5 Production
Once a new application is developed in development and tested in pre-production, it can then be stood up in production. The production application utilizes production GIS web services which point to data located in production. If these are new GIS web services, then they must be stood up in production pointing to production data. Existing GIS web services will not require
EGIS US Forest Service Page 58 Map Services User Guide any additional installations. Third party GIS web services can also be utilized by a production application as long as it is public facing and accessible from the production environment.
5.6 Types of Available GIS Web Services
See section 1.4 for types of GIS web services available for use at the VDC.
5.7 Tips for Using Enterprise GIS Web Services in Applications
This section lists recommended best practices and patterns when using GIS web services in applications at the VDC.
5.7.1 Best Practices and Patterns
Use ESRI API’s such as JavaScript, Flex, or Silverlight if possible when creating web mapping applications that utilize GIS web services. Use global variables to define the GIS web service URLs used in the application. Following this practice will allow for easier maintenance and quicker updates, if needed, to the application. When creating applications that allow data editing through map services, make sure the map is published with feature access capability enabled. The data must be in an enterprise SDE database to be published as a feature service. Avoid drawing features as client graphics or feature layers in the browser for map services using non-generalized data. Requesting feature geometries from a map service to draw feature layers or query results at small scales may not perform well for data that isn't optimized with simpler geometry information.
5.8 Accessing GIS Web Services across Different Hosting Environments
Flex and Silverlight-based applications must be granted permission to access GIS web services running on a different domain than the client application. There are two ways an application gains permission to access web services on a remote domain.
1. Install two policy files on the ArcGIS Servers where the GIS web services are running o crossdomain.xml o clientaccesspolicy.xml 2. Deploy a proxy page file that the application uses to forward requests to the GIS web service o ArcGIS API for Flex proxy page o ArcGIS API for Silverlight proxy page
All GIS servers in the VDC have policy files deployed that give permission to applications running on the following domains:
fs.fed.us apps.fs.usda.gov
EGIS US Forest Service Page 59 Map Services User Guide
usda.gov
If a Flex or Silverlight-based application is running on one of these domains, the application will be able to access GIS web services running in production. Policy files deployed in the development environment give access to applications on any domain.If the application is running on a domain that isn’t covered by the above US Forest Service domains, the proxy page file will need to be deployed for the application to use GIS web services running in the VDC. Details about the proxy page file can be found at the links listed above.
Clientaccesspolicy.xml and crossdomain.xml files would generally go at the root of the web adapter server. But the Forest Service uses reverse proxy servers in addition to the web adapters so we need these policies at the root of apache reverse proxy servers. Policy files can be accessed here:
https://apps.fs.usda.gov/crossdomain.xml https://apps.fs.usda.gov/clientaccesspolicy.xml
EGIS US Forest Service Page 60