ESRI ArcGIS Server (WAM Only)
The GIS Integration uses ESRI ArcGIS server to allow users to view asset layers on a map, and to create and view work requests and work orders on the map.
Refer to the GIS integration section of the Oracle Utilities Work and Asset Management Administrative Guide for configuration information after installing.
Note: For ESRI integration functionality, you must purchase ESRI ArcGIS Server software, along with Portal for ArcGIS, or ArcGIS Online cloud subscription from ESRI.
Perform the following for initial installation and importing the GIS metadata:
Notes on SSL:
• Oracle Utilities Work and Asset Management is set up with SSL (https) enabled as default.
• ESRI ArcGIS is set up with SSL (https) enabled as default.
Supported ESRI ArcGIS Server Versions
At the time of this release, the following ESRI ArcGIS Server and ArcGIS Portal versions are supported: V10.7.1 and V10.8.1
Installing and Configuring the ESRI ArcGIS Desktop
Make sure to install the ArcGIS Desktop V10.7.1 and V10.8.1 in the GIS environment.
To install and configure the appropriate ArcGIS Desktop software version, refer to the instructions at:
Installing and Configuring the ESRI ArcGIS Server
To install and configure the ArcGIS Server software, refer to the instructions at:
Make sure to select the installation steps specific to the operating system.
Configuring the Enterprise Geodatabase
Note: Ignore this step if the Enterprise Geodatabase is already set up and the connection is established from ArcGIS Desktop.
To set up Enterprise Geodatabase refer to the instructions at:
Select the database accordingly. Establish a connection to the geodatabase from ArcGIS Desktop and enable the data accessible from ArcGIS server.
For more information refer to:
Importing Data to Geodatabase
After the Geodatabase is set up, make sure that the necessary customer specific datasets are imported.
To import the work locations dataset:
1. Download the Oracle Utilities Work and Asset Management V2.4.0.0.0 ESRI Integration component from the Oracle Utilities Work and Asset Management V2.4.0.0.0 package.
2. Copy the file to the server where ArcGIS is installed and unzip it.
3. Navigate to the XML workspace file located at /metadata/xmlWorkspaceDocument/WORKLOCATIONS.XML.
4. Copy the workspace file to the relevant destination folder.
5. Select Database connections in the Catalog.
6. To import the XML workspace document:
a. Select Schema only in the import options.
b. Specify the path of the work locations XML file.
7. Once the import process is complete, the Contents tab displays the WorkLocationDataset imported into the Geodatabase.
Note that the Map Notes dataset configuration is optional. However, to display a Map Notes layer, any layer dedicated to capture notes/redlining can be used.
Map Notes is a customer specific layer and Oracle Utilities Work and Asset Management does not own/manage it and is not delivered as part of base product. To create a feature class in Geodatabase, refer to the instructions at:
Register data with the ArcGIS Server using Manager. For instructions refer to:
Publishing Data as Services in the ArcGIS Server
After importing the datasets, publish the respective map documents as map/feature services in the ArcGIS server.
For more information about publishing a map document as a map service, refer to:
To create a Work Locations Map service:
1. Create a map document using the Work Locations dataset.
2. In ArcCatalog, right-click Work Locations. From the content menu, click Share as Service.
3. In the Share as Service wizard, select Publish a Service, and then click Next.
4. From the Choose a Connection drop-down list, select ArcGIS Server.
5. Enter the service name with which the service has to be published.
Make sure the name is updated in ESRI Integration Master Configuration portal in Oracle Utilities Work and Asset Management.
6. Click Next to proceed.
7. Enter the folder path and then click Continue.
8. In the Service Editor wizard, select Feature Access Capability.
9. Click Publish to publish the map document as a service.
Follow these steps to publish the Map Notes document as a feature service in ArcGIS Server.
Creating Web Maps Using ArcGIS Online
Create a web map using ArcGIS Online or the ArcGIS portal.
For information about creating web map using ArcGIS online, refer to:
The web map includes layers from the published map/feature services (Utility specific network map service, Work Locations map service, and an optional Map notes feature service) in ArcGIS server. Make sure that the web map is shared to the intended users.
Installing the ArcGIS Web Adaptor
If ArcGIS Online is set up with web maps, ArcGIS web adaptor installation is not required. However, if the web maps are intended to set up on the ArcGIS portal, then the ArcGIS web adaptor should be installed.
For information about installing and configuring ArcGIS web adaptor, refer to:
Installing and Configuring the ArcGIS Portal
If ArcGIS Online is set up with web maps, ArcGIS portal installation is not required. However, if the web maps are intended to set up on the ArcGIS portal, then the ArcGIS portal should be installed and configured with ArcGIS web adaptor.
For instructions to install and configure the ArcGIS portal, refer to:
Creating Web Maps Using the ArcGIS Portal
Create a web map using ArcGIS Online or ArcGIS portal. For instructions to create a webmap using the ArcGIS portal, refer to:
The web map includes layers from the published map/feature services (Utility specific network map service, Work Locations map service, and an optional Map notes feature service) in ArcGIS server. Make sure that the web map is shared to the intended users.
Connecting ArcGIS Portal with Enterprise LDAP
Note that this step is optional.
The integration of ArcGIS portal with Enterprise LDAP ensures that the users in an organization should be created/managed on the portal page and the authentication is done using LDAP.
Configure the identity store accordingly and then import the enterprise users into the ArcGIS portal.
For more information about configuring the identity store and importing the enterprise users, refer to:
Configuring Inbound Sync (GIS)
This section describes the GIS server configurations to set up inbound synchronization service.
Configuring the inbound synchronization includes the following steps:
1. Deploying the jar file.
2. Configuring the property file.
3. Executing the tool.
4. Publishing the results as Geoprocessing service.
Deploying the Jar File
To deploy the jar file:
1. Download the Oracle Utilities Work and Asset Management V2.4.0.0.0 ESRI Integration component from the Oracle Utilities Work and Asset Management V2.4.0.0.0 package.
2. Copy the file to the server where ArcGIS is installed and unzip it.
3. Navigate to the /GPService/lib/spl-w1-2.4.0.0.0-gis.jar file.
The deployment of this jar requires ArcGIS Desktop (to execute the jar and generate the results) and ArcGIS Server (to publish the results as Geoprocessing service). Extract the additional jar files jackson-annotations-x.x.x.jar, jackson-core- x.x.x.jar, and jackson- databind- x.x.x.jar from the below ArcGIS Server installation location.
<ArcGIS Server Installation Path>\Server\framework\lib\shared
Example: C:\Program Files\ArcGIS\Server\framework\lib\shared
It helps the extractor program to access the map/feature services if they are secured.
These jar files should be placed in the following ArcGIS desktop and ArcGIS server running locations:
• ArcGIS Desktop installation folder path
Example: C:\Program Files (x86)\ArcGIS\Desktop10.8\java\lib\ext
• ArcGIS Server installation folder path
Example: C:\Program Files\ArcGIS\Server\usr\lib\ext
Configuring Property files
The property or Config file is located where the jar file exists. Copy the Config file to the location of the jar file. Refer to the
Deploying the Jar File section for information about the folder.
Configuring the property file is a one-time step by the Administrator to set up the synchronization process. The property file consists of input parameters required for the GIS Extractor program to establish a connection to the Geodatabase.
The parameters to be configured in the property file are:
• keyDBServer - Database server name
Example: xxxxxxxxxxxxx.us.oracle.com
• keyDBInstance - Database instance name
Example: sde:oracle11g:WAMV2200DEV
• keyDBName - Database name
Example: WAMV2200DEV
• keyDBUser - Database user name
Example: sde
• keyDBPwd - Database user password
• keyUsername - ArcGIS Server user name to generate security token
Example: siteadmin
• keyPassword - ArcGIS Server user password
Example: siteadmin
• keyExpiration - Token Expiration duration in seconds
Example: 60
Executing the Tools
To create and execute a new/custom tool:
1. Open the ArcMap or ArcCatalog application.
2. In the Catalog window, navigate to Toolboxes > My Toolboxes.
3. Right-click My Toolboxes and select New > Toolbox.
4. Enter “WAMGPTools.tbx” as the toolbox name and click Enter.
5. Right-click the new toolbox and click Add > Tool.
6. In the Add Tool dialog box, select WAMGIGPFF and click OK.
7. To execute the Extract_Delta_Changes tool in ArcToolbox:
a. Select and double-click the tool.
b. View the tool's parameters.
c. Provide the respective inputs to the parameters:
• Task_Name: QueryIDs
• Execution_Mode: Initial
• Feature_Class_List
Example: SDE.ZZ_wControlValve
• Source_Version: SDE.DEFAULT
• Temp_Version: Temp
• WKID: Well-known identifier for the target spatial reference
• WAM Sync Version: The version name to be created in Geodatabase to track incremental changes
Example: WAMSyncVersion
Leave the remaining parameters as “NA”.
d. Click OK to run the tool.
Publishing the Results as Geoprocessing Service
After the configuration file is set up and the tool is executed, the results of the tool should be published as a Geoprocessing service in the ArcGIS server.
To publish the results as a Geoprocessing service:
1. In the ArcCatalog tool, navigate to Geoprocessing Menu > Results.
The results of the tool are displayed.
2. Right-click Extract_Delta_Changes […] and select Share As > Geoprocessing Service.
3. In the Share as Service window, select Publish a service, and then click Next.
4. From the Choose a connection drop-down list, select ArcGIS Server.
5. Enter ExtractDeltaChanges in the Service name field and click Next.
6. Select Create new folder.
7. Enter GPServices and click Continue.
8. In the Service Editor dialog box, select the required parameters in the Extract_Delta_Changes node. Then, provide the details in the Description field.
• Task_Name: Enables the service to retrieve GUIDs of the requested feature classes. The other possible values for task are:
• Query Specific Changes
• Query Complete Changes
• Query Inserts
• Query Updates
• Delete Version
• Execution_Mode: Assists in retrieving all GUIDs of the feature class or updated GUIDs of the feature class. The possible values are “Initial” and “COU” (Change Only Updates).
• Feature_Class_List: Enables to query GUIDs in the feature class of interest. Only one feature class name should be passed to service at a time.
• Feature_Count_Range: Limit on the records that can be sent using QueryCompleteChanges task.
• Fields: Helps the GP service to extract the information only for the fields of interest. Oracle Utilities Application Framework batch process reads the list of fields from extendable lookup and passes the value as a comma separated list.
• Life_Cycle_Status: Field and its value (comma separated) to identify if a feature is Abandoned.
• Skip_Feature: Configuration to identify features to skip while retrieving data.
• GUIDs: The list of GUIDs should be provided to extract the attribute information for the mentioned GUIDs.
• WKID: The WKID of the coordinate system in which the features has to be present in results.
• Source_Version: Establishes a connection with the underlying Geodatabase.
• Temp_Version: Creates a temporary version on top of the DEFAULT/parent version.
• WAM_Sync_Version: Connects to WAMSync version and performs a version difference between the Temp version and the WAMSync version.
• Response_XML: Output XML response
9. Provide the Summary, Tags, and Description (Optional parameters).
10. Click Analyze and then click Publish.
11. Click OK.
The service should be published in asynchronous mode. It is set by default while publishing the Geoprocessing service.
Important! If any error occurs while publishing the Geoprocessing service, modify the configuration ‘synchronous’. After the service is published, navigate to the service properties in ArcGIS server and change the configuration to ‘asynchronous’.
While publishing the Geoprocessing service, configure the service instances and client timeout configurations (using pooling option) based on the number of records that need to be in sync from GIS. The configurations can also be altered after the service is published in ArcGIS server.
To configure Geoprocessing service instances:
1. Login to ArcGIS Server Manager console.
https://xxxxxxxxxx:6443/arcgis/manager
2. Navigate to the Geoprocessing service directory where the Extractor program is deployed.
Example: GPServices > Extract DeltaChanges
3. From the service options, select Pooling.
4. Specify the minimum and maximum number of instances per machine along with maximum time a client can use a service.
The configurations are based on the number of records processed by the Geoprocessing service. On an estimate, a single Geoprocessing service instance can process 90000+ records at a time. However, the number of records are tentative and is dependent on multiple factors including the number of fields for which information is requested and memory consumed by the Geoprocessing service. The number of instances should be selected accordingly.
Also, configure the time in seconds (example: 36000) during the initial load based on the number of records to be synchronized and the maximum time a client can use the Geoprocessing service.
5. Restart the Geoprocessing service/ArcGIS server for the configurations to reflect.
Changes to ENVIRON.INI
This section focuses on the parameter configurations in the ENVIRON.INI file:
OWSM_PROTECTION_FOR_REST_SERVICES
This parameter should be configured only if Oracle Web Service Manager Protection has to be enabled for REST services.
The default parameter value is set to ‘true’ in the ENVIRON.INI file. Set it to ‘false’ if Oracle Web Service Manager is not configured. Also the WEBSERVICES_ENABLED parameter value should be set to ‘true’.
The ENVIRON.INI file is found in the etc folder of the environment (example: /scratch/<environment name>/etc).
Important! These parameters should be configured properly to launch the GIS Viewer.
CLOUD_RESTRICTION_URLS_ENABLE
Configure this parameter only if a set of server URLs should be accessed from the Oracle Utilities Work and Asset Management system.
The default parameter value for this parameter is set to ‘false’. If the parameter value is set to ‘true’, the GIS server URLs that are configured in ESRI Maps Master Configuration and ESRI WAM Integration Master Configuration objects should be mentioned in the whitelist xml file configured in the CLOUD_WHITE_LIST_PATH parameter.
Importing Certificates into ouaf truststore
This section includes the steps to be performed during the environment set up. It is required for outbound sync to work.
1. Download the ESRI server certificate where the services are published.
Example: https:// xxxxxxxxxxxxx/arcgis/rest/services/WAM/WorkLocations/FeatureServer/0
2. Click View Certificate.
3. Click Copy to File and then click Next.
4. Select 64 bit and click Next.
5. Save the certificate in .cer format and click Finish.
The export successful message is displayed.
6. Save the certificate.
7. Validate the certificate.
Open the certificate in Notepad++ or any other editor tool. If the data is in non-readable format, re-download the certificate.
8. Import the ESRI certificate into the certs folder of the environment.
9. Run the following commands to place the certificate into ouaf trust store:
keytool -import -alias <alias_name> -keystore <folder where environment is configured>\ks\.ouaf_truststore -file <environment>\certs\<cert file name> -storetype JCEKS -storepass <ouaf_truststore_pass>
Example:
keytool -import -alias mykeynew1 -keystore C:\spl\sharedapps\W1_V22060_DEV\ks\.ouaf_truststore -file C:\spl\sharedapps\W1_V22060_DEV\certs\slc07zjq.cer -storetype JCEKS -storepass <ouaf_truststore_pass>
10. Verify the import using the following command:
keytool -list -keystore <environment>\ks\.ouaf_truststore -storetype JCEKS -v -storepass <ouaf_truststore_pass>
11. Run the following commands to place the certificate into ouaf demo trust:
keytool -import -file <environment>\certs\<cert file name> -alias <alias name> -keystore <environment>\splapp\certs\ouaf_demo_trust.jks -storepass <ouaf demo trust password>
keytool -import -v -trustcacerts -alias <alias name> -file <environment>\W1_V22060_DEV\splapp\certs\<cert file name> -keystore <environment>\W1_V22060_DEV\splapp\certs\ouaf_demo_trust.jks -noprompt -storepass <ouaf demo trust password>
Example:
keytool -import -v -trustcacerts -alias mykeynew1 -file C:\spl\sharedapps\W1_V22060_DEV\splapp\certs\slc07zjq.cer -keystore C:\spl\sharedapps\W1_V22060_DEV\splapp\certs\ouaf_demo_trust.jks -noprompt -storepass <ouaf demo trust password>
12. Verify the import using the following command:
keytool -list -v -keystore <environment>\splapp\certs\ouaf_demo_trust.jks -storetype jks -storepass <ouaf demo trust password>