Getting Started



Blue Spatial Server is a multi-user enterprise geodatabase GIS Server that is compatible with ESRI tools, SDKs and APIs. Blue Spatial functions similarly to ArcSDE. This is possible because Blue Spatial outputs the same open protocol as ArcGIS Server / Enterprise. Blue Spatial supports Esri Map Services (read only) and Feature Services (used for editing data). Esri tile caches are also supported. Blue Spatial supports most of the features for Map Services and Feature Services. You can view the ArcGIS Server feature comparison to learn more. You can also output OData, WMS 1.3.0, WMTS, KML and GeoJSON.

Blue Spatial supports connecting to vector data stored in your Sql Server or Sql Azure databases. You can upload your data using various file formats including shape files and geodatabase files. Or you can connect to existing data in your database by creating a layer from a table. This table could be from existing business data and applications or imported from a tool like FME. Blue Spatial supports multiple database connections so that you can expose GIS data from different sources. Blue Spatial stores it’s metadata and settings in a database that you create on setup.

Blue Spatial can be deployed with Windows Server and Sql Server instances. Alternatively it can be deployed to Azure with Azure Web Apps and Sql Azure. Deploying to Azure Web Apps has several advantages including simple autoscaling and reduced maintenance since you do not manage OS details. Blue Spatial has three different versions. You can use Basic for free or purchase a license for Pro or Enterprise. See the feature comparison on our pricing page.

Back To Top

On Premise Install

  • Windows Server 2012 or later with IIS 7 or later
  • .NET Framework 4.5 or later
  • 4.5 or later
  • Connection to Sql Server 2012 or later (Does not have to be on the same machine as IIS)
  • Before installing stop the Default Website in IIS. BlueSpatial installs as a new website with a binding to port 80. If you do not stop the Default Website the BlueSpatial website will not start.
  • Make sure your Sql Server authentication is set to mixed mode and that you have a Sql Server login ready with sysadmin permissions.
  • If you are installing on a machine with a local instance of Sql Server you must enable the named pipes protocol and restart the Sql Server service. This can be done via Sql Server Configuration Manager –> Sql Server Network Configuration –> Protocols for MSSQLSERVER –> Named Pipes

Download the on premise MSI installer from our downloads page.

  1. Execute the MSI package on your target windows server.
  2. Indicate if you accept the EULA agreement.
  3. Choose a folder location for the Blue Spatial install.
  4. Enter your Database Settings. Ensure that the connection is working by clicking the Test Connection before proceeding. Make sure the user you enter has the create database permission on the server. If you are having trouble connecting to a local Sql Server instance you may need to enable named pipes for the install. See prerequisites above.
  5. Finalize by clicking Install
  6. Create an admin account on first login
The installer will create a website in IIS named Blue Spatial along with an app pool and appropriate folder permissions for the site. Once the install is finished it will bring up the login page for the website at http://localhost/admin. You will be asked to create an admin account and login. If this page shows an error you may need to stop the Default Website in IIS and start the Blue Spatial Server site.

You can uninstall Blue Spatial Server via Add Remove Programs. The uninstall process will not delete the database that was created on install.        

Back To Top

Azure Install

The following diagram illustrates the architecture for deploying to Azure.

You can easily deploy to Azure by clicking the deploy to Azure button on the download page

The following screen will appear after logging into your Azure instance.

  1. Select a subscription.
  2. A resource group is just a logical way to organize Azure resources. Create a new resource group called Blue Spatial.
  3. Select a location that is closest to your users.
  4. Select a Sku name and capacity that is appropriate for your anticipated usage. You can see the comparison of resource and pricing here.
  5. Blue Spatial will create a new Azure Database server and a new database on that server. Enter the Administrator credentials for the server.
  6. Review Azure TOCs and click Purchase button at the bottom.
The install will create the Azure Web App, the Sql Azure instance and the Blue Spatial database. Browse to the url that was created for the Blue Spatial web app. Click the login link at the top right and you will be prompted to create your admin account and login. Be sure and configure your auto scale settings after your deployment is complete.

Troubleshooting Tips: 

Do not use “sa” as the Sql Administrator Login as it is not allowed and the deploy will fail.
Use a strong password for the Sql Aministrator Login Password otherwise the deploy will fail.
If you had a failed deploy click the resource group you used / created and delete. The resource group you deploy to must be empty otherwise there will be a name conflict and the deploy will fail.

Back To Top


Blue Spatial has three versions. By default the Enterprise version is installed with a 30 day trial. After the trial expires the license will revert to the free Basic version. The button at the top right displays which version you are using. You can click it to get more information. You may request an extended trial by emailing 

When purchasing a license you must specify your hardware Id which is visible on the version page. Once your order has been processed a license file will be emailed along with an invoice. You can upload the license on the version page. The Azure version does not have a trial capability currently. However you can request a private Azure trial instance by emailing 

Back To Top

Managing Services and Layers

Services Overview

Blue Spatial supports Map Services (read only) and Feature Services (editable). Services are organized into folders and each service has one or many layers. The following diagram illustrates this structure.

This hierarchy is accessed from the Manage services page.

To get started with Blue Spatial you can perform the following steps:
  1. Add a folder.
  2. Add a service to the folder you just added.
  3. Add a layer to the service you just added.
  4. Preview the layer you just added by clicking the Preview option on the More button.
Clicking on the name of the folder, service or layer on the left will navigate you to that item in the Service Catalog. You can edit or delete any item. Use caution when deleting a folder or service as that will delete all child items.

Back To Top

Adding Services

To add a service simply click on the Add Service button for the folder you would like to add the service to.

In the modal dialog you can select a name for the service, the service type and if it’s a Map Service whether to use cached tiles. You can also select the database connection for the service if you have added multiple connections. For convenience the folder you are adding to is listed at the top.

Map Services are read only and can be used with Tile Caches. Feature Services allow edit capability and can include Attachments.

Back To Top

Adding Layers

To add a layer click on the Add Layer button to the right of the service that you would like to add the layer to.


You can choose to add a layer from a file or from a table in the database connection for the service. The name of the folder and service that you are adding to is displayed at the top of the dialog for convenience. The following file formats are currently supported for upload: Esri Geodatabase file, shape file as .zip, geojson, kmz/kml, gml, mapinfo and gpx.    

Back To Top

Import Esri Service

Besides being able to add layers from files and from database tables, you can also import data from an existing Esri map or feature service. Simply click on the Import Service button from folder you would like to import the service into.

Simply input the service URL and select the database connection to import to and click Import.

Back To Top

Field Configuration

The field configuration page allows you to edit the attributes from your data that are exposed through the REST services.

Filter Expression
Set the filter expression if you would like some of your data automatically filtered from query results. String fields must be contained in single quotes.

Alias The alias is the name that gets exposed through the services. Changing the alias allows you to display something different than the table field name in the REST output.

Included and Editable You can choose to exclude fields from the database and also select if they are editable through the feature service.

Display Field Setting the display field allows you to set the default field for labels.

Back To Top

Time Aware Layers

If you add a layer that has a date field you can enable time query and select the date field you would like to use for time query from the field configuration page.

Back To Top

Renderer Configuration

Click the Edit Renderer button on the right of the layer that you would like to configure.

Simple Renderer


The default is a Simple Renderer. You can select a symbol from a list of built in symbols or choose to upload from file or a link on the web.

Unique Value

You must set the rendering field in order to select unique values. Once you have made a selection the Blue Spatial will allow you to add available unique values individually or all at once.


Click the links with the unique values to set the symbols for those values.

Class Breaks

When you select the class breaks Renderer you can use the slider to adjust the range for each class. You can also change the number of classes by updating the Total classes field. Use the links which show the range below the slider to set the symbol for each class.

Back To Top

Tile Caches

Map Services support tile caches. Tile caches may be appropriate for some data, e.g., large polygon datasets, as it can improve the user experience. You can check the Cached Tiles checkbox on the Map Service to enable tile caching.

Tiles can only be generated at the Map Service level so if you have multiple layers they will be rendered on the same tiles. When adding to ArcCatalog, ArcGIS PRO or one of the SDKs tiles are fetched when adding the Map Service URL. You can still choose to fetch vector data by adding the Layer URL. There are two mechanisms for caching tiles. You can cache the tiles on demand as they are requested by users. This is the default behavior. Or you can pre-cache the tiles by clicking the Build Tiles button.

When you select scale levels Blue Spatial will estimate the file storage size for creating all the tiles. After you click Create Tiles you can see the progress of tiles created and the actual storage size.

If your data is ever updated you can use the Clear Cache button to delete the tiles.

Back To Top

HTML Popups

Configure the HTML template for a layer by clicking the Config HTML button.

Use the HTML Editor to create your HTML template. A table template with all of the fields in the layer is provided by default. Blue Spatial uses bracket notation to indicate data that will be replaced at runtime with field values e.g., in the template below [Address] will be replaced with the actual address of the feature in the layer. You can easily test your HTML templates by exporting the layer to KML in the service catalog.

Back To Top

Related Records

You can setup related records from the More menu drop down:

In order to use related records there must be a foreign key from the related table that references the primary key in the selected layer.

Back To Top

Range and Value Domains

You can configure range and value domains from the field configuration page. There is a separate column for Domains:

When you click the domain link f0r a field you can add your range:

Or add your values:

Back To Top

Scale and Record Count Settings

You can modify the min and max scale as well as the max record count at the service level. 

You can also modify scale settings at the layer level.

Back To Top


Map Preview Plugin

By default Blue Spatial ships with a map preview button which works on any layer. The preview page use Esri Leaflet. This preview page is based on a plugin model. You can modify the preview functionality by changing the code in the Map.html page in the MapPreview folder in your installation.

We also provide an Esri plugin that you can use and modify here. To install the Esri plugin you would just delete the contents of the MapPreview folder and copy the code from Github. The code in our Esri preview plugin includes capabilities for adding and editing data in layers. You can customize either of these plugins for your own workflow or even create your own!

Back To Top

Service Catalog

Using the Service Catalog

The service catalog can be found at the root URL of your Blue Spatial instance. The service catalog contains all the metadata for services and layers organized by folder.

Navigate and drill down into the Folders –> Service –> Layers structure via the html output.


Or request JSON by appending the “?f=json” query string in the HTTP/S request.

Optionally disable the services catalog for added security.

Back To Top

Adding Services and Layers to Esri Products

You can easily add your services and layers to Esri products with a URL. You can find this URL by browsing the Services Catalog as mentioned above or you can just click the links from the Service name or Layer name as highlighted below.

Once you have browsed to the appropriate URL you can copy it from the address bar in your browser for use in Esri products.

ArcGIS Online

ArcGIS Pro ArcCatalog / ArcMap

Back To Top


Blue Spatial Server supports several different mechanisms for getting KML output. One mechanism is through the f=kmz output format. Any query request can output a KMZ file by modifying the f=json to f=kmz. You can also access a link to the KMZ output for all features in a layer on the layer page of the service catalog. All render styling is preserved in the KMZ documents. You can also configure HTML popups and your HTML template will be applied in the KML placemark. Currently Blue Spatial only outputs vector KML and not KML Super-Overlay tiles.

You can output GeoJSON from any query by specifying f=geojson in any REST query request.

Blue Spatial also supports sending the callback parameter / JSONP requests.

Back To Top

WMS Services

Blue Spatial supports WMS 1.3.0 services. You must enable WMS when creating the service or you can edit the service to enable WMS. 


Once WMS is enabled the WMS Service will appear in the service catalog alongside the link to the Map Service.

The link to the WMS points to the GetCapabilities url:

Back To Top


For each layer in Blue Spatial you can optionally enable OData by clicking the edit button for the layer.

You can navigate to the OData endpoint by going to [YourDomain]/odata/layers.

OData layers in Blue Spatial are read only and return spatial types with each OData entity record. However we do not currently support the OData spatial query semantics but will soon.

There are lots of libraries for working OData and many connectors to enterprise software products. Here are a few:

Back To Top

Database Connections

Managing Connections

The PRO and Enterprise versions of Blue Spatial support connecting to multiple database connections. You can select a connection when creating a Map Service or Feature Service. The default database connection which was created on install can not be deleted since it stores metadata for Blue Spatial. The Add connection dialog has a button to connect to the database server. Once a connection to the server is established you can select the database from the dropdown list and save.

For Azure database connections use the following format for the server name: tcp:[AzureSqlServerName],1433

Back To Top


Anonymous Authentication

Map Services and Feature Services are secured by default. If you would like to allow anonymous access you can check the setting on the service.

Be cautious when enabling this feature especially with Feature Services.

Back To Top

User Management

Default Admin User
A default admin user is created on the first login after install.

Adding Users
Click the Security menu then Manage users and then the Add User button.

Choose a username, password and role. Select the services that the user is allowed to access.

There are three available Roles: Admin, Edit Features and Read Only. Admin – Has all permissions available on all services and is the only role with login access to the Admin UI. Edit Features – Allowed to make edits within Feature Services and allowed read access to Map Services. Read Only – Allowed read only access to Map Services and Feature Services.

Service Mapping
When adding a user you can select the services that the user has permissions to.

Secure Access from Esri Products
Users can securely access services using their credential within ArcDesktop, ArcGIS Pro and ArcGIS Online.

Back To Top


Cross-origin resource sharing (CORS) allows your REST services to be called from the ArcGIS Javascript API from a different domain than your Blue Spatial instance. By default Blue Spatial returns the * or Allow All in the CORS header which means it will allow Javascript requests from all domains. You can restrict this by adding the domains that you want to allow to make Javascript requests.

Back To Top

Disable Service Catalog

You may want to expose the Service Catalog which contains the metadata in html and JSON for your server during development and then disable the catalog to reduce the surface area of your server. Under Security and Other Settings menu click the Disable Catalog checkbox and the Service Catalog will no longer be available.

Back To Top