2 Creating and Configuring the Connector

This chapter provides the following information for setting up and configuring the Remedy Service Desk Connector and related tasks:

• Prerequisites

• Creating a Connector Instance

• Configuring the Connector

• Enabling or Disabling the Connector

• Providing General Settings

• Working with Ticket Templates

• Deleting the Connector

Prerequisites

The Remedy Service Desk Connector communicates through webservices with the IT Service Management component of Remedy Service Desk. Before using Remedy Service Desk Connector, ensure that you meet the following prerequisites:

• One of the following:

  • Remedy Service Desk 7.0.03 patch 008 with:

    • IT Service Management 7.0.03 with the Incident Management patch “IT Service Management Patch 008” is installed and configured.

    • Action Request Server 7.1 (AR Server 7.1) Patch 002.

  • Remedy Service Desk, which is part of IT Service Management Suite 7.5.00 with Incident Management, is installed and configured. This also includes Action Request Server 7.5 (AR Server 7.5).

• Remedy Service Desk web services are up and running.

• Remedy User exists with all necessary permissions and personnel information.

Installing the Definition Files

The Remedy Action Request Server (ARS) customizations for Enterprise Manager 12c definition files can be extracted from the following .jar file:

<$OMS_HOME>/sysman/connector/remedy7connector.jar

OMS_HOME is the file system location where the OMS is deployed.

These customization files assume a fresh installation of Remedy ARS. When integrating with a production instance of Remedy, exercise care that these customizations are compatible with any previous customizations that have been made to the Remedy instance.

The definition files to import are:

• HPD_IncidentInterface_CustomWS.def

• HelpDesk_Query_Service_getIncident.def

Install both definition files (.def) files in the running Remedy environment by completing the steps in the following sections for AR Server 7.1 and AR Server 7.5:

• Import Steps for AR Server 7.1

• Import Steps for AR Server 7.5

Import Steps for AR Server 7.1

1. Log in to the Remedy Administrator tool.

2. Select the Remedy instance from the hierarchy on the left.

3. Click the Tools menu, select Import Definitions, then From Definition File...

4. Select the definition file to import from the list above.

5. Check the box labeled Replace Objects on the Destination Server.

6. Choose the drop-down option Replace With New Type.

7. Click Import.

   You should not encounter any errors during this process. At the end of the import, an Import Complete message should appear.

8. When done, repeat the procedure for the rest of the customization files.

Import Steps for AR Server 7.5

Note:

Back up the HPD_IncidentInterface_WS Web Service before importing HPD_IncidentInterface_CustomWS.def.

1. Log in to the BMC Remedy Developer Studio, then open a workspace.

2. Select the Remedy instance from the left pane.

3. From the File menu, select Import.

4. Select Object Definition in the Import window, then click Next.

5. Select the AR System Server Instance, then click Next.

6. Click Browse and select the definition file (for example, HPD_IncidentInterface_CustomWS.def), then click Next.

7. Click Finish in the Import Objects window.

   You should not encounter any errors during this process. At the end of the import, an Import Complete message should appear.

Displaying the New Objects

After importing, the new objects are shown under the Remedy instance. You can access them as follows:

1. Select the Remedy Instance from the left pane of the Developer studio.

2. Select All Objects, then Web Services.

   You should be able to see a new Web service called HPD_IncidentInterface_get_WS.

3. Select All Objects, then Web Services, then HPD_IncidentInterface_WS.

4. Click WSDL Ports, then Ports, then WSDL Operations.

   You should see 'HelpDesk_Modify_status_service' and 'HelpDesk_Modify_Service' under WSDL Operations.

HelpDesk_Modify_status_service and HelpDesk_Modify_Service WSDL Operations should appear under HPD_IncidentInterface_WS.

Forms Customization

Customizing the HPD:IncidentInterface_Create, HPD:IncidentInterface, and HPD:HelpDesk forms are needed to add the ConnectorGUID field on these forms. The purpose of this field is to track a ticket/incident created by Oracle Enterprise Manager 12c.

Forms Customization for AR Server 7.1

1. Log in to the Remedy Administrator tool.

2. Select Forms.

3. Open the HPD:HelpDesk form.

4. Create a Character field and place the field as required.

   Note:

   In the HPD:HelpDesk form, you can place the new field next to Create Request radio button.

5. Open the Field Properties dialog box for the character field that you create.

6. Click the Display tab. Enter ConnectorGUID on the Label Field.

7. Click the Database Tab. In the ID field enter 500000021. In Name Field, enter ConnectorGUID.

8. Click the Permissions tab and then assign Public Permission.

   Note:

   You can also enable the Allow Any User to Submit check box.

9. Close the Field Properties page.

10. Save the form.

Repeat steps 3 to 10 for the HPD:IncidentInterface_Create and HPD:IncidentInterface forms in order to add the ConnectorGUID field for all forms.

Update the HPD:HII:CreateIncident_100'! filter as follows so that it pushes values from the HPD:IncidentInerface_Create form to the HPD:HelpDesk form:

1. Log in to the BMC Remedy Administrator.

2. Click Filters.

3. Open the HPD:HII:CreateIncident_100`! filter.

4. Click the If-Action(1) tab.

5. In the Fields region:

   • From the Name menu, select ConnectorGUID.

   • From the Value menu, select ConnectorGUID.

6. Save the filter and close.

Forms Customization for AR Server 7.5

1. Log in to the BMC Remedy Developer Studio, then open a workspace.

2. Select the Remedy instance from the pane that appears in the left side of the window.

3. Select All Objects, then Forms.

4. Open the HPD:HelpDesk form.

5. Right-click and create a New Character field.

6. In the Field Properties window under Display property, provide ConnectorGUID as the Label.

7. Click the Permissions tab, then assign Public Permission.

   Note:

   You can also enable the Allow Any User to Submit check box.

8. Save the form.

Repeat steps 4 through 8 for HPD:IncidentInterface_Create to add the ConnectorGUID field.

Add a new field in the HPD:IncidentInterface form as follows:

1. Open the HPD:IncidentInterface form.

2. Do not create a new field. Instead, right-click on the form.

3. Select Add Fields from HPD:HelpDesk.

4. Select ConnectorGUID from the list.

5. Save the form.

Update the HPD:HII:CreateIncident_100'! filter as follows so that it pushes values from the HPD:IncidentInerface_Create form to the HPD:HelpDesk form:

1. Log in to the BMC Remedy Developer Studio, then open a workspace.

2. Select the Remedy instance from the left pane.

3. Select All Objects, then Filters.

4. Click the If-Action(1) tab.

5. In the Fields region:

   1. From the Name menu, select ConnectorGUID.

   2. From the Value menu, select ConnectorGUID.

6. Save the filter and close.

Web Services Customization

The following sections explain how to include the ConnectorGUID field in the Web services. This section assumes that the *.def files are imported/installed as mentioned in previous sections.

Web Services Customization For AR Server 7.1

1. Log in to the Remedy Administrator tool.

2. Select Webservices, then select HPD_IncidentInterface_Create_WS. Right-click and select Open.

3. Select Input Mapping.

4. Add a new element (right-click on the ROOT element). A new element will be added at the end.

5. Rename the element as ConnectorGUID.

6. Map ConnectorGUID with ConnectorGUID from the left window.

7. Click OK to save.

8. Select the WSDL tab and perform the following steps:

   1. In the input on top, modify the midtier_server and servername values in the WSDL Handler URL.

   2. If mid-tier is on localhost, you can enter localhost right after http://.

   3. If the mid-tier uses port 80, you can omit the port. Otherwise, include the port number after the server name.

   4. For the server name after public/, enter the name of the Remedy server.

   5. Click the View button.

   6. If you see the XML content after clicking View, then close this window and save the changes.

      Note:

      You should see XML representing the web service WSDL file for the web service.

      If you see an error, check the midtier_server name, port, or servername. Also, you can try adding/removing the domain part of the servername.

9. Open the HPD_IncidentInterface_WS web service.

10. Select HelpDesk_Modify_Service from Operations List.

11. Select the Input Mapping... item. (XML Data Type windows are mapped with HPD:IncidentInterface.)

12. Map Incident_Number (on the right window) to "Incident Number" (On left window). Select both XML elements and click Map.

13. Add a new element (right-click on the ROOT element). A new element will be added at the end.

14. Rename the element as ConnectorGUID.

15. Map ConnectorGUID with ConnectorGUID from the left window.

16. Click OK to save.

17. Select HelpDesk_Modify_Status_service from Operations List. Repeat steps 11 through 16.

18. Select the WSDL tab and perform the following steps:

    1. In the input on top, modify the midtier_server and servername values in the WSDL Handler URL.

    2. If mid-tier is on localhost, you can enter localhost right after http://.

    3. If the mid-tier uses port 80, you can omit the port. Otherwise, include the port number after the server name.

    4. For the server name after public/, enter the name of the Remedy server.

    5. Click the View button.

    6. If you see the XML content after clicking View, close this window and save the changes.

       Note:

       You should see XML representing the web service WSDL file for the web service.

       If you see an error, check the midtier_server name, port, or servername. Also, you can try adding/removing the domain part of the servername.

Web Services Customization For AR Server 7.5

1. Log in to the BMC Remedy Developer Studio, then open a workspace.

2. Select the Remedy instance from the left pane.

3. Select All Objects, then Web Services, then HPD_IncidentInterface_Create_WS.

4. Select WSDL Ports, then Port, then WSDL Operations, then Create Operation.

5. In the Input Mapping section, select and right-click ROOT under the XML Data Type column.

6. From the New menu, select Element, then Field.

   A New Field Element is added as the last element, which appears under the XML Data Type column.

7. Click the element and rename it as ConnectorGUID.

8. Click on the Form/Field column.

   The Field Selector window appears.

9. Select ConnectorGUID from the list of available fields.

10. Click OK to save.

11. Click the WSDL Publishing Location tab and perform the following steps:

    1. In the input area at the top of the window, modify the midtier_server and servername values in the WSDL Handler URL.

    2. If mid-tier is on localhost, you can enter localhost directly after http://.

    3. If the mid-tier uses port 80, you can omit the port. Otherwise, include the port number after the server name.

    4. For the server name after public/, enter the name of the Remedy server.

    5. Click View.

    6. If you see the XML content after clicking View, close this window and save the changes.

You should now see XML representing the web service WSDL file for the Web service. If you see any error or no XML content, check the midtier_server name, port, or server name. You can also try adding/removing the domain portion of the server name.

Adding ConnectorGUID on the HPD_IncidentInterface_WS Web Service

1. Open the HPD_IncidentInterface_WS Web service.

2. Select HelpDesk_Modify_Service from the WSDL Operations list.

3. In the Input Mapping section, select the Incident_Number field under ROOT.

4. Click on the Form/Field column.

   The Field Selector window appears.

5. Select Incident_Number from the list of available fields.

6. Click OK to save.

7. In the Input Mapping section, select and right-click ROOT under the XML Data Type column. A new element is added at the end.

8. From the New menu, select Element, then Field.

   A New Field Element is added as the last element, which appears under the XML Data Type column.

9. Click the element and rename it as ConnectorGUID.

10. Click on the Form/Field column.

    The Field Selector window appears.

11. Select ConnectorGUID from the list of available fields.

12. Click OK to save.

13. Select HelpDesk_Modify_Status_Service from WSDL Operations.

14. Repeat steps 3 through 12 to map the Incident_Number and ConnectorGUID fields on HelpDesk_Modify_Status_Service.

15. Click the WSDL Publishing Location tab and perform the following steps:

    1. In the input area at the top of the window, modify the midtier_server and servername values in the WSDL Handler URL.

    2. If mid-tier is on localhost, you can enter localhost directly after http://.

    3. If the mid-tier uses port 80, you can omit the port. Otherwise, include the port number after the server name.

    4. For the server name after public/, enter the name of the Remedy server.

    5. Click View.

    6. If you see the XML content after clicking View, close this window and save the changes.

Creating a Connector Instance

The Remedy Service Desk Connector 12.1.0.2 connector type is deployed out-of-box with Enterprise Manager. To use this connector, you need to create one or more instances of this connector type. A connector instance refers to the configured instance of the connector with specific details, such as connector name, web-service end-points, username/password, and so forth of the Remedy Help Desk system. Multiple connector instances for the same connector type are supported, which provides the flexibility to configure multiple Remedy Help Desk systems with Enterprise Manager.

For example, you could have a production database and test database that Enterprise Manager monitors, and you can create two different connector instances and configure these with two different help desk systems to create tickets.

To create a connector instance:

1. From the Enterprise Manager console, click Setup.

2. Select Extensibility in the pane.

3. Select Management Connectors in the left pane.

4. Select a connector type from the Create Connector drop-down list and click the Go button.

5. Enter the connector name and description on the next screen and click the OK button.

6. The connector instance appears as unconfigured on the Management Connectors page, shown in Figure 2-1.

   Figure 2-1 Management Connectors Page

   
   

Configuring the Connector

Perform the following steps for basic configuration:

1. As Super Administrator, from the Enterprise Manager console, click Setup.

2. Click Extensibility, then Management Connectors.

   The Management Connectors page appears that list all created connector instances.

   Note:

   The status column with a green tick mark indicates that the connector is already configured.

3. Click the Configure button for the Remedy Service Desk Connector. The General tab of the Configure Management Connector page appears.

4. Provide the required settings. See "Providing General Settings" for details.

5. Click OK.

   The Management Connectors page reappears. The row for the Remedy Service Desk Connector should have a check mark in the Status column, as shown in Figure 2-2.

6. Optional: Register any customized templates using the emctl command from the ORACLE_HOME/bin directory, where ORACLE_HOME is the Oracle home directory of OMS.

   You can view all ticket templates by clicking the Ticket Templates tab.

7. If you choose HTTPS as the protocol to establish a connection between Remedy and Enterprise Manager, see Chapter 5, "Enabling SSL for HTTPS".

Figure 2-2 Configuration Confirmation

Enabling or Disabling the Connector

You can enable or disable a connector instance without needing to reconfigure or remove the connector from the system.

You can enable or disable a connector from the Management Connector page by selecting the connector and clicking either the Enable or Disable button. After a connector is disabled, you will see a red cross icon under the Status column. By default, the connector instance is enabled as soon as it is configured.

Note:

Only enabled connectors are available for ticketing operations.

Providing General Settings

The following sections explain how to provide various configuration details for the General tab of the Configure Management Connector page, shown in Figure 2-3.

Figure 2-3 Configure Management Connector Page

Connection Settings

The Remedy Service Desk Connector communicates with the Service Desk through their Web services. Mandatory fields are indicated with an asterisk ( * ).

• Web Service End Points — End points to createTicket, updateTicket, and getTicket web services exposed by Remedy Service Desk.

• Remedy Username — User with the privilege to create, update, and query tickets in Remedy.

• Remedy Password (optional) — Password associated with the supplied Remedy user.

• Authentication (optional) — String that a Remedy administrator sets for additional security. Applies only if the Remedy Administrator has configured it on the Remedy AR server.

• Locale (optional) — Language of the Remedy system.

• Time Zone (optional) — Time zone of the Remedy AR System Server.

• Ticket Number (required) — Enter a valid ticket number to test the configuration.

  • If you specify the correct Web service end points and enter a valid ticket number, the following message appears on the Management Connectors page after you click OK:

    "Connection test succeeded. The configuration was saved."

  • If you have not previously saved the connector configuration and enter an invalid ticket number, the following message appears on the Management Connectors page after you click OK:

    "Connection test failed. The configuration was saved."

  • If the mandatory field is missing, you will see the following message:

    "Missing mandatory field(s) - <actual field name>."

    For example, if web service points are missing, you will see the following message:

    "Missing mandatory field(s) - Web Service End Points"

Web Console Settings

Web Console settings are required if you want the connector to provide links to Remedy Service Desk tickets created by Enterprise Manager in the context of an incident.

To enable this functionality, provide the following Web console settings.

• Enable web console — Check this box to enable launching of the Remedy ticket page within context from Enterprise Manager.

• ARServer Name — Remedy AR Server name.

• HelpDesk Case Form Name — Remedy form name that the Remedy Web Services (you configured the connector to use) is based on. The Remedy default Service Desk Web services, for example, use the form HPD:IncidentInterface.

• Web Server — The name or IP address of the server that hosts Remedy Mid-Tier.

Grace Period

You can enable and disable the grace period and configure its value. By default, the grace period is disabled. See Grace Period for details. This setting applies to all incidents the Remedy Service Desk Connector processes. The grace period interval accepts the number of hours as any integer value. For example, - 1 or 2.

Retry

You can enable and disable the Retry option and configure its interval value. By default, the Retry is disabled. See Retry for details. This setting applies to all incidents in the Remedy Service Desk Connector processes. The retry period interval accepts the number of hours as any integer value. For example, - 1 or 2.

Working with Ticket Templates

When a connector instance is created in Enterprise Manager, all associated templates are available for ticket create/update operations. There are three default Remedy templates:

• Remedy_DefaultCategory_AutoResolve.xsl

• Remedy_DefaultCategory_AutoClose.xsl

• Remedy_DefaultCategory.xsl

Tip:

See Template Process for detailed information about these templates.

The following sections provide information about adding, viewing, removing, and replacing ticket templates.

Adding Ticket Templates

You need to add ticket templates before they are recognized in Enterprise Manager.

For each template above, run the following emctl register_template connector command as a user with execute privilege on emctl and the ability to read the ticket template:

$ORACLE_HOME/bin/emctl register_template connector
[-t <template.xml>]
[-repos_pwd <repos password>]
[-cname <connectorName>]
[-iname <internalName>]
[-tname <templateName>]
[-ttype <templateType>]
[-d <description>]

Where:

-t           Template(full path)
-repos_pwd   Enterprise Manager Root (SYSMAN) Password
-cname       Connector Name
-iname       Template Internal Name
-tname       Template Name Displayed
-ttype       Template Type
             <templateType> 1 - inbound transformation
             <templateType> 2 - outbound transformation
             <templateType> 3 - XML outbound transformation
-d           Description

For example: This command adds a new outbound template (newTemplate.xsl) for a connector instance with the name Remedy Connector Instance:

emctl register_template connector
-t <template.xml>
-repos_pwd <repos password>
-cname "Remedy Connector Instance"
-iname "newTemplate"
-tname "newTemplateOutbound"
-ttype 2
-d "Demo template"

Viewing Template Code

1. Select the connector instance and go to the connector configuration page.

2. Select the Template tab, as shown in Figure 2-4.

3. Click a template name to view the XSLT code for the template.

The ticket templates are in XSLT format. A basic knowledge of XSLT is required to understand the code.

Figure 2-4 Template Tab

Removing a Template

1. Select the connector instance and go to the connector configuration page.

2. Select the template tab.

3. Select the template and click the Remove button.

4. Click OK for the deletion to take effect.

Important:

If the template you delete has an incident rule associated with it, ticketing will not function for this particular incident rule after the deletion.

Editing Templates

Note:

The Edit Template feature is available in Oracle Enterprise Manager Release 12.1.0.2 and later.

Release 12.1.0.2 and Later

To edit an existing ticket template for Release 12.1.0.2 and later, do the following:

1. Select the connector instance and go to the Configure Management Connector page.

2. Select the Template tab.

3. Select the template and click Edit.

4. Edit the Description and Template Contents fields as needed, then click Save.

The ticket template is automatically registered. Saving the registered template updates it in the repository.

Releases Prior to 12.1.0.2

To edit an existing ticket template for versions prior to Release 12.1.0.2, replace the template as a substitute for direct editing:

1. Click Delete to remove the ticket template.

2. Re-register the separately edited template using the emctl register_template command described in Adding Ticket Templates.

For instance, for a template named template1.txt that you have just edited outside of Enterprise Manager, to use this newer version of the file, you would delete template1.txt as instructed above, then re-register the edited template1.txt file.

Restoring Templates

After you edit or customize a template, you can restore it to its previous default contents if needed by performing the following steps.

Note:

The Restore feature is available in Oracle Enterprise Manager Release 12.1.0.2 and later.

You can restore out-of-box templates that you have may edited or customized to their default values. You cannot restore new templates that you have created (using the emctl register_template command).

1. Select the connector instance and go to the Configure Management Connector page.

2. Select the Template tab.

3. Select the template and click Restore.

4. Click Yes in the confirmation page that appears in order to restore.

Deleting the Connector

You can delete a connector from the Management Connector page by selecting the connector and clicking the Delete button. After a connector is deleted, all associated incident rules are no longer configured for ticketing operations.

Additionally, if the connector deleted is the only connector instance of that connector type, the corresponding connector type is also deleted.

Note:

The above rule is not applicable to the out-of-box connector type.