Configuring HP Service Manager (Micro Focus) for IdentityIQ Integration

This section provides the required information for configuring IdentityIQ to integrate with HP Service Manager. This integration enables IdentityIQ to create tickets for requested revocations, track ticket numbers in association with revocation tasks, and update IdentityIQ with the status of current tickets.

SailPoint provides a default HP Service Manager Service Integration configuration. This configuration implements the integration between IdentityIQ and the HP Service Manager (Micro Focus) to fulfill creation of tickets based on IdentityIQ access certification remediation events.

Configuration

• The default configuration is located in iiqHome/WEB-INF/config/ directory, where iiqHome is the location where IdentityIQ was installed.

• When integrating with the following requests, modify the respective config files and import in IdentityIQ:

  Request	XML files
  Service Request	HPServiceManagerIntegrationConfigForRequest.xml
  Incident Request	HPServiceManagerIntegrationConfigForIncident.xml
  Change Request	HPServiceManagerIntegrationConfigForChange.xml

• The integration configuration must include the following entries:

  • endpoint: URL to the web service

  • namespace: namespace of the XML returned by the web service

  • prefix: prefix associated with the namespace
    

  For more information of the entries in the IntegrationConfig file, see Appendix A: Common Identity Management Integration Configuration.
  

• The integration configuration includes the following entries if the web service side of the integration is configured for authentication using the SOAP authentication specifications:

  • username

  • password

  • statusMap

  • statusMapClosureCode
    

  The web services and authentication entries are consumed by configuration entries for each web service. They can be positioned either within the configuration entries themselves or as children of the Attributes element. Entries that are children of the Attributes element can be thought of as global values, while entries within the configuration entities can be thought of as local.

  For example, if both entries share the same authentication credentials, those credentials might be placed in the Attributes element as peers of the configuration entries and the integration code searches the parent entry for the credentials if they are not found in the configuration entries. Conversely, if the configuration entries have different endpoints (are handled by separate web services), each configuration entry specifies the endpoint of the web service to call and any value outside of the configuration entry is ignored.

• Following are the supported configuration entries for integration with HP Service Manager. These entries are children of the integration Attributes element:

  • provision

  • getRequestStatus
    

  The values of each are Map elements containing key/value pairings of the configuration data. They contain the specific data needed by the provision() and getRequestStatus() methods of the IdentityIQ integration executor and correspond to HP Service Manager Web Service methods.

  The provision and getRequestStatus entries contain the following entries:

  Items marked with * are required entries.

  Entries	Description
  soapMessage*	Full XML template of the entire SOAP envelope that is sent to the web service. The integration code first runs this template through Apache's Velocity template engine to provide the data needed by the web service.
  responseElement*	Name of the element containing the results of the web service call (for example, the element containing the ticket number opened by the web service in response to the call from IdentityIQ).
  SOAPAction*	SOAP requests action
  endpoint*	HP Service Manager endpoint to send create and get ticket status
  namespace*	Namespace of the XML returned by the web service
  prefix*	Prefix associated with the namespace

  Before a template is sent to the web service, it is processed by the Velocity template engine. The integration code provides different data objects to Velocity for evaluation based on the integration method.

  The following calls pass the respective objects to Velocity:

  Call	Objects	Description
  provision	config	The integration configuration for provision, represented as a Map
  	provisioninPlan	The data model of the provision request
  getRequestStatus	config	The integration configuration for getRequestStatus, represented as a Map
  	requestID	The string ID of the request whose status is being queried

  Both calls have access to a timestamp variable containing a current Date object and a dateFormatter object. The dateFormatter is built using an optional dateFormat attribute from the config object. If the dateFormat attribute does not exist, the formatter defaults to the pattern EEE, d MMM yyyy HH:mm:ss z.

Mappings for Service, Incident and Change Request

If any changes required in the mapping, change the value/key values in "statusMap" and "statusMapClosureCode" as mentioned in the following tables for Service, Incident and Change Request:

Service Request

statusMap

Status Map Closure Codes

Incident Request

statusMap

Status Map Closure Codes

Change Request

statusMap

Status Map Closure Codes

Configuration Procedure

The following steps should be performed to modify the default HP Service Manager Service Integration configuration for a specific HP Service Manager Server.

1. Obtain the environment-specific Web Service "endpoint", for example:

   http://<host>:<port>/SM/7/ws.

2. (For HP Service Manager 9.5 or later)

   • HPServiceManagerIntegrationConfigForIncident: Set Service as a Configuration Item Identifier. For example:

     <ns:Service type="String" mandatory="" readonly="">CI1001030</ns:Service>

   • HPServiceManagerIntegrationConfigForChange:

     • Set Category as a Standard Change. For example:

       <ns:Category type="String" mandatory="" readonly="">Standard Change</ns:Category>

     • Set Service as a Configuration Item Identifier. For example, CI1001030

       For example:

       <ns:Service type="String" mandatory="" readonly="">CI1001030</ns:Service>

3. Once you are familiar with the WSDL, modify the default IdentityIQ HP Service Manager configuration using the information collected about the web service.

   • In the <IntegrationConfig> element of the integration configuration, modify the username and password entries in the attributes map to contain the credentials required for authentication to the web service.

   • In the <IntegrationConfig> element of the integration configuration, modify the provision entry of the Attributes map by setting the endpoint, and, if necessary, the namespace, the prefix, the responseElement, and the soapMessage attributes (the default values: IdentityIQ HP Service Manager IntegrationConfig):

     1. Set the value for endpoint to the value located in the WSDL earlier.

        The value in the IdentityIQ integration configuration must be a valid HTTP URL and have any special characters escaped. The most common change that must be made is to replace all and symbols with &amp;

     2. The value for namespace comes from the targetNamespace attribute of the xsd:schema element in the WSDL.

     3. The value for prefix is the prefix of the XML elements that will be contained in the SOAP response.

     4. The value for responseElement should be the HP Service Manager form field that corresponds to the id of the form that the web service creates.

     5. The value for soapMessage should be the SOAP message body that IdentityIQ will send to HP Service Manager. The exact format of this message is a function of the form that is published as described by the form's WSDL. The XML elements in the soapenv:Body element should be changed to match the HP Service Manager form fields for the published web service. Each required HP Service Manager form field must have an element in the SOAP message. The value can be fixed or can be a variable that will be substituted using IdentityIQ's Velocity templating.

        For more information on <ManagedResources> in the IntegrationConfig file, see Appendix A: Common Identity Management Integration Configuration.

4. (Only for Service Request and Micro Focus version 9.7) In the <IntegrationConfig> element of the integration configuration, modify the catalogItem entry of attributes map. Provide key as Managed Application name and value as Request Item Name. This request item must be present on HP Service Manager’s Service Request.
   For example:

   <entry key="Demo App1" value="Identity Access Request Item"/>

5. (Only for Service Request) Modify the Rule for applicationName and provide its value same as that of application created while importing HP Users in IdentityIQ.

   In Rule, the ‘attributeName’ represents the Application's link attribute and is used to populate the ‘requestedFor’ field in Service Request.

6. (For Micro Focus version 9.7 only): Replace all occurrences of incident.id in HPServiceManagerIntegrationConfigForRequest.xml file with InteractionID.

The information in the reference section above show the variables that are provided and the example integration configuration provides examples of how they are used.

Verifying Connectivity between IdentityIQ and HP Service Manager (Micro Focus)

Obtain the integration configuration name and an existing ticket number from MicroFocus Service Manager Service Desk System.

Perform the following procedure for verifying the connection between IdentityIQ and HP Service Manager:

1. Using the IdentityIQ integration console, launch the console by using the following IdentityIQ script in the WEB-INF/bin directory of the IdentityIQ installation to run IdentityIQ integration:

   iiq integration

2. From the console enter the following:

   use applicationName

   where applicationName is the name of the MicroFocus Service Manager Service Desk Integration Module. Therefore the command would be as follows:

   use HPSMServiceIntegrationModuleRequest

   This makes the application ready for further console commands.

3. Enter the following command to get the connection status:

   getRequestStatus ticketNumber

   where ticketNumber is the number of the existing ticket obtained from MicroFocus Service Manager Service Desk System. For example:

   getRequestStatus SD10001

   In the above example, SD10001 is the ticketNumber. The following status is returned:

   Result: status = committed; request ID = SD10001; warnings = null; errors = null

   This indicates that the connection is successful.

Retryable Mechanism

By default IdentityIQ for MicroFocus Service Manager Service Desk provides retry mechanism for Connection reset and for unknown host problems occurred from network issues.

However you can configure retryableErrors list in integration configuration (IntegrationConfig) file to add new exception strings to the attributes map in integration configuration file.

The retryableErrors entry is a list of strings through which the integration searches when it receives a message from the IdentityIQ for MicroFocus Service Manager Service Desk. Only SOAPException strings are considered for retry that is, the exceptions raised from SOAP web service. If one of the strings in the entry exists in the error, the integration attempts to retry the request. When the configured error string is not a part of the error message returned from MicroFocus Service Manager Service Desk, then IdentityIQ will not attempt a retry.

For example,

<entry key="retryableErrors">    
   <value> 
      <List> 
        <String>Connection reset</String> 
      </List> 
    </value>
</entry>

Error messages containing very specific information about date/time, sequence ID and so on must be avoided. Error codes or error message substrings would be good candidates for inclusion. Only exceptions raised from soap web service are considered for retry.