2 Installing and Configuring the Connector

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

• Prerequisites

• Installing the Connector

• Creating a Connector Instance

• Configuring the Connector

• Enabling or Disabling the Connector

• Providing General Settings

• Working with Ticket Templates

• Deleting the Connector

• Uninstalling Customizations to BMC Remedy

2.1 Prerequisites

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

• Remedy Service Desk is installed and configured, which is part of IT Service Management Suite 7.6.04 SP2, 8.0.x, 8.1.x, 9.0.x, or 9.1.x with the Incident Management Application.

• Action Request Server 7.6.04 SP1 (AR Server 7.6.04 SP1), 8.0.x, 8.1.x, 9.0.x, or 9.1.x is installed.

• Remedy Service Desk web services are up and running.

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

• My Oracle Support Preferred Credentials are set. To set the credentials, perform the following steps:

  1. From the Enterprise Manager console Setup menu, select My Oracle Support, then Set Credentials.

  2. Enter the user name and password information, then click Apply.

  3. From the Enterprise Manager console Setup menu, select Extensibility, then Self Update.

  4. From the Self Update page, look for the Remedy Service Desk 7.6 connector in the table list. If it does not appear, go to the next step.

  5. Click Check Updates to schedule a job to collect the metadata for the connector, as shown in Figure 2-1.

     See Also:

     Refer to the "Setting up Self Update" section of the "Updating Cloud Control" chapter in the Oracle Enterprise Manager Cloud Control Administrator's Guide for more details:

     http://docs.oracle.com/cd/E24628_01/doc.121/e24473/self_update.htm#BEJJEHDJ
     

     Note:

     You can also set up Self Update in offline mode. See the "Applying an Update in Offline Mode" section from the Oracle Enterprise Manager Cloud Control Administrator's Guide for details:

     http://docs.oracle.com/cd/E24628_01/doc.121/e24473/self_update.htm#BEJICEBD
     

     Figure 2-1 Check Updates on Self Update Page

     
     

     

     
     

2.2 Installing the Connector

This section provides the procedure required to download and install (apply) the connector. The Remedy Service Desk 7.6 connector is not included out-of-the-box, so you need to download it from the Oracle Enterprise Manager store. All connectors in the Enterprise Manager store are available on the Self Update page for downloading.

To install the connector:

1. From the Enterprise Manager console Setup menu, select Setup, then select Extensibility, then select Self Update.

2. Click on the Management Connector link in the Type column.

   The Remedy Service Desk 7.6 connectors appear in the list with a status of Available.

3. Click on the appropriate Remedy Service Desk 7.6 connector to select it, and then click Download.

   The Schedule Download window appears, where you can determine when the download should be performed.

4. Click Select to download immediately.

   If you want to schedule the download for a later time, specify the date and time when the download should occur, and click Select. You will need to return and finish the remainder of this procedure after the scheduled download date and time.

5. If necessary, refresh the screen until the status of the connector changes to Downloaded.

6. Click on the Remedy Service Desk 7.6 connector to select it, then click Apply.

   After you respond to the prompt to confirm the operation, a page appears that indicates the request has been submitted.

7. Refresh the screen until the status of the connector changes from Apply Scheduled to Applied.

2.2.1 Exporting the Definition File

The Remedy customized definition file is included in the Self Update archive that was installed in the previous section.

To extract the installation file:

1. Determine the command required to export the Remedy installation file. To do this, perform the following steps:

   1. From the Setup menu, select Extensibility, then Self Update.

   2. Click on the Management Connector link in the Type column.

   3. Click on the Remedy Service Desk 7.6 connector to select it, then select Export from the Actions list.

      A pop-up window, like the example shown in Figure 2-2, appears with the command required to export the file.

      Figure 2-2 Export Command Example

      
      

      

      
      

2. Open a command window on the Management Server host system and navigate to a temporary directory where you can copy and unzip the file.

3. Log into EM CLI using the following command. You will be asked to provide the password information for the sysman account.

   emcli login -user=<EM_Super_Adminstrator> -pass=<PASSWORD>
   

   EM CLI must be executed from the OMS host. See the Oracle Enterprise Manager Command Line Interface for information about setting up EM CLI.

4. Run the EM CLI export_update command from your system, changing <dirname> to the full path of the temporary directory.

   This action creates a zip file with a name of p18729198_112000_Generic.zip.

5. Extract the Remedy definition xml file HPD_IncidentInterface_Custom_WS.xml from the .zip file using the following command:

   unzip *.zip archives/HPD_IncidentInterface_Custom_WS.xml
   

2.2.2 Installing the Definition File

These customization files assume a fresh installation of Remedy AR Server 7.6.04, 8.0.x, 8.1.x, 9.0.x, or 9.1.x. 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.

Note:

In order to import the definition files for use with the connector, it is required to overwrite existing Web Services. Oracle recommends that you back up these Web Services before you start the uninstall process. Refer to Uninstalling Customizations to BMC Remedy for details.

Before you install the definition file, do the following:

1. Ensure that you have already exported the definition file from the Self Update archive as instructed in the previous section.

2. Select the default value in the BMC Remedy Developer Studio:

   1. Log in to the Studio, then open the HPD:HelpDesk form.

   2. Select the Status field, then right-click and select Create Overlay.

   3. Go to the Status field Properties window.

   4. Click Selections, then select Assigned as the default value.

   5. Click Save to save the changes to the form. The save action may show as successful with warnings. These warnings are harmless.

3. Flush the mid-tier cache.

Install the definition file (.xml) in the running Remedy environment by completing the following steps.

1. Open a work space from the BMC Remedy Developer Studio.

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 HPD_IncidentInterface_Custom_WS.xml definition file, then click Next.

   The Object Selection window appears.

7. Enable the Replace Objects on the Destination Server check box, then click Finish.

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

2.2.3 Displaying the New Objects

After installing the definition file, the new objects are shown under the Remedy instance. To view the new objects on the Remedy Server, flush the mid-tier cache and perform the following steps to verify.

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

2. Select All Objects, then Web Services.

   You should now be able to see a new HPD_IncidentInterface_Custom_WS web service.

3. Select HPD_IncidentInterface_Custom_WS.

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

   You should now see HelpDesk_Query_Service, HelpDesk_Modify_Status_Service, and HelpDesk_Modify_Service under WSDL Operations.

Note:

If the WSDL Operations do not appear, or the import step failed due to the Remedy 7.6.04 Overlay Feature, try switching the mode:

1. Select File, then select Switch Mode.

2. Switch to Base Development instead of Best Practice Customization.

3. Try to import the definition file again.

2.2.4 Customizing Web Services

Customize Web Services as follows:

1. Open a work space in the BMC Remedy Developer Studio.

2. Select the Remedy instance from the left pane.

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

4. 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 an error or no XML content, check the midtier_server name, port, or server name. You can also try adding or removing the domain portion of the server name.

For HPD_IncidentInterface_Custom_WS, repeat steps 3 and 4.

Note:

For AR Server 7.6.04 the Ticket Response Template must be modified. Refer to Working with Ticket Templates for instructions.

2.3 Creating a Connector Instance

To use the Remedy Service Desk 7.6 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 Service Desk system. Multiple connector instances for the same connector type are supported, which provides the flexibility to configure multiple Remedy Service Desk systems with Enterprise Manager.

For example, since Enterprise Manager is monitoring production targets and test targets, you can then create two instances of the connector and configure Enterprise Manager so that incidents from production targets create tickets in one connector instance, and incidents from test targets create tickets in the second connector instance.

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 OK.

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

   Figure 2-3 Management Connectors Page

   
   

   

   
   

2.4 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 lists 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-4.

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 Enabling SSL for HTTPS.

Figure 2-4 Configuration Confirmation

2.5 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.

2.6 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-5.

Figure 2-5 Configure Management Connector Page

2.6.1 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.

  Note:

  They must have the same value for First Name, Last Name, and Login ID. It is recommended to create a new user account with these specifications in addition to the correct privileges.

• 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"

2.6.2 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.

• 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.

  To enable the use of Web Console for AR Server 8.0.x and 8.1.x, set the HelpDesk Case Form Name to use the Best Practice View. This view will also work for AR Server 7.6.04. For example, use the form:

  HPD%3AHelp+Desk/Best+Practice+View
  

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

• ARServer Name — Remedy AR Server name.

2.6.3 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.

2.6.4 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.

2.7 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.

2.7.1 Adding Ticket Templates

You need to add ticket templates before they are recognized in Enterprise Manager. The connector provides out-of-box templates that are automatically registered when the connector instance is created. If you want to edit these, you can do so directly in Enterprise Manager. However, if you need to use a new template (other than one out-of-box), you need to register the new template using the emctl command. You can then edit the template in Enterprise Manager. See Editing Templates for more information.

To add and register a template:

1. Ensure that you have execute privilege on emctl and the ability to read the ticket template.

2. For each template, run the following emctl register_template connector command:

   $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
   

Example 2-1 Template Registration

The following 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"

2.7.2 Viewing Template Code

To view template code, do the following:

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

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

3. Click a template name or click View 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-6 Template Tab

2.7.3 Removing a Template

To remove a template, 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 Delete.

4. Click Yes to confirm the delete operation.

Note:

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

2.7.4 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.

2.7.5 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.

2.7.6 Editing the Create Ticket Response Template for AR Server 7.6.04

Note:

Editing of the Ticket Response Template is only required for AR Server 7.6.04. For versions 8.0.x, 8.1.x, 9.0.x, or 9.1.x, do not perform these steps.

Edit the Create Ticket Response Template for AR Server 7.6.04 by performing the following steps:

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

2. Select the Template tab.

3. Select the Create Ticket Response template and click Edit.

4. Edit the Template Contents fields as by performing the following steps:

   1. Locate and view line 3 of the Template:

      xmlns:urn="urn:HPD_IncidentInterface_Create_WS"
      

   2. Edit the line by removing the syntax error. The new line should read as follows:

      xmlns:urn="HPD_IncidentInterface_Create_WS"
      

5. Click OK to save.

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

2.8 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.

2.9 Uninstalling Customizations to BMC Remedy

To uninstall and remove customizations to BMC Remedy, perform the following steps:

1. Back Up Web Services

2. Remove Customizations to Web Services

3. Remove Customizations for Installing the Definition File

2.9.1 Back Up Web Services

Before importing the definition files, it is recommended to back up the existing Web Services. To back up the Web Services perform the following steps:

1. Open a work space from the BMC Remedy Developer Studio.

2. Select the Remedy instance from the left pane.

3. Right-click and select Export, and select Object Definitions.

4. Search for HPD:IncidentInterface. Highlight and select both results from the search:

   HPD:IncidentInterface
   HPD:IncidentInterface_Create
   

5. Click Next, and select a path and name for the export file.

6. Click Finish to process the export.

2.9.2 Remove Customizations to Web Services

To remove the customization to the Web Services, perform the following steps:

1. Open a work space in the BMC Remedy Developer Studio.

2. Select the Remedy instance from the left pane.

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

4. Click the WSDL Publishing Location tab and remove the URL. Click Save.

2.9.3 Remove Customizations for Installing the Definition File

To remove the customization to made during the installation of the definition file, perform the following steps:

1. Open a work space in the BMC Remedy Developer Studio.

2. Select the Remedy instance from the left pane.

3. Select All Objects, then Forms, then search for the HPD:HelpDesk form.

4. Locate and select the Status field.

5. Go to the Status field Properties window.

6. Click Selections, then select New as the default value. Click Save.

To remove the Web Service that was installed by importing the definition file, perform the following steps:

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

2. Select All Objects, then Web Services.

3. Search for the HPD_IncidentInterface_Custom_WS web service.

4. Right-click and select Delete, and OK to confirm.

To import the backup definition files, perform the following steps:

1. Locate backup definition files for the HPD:IncidentInterface and HPD:IncidentInterface_Create forms.

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

3. From the File menu select Export.

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

5. Click Browse and select the backup definition file, then click Next.

   The Object Selection window appears.

6. Enable the Replace Objects on the Destination Server check box, then click Finish.