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.
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.
Setting up ESRI integration is a two-step process:
Set up Integration Broker for address geocoding, map extent, and map integrations.
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
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
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:
EIP Name |
Description |
Message Name |
Direction of Integration |
Technology |
Address information |
RBG_SYNC_ADDRESS_US_MSG |
CRM —> ESRI |
Integration Broker |
|
Geocode for the requested address |
RBG_SYNC_GEO_CODE_US_MSG |
ESRI —> CRM |
Integration Broker |
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:
EIP Name |
Description |
Message Name |
Direction of Integration |
Technology |
Service map information to obtain map coordinates from ESRI |
RBG_MAP_EXT_REQ_MSG |
CRM —> ESRI |
Integration Broker |
|
Minimum/Maximum X/Y coordinates of the service map |
RBG_MAP_EXT_REPLY_MSG |
ESRI —> CRM |
Integration Broker |
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:
EIP Name |
Description |
Message Name |
Direction of Integration |
Technology |
Service map information and list of geocodes to be displayed on the map |
RBG_MAP_REQ_MSG |
CRM —> ESRI |
Integration Broker |
|
URL to the generated image map |
RBG_MAP_REPLY_MSG |
ESRI —> CRM |
Integration Broker |
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 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 PeopleBook: Integration Broker
Page Name |
Object Name |
Navigation |
Usage |
PeopleTools, Integration Broker, Integration Setup, Nodes, Node Definitions |
Define the ESRI node. |
||
PeopleTools, Integration Broker, Integration Setup, Messages, Message Definition |
Define messages for address geocoding, map extents, and maps. |
||
PeopleTools, Integration Broker, Integration Setup, Routings, Routing Definitions |
Define routings for address geocoding, map extents, and maps. |
||
PeopleTools, Integration Broker, Integration Setup, Routings, Connector Properties |
Define node connectors for address geocoding, map extents, and maps. |
||
PeopleTools, Integration Broker, Integration Setup, Routings, Parameters |
Define node transformations for address geocoding, map extents, and maps. |
||
PeopleTools, Integration Broker, Integration Setup, Services, Services |
Define services for address geocoding, map extents, and maps. |
||
PeopleTools, Integration Broker, Integration Setup, Service Operations, Find Service Operation |
Find service operations for address geocoding, map extents, and maps. |
||
Click the Service Operation link on the Find Service Operation page. Then click Routings. |
Review the routing definitions of the service operation. This includes name, version, routing type, sender node, receiver, node, direction, and status |
Access the Node Definitions page.
Your ESRI node definition should look similar to the example shown here.
See Also
Enterprise PeopleTools PeopleBook: Integration Broker
Access the Message Definition page.
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:
Message Name |
Description |
RBG_MAP_EXT_REPLY_MSG |
Reply message from ESRI with map extents. |
RBG_MAP_EXT_REQ_MSG |
Request message from PSFT for map extents. |
RBG_MAP_REPLY_MSG |
Reply message for ESRI with the map. |
RBG_MAP_REQ_MSG |
Request message from PSFT for map. |
RBG_SYNC_ADDRESS_US_MSG |
Request message from PSFT to get the geocode of an address or intersection. |
RBG_SYNC_GEO_CODE_US_MSG |
Reply message from ESRI with the geocode of an address or intersection. |
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.
Message Name |
Description |
ESRI_ADDRESS_US_MSG |
Transformed request message to get the geocode of an address or intersection. |
ESRI_GEO_CODE_US_MSG |
Transformed reply message with geocode of an address or intersection. |
ESRI_MAP_EXT_REPLY_MSG |
Transformed reply message from ESRI with map extents. |
ESRI_MAP_EXT_REQ_MSG |
Transformed request message for map extents. |
ESRI_MAP_REPLY_MSG |
Transformed reply message from ESRI with the map. |
ESRI_MAP_REQ_MSG |
Transformed request message for map. |
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 PeopleBook: Integration Broker
Access the Routing Definitions page.
Before you access this page, enter Map in the Routing Name field and click Search. These routings appear as search results:
Routing Name |
Description |
MAP_EXTENTS_ROUTING |
Routing for Service Map Extents. |
MAP_GEOCODE_ROUTING |
Routing for geocoding an address or intersection |
MAP_ROUTING |
Routing for getting a Map. |
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.
Access the Connector Properties page.
Access the Connector Properties page for each of these routings:
Routing Name |
Description |
MAP_EXTENTS_ROUTING |
Routing for ESRI extents. |
MAP_GEOCODE_ROUTING |
Geocode routing for map. |
MAP_ROUTING |
ESRI routing for map. |
To re-configure the connector properties for these routings, use the fields on the pages to make any necessary changes or add new information.
PRIMARYURL |
Use the examples below to enter a URL in the PRIMARYURL field:
Note. You must substitute your map service for the ServiceName parameter and the name of your server for <ESRI-SERVER NAME>. |
Access the Parameters page.
Access the Parameters page for each of these routings:
Routing Name |
Description |
Outbound Request Transform Program 1 |
Inbound Request Transform Program 1 |
MAP_EXTENTS_ROUTING |
Routing for Map extents. |
RBG_OEXT_XSL |
RBG_IEXT_XSL |
MAP_GEOCODE_ROUTING |
Routing for Address geocoding |
RBG_ADDR_XSL |
RBG_GEO_XSL |
MAP_ROUTING |
Routing for Map |
RBG_OMAP_XSL |
RBG_IMAP_XSL |
To re-configure the transformations for these routings, use the fields on the pages to make any necessary changes or add new information.
Access the Services page.
These services are used for the integration:
Service |
Description |
RBG_MAP_EXT_REQ_MSG |
Service to get the extents of a Map Service. |
RBG_MAP_REQ_MSG |
Service to get a Map. |
RBG_SYNC_ADDRESS_US_MSG |
Service to get the geocode of an address or intersection. |
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.
Access the Find Service Operation page.
Enter RBG in the Service field, and click Search. These services appear as search results:
Service |
Service Operation |
Operation Type |
RBG_MAP_EXT_REQ_MSG |
RBG_MAP_EXT_REQ_MSG |
Synchronous |
RBG_MAP_REQ_MSG |
RBG_MAP_REQ_MSG |
Synchronous |
RBG_SYNC_ADDRESS_US_MSG |
RBG_SYNC_ADDRESS_US_MSG |
Synchronous |
Click the link under the Service Operation field and then click the Routings tab to view the routing definitions associated with the service operation.
Access the Routings page.
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.
Page Name |
Object Name |
Navigation |
Usage |
Set Up CRM, Install, Installation Options, General Options, Installation Options |
Select the flag for geocode integration. |
||
Set Up CRM, Common Definitions, Integration Rules, Map Services, Map Services |
Select the flags for map extent and map integration. |
Access the Installation Options - General Options page.
Select the Geo Code Integration check box.
Note. After you save the page, you must clear the cache and reboot the application server.
Access the Map Services page.
Select the Enable Map Extent Integration and Enable Map Integration check boxes.
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.
Page Name |
Object Name |
Navigation |
Usage |
Set Up CRM, Common Definitions, Integration Rules, Map Services, Map Services |
Define the GIS vendor and the map services that you are using. |
||
Set Up CRM, Common Definitions, Integration Rules, Map Services, Query Definition |
Define the components used for map-related queries. As delivered, map-related queries are enabled for case and service order. |
Access the Map Services page.
Note. The previous section includes an example of the Map Services page.
Market |
Displays market defaults from the search page. |
GIS Vendor Name (geographical information system vendor name) |
Enter the name of the GIS vendor. |
Description |
Enter a description of the service defined on this page. |
Enable Map Extent Integration |
Select to enable map extent integration. Map extent information determines the boundaries for zooms and pans. You must select this check box to enable the Get Map Service Extents button in the Services group box. |
Enable Map Integration |
Select to enable the publishing of maps to the PeopleSoft CRM system. |
Services
Map Service |
Enter each map service that is to be used. The user can select the appropriate map service from the Map Dashboard search. Map services are set up on the ESRI site. |
Description |
Enter a description of the map service. |
Request Message |
Enter the message to be sent to ESRI to request the service. |
Active Map Service |
Select to make the map service active. |
Default Map Service |
Select to use the map service as the default. |
Get Map Service Extents |
Click to get the extents for the map service that you are defining. This sends a request to ESRI for the map service extent data and populates the map extent information on the page. The Get Map Service Extents button only works if you have selected Enable Map Extent Integration. |
Map Minimum X (minimum X coordinate), Map Maximum X (maximum X coordinate), Map Minimum Y (minimum Y coordinate), and Map Maximum Y (maximum Y coordinate) |
After you request the map service extents, the system populates the minimums and maximums for the X and Y coordinates. This data establishes the boundaries for zooms and pans. Latitude and longitude appears in degrees. |
Access the Query Definition page.
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.
From Record |
Select the record name from which to retrieve the data. |
From Field |
Select the field name from which to retrieve the data. |
To Record |
Select the record name in the destination table. |
To Field |
Select the field name in the destination table. |
Active |
Select to enable the copying of the specified fields. |
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.
Page Name |
Object Name |
Navigation |
Usage |
From the left navigation, click the Map Dashboard link on the menu. |
Define the criteria for the search. You can search on one or more fields to define the results. |
||
|
Click the button on the Case page or the link on the Service Order page to go directly to the Map Dashboard. The system carries forward all of the values that you defined in the Query Definition setup. |
Access the Map Dashboard - Query page.
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.
Search |
Select Case or Service Order. |
Map Service |
The map service appears by default to the map that you defined on the Map Definition page. You can select from a list of available map services. The map services are configured on the ESRI site. |
Use Saved Search |
Select a saved search from the list. |
Map It |
Click the Map It button to submit the search and generate the map. |
Save Search Criteria |
Click the link to save the search criteria. |
Personalize Search |
Click the link to display a list of search fields. You can select the fields that will appear on the search page. |
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.
Page Name |
Object Name |
Navigation |
Usage |
Click Map It on the Map Dashboard - Query page. |
Use this page to view the map and tabular data generated by the search. |
Access the Map Dashboard - Map page.
Use the directional arrows and zoom in and zoom out buttons to navigate to the areas on the map that you want to view.
Access the Map Dashboard - Cases page.
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.
Access the Map Dashboard - Service Orders page.
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.
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 Name |
Object Name |
Navigation |
Usage |
Customers CRM, Geocode Error Log, Geocode Error Log |
View addresses that do not generate valid geocodes. |
Access the Geocode Error Log page.
This page displays addresses that do not generate valid geocodes.