Appendix: Integrating Oracle's Enterprise Manager with PeopleSoft CRM HelpDesk

Oracle’s Enterprise Management (EM) system is now integrated with PeopleSoft CRM to let help desk cases be automatically generated from alerts initiated from the EM system. This integration requires certain files to be deployed and configured on the EM system, as well as certain PeopleSoft CRM settings as described in this appendix.

This appendix addresses the following topics:

• Understanding Oracle’s EM System Integration with PeopleSoft CRM.

• Setting up Options in PeopleSoft CRM.

• Deploying and Configuring the PeopleSoft Connector to the EM Console.

Understanding Oracle’s EM System Integration with PeopleSoft CRM

This section discusses:

• How it works.

• Integration flow process.

• Connector descriptor.

• Trouble ticket template.

• Sample case created from EM.

How it works

Enterprise Manager (EM) is Oracle’s integrated solution for administering and monitoring software and systems. It provides Application Performance Management, distributed database and application server administration, and automated tuning of Oracle environments.

Oracle’s EM utilizes a notification system that enables users to set up event rules which generate notifications (for example you may want the system to issue an alert when disk space is 99% full). When such an event occurs, the system can create a case within Oracle’s PeopleSoft HelpDesk application, which can assign a worker to take action to resolve the case.

Through the notification system, PeopleSoft Case Connector (trouble ticketing system connector) integrates with Oracle’s Enterprise Manager. When the system triggers a rule, the connector is notified and a case is created or updated based on a trouble ticket template. The system then sends a response message with the case ID (ticket ID) back to Enterprise Manager.

Once the case is created, a help desk user can drill into the details on the EM Alert page from the case. In addition, an EM user can drill back to the case from the EM Detail page.

Integration flow process

This illustration shows the integration between PeopleSoft’s CRM HelpDesk application and Oracle’s EM system. When a defined rule in EM is triggered, the connector is notified to create or update a case. The case ID is then sent back to the EM system.

Integration Flow

Connector Descriptor

The connector descriptor describes how the EM system communicates with the CRM case trouble ticketing system. The connector descriptor is an XML based file that defines the PeopleSoft web service end point for service operations and the authentication schema. It also cross-references a URL to link an alert back to a case. Once the connector is deployed, the user can configure it on the connector console.

Authentication is completed while mapping data from web services security (WS-security or wsse) on the case to the TicketingConnector authentication. TicketingService methods, such as createTicket or updateTicket, are used in EM to create or update a ticket

The BaseURL in the connector descriptor is the base URL for the EM console. The ExternalURL is the URL pointing to CRM case.

Note. WS-Security is a building block that is used in conjunction with other web services and application-specific protocols to accommodate a wide variety of security models and encryption technologies. WS-Security describes enhancements to SOAP (Simple Object Access Protocol) messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms are used to accommodate a wide variety of security models and encryption technologies. For this release, EM supports UserNameToken security on SOAP headers.

Trouble Ticket Template

The Trouble Ticket template is an XSLT file that transforms a message from the EM model format to the CRM model format. It is based on the XML schemas of the EM Alert and the Trouble Ticketing system.

The templates are used to construct tickets in the context of an EM alert. When a PeopleSoft Connector is notified, the EM alert information is transformed into a trouble-ticketing message that is used to create or update a case in the trouble ticketing system.

PeopleSoft delivers several default trouble ticket templates. You can easily modify them to fit your needs. The delivered XSL files include

• PSFTSampleTicketTemplate.xsl; default ticket template used to create or update a case.

• PSFTSampleTicketTemplate_AutoClose.xsl: used to create a new case if none already existed, or to add a note and auto close an existing case after it has been updated.

• createTicketResponse.xsl: used to transform the response from CRM to EM when the CreateCase or UpdateCase method is invoked. It returns the Case ID from CRM help desk as a Ticket ID to EM.

The system will create a new case or update an existing case depending on whether the ticket ID is provided in the EM alert message. If no case ID is provided from EM, the system creates a new case; otherwise, the system updates the case with the given case ID.

When creating a new case, the system adds an anonymous help desk case. The delivered default template specifies that the case will be created using the IT Help Desk business unit (ITHDK), but this can easily be modified in the template to use any desired business unit.

The system stores the EM alert summary information in the Case Summary field, and adds other information such as target type, metric, and key information in the Case Description field. Based on the business unit setup, the system can also auto-trigger the assignment engine in PeopleSoft CRM upon saving the case so that the case is assigned to the appropriate provider group and agent.

When updating an existing case, the system updates the severity on the HelpDesk case and adds the new EM information into a case note.

The following table lists the HelpDesk case fields which are given values in the delivered sample template when creating a new case.

Note. It is important to remember that these are sample templates provided only as examples, and that you may need to modify them to fit your requirements. Specifically, please note that some values specified here refer to sample data, not system data, and therefore are values that you would need to add to or modify in your production system.

When updating a case, the delivered sample template creates a note for the case using the following field values from the EM system:

• EMUser

• ConnectorId

• Target Type

• MetricColumn

• MetricName

• KeyColumn

• KeyValues

• Severity

• CollectionTime

• EventPageURL

In the delivered sample template, we also provide entries marked as comments, which list many fields without an assigned value. This lets you know which fields are available for use when creating or updating a case. You can simply un-comment the lines for the fields that you want to use and enter the appropriate values.

View the Case web service definition for more technical information on the available Case fields. You can view the elements and fields that are included in each Case operation message through PeopleTools. Cases are created using the CreateCase service operation, and are updated using the UpdateCase service operation under the web service RC_CASE. Note that these service operations need to be activated as part of the integration setup.

To view a list of field names and aliases for a particular service operation:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operation.

2. Enter RC_CASE in the Service Operation field and click Search.

   The system lists all the service operations that are related to Case.

3. Select the service operation you want to view.

4. Click the View Message link in the Message Information area of the page for each message which you want to view .

   The system opens the Message Definition page in a new browser.

5. Click the Message Name link under the Parts grid of the Message Definition page.

6. Click the plus sign next to the table name at the bottom of the page to view the fields and aliases associated with the message.

Sample Case Created from EM

This is an example of case created from EM:

Note that certain values shown in this example (including those for department, location, status, and priority) are derived directly from CRM defaults or configuration rather than from the template or EM data.

Note. When updating cases, the system doesn’t override the Case Summary and Description fields. The EM alert summary and other additional information is added, however, as a note for the case.

Setting up Options in PeopleSoft CRM

This section discusses the following changes made within the PeopleSoft CRM system to enable the integration with Enterprise Manager:

• New source code.

• New severity codes.

• New Enterprise Manager link definition.

• New Enterprise Manager Active Analytics Framework (AAF) action type.

• New policy to create an Enterprise Manager related action.

• Related action changes on the Case page.

Note. Please refer to the appropriate sections in PeopleBooks for additional information on using the Source page, Severity page, Case page, AAF, related actions, link definitions, and web services.

See Setting Up Call Center Prompt Tables.

See Setting Up Links and Related Actions.

See Processing Cases.

See Delivered Web Service and Service Operations.

See Working with Active Analytics Framework.

As you read the rest of this section keep in mind the following action items that must be completed in order to set up the integration:

• Create a new source code EM.

• Create new severity codes 15, 20, and 25.

• Activate Create Enterprise Manager Related Action policy.

Also note that to enable the integration you must activate the Case web services operations under the RC_CASE web service.

See Delivered Web Service and Service Operations.

See PeopleTools 8.52: PeopleSoft Integration Broker PeopleBook

See PeopleTools 8.52: PeopleSoft Integration Broker Administration PeopleBook

Note. In addition to these setup items within the PeopleSoft CRM system, remember that you must also deploy and configure the PeopleSoft connector, as described in a later section in this document.

New Source for Enterprise Manager

PeopleSoft sample data includes a new row in the Source table (PS_RC_SOURCE_TBL) for the IT Help Desk (ITHD1) setID to identify Enterprise Manager as a source for creating cases. The data contained in the Source field is EM, and the data contained in the Short Name and Long Description fields is Enterprise Mgr and Enterprise Manager, respectively.

Oracle delivers this information as sample data. You must add corresponding entries for any desired setID’s in your production system

Access the Source page (Set Up CRM, Product Related, Call Center, Source.)

Add an entry in the desired setID for the new source code EM. Note that this code must match the value for Source field on the trouble ticket template.

New Severity Codes for Enterprise Manager

Oracle’s PeopleSoft CRM application provides these severity codes as sample data for the IT HelpDesk (ITHD1) setID. Although EM uses many more severity codes, only these codes are used for integration purposes:

• 25 - Critical

• 20 - Warning

• 15 - Clear

Oracle delivers this information as sample data. You must add corresponding entries for any desired setID’s in your production system.

Access the Severity page (Set Up CRM, Product Related, Call Center, Severity.)

Add entries in the desired setID for the three new severity codes (15 = Clear, 20 = Warning, and 25 = Critical).

New Enterprise Manager Link Definition

Oracle’s PeopleSoft CRM application includes a new link definition called Enterprise Manager under the Link Category RELA. This link definition is set up as Solvable. It will not be part of any link group; therefore, a user will not be able to perform this related action manually. It is a hidden option that can only be performed automatically by the system.

Access the Link Definition page (Set Up CRM, Product Related, Call Center, Link Definition).

New Enterprise Manager AAF Action Type

To create a related action for the Enterprise Manager link definition on the Case page, Oracle’s PeopleSoft CRM application delivers the new action type Case Enterprise Manager.

This action type can only be triggered from a component interface. You cannot trigger it from PeopleSoft pages. The Case Enterprise Manager action type will not have any design time configuration. It is delivered as system data.

Access the Action Type page (Enterprise Components, Active Analytics Framework, Action Framework, Register Action Type).

This action type is associated with the After a Helpdesk Case is Saved trigger point.

New Policy to Create an Enterprise Manager Related Action

Oracle’s PeopleSoft CRM application includes a new policy called Create Enterprise Manager Related Action for the SHARE setID. This policy is associated with the After a HelpDesk Case is Saved trigger point. It is delivered with a status of In Design. You must update the status to Active if you wish to enable it for the EM integration.

The policy condition uses Enterprise Manager as its source. The policy action uses the Enterprise Manager AAF Action described earlier in this documentation.

Access the Build a Policy page (Enterprise Components, Active Analytics Framework, Policies, Manage Policies).

If you use a setID other than SHARE, copy this policy using the desired setID. Remember to activate the policy as part of the setup for the integration.

Related Action Changes on the Case page

The system creates a related action on the case page when a new case is created from Enterprise Manager. The related action summary contains a link that enables the user to transfer to the EM Console.

When a case is updated from Enterprise Manager, the system adds a new note to the case, but does not create a related action.

Access the Related Actions page (Support, Search Cases, Related Actions).

To go to the EM Console Metrics Detail page, click the link under the Summary field in the Related Action Summary section.

Deploying and Configuring the PeopleSoft Connector to the EM Console

To enable the integration, several files need to be copied to the EM Server, and the Peoplesoft connector must be deployed, registered, and configured. This section discusses:

• Copying the JAR file.

• Deploying and registering the connector.

• Configuring the connector.

Copying the JAR File

PeopleSoft delivers a JAR file (PSFTConnector.jar) that includes the EM Event Model XML, the Peoplesoft Connector Descriptor XML, and the sample template XSLT files mentioned in this documentation for the Peoplesoft connector. Copy the JAR file to EM server oracle home.

Deploying and Registering the Connector

Several Enterprise Manager Command-Line Utility (emctl) commands are used to deploy and register the connector.

Note that the deploying command line shown in this section is applicable for EM 10gR3 and 10gR4. If you are using different version of EM, the command line may be a little different.

To extract the JAR file into $ORACLE_HOME/sysman/connector/<connector_name_wo_space> directory run this command

emctl extract_jar connector <jar_file_name> <connector name> <oracle home>

Note. The connector name is the name specified in the connector descriptor XML file. The command replaces the spaces in the connector name with underscores (_) in connector_name_wo_space. For instance, a connector called Peoplesoft Connector will have a directory of Peoplesoft_Connector under the directory of the Oracle home connector. If the Peoplesoft_Connector directory already exists, the extract_jar command will extract files to this directory; otherwise, it will create a new directory called Peoplesoft_Connector and copy files to it.

Register the connector using this command (use the user name sysman):

emctl register_connector connector  <PSFTConnectorDescriptor.xml> ​
<serverName>⇒
 <port> <databaseSid> <username> <password> <oracle home>

Oracle delivers two templates: The PeopleSoft Sample Template is used to create or update a case. The PeopleSoft Auto-Close Template automatically closes out an open case with a solvable EM action.

Register the shipped ticket templates using this command:

emctl register_ticket_template connector <PSFTSampleTicketTemplate.xsl> ​
<server⇒
Name> <port> <databaseSid> <username> <password> ​
<connectorTypeName> <connector⇒
Name> <templateName> <templateDescription>

The <connectorTypeName> and <connectorName> use the same value: Peoplesoft Connector. The <templateName> and <templateDescription> are quoted strings, which can have spaces in them. The template name and description are displayed on the EM console.

Note. Because the EM connector can only support one active connector, make sure to delete the connector from the console first. After you re-deploy a connector, you need to re-register the templates again even if they have not changed, as the templates are disconnected at the time the connector is deleted.

Configuring the Connector

Once the connector is successfully deployed, you can log in to the EM console to configure the connector. On the configuration page, you can set up:

• WS end points: Specify WebService End Points for createTicket, updateTicket and getTicket web service operations.

• WS credentials: User ID and password to log in to the PeopleSoft CRM system for adding or updating a case.

• Web console settings: A URL that can transfer to the CRM case from the EM system. This is used on the EM metric detail page to drill into the case.

• Grace period: A time value that is compared against the data when an alert is cleared to the time when it has transitioned out of clear. If this span of time is greater than the grace period, a new ticket is created for the alert, otherwise, the ticket is reopened. The idea is not to create the case for the same alert within a defined time period.

Select Peoplesoft Connector from the Oracle Enterprise Manager page and then click the Configure button to access the following page. Use the Configure Management Connector page to enter URLs for the WebService End Points. You can also add a user name and password and enter web console settings (machine and port and database name).

The Ticket Template page lists all registered templates for the connector.

Set up your desired rules to use the registered template to create a case in the HelpDesk system.

Once a case is created or updated, the user can drill into case from the EM Metric Detail page

Please refer to Enterprise Manager documentation for additional information on using the EM Console and the Alert History page.