Setting Up ESRI Integration

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

• Set up transactions and transaction connectors.

• Set up relationships and transaction modifiers.

• 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 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 their 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, using this functionality, you can 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. PeopleSoft does not provided this documentation.

Understanding ESRI Integration

. Setting up ESRI integration is a two-step process. You will initially set up Integration Broker for geocode, map extent, and map integrations. Then you will set up the integration with ESRI for map and query definitions.

Note. PeopleSoft CRM integrates with ArcIMS 4.0. ArcIMS provides the foundation for distributing high-end geographic information systems (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 graphic illustrates the steps that you will follow to set up Integration Broker for the ESRI integration:

Integration Broker setup

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

ESRI integration setup

Understanding ESRI Processes

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

This section discusses the processes and defines the enterprise integration points (EIP) for each.

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 US addresses only.

Note. The Geocode Integration Flag on the Installation Options page must be turned on to enable geocode address functionality.

You have two options for obtaining geocode addresses:

• Synchronous, realtime connection with ESRI.

• Scheduled batch job that runs periodically.

You can obtain geocodes from ESRI in synchronous realtime. 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.

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 graphic 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 graphic 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, suppose that you need to access a city map, a state map, and a map of the United States. There is no restriction to the number of map services to which you can subscribe.

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. PeopleSoft transforms the XML to ArcXML and sends the map service information to ESRI. This graphic illustrates the outbound process flow for map service information.

Request map service information process flow

ESRI sends the map service information and PeopleSoft reads the incoming ArcXML. If the map service is found, PeopleSoft 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 graphic 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. PeopleSoft gets the map service name, the minimum and maximum extents for the map, and all address geocodes associated with cases or service orders. PeopleSoft sends the message in ArcXML. This graphic 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 PIA 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 the Transactions and Transaction Connectors

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 PeopleSoft Integration Broker PeopleBook. 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.

• Create transactions.

• Create transaction connectors.

See Also

PeopleSoft Integration Broker PeopleBook

Pages Used to Set Up the Connectors

Defining the ESRI Node

Access the ESRI Node Definitions page.

See Also

PeopleSoft Integration Broker PeopleBook

Creating Transactions

Access the Transactions and Messages pages.

In the default ESRI node that you defined, you need to create a total of six transactions:

• Three outbound synchronous transactions for the geocode, map extent, and map integrations,

• Three outbound synchronous transactions that contain the transformed outbound message and transformed inbound reply message for the geocode, map extent, and map integrations

To add the outbound synchronous transaction for geocodes:.

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select RBG_SYNC_ADDRESS_US_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. On the Transaction (Detail) page, select Implicit as the routing type.

6. Select the Messages tab.

7. Select RBG_SYNC_GEO_CODE_US as the response message name.

8. Select VERSION_1.

9. Click the Return to Transaction List link.

To add the outbound synchronous transaction to contain the transformed outbound and inbound reply message for geocodes:.

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select ESRI_ADDRESS_US_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. Select Implicit as the routing type on the Transaction (Detail) page.

6. Select Override Connector.

7. Verify the gateway ID is LOCAL and the connector is HTTPTARGET.

8. Select the Messages tab.

9. Select ESRI_GEO_CODE_US_MSG as the response message name.

   Select VERSION_1.

10. Click the Return to Transaction List link.

To add the outbound synchronous transaction for map extents:

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select RBG_MAP_EXT_REQ_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. Select Implicit as the routing type on the Transaction (Detail) page.

6. Select the Messages tab.

7. Select RBG_MAP_EXT_REPLY_MSG as the response message name.

   Select VERSION_1.

8. Click the Return to Transaction List link.

To add the outbound synchronous transaction to contain the transformed outbound and inbound reply message for map extents:.

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select ESRI_MAP_EXT_REQ_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. Select Implicit as the routing type on the Transaction (Detail) page.

6. Select to override connector.

7. Verify that the gateway ID is LOCAL and the connector is HTTPTARGET.

8. Select the Messages tab.

9. Select ESRI_MAP_EXT_REPLY_MSG as the response message name.

   Select VERSION_1.

10. Click the Return to Transaction List link.

To add the outbound synchronous transaction for map integration:.

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select RBG_MAP_REQ_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. Select Implicit as the routing type on the Transaction (Detail) page.

6. Select the Messages tab.

7. Select RBG_MAP_REPLY_MSG as the response message name.

   Select VERSION_1.

8. Click the Return to Transaction List link.

To add the outbound synchronous transaction to contain the transformed outbound and inbound reply message for map integration:.

1. Click the Add Transaction button on the Transactions page.

2. Select Outbound Synchronous as the transaction type on the Node Transactions page.

3. Select ESRI_MAP_REQ_MSG as the request message.

4. Select VERSION_1 as the request message version.

   Click Add.

5. On the Transaction (Detail) page, select Implicit as the routing type.

6. Select to override connector.

7. Verify that the gateway ID is LOCAL and the connector is HTTPTARGET.

8. Select the Messages tab.

9. Select ESRI_MAP_REPLY_MSG as the response message name.

   Select VERSION_1.

10. Click the Return to Transaction List link.

See Also

PeopleSoft Integration Broker PeopleBook

Creating Transaction Connectors

Access the Connectors page.

To define the transaction connector for map extent integration:

1. Click the Edit link beside the ESRI_MAP_EXT_REQ_MSG request message on the Transactions page.

2. Select the Connectors tab.

3. Enter this URL as the value for the PRIMARYURL property:

   http://<EsriServer>/servlet/com.esri.esrimap.Esrimap?ServiceName=<Service Name>

   Substitute the map service defined on ESRI for the <Service Name> parameter in this URL and the name of the server for <EsriServer>.

To define the transaction connector for map integration:

1. Click the Edit link beside the ESRI_MAP_REQ_MSG request message on the Transactions page.

2. Select the Connectors tab.

3. Enter this URL as the value for the PRIMARYURL property:

   http://<EsriServer>/servlet/com.esri.esrimap.Esrimap?ServiceName=<Service Name>

   Substitute the map service defined on ESRI for the <Service Name> parameter in this URL and the name of the server for <EsriServer>.

To define the transaction connector for geocode integration:

1. Click the Edit link beside the ESRI_ADDRESS_US_MSG request message on the Transactions page.

2. Select the Connectors tab.

3. Enter this URL as the value for the PRIMARYURL property: http://<EsriServer>/servlet/com.esri.esrimap.Esrimap?ServiceName=<Service Name>&CustomService=Geocode

   Substitute the map service defined on ESRI for the <Service Name> parameter in this URL and the name of the server for <EsriServer>.

See Also

PeopleSoft Integration Broker PeopleBook

Setting Up Relationships and Transaction Modifiers

To implement ESRI, you must also create a relationship called PSFT2ESRI that defines the source and destination node used for transformation. You must also create transaction modifiers to define the initial request message, the result request message, and the transformation request and response, which is an application engine program.

Pages Used to Set Up Relationships and Transaction Modifiers

Creating the Relationship

Access the Relationships page.

To create the PSFT2ESRI relationship:

1. Create a relationship definition with the relationship ID of PSFT2ESRI.

2. Enter a description.

3. Change the relationship status to Active.

4. Enter the default node in both the Node Name definition fields.

Creating Transaction Modifiers

Access the Transaction Modifiers page.

You will create transaction modifiers for the geocode, map extent, and map integrations.

To add the transaction modifier for geocode integration:

1. Click the Add Transaction Modifier button on the Transaction Modifiers page.

   The Relationship Transactions - Add a New Value page appears.

2. Create the transaction modifier for geocode integration using the data in this table:

1. Enter the sequence number 10 on the Relationships - Transaction Modifiers page.

2. Select OS as the transaction type in the Result section of the page.

3. Select RBG_ADDR_XSL as the request in the Transformations region of the page.

4. Select RBG_GEO_XSL as the response in the Transformations region of the page.

To add the transaction modifier for map extent integration:

1. Click the Add Transaction Modifier button on the Transaction Modifiers page.

   The Relationship Transactions - Add a New Value page appears.

2. Create the transaction modifier for geocode integration using the data in this chart:

1. On the Relationships - Transaction Modifiers page, enter the sequence number 20.

2. Select OS as the transaction type in the Result region of the page.

3. Select RBG_OEXT_XSL as the request in the Transformations region of the page.

4. Select RBG_IEXT_XSL as the response in the Transformations region of the page.

To add the transaction modifier for map integration:

1. Click the Add Transaction Modifier button on the Transaction Modifiers page.

   The Relationship Transactions - Add a New Value page appears.

2. Create the transaction modifier for map integration using the data in this table:

1. Enter the sequence number 30 on the Relationships - Transaction Modifiers page.

2. Select OS as the transaction type in the Results region of the page.

3. Select RBG_OMAP_XSL as the request in the Transformations region of the page.

4. Select RBG_IMAP_XSL as the response in the Transformations region of the page.

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.

Select the Geo Code Integration check box.

Selecting the Map Extent and Map Integration Flags

Access the Map Services page.

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.

To set up ESRI integration, define the ESRI map services to which you subscribe. You can define one or more map services to be used in PeopleSoft Customer Relationship Management (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 PeopleSoft 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.

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

Services

Setting Up Query Definition

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 delivers PeopleSoft CRM 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 are to appear in the case or service order-related information grid that appears under the map on the Map Dashboard. 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.

Pages Used to Access the Map Dashboard

Accessing the Map Dashboard

Access the Map Dashboard - Query page.

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 choose the fields to display on the search page.

Viewing the Map Dashboard

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

Page Used to View the Map Dashboard

Viewing the Map Dashboard

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.

Viewing Case-Related Information on the Map Dashboard

Access the Map Dashboard - Cases page.

The Cases grid displays details of the case-related information that appear 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.

The Service Orders grid displays details of the service order-related information that appear 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, an error log is created.

Page Used to View Geocode Errors

Viewing Geocode Errors

Access the Geocode Error Log page.

This page displays addresses that do not generate valid geocodes