Setting Up ESRI Integration

This chapter provides overviews of geographical information systems, Environmental Systems Research Institute (ESRI) integration, and ESRI processes and discusses how to:

• Set up Integration Broker for ESRI integration.

• Set up integration flags.

• Set up ESRI integration.

• Access the Map Dashboard.

• View the Map Dashboard.

• View geocode errors.

Understanding Geographical Information Systems

ESRI is a geographical information system (GIS) and mapping software solution. Using ESRI's mapping and GIS software, you can spatially enable the geographical data. The GIS can be an effective way to explain events, predict outcomes, or plan strategies.

The cornerstone of GIS is location information. Addresses are actually the most common form of location information. An address specifies a location in much the same way as a geographic coordinate does. But, addresses are merely text strings containing a house number, street name, direction, and postal code. The GIS needs a mechanism to calculate geographic location coordinates such as latitude and longitude before you can display them on a map.

Use address geocoding to display tabular data containing addresses as points on a map.

Use geocodes and ESRI mapping functionality to generate incident-related maps that are tailored to your business needs. For example, you can use this functionality to show:

• Incidents or cases of the same type on a map.

• All types of incidents in a given area.

Note. For information on installing the ESRI software, refer to the installation documentation that was provided by ESRI when you purchased the ESRI software.

Understanding ESRI Integration

Setting up ESRI integration is a two-step process:

1. Set up Integration Broker for address geocoding, map extent, and map integrations.

2. Set up the integration with ESRI for map and query definitions.

Note. PeopleSoft Customer Relationship Management (CRM) integrates with ArcIMS 4.0 and ArcIMS 9.0. ArcIMS provides the foundation for distributing high-end GIS and mapping services using the internet. ArcIMS software enables users to integrate local data sources with internet data sources for display, query, and analysis in an easy-to-use web browser.

This flowchart illustrates the steps that you follow to set up Integration Broker for the ESRI integration:

Integration Broker setup for the ESRI integration

This flowchart illustrates the steps you follow to set up the ESRI integration:

ESRI integration setup

Understanding ESRI Processes

Once ESRI is installed and you have set up the integrations, three processes occur on an ongoing basis: geocode retrieval, map service information updating, and map generation.

This section discusses:

• Geocode addresses

• Map service information

• Map generation

Geocode Addresses

PeopleSoft CRM stores geocodes for all consumer and company addresses, case addresses or locations, and service order addresses or locations. You can enter either an absolute address, which requires address and the postal code, or an intersection, which requires two cross streets and an optional postal code.

Geocoding is available for U.S. addresses only.

Note. The Geocode Integration check box on the Installation Options page must be selected to enable geocode address functionality.

You have two options for obtaining geocode addresses:

• Synchronous, real-time connection with ESRI.

• Scheduled batch job that runs periodically.

You can obtain geocodes from ESRI in synchronous real time. When you create or modify an address, the system calls ESRI to get the geocode. If the geocode is found, the system updates the address record with the geocode. If no geocode is found, the system logs an error.

This flowchart illustrates the request process for synchronous geocode addresses:

Request process flow for synchronous geocode addresses

Geocodes for addresses can be obtained by a scheduled job that runs periodically. When you first set up the system, use this method to retrieve geocodes for addresses. You can also run this process periodically to pick up any addresses that do not have geocodes. The address record is updated with geocodes obtained from the ESRI system. The system transforms the address or intersection information from XML to ArcXML and sends it to ESRI.

This flowchart illustrates the outbound process flow for obtaining geocode addresses using a batch process:

Request process flow for batch geocode addresses

ESRI publishes the geocode for the address or intersection. If no geocode is found, an error is logged. If a corresponding geocode is found, the PeopleSoft system transforms the incoming ArcXML sent by ESRI to XML. The address record is updated with the geocode.

This flowchart illustrates the inbound process flow for geocode retrieval:

Reply process flow for geocode addresses

The RBG_GEO_CODE_US channel is used for the PeopleSoft ESRI integration. This table lists the EIPs for geocode retrieval:

Map Service Information

Each map that is available in the system is called a map service. You can use one map or a number of different maps, depending on your business needs. For example, you can access a city map, a state map, and a map of the U.S. The number of map services to which you can subscribe is not restricted.

In addition to setting up the map services to which you have subscribed, ESRI defines the minimum and maximum extents to be used when zooming in and out on the Map Dashboard.

You create the map service record in the Map Definition component. The PeopleSoft system transforms the XML to ArcXML and sends the map service information to ESRI. This flowchart illustrates the outbound process flow for map service information:

Request map service information process flow

ESRI sends the map service information and the PeopleSoft system reads the incoming ArcXML. If the map service is found, the PeopleSoft system transforms the ArcXML to XML and updates the map service record with the minimum and maximum extents. The minimum and maximum X and Y coordinates appear on the Map Definition page. This flowchart illustrates the inbound process flow for updating the map service record:

Reply map service information process flow

The RBG_GEO_CODE_US channel is used for the PeopleSoft ESRI integration. This table lists the EIPs for map service information:

Map Generation

This integration is used to send a list of geocodes from either a case or service order search. A request XML is sent to the ESRI system to generate a map with geocodes that appear as dots. The PeopleSoft system gets the map service name, the minimum and maximum extents for the map, and all address geocodes associated with cases or service orders. It sends the message in ArcXML. This flowchart illustrates the outbound process flow for generating the map:

Request map generation process flow

The ESRI system responds with a URL to the image map based on the map service and geocodes. The map appears on the PeopleSoft page. This graphic illustrates the outbound process flow for generating the map:

Reply map generation process flow

The RBG_GEO_CODE_US channel is used for the PeopleSoft ESRI integration. This table lists the EIPs for map generation:

Setting Up Integration Broker for ESRI Integration

PeopleSoft CRM uses Integration Broker to send and receive messages for the ESRI integration. Before setting up the integrations for the geocode, map extent, and map integrations, read the Enterprise PeopleTools 8.50 PeopleBook: Integration Broker.

This section does not provide details on Integration Broker; instead, it provides directions for setting up the geocode, map extent, and map integrations.

This section discusses how to:

• Define the ESRI node.

• Define messages.

• Define routings.

• Define connectors.

• Define transformations.

• Define services.

• Define service operations.

• Review routing definitions for service operations.

See Also

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker

Pages Used to Set Up the ESRI Integration

Defining the ESRI Node

Access the Node Definitions page (PeopleTools, Integration Broker, Integration Setup, Nodes, Node Definitions).

Your ESRI node definition should look similar to the example shown here.

See Also

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker Administration

Defining Messages

Access the Message Definition page (PeopleTools, Integration Broker, Integration Setup, Messages, Message Definition).

Note. The system does not display the Service Operation References and Add Record to Root links on the Message Definition pages for ESRI messages. Also, the system does not display links to the message record and message fields on the Message Definition pages for ESRI messages.

These messages are used for the integration:

To re-configure these messages for your business operation, click the link under the Message Name field. The system displays the Message Definition page. Use the fields on the pages to make any necessary changes or add new information.

These messages are used to contain the transformed request or reply messages.

To re-configure these messages for your business operation, click the link under the Message Name field. The system displays the Message Definition page. Use the fields on the pages to make any necessary changes or add new information.

See Also

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker

Defining Routings

Access the Routing Definitions page (PeopleTools, Integration Broker, Integration Setup, Routings, Routing Definitions).

Before you access this page, enter Map in the Routing Name field and click Search. These routings appear as search results:

To re-configure these routings for your business operation, click the link under the Routing Name field. The system displays the Routing Definitions page. Use the fields on the pages to make any necessary changes or add new information.

Defining Connectors

Access the Connector Properties page (PeopleTools, Integration Broker, Integration Setup, Routings, Connector Properties).

Access the Connector Properties page for each of these routings:

To re-configure the connector properties for these routings, use the fields on the pages to make any necessary changes or add new information.

Defining Transformations

Access the Parameters page (PeopleTools, Integration Broker, Integration Setup, Routings, Parameters).

Access the Parameters page for each of these routings:

To re-configure the transformations for these routings, use the fields on the pages to make any necessary changes or add new information.

Defining Services

Access the Services page (PeopleTools, Integration Broker, Integration Setup, Services, Services).

These services are used for the integration:

To re-configure these services for your business operation, click the link under the Service field. The system displays the Service page. Use the fields on the pages to make any necessary changes or add new information.

Note. You must change the URL in the Namespace field so it coincides with your business for both the RBG and ESRI messages.

Defining Service Operations

Access the Find Service Operation page (PeopleTools, Integration Broker, Integration Setup, Service Operations, Find Service Operation).

Enter RBG in the Service field, and click Search. These services appear as search results:

Click the link under the Service Operation field and then click the Routings tab to view the routing definitions associated with the service operation.

Reviewing Routing Definitions for Service Operations

Access the Routings page (Click the Service Operation link on the Find Service Operation page. Then click Routings.).

Setting Up Integration Flags

Three integration flags must be selected for the ESRI integration to work effectively. To implement ESRI, select integration flags for the geocode, map extent, and map integrations.

This section discusses how to:

• Select the geocode integration flag.

• Select the map extent and map integration flags.

Pages Used to Set Up Integration Flags

Selecting the Geocode Integration Flag

Access the Installation Options - General Options page (Set Up CRM, Install, Installation Options, General Options, Installation Options).

Select the Geo Code Integration check box.

Note. After you save the page, you must clear the cache and reboot the application server.

Selecting the Map Extent and Map Integration Flags

Access the Map Services page (Set Up CRM, Common Definitions, Integration Rules, Map Services, Map Services).

Select the Enable Map Extent Integration and Enable Map Integration check boxes.

Setting Up ESRI Integration

To set up ESRI Integration, use the Map Setup (RBG_MAP_SETUP) component.

You must define the ESRI map services to which you subscribe. You can define one or more map services to be used in PeopleSoft CRM. The map services that you define appear as options on the case and service order components. On the Query Definition page, you define the components that support map-related queries.

This section discusses how to:

• Set up map services.

• Set up query definition.

Pages Used to Set Up ESRI Integration

Setting Up Map Services

Access the Map Services page (Set Up CRM, Common Definitions, Integration Rules, Map Services, Map Services).

Note. The previous section includes an example of the Map Services page.

Services

Setting Up Query Definition

Access the Query Definition page (Set Up CRM, Common Definitions, Integration Rules, Map Services, Query Definition).

Query Name	Enter a name for the query. The query name is selected on the Map Dashboard search page.
Component Interface Name	Enter the component interface that provides access to the component.
Component Name	Enter the name of the component on which you want to perform the query. PeopleSoft CRM is delivered set up to query on cases and service orders.
Base Record	Enter the name of the base record for the component.
Active Query	Select to enable the query definition.
Default Query	Select to use this query as the default.

Copy Fields

In the Copy Fields group box, define the fields that you want to appear in the case or service order-related information grid that appears under the map on the Map Dashboard page. For example, in a service order-related query, you may want to display the business unit, service order ID, consumer name, city, postal code, state, service order status, and service order priority. Each of these rows corresponds to a point shown on the map.

Accessing the Map Dashboard

Using the Map Dashboard search page, you can create customized searches to display the data. You can access the Map Dashboard search page from the agent view, navigation bar, Case page, or Service Order page.

This section discusses how to access the Map Dashboard.

Pages Used to Access the Map Dashboard

Accessing the Map Dashboard

Access the Map Dashboard - Query page (from the left navigation, click the Map Dashboard link on the menu).

Note. Users must specify a business unit, setID, and market on the Overall Preferences page under Set Up CRM, Security, User Preferences in order to access the map dashboard.

Viewing the Map Dashboard

The Map Dashboard presents a graphical and tabular representation of the search results.

This section discusses how to:

• View the Map Dashboard.

• View case-related information on the Map Dashboard.

• View service order-related information on the Map Dashboard.

Pages Used to View the Map Dashboard

Viewing the Map Dashboard

Access the Map Dashboard - Map page (on the Case page, click the Map Dashboard button on the toolbar).

Use the directional arrows and zoom in and zoom out buttons to navigate to the areas on the map that you want to view.

Viewing Case-Related Information on the Map Dashboard

Access the Map Dashboard - Cases page (from the left navigation, click Map Dashboard, then select Case in the Search field of the Query section of the page to search for Cases).

The Cases grid displays details of the case-related information that appears on the map. Click the Case ID link to navigate to the case details.

Viewing Service Order-Related Information on the Map Dashboard

Access the Map Dashboard - Service Orders page (from the left navigation, click Map Dashboard, then select Service Order in the Search field of the Query section of the page to search for Service Orders).

The Service Orders grid displays details of the service order-related information that appears on the map. Click the Service Order ID link to navigate to the service order details.

Viewing Geocode Errors

If the ESRI system cannot return a valid geocode for the address that is published, the system create an error log.

This section discusses how to view geocode errors.

Page Used to View Geocode Errors

Viewing Geocode Errors

Access the Geocode Error Log page (Customers CRM, Geocode Error Log, Geocode Error Log).

This page displays addresses that do not generate valid geocodes.