GIS Concepts

A geographic information system (GIS) is a system designed to capture, store, manipulate, analyze, manage, and present all types of geographical data. One example of a GIS software is ArcGIS from the company ESRI. ArcGIS enables geographical information to be published to a server. The published information could then be shown in a web application, such as IFS GIS Map. This enables easy access to business information by using a map. Some general definitions are useful to understand:

• ArcGIS from ESRI is a geographic information system (GIS), from here on called ArcGIS.
• Features on the map (geographical information) are referred to as GIS objects.
• Feature classes in GIS system are referred to as GIS layers.
• GIS Services are hosted by an ArcGIS server and accessed using the REST API.
• Resources and operations exposed by the REST API e.g. GIS objects & layers are accessible through an URL.
• Equipment Objects, Work Orders and Customers etc. in IFS Cloud are referred to as IFS business objects.
• IFS Cloud GIS Map is technically a web application and embedded inside a IFS Cloud form, from here on called GIS Map.

Publish a map to a service

Publish a map is the first step and done outside IFS Cloud, using an ArcGIS desktop tool, ArcGIS Server Manager or by using ArcGIS Portal. A service can be created from many data sources e.g. service definition files or even CSV files. The service, once it's published is stored on an ArcGIS Web server. The service is accessed by using a server address (URL), like this: http://:/argis/rest/services

The service directory contains detailed information about services and map layers. A map layer represents geographical data in GIS and defines a GIS object's properties and how it is symbolized. It also reference the data stored in ArcGIS. Each layer is defined with a unique identification number. A layer's unique number together with server address (URL) is used by basic data in GIS Map, in order to filter what geographical information to be shown. It's also used in order to define possible connections between GIS objects and IFS business objects.
What to publish and how it should be published is decided by the customer together with an expert on GIS. A few consideration and some different strategies should be evaluated during the creation of a new service, in order to gain best performance and also to meet the requirements from business:

• GIS objects to be connected against IFS business objects should have been defined with a field IFSID to store an unique identification ID. The ID value, once saved on the GIS object, completes the connection. Disconnecting removes the ID value from the GIS object. It will not be possible to establish connections between GIS object and IFS business object if field IFSID is missing on the GIS object.

Note: The default name for the field is IFSID, but it is possible to have a different name. The selected field name must also be entered as parameter value in Map Services/Basic Data/GIS Settings page. The name of the parameter is IFS_ID_FIELD_NAME.

• Considerations should also be done in order to decide the purpose of the published information. Is it for actively work with connecting GIS object and IFS business object where edit access for the service is required? Or, is it done in order to monitor information in GIS Map e.g. show position of a valve, and if it is currently closed or opened, using a read-only service?
• A few different services could be created in ArcGIS. GIS integration supports two of them called map service and feature service. Feature service enable edit access and map service enable read access. It's good to investigate and decide about what service to use not only based on edit and read-only possibilities, but also because different services have different limitations, possibilities and might also load GIS objects (features) with different performance. Detailed information about services limitations, possibilities and performance considerations is found in ArcGIS online documentation. It's a good idea to investigate customers requirements carefully, and then design layers and services together with an expert on ArcGIS and IFS. Some important thumb should be considered:
  • Layers on an editable feature service allocate more resources and usually load slower compared to read-only layers on a map service. Only use layers from feature service when editing of attribute data is required for the user.
  • Layers on read-only map services loads quicker and should be used when the main purpose for a user is to monitor and analyze map information.
  • Optimal performance is achieved when using a cached read-only map service. The cache is created in ArcGIS and common for basemaps.
  • The initial design of layers are done in ArcGIS desktop tools or on ArcGIS online. The performance can be improved a lot, by using a few design principles. For example, by adding a filter to show a reasonable amount of features and by defining zoom levels, where feature should be shown/not shown. It's usually not a good idea to show all features when the map is fully zoomed out.
• A service where edit possibilities are enabled must be selected if the purpose is to enable GIS objects to be connected against business objects in GIS Map. This service is often referred to as feature service in ArcGIS documentation..
• A service with read-only access could be selected if the purpose is to only shown information in GIS Map. This service is often referred to as map service in ArcGIS documentation.
• The background map should also be selected and is often referred to as basemap layer. The basemap layer is used for locational references and only enables read-only access.
• A combination of map services (read-only access) and feature services (edit access), to fulfill required business needs is usually the best way to gain optimal performance in GIS Map.

The layer mapping and the configuration of the map should be carefully planned together with a GIS expert, customer and an IFS consultant. A GIS expert has knowledge about the content of published services and could give advice about how to best mix editable or read-only layer to gain optimal performance and usage of published maps. The GIS expert could also add the above field IFSID on editable layers. The customer gives information about its business needs and when an editable layer must be used in order to enable connections. IFS system administrator knows about available LUs and its content and could create the wanted layer mapping and enable the wanted business information to be shown in the map.

GIS objects to be connected against IFS business objects

A GIS object belongs to a specific layer. These layers are defined in GIS object layer configuration and assigned with a business object's LU name. For example, GIS objects in a layer that represents pipelines could be assigned to a LU in IFS, where linear asset information exists. This enables the graphical representation of a pipeline in the map to be connected against corresponding business object representation in IFS. The configuration is done in layer mapping & layer group configuration in IFS.

Layer Types in GIS Integration

GIS integration is grouping layers into three Layer Types: Basemap, Read Only and Editable. These three layer types is a simplified view and enables users to easier understand how layers are used without having to understand the underlying technical details. The name of these layer types gives a clear and easy information about what a layer is used for.

Layers defined with type Basemap is first drawn in GIS Map and secondly Read Only and finally layers defined as Editable. Layers within each layer type is also drawn according to the defined sort order in GIS Layer Mapping page and where layer with lower sort order number is drawn first. Layer navigator can also be used in order to understand in which order layers are drawn:

Basemap

Layer A with sort order 1

Layer B with sort order 2

Read Only

Layer C with sort order 1

Layer D with sort order 2

Editable

           Layer E with sort order 1

           Layer F with sort order 2

This will draw layers in the following order: A, B, C, D, E and F. To move layer E, so that it's shown on top of layer F, simply change sort order in GIS Layer Mapping page. This will also be reflected in Layer Navigator:

Editable

           Layer F with sort order 1

           Layer E with sort order 2

Technical information about Layers

GIS Map is implemented by using ArcGIS Javascript API. The API enables layers to be added by using a few different Javascript classes. Refer to ArcGIS Javascript API reference section for a list of all classes. GIS Map is today implemented to add layers from three classes: ArcGISDynamicMapServiceLayer, ArcGISTiledMapServiceLayer and FeatureLayer.

• ArcGISDynamicMapServiceLayer allows us to work with a dynamic map service. A dynamic map service generates images on the fly.
• ArcGISTiledMapServiceLayer allows us to work with a cached map service. A cached service accesses tiles from a cache instead of dynamically rendering images.
• FeatureLayer display features from a single layer in either a Map Service or Feature Service. The features in a feature layer can be edited if the isEditable method is true and displayed by using Feature Service.
  Note: The layer type Editable in GIS integration enables layers to be configured from a Feature Service and not from a Map Service.

Layers for GIS integration are added in GIS Layer Mapping page and must be defined with a layer type (Basemap, Read Only or Editable).

Basemap Layer

Basemap layer enables a background map to be shown. These layers are read-only and could not be connected to IFS business objects. A typical customer in service might have several basemaps in use; for call center: Street, for Technicians: Street and Network and for engineering department: Network, Utility Services and Land Planning maps.

Some basemaps are available on ArcGIS online. These basemaps are free to use and could accessed by using "http://server.arcgisonline.com/arcgis/rest/services" URL.

Layer Display Name	Map Service URL	Description
Light Gray	http://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Light_Gray_Base/MapServer	Only key information is represented to provide geographic context, allowing your data to come to the foreground.
Terrain	http://services.arcgisonline.com/ArcGIS/rest/services/World_Terrain_Base/MapServer	The basemap features shaded relief imagery, bathymetry, and coastal water features designed to provide a neutral background for other data layers.
Ocean	http://services.arcgisonline.com/ArcGIS/rest/services/Ocean_Basemap/MapServer	The basemap features marine bathymetry. Land features include inland waters and roads overlaid on land cover and shaded relief imagery.
Topographic	http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer	The map includes administrative boundaries, cities, water features, physiographic features, parks, landmarks, highways, roads, railways, and airports overlaid on land cover and shaded relief imagery for added context.
Streets	http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer	This comprehensive street map includes highways, major roads, minor roads, one-way arrow indicators, railways, water features, administrative boundaries, cities, parks, and landmarks, overlaid on shaded relief imagery for added context. Street basemap is used in GIS Map page when no other basemap is defined.
Imagery	http://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer	World Imagery provides one meter or better satellite and aerial imagery in many parts of the world and lower resolution satellite imagery worldwide.

A Map Service can be defined to draw dynamically from the data (ArcGISDynamicMapServiceLayer) or by using tiles from a cache (ArcGISTiledMapServiceLayer), in a GIS application. Both situations works fine for layers defined as Basemaps in GIS Map:

• Services defined to use tiles from a cache will load data as ArcGISTiledMapServiceLayer.
• Services defined to draw dynamically from the data will load data as ArcGISDynamicMapServiceLayer.

There could be situations where services use tiles from a cache (ArcGISTiledMapServiceLayer) from different data sources and/or different spatial references where only one of the them will load data in GIS applications. Try to avoid this situation by adding all services using cached tiles on the same server and by using the same spatial references on all services. An alternative might also be to show some of the cached layers as Read Only layers and where they will be loaded as ArcGISDynamicMapServiceLayer.

A layer from a Map Service have the word MapServer in the end of the URL. Layers from a Map Service can be defined as Basemap or Read Only in GIS integration. Layers from a Map Service cannot be defined as Editable in GIS integration.

Read Only Layer

Read only layers enable GIS objects to be shown in GIS Map. These layers are used for information purpose in GIS Map and connections to business objects cannot be made. These layers loads quicker compared to editable layers and could also be cached on the ArcGIS server to gain performance. Editable layers cannot be cached.

A Map Service can be defined to draw dynamically from the data (ArcGISDynamicMapServiceLayer) or by using tiles from a cache (ArcGISTiledMapServiceLayer), in a GIS application. Layers defined as Read Only always load data as ArcGISDynamicMapServiceLayer, in GIS Map, regardless if the service is cached with tiles or not. Use the type Basemap if the service is defined to use tiles from a cache and it's required to load as ArcGISTiledMapServiceLayer.

A layer from a Map Service has the word MapServer in the end of the URL. Layers from a Map Service can be defined as Read Only or Basemap in GIS integration. Layers from a Map Service cannot be defined as Editable in GIS integration.

Editable Layer

Editable layer enables GIS objects to be shown in GIS Map and connections to IFS business objects to be made. These layers should have been published using an ArcGIS service where edit possibilities are enabled. Entering a LU is mandatory for these layers, for example create a record to show electrical distribution lines or pipelines in GIS Map and enable it to be connected to linear asset objects in IFS. Editable layers loads slower compared to read-only layers. Editable layers is also required for some GIS Map tools:

• Attribute search
• Attribute inspector
• Editing tool

Some considerations for editable layers

• Use editable layers if the purpose is to connect business objects, read attribute information or manipulate GIS objects with editing tool, else a read-only layer could be used.
• Revoke create, update and delete on editable layers feature service, in ArcGIS if business objects connections and editing of GIS objects isn't required. Attribute search, attribute inspector and attribute table will still work and show information from ArcGIS.
• Revoke create and delete will enable business objects connections and it will show and edit attribute information. But it will not be possible to add new GIS objects or delete existing.

Layers from a Feature Service can only be defined as Editable in GIS integration. They will be drawn by using the FeatureLayer class in GIS Map. GIS objects in a feature layer can be edited if the isEditable method is true.

A layer from a Feature Service has the word FeatureServer in the end of the URL. Layers from a Feature Service can be defined as Editable in GIS integration. Layers from a Feature Service cannot be defined as Basemap or Read Only in GIS integration.

Technical information about measurements widget and geometry service

The Measurement widget provides tools for calculating the current location (Get Location) and measuring distance (Measure Distance) and area (Measure Area). If the map's coordinate system is not Web Mercator or geographic or if complex polygons are drawn the measure widget will need to use the geometry service to project or simplify geometries:

• Information about the Measurement Widget is described in ArcGIS API for Javascript online documentation.
• Information about how to create and publish a Geometry Service is described in ArcGIS Resource Center online documentation.

Geometry service to be used by measurements widget in GIS Map page can be defined by a system parameter in Solution Manager/System Parameters page. The name of the parameter is URL to the Geometry Service used by the Measurement tool in GIS Map (optional). Default value is NONE.

Experimental debugging of a layer in ArcGIS.com Map

This section describes a few experimental and unsupported features in GIS Map.

Open a layer in a external web application or open the layer on its ArcGIS service page, can be useful during debugging and testing of GIS Map. Parameters enables this. Create a new shortcut for GIS Map window in IFS Aurena and add parameters.

This adds a globe, close to all layers in layer navigator. Click on the symbol and the layer is opened in ArcGIS.com Map:

• HTML_PAGE_PARAMS=showago=true

This adds an arrow, close to all layers in layer navigator. Click on the arrow and the layer is opened on its ArcGIS service page:

• HTML_PAGE_PARAMS=openservice=true

This adds a button in Serach and Select panel with the name Show Mock Values. Click on the button and it generate a page showing all values that have been sent into GIS Map:

• HTML_PAGE_PARAMS=mockvalues=true

Using private layers and map services

A map service, which exposes one or more map layers, can be public or it can be private (also known as secured or protected services.) Public services can be used easily in GIS Map since anyone that has access to the ArcGIS server can access the content. For some customers this works well. Other customers want to have more control over their map data and want to restrict it to certain users. We call this private map services.

Authenticating private services

In order to use private map services, the user needs to be authenticated in some way. Since we are embedding maps inside IFS, either the user can be made to login again inside IFS, or we can configure the system to login to the map service automatically. Regardless of what option is chosen, the GIS proxy (see below) needs to be configured.

Using private map services together with SSL

Sometimes it is not enough to protect a service by requiring authentication. The service can then be configured to use SSL (HTTPS). GIS Map supports this but to get it to work it is important to know how to setup and use SSL certificates in the client and on the application server (since the application server, via the proxy, access the ArcGIS server, it needs to be able to work with the certificates on the ArcGIS server). This is especially important when using self-signed certificates. GIS Map might not give any error if a self-signed certificate is not accepted by the client so it has to be verified outside IFS Cloud, in Internet Explorer. How to accept these certificates is not explained in this documentation. For simpler testing and implementation it is recommended to use proper SSL certificates created by a real Certificate Authority.

Configuring the GIS proxy

The GIS proxy ("proxy") is a critical part of the GIS integration. It needs to be configured to work correctly and it is needed for most scenarios but the simplest ones. Without a properly configured proxy, GIS Map will not work.

What is the proxy and what is it used for?

The proxy is a small web service that is automatically installed inside the IFS Cloud application server (MWS). It acts as a middle man (hence the name "proxy") between the client and a server and makes requests on behalf of the user. When the proxy is used, GIS Map makes a certain request against the proxy, and the proxy in turn process this request (it also checks if it is a valid request) and makes a request of its own to some map service. The result is returned back to the GIS Map client.

The proxy enables the following:

1. Using specific basemaps from ArcGIS online or other ArcGIS servers
2. Writing data to a map service (feature service/server).
3. Allowing access to secured map services that requires login.

Where to configure the proxy

The proxy configuration is placed in the conf folder of the instance in IFS home. The file is named gisint.proxy.config. Because this file needs to be configured for all application server nodes, a special feature exists to edit this file directly from inside IFS Cloud. The proxy configuration can be edited from the GIS Settings page. For more information, refer to Define GIS Settings. When the proxy configuration has been changed and saved, it will be saved on each application server node.

Note: After installing IFS Cloud, there is not yet a proxy configuration file on the application server. To create one, you need to change the proxy configuration from the GIS Settings page and save it. That will write the proxy configuration to disk on all application server nodes.

Configure the proxy for using basemaps from ArcGIS Online

If you are not only relying on the default "streets" basemaps and want to provide other basemaps from ArcGIS Online to users, then the proxy needs to be configured to be able to access information, or metadata, about those basemap's map services. The following example configuration should allow for most, if not all, basemaps from ArcGIS Online to be used within GIS Map:

      <serverUrl url="https://services.arcgisonline.com/ArcGIS/rest/services"
                 matchAll="true"/>
      

Note: If https is used to access the services, then https must be specified in the proxy configuration as above. Similarly for http. Also, although the proxy is used to access information about the basemap, it does not mean that all the basemap data goes through the proxy. If, after saving the proxy configuration setting, the proxy still not appear to work, open the Background Jobs page and populate (the proxy configuration is saved to the application server using a background job). Look for jobs with the description "GISINT - Refresh proxy configuration". If there are rows with that description, open the details and look into the Error Text field to get clues to why the proxy configuration could not be saved to the application server. One problem could be that the PL/SQL access provider (PLAP) has not been configured properly.

One way to verify if the proxy configuration has been saved and that the proxy is running is to open up the following URL in a web browser:

      http(s)://SERVER:PORT/gisint/proxy/proxy.jsp?ping

If you get the message "The proxy configuration file is NOT Found." it means the proxy configuration does not exist.

If you get a message that looks something like this, it means the proxy is running and that the proxy configuration is written to the application server:

    { "Proxy Version": "1.1.2", "Configuration File": "OK", "Log File": "OK"}

You can also test if the proxy works with a certain map layer service URL, by opening a URL like this in a web browser:

      
      http(s)://SERVER:PORT/gisint/proxy/proxy.jsp?http(s)://ARCGISMAPSERVICEURL

For example, if you test the following URL, it will probably return the error below:

      http(s)://SERVER:PORT/gisint/proxy/proxy.jsp?http://google.com

Error:

{"error": {"code": 403,"details": ["Proxy has not been set up for this URL. Make sure there is a serverUrl in the configuration file that matches: http://google.com"], "message": "Proxy has not been set up for this URL."}}

If on the other hand, the proxy is correctly configured with the map service URL, your web browser will show you metadata from the map service.

Writing data to a map service

In GIS Map, there are some operations the user can do that requires writing data to the map service. This only works for editable services which uses a feature service in the ArcGIS server.

These are the operations that requires writing data to the map service:

1. Connect or disconnect a GIS object to or from a business object in IFS.
2. Create GIS objects or edit GIS object attributes using the Tools / Editing.

Example

This is how to configure the proxy if the user needs to edit data in the following map service:

    http://ARCGISSERVERNAME/ArcGIS/rest/services/SERVICENAME/FeatureServer/0
      

The following directive needs to be added to the proxy configuration for a server named ARCGISSERVERNAME:

    <serverUrl url="http://ARCGISSERVERNAME/ArcGIS/rest/services/SERVICENAME/FeatureServer/0"
               matchAll="true"/>
      

If more than one feature service needs to be edited on the same server, or more than one layer in the same service needs to be edited, it is possible to leave out the service name, like this:

    <serverUrl url="http://ARCGISSERVERNAME/ArcGIS/rest/services"
               matchAll="true"/>
      

This will enable changes to be written back to the server for all services on ARCGISSERVERNAME.

Note: Be careful to use http or https in the correct way. If the map service URL starts with "https", https need to be specified in the proxy configuration as well.

Allowing access to secured map services

Public map services that does not require a user to login to see the information can be used without configuring the proxy as long as the user only need to view the information and not create new objects or connect objects.

For services that require login ("secured services"), the proxy is used and needs to be configured. There are two main scenarios on how to handle this.

1. Let the user enter the required credentials (username and password) when using the GIS Map page.
2. Let the proxy "login" for the user.

Access secure services by manual user login

If access to secure map services should be provided by having users login once they open GIS Map (by providing username and password), the proxy needs to be configured to generating a temporary token that will be used to access the map service.

There are two main scenarios:

1. Using an ArcGIS server (on-premise or in a managed cloud).
2. Using ArcGIS Online (or Portal).

Example

This is how to configure the proxy for ArcGIS server:

    <serverUrl url="http://ARCGISSERVERNAME:PORT/arcgis/tokens/"/>
      

Above, replace ARCGISSERVERNAME and PORT with the name and port number of the ArcGIS server machine.

This is how to configure the proxy for ArcGIS Online:

    <serverUrl url="https://www.arcgis.com/sharing/generateToken"
               matchAll="true"/>
      

For Portal, replace arcgis.com above with the servername where Portal is installed.

Once the user has manually logged in to the necessary map services in GIS Map, the credentials will be cached for some time. This means that if a user changes to another page and then back to GIS Map, he might not have to login again, depending on how much time has passed. The time (in minutes) can be controlled by the GIS setting CREDENTIALS_EXPIRATION_TIME. If not set, the default is 60 minutes. The setting CREDENTIALS_EXPIRATION_TIME is valid when manually entering credentials.

Access secure services without manual user login

If access to secure map services should be provided to users without having them to login, the proxy has to be configured with a username and password that can be used to login on the users' behalf. This can be used for on-premise ArcGIS servers as well as ArcGIS Online but is especially important for the latter, where all services are available on the public internet.

Note: For this to work, the option Use Proxy must be selected on the layer in the GIS Layer Mapping page. If the option is not enabled, the request will not go via the proxy, and then proxy will not be able to login to the map service on the user's behalf.

Example

This is how to configure the proxy to login on the users' behalf on map services hosted on a certain account on ArcGIS Online:

    <serverUrl url="https://services.arcgis.com/MYCLOSEDSERVICEID/ArcGIS/rest/services"
               matchAll="true"
               username="myusername"
               password="mypassword"/>
      

Above, replace "myusername" and "mypassword" with the appropriate username and password that will be used to access the map service. If needed, the URL can be longer and specify the full URL to the map service, or even to a certain layer in the map service, like this:

This configuration will only work for one specific service named SERVICENAME and for layer LAYERID (a number from zero and up).

    <serverUrl url="https://services.arcgis.com/MYCLOSEDSERVICEID/ArcGIS/rest/services/SERVICENAME/LAYERID"
               matchAll="false"
               username="myusername"
               password="mypassword"/>

Note: This requires the setting Use Proxy to be enabled on the layer in GIS Layer Mapping page. In all other situations the setting Use Proxy can be disabled on the layer.

The user will now be automatically logged in to the map service without having to manually enter credentials. A token is automatically generated by the REST service and valid for 60 minutes.

Example of a complete proxy configuration

Here is an example of a complete proxy configuration, including header and footer information. For the latest and complete documentation about the configuration capabilities of this proxy, refer to Esri's documentation on Github via "https://github.com/Esri/resource-proxy" URL. Note that the capabilities might differ, since the version of the proxy in IFS Applications does not always include the latest proxy from Esri, and the proxy in IFS Cloud is slightly modified.

    <?xml version="1.0" encoding="utf-8" ?>
    <ProxyConfig allowedReferers="*"
             logFile="c:/ifs/gisproxy.log"
             logLevel="FINEST"
             mustMatch="true">
       <serverUrls>

           <!-- For basemaps on ArcGIS Online to work -->

           <serverUrl url="https://services.arcgisonline.com/ArcGIS/rest/services"
                      matchAll="true"/>

           <!-- For allowing writing to a certain service and layer on an on-premise ArcGIS server -->

           <serverUrl url="http://ARCGISSERVERNAME/ArcGIS/rest/services/SERVICENAME/FeatureServer/0"
                      matchAll="true"/>

           <!-- For allowing writing to a public map service on ArcGIS Online -->

           <serverUrl url="https://services.arcgis.com/SECRETARCGISONLINETHING/ArcGIS/rest/services/SERVICENAME/FeatureServer"
                      matchAll="true"/>

           <!-- For allowing users to login manually on secure (not public/for Everyone) ArcGIS Online services -->

           <serverUrl url="https://www.arcgis.com/sharing/generateToken"
                      matchAll="true"/>

           <!-- Accessing a secure map service using username and password -->

           <serverUrl url="https://services.arcgis.com/MYCLOSEDSERVICEID/ArcGIS/rest/services/SERVICENAME/LAYERID"
               matchAll="false"
               username="myusername"
               password="mypassword"/>


       </serverUrls>
    </ProxyConfig>
      

Pages

GIS Connections
GIS Layer Group
GIS Layer Mapping
GIS Map
GIS Object Configuration
GIS Settings

Activity Diagrams

Map Services