Docs

Getting Started

Overview


Capabilities

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 almost all of the specification 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, GeoJSON, Shape and CSV.

Data
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. You can also import data from an existing Esri REST service. 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. 

Deployment
Blue Spatial can be deployed to 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

Prerequisites 
  • Windows Server 2012 or later with IIS 7 or later
  • .NET Framework 4.5 or later
  • ASP.net 4.5 or later
  • Connection to Sql Server 2012 or later (Does not have to be on the same machine as IIS)
  • You may want to delete or stop the Default Website in IIS. BlueSpatial installs as a new website with a binding to port 80 which could cause a conflict if another site has the same binding in IIS. You can change the port / url binding in IIS after install.
  • 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
Download the on premise MSI installer from our downloads page.

Steps


  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 have a port conflict (Blue Spatial installs with port 80 binding by default) in which case the Blue Spatial site will be stopped in IIS. You can either change the port / url binding or stop the Default Website in IIS and start the Blue Spatial Server site. Optionally you can configure Blue Spatial to use SSL and port 443 just like any other IIS 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

Licensing

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 support@bluespatial.com. 



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 support@bluespatial.com. 

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 within the layer tree-view control on the left.



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.
You can edit or delete any item. Use caution when deleting a folder or service as that will delete all child items. When deleting a layer you will be prompted if you would like to delete the layer in the table.

Clicking on the name of the folder, service or layer in the breadcrumb will navigate you to that item in the Service Catalog.

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 service dialog you can select a name for the service and the service type (either Map Service or Feature Service). Map Services are read only and can be used with Tile Caches. Feature Services allow edit capability and can include Attachments. You can also select the database connection for the service if you have added multiple connections. You may also want to set the scale settings. Blue Spatial uses the same convention as ArcGIS where the zero for Max and Min scale indicates no scale limit. Max record count is 1000 by default. The max record count is used to avoid scenarios that would potentially return very large datasets. For example, if you have 1 million features in a layer that are all visible at the CONUS level you may want to set your scale settings and or restrict the number of features that can be returned via the Max Record Count setting.  

Back To Top

Adding Layers

To add a layer select the service in the treeview and 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.

Sync Table Schema Your data schema may evolve e.g., database field names change, fields are added and dropped. When that happens you can sync your database schema with the Sync Table Schema button to synchronize your layer fields from the database table.

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 on the HTML tab for the layer.

 

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 Related Records tab:



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

Versioning

You can enable versioning for any feature layer within Blue Spatial. Versioning can only be enabled for systems with Sql Azure or Sql Server 2016 or greater as it depends on Temporal Tables. Once you enable versioning you will have a complete history of changes that function similar to source control systems. When you select one of the changes you can:
  • View Changeset – allows you to compare just the current data and the previous data. Data that changed is highlighted.
  • Revert Changeset – you can revert individual changes
  • View Data at That Time – allows you to view your features in a grid as they were at the point in time
  • Revert Data to Time – you can revert your data to any point in time (similar to Apple Time Machine)

Back To Top

Customization

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

SDKs and Tools Compatible with Blue Spatial

Blue Spatial can be used with a wide range of tools and SDKs. This is possible via the support for standards including Esri REST (Geoservices REST), KML/KMZ, GeoJSON, WMS, WMTS, OData

SDKs:
Esri SDKs – Esri REST
Google Maps – KML/KMZ
Leaflet – Esri REST
Mapbox – GeoJSON
Bing Maps – KML/KMZ, GeoJSON
OpenLayers – WMS, GeoJSON

Tools:
ArcGIS Desktop (ArcMap and ArcGIS Pro) – Secured Esri Map Services and Feature Services 
QGIS – Esri REST, WMS
Tableau – Web Data Connector
Power BI – OData

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

Output Formats

You can download the following formats through the catalog…



Or you can specify the format parameter (f=[format]) in your query reqeust.

Esri JSON (default f=json)
By default Blue Spatial outputs the Esri JSON format (Geoservices REST). You can optionally specify f=pjson for formatted Esri JSON.

KML/KMZ (f=kmz)

You can output KML from any query by specifying f=kmz in any REST query request. 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.

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

Shape File (f=shp)
You can output GeoJSON from any query by specifying f=geojson in any REST query request. Shape file attribute names are limited to 10 characters so your attribute names may be concatenated or renamed.

CSV (f=csv)
You can output CSVfrom any query by specifying f=geojson in any REST query request. For point layers latitude and longitude columns are output. For line and polygon layers a geometry column with wkt is output.

JSONP
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

OData

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].database.windows.net,1433

Back To Top

Security

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.

Roles
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

CORS

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

Realtime Mapping / Event Publishing

Overview

Blue Spatial Server has the capability to publish data events (adds, updates and deletes) to event providers. This capability can be used for realtime mapping, notifications and geofencing solutions. There are three providers for publishing data events: Pubnub, Microsoft Azure Event Hubs, Signal R / Websockets. You can also configure which data events you would like to publish for example only update events etc. When a data event occurs the feature is published as GeoJSON to the configured provider. Publishing of data events is configured on the Events tab for the layer.



Back To Top

PubNub

To configure Blue Spatial Server to publish events to PubNub:
  1. Create a project in PubNub
  2. Copy the Publish Key and Subscribe Key into the PubNub section on the Events tab for the Layer as shown in the overview.
  3. Select the checkboxes for the events you would like to publish including Add, Edit and Deletes

Back To Top

Location Intelligence

Tableau

Getting your real time layer data in Tableau is as simple as entering a Url. 

 


  • Navigate to the layer that you want to add to Tableau in the Blue Spatial service catalog and copy Tableau Web Data Connector link.


  • In Tableau select Web Data Connector

   

  • Paste the link you copied earlier into the Web Data Connector dialog and hit Enter
  • Your layer will appear in Tableau. Click Update Now. You can refresh your data at any time from the live layer data by clicking the refresh icon at the top left and then the update now button again.



  • Create a sheet and drag your geometry column to the Marks section in Tableau Desktop




It is also possible to import spatial files into Tableau from Blue Spatial Server by downloading KML, GeoJSON or Shape files from the service catalog. Yet another option is to leverage Blue Spatial support for OData within Tableau. Unfortunately Tableau does not support OData spatial types so connecting to the Web Data Connector is preferred.

Back To Top