Configuring IdentityIQ for BMC Remedy Action Request System Integration

This is intended as an introduction to the configuration needed to integrate IdentityIQ with the BMC Remedy Action Request System. This integration enables IdentityIQ to interact with many of the product solutions that are built on top of the AR System Server including BMC Remedy Change Management, BMC Remedy IT Service Management Suite, and BMC Remedy Service Desk.

BMC Remedy Action Request System Integration

SailPoint provides a default Remedy integration configuration. This configuration implements the integration between IdentityIQ and the Remedy Change Management Application to fulfill creation of tickets based on IdentityIQ access certification remediation events.

The default configuration is located in iiq/Home/WEB-INF/config/remedy-integration.xml directory, where iiq/Home is the location where IdentityIQ was installed.

This section explains the various entries that are specific for this integration. For more information of the entries in the IntegrationConfig file, see Appendix A: Common Identity Management Integration Configuration.

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

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

  • authentication

  • locale

  • timeZone

  • statusMap

The integration configuration includes the following entries if the http authentication is configured:

  • basicAuthType: if http authentication is configured the value of basicAuthType is true.

  • httpUserName

  • httpUserPass

User must modify remedy integration configuration file with the following entries to create incident in BMC Remedy Action Request System:

  • endpoint

  • responseElement key

  • SOAP envelop and body details

  • status mapping

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.

There are two supported configuration entries for integration with Remedy. These entries are children of the integration Attributes element:

  • getRequestStatus

  • provision

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

The getRequestStatus and provision entries contain the following entries:

  • soapMessage (required): 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 (required): 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).

  • statusMap (optional, see Sample getRequestStatus entry for an example)

  • username (optional)

  • password (optional)

  • authentication (optional)

  • locale (optional)

  • timeZone (optional)

  • endpoint (optional)

  • namespace (optional)

  • prefix (optional)

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 provision call passes the following objects to Velocity:

  • config: the integration configuration for provision, represented as a Map

  • provisioningPlan: the data model of the provision request

The getRequestStatus call passes the following objects to Velocity:

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

Sample getRequestStatus entry

The entries contained in the Map are the only required entries. Any authentication information required by this integration is inherited from the parent Attributes element.

Copy 
<entry key="getRequestStatus">  <value>
    <Map>
        <entry key="responseElement" value="Status"/>
        <entry key="soapMessage">
            <!-- XML template – DO NOT add line breaks before the CDATA! -->
            <value><String><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
#if ($config.username)
<soapenv:Header>
<ns1:AuthenticationInfo xmlns:ns1="urn:AuthenticationInfo">
                 <ns1:userName>$config.username</ns1:userName>
                 <ns1:password>$config.password</ns1:password>
        #if ($config.authentication)
                <ns1:authorization>$config.authentication</ns1:password>
#end
#if ($config.locale)
                <ns1:locale>$config.locale</ns1:password>
#end
#if ($config.timeZone)
                <ns1:timeZone>$config.timeZone</ns1:password>
#end
</ns1:AuthenticationInfo>
</soapenv:Header>
#end
<soapenv:Body>
       <:Get xmlns:="urn:GetAgreementWebService">
          <:Issue_ID>$requestID</:Issue_ID>
       </:Get>
     </soapenv:Body>
</soapenv:Envelope>
]]>
                   </value>
               </entry>
           </Map>
        </value>
</entry>

Sample provision entry

This Map contains its own web services information. Any authentication information required by this integration is inherited from the parent Attributes element.

Copy 
<entry key="provision">
       <value>
           <Map>
               <entry key="endpoint" value="http://my.server.com:8080/path/to/WS"/>
               <entry key="namespace" value="urn:openTicketWebService"/>
               <entry key="prefix" value="xyz"/>
               <entry key="responseElement" value="Issue_ID"/>
               <entry key="soapMessage">
                  <!-- XML template – DO NOT add line breaks before the CDATA! -->
                  <value><String><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
#if ($config.username)
<soapenv:Header>
<ns1:AuthenticationInfo xmlns:ns1="urn:AuthenticationInfo">
                 <ns1:userName>$config.username</ns1:userName>
                 <ns1:password>$config.password</ns1:password>
#if ($config.authentication)
                 <ns1:authorization>$config.authentication</ns1:password>
#end
#if ($config.locale)
                 <ns1:locale>$config.locale</ns1:password>
#end
#if ($config.timeZone)
                 <ns1:timeZone>$config.timeZone</ns1:password>
#end
</ns1:AuthenticationInfo>
</soapenv:Header>
#end
<soapenv:Body>
     <:Get xmlns:="urn:openTicketWebService">
         <:Submitter>
         #foreach ($req in $provisionPlan.requesters)
              $req.name
         #end
         </:Submitter>
         </:SubmitDate>$timestamp</:SubmitDate>
         <:Summary>
               Remediation request from 
         </:Summary>
         <:Description>
               Remove Active Directory for $provisionPlan.identity.fullname
         </:Description>
         <:Issue_ID>$requestID</:Issue_ID>
       </:Get>
     </soapenv:Body>
</soapenv:Envelope>
]]>
             </value>
          </entry>
       </Map>
    </value>
</entry>

Sample statusMap entry

The noMappingFromWS entries are placeholders as there are no results from the web service corresponding to those IdentityIQ result codes.

Copy 
<entry key="statusMap">
    <value>
        <Map>
           <entry key="Closed" value="committed" />
           <entry key="Rejected" value="failure" />
           <entry key="Draft" value="inProcess" />
           <entry key="Pending" value="inProcess" />
            <entry key="noMappingFromWS" value="retry" />
            <entry key="noMappingFromWS" value="warning" />
        </Map>
    </value>
</entry>

Creating Multiple Tickets in Remedy System

To create multiple tickets in Remedy System via IdentityIQ, add the following attributes in remedy-integration.xml file:

  • multipleTicket: If multipleTicket attribute is defined, then the value can be one of the following:

    Default value: true

    • True: A separate Remedy ticket would be created for each line item from the IdentityIQ access request.

    • False: Single Remedy ticket would be created against all line items from the IdentityIQ access request.

    The format of the entry is as follows:

    <entry key='multipleTicket' value='true'/>

  • groupTicketBy: If groupTicketBy attribute is defined, then value can be one of the following:

    Default value: none

    • none: If the attribute is not defined or if attribute value is other than Application, then IdentityIQ sets this attribute to none.

    • Application: If the attribute value is Application and multipleTicket=true, then IdentityIQ access request lines from the same application would be moved to a single ticket.

    The format of the entry is as follows:

    <entry key='groupTicketBy' value='none'/>

    For example, the multipleTicket and groupTicketBy keys can be placed in the Integration configuration file as follows:

    Copy 
    <IntegrationConfig>
      <Attributes>
        <Map>
          <entry key="multipleTicket" value="true"/>
          <entry key='groupTicketBy' value='none'/>
          <entry key="provision">
            <value>
              <Map>
                <entry key="endpoint" value="%%REMEDY_REQ_TICKET_ENDPOINT%%"/>
              ...
              ...
              ...
              </Map>
            </value>
          </entry>
        </Map>
      </Attributes>
    <IntegrationConfig>

Verifying Connectivity between IdentityIQ and BMC Remedy

Obtain the integration configuration name and an existing ticket number from BMC Remedy Service Desk System.

Perform the following procedure for verifying the connection between IdentityIQ and BMC Remedy:

  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 BMC Remedy Service Desk. Therefore the command would be as follows:

    use tst_RemedyIntegration

    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 BMC Remedy Service Desk System.

    For example:

    getRequestStatus IM10001

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

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

    This indicates that the connection is successful.

Retryable Mechanism

By default IdentityIQ for BMC Remedy 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 the file.

The retryableErrors entry is a list of strings through which the Remedy Integration searches when it receives a message from the BMC Remedy 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 the BMC Remedy Service Desk, then IdentityIQ will not attempt a retry.

For example:

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

Additionally IdentityIQ would retry for following exception strings:

Copy 
<entry key="retryableErrors">
   <value>
     <List>
       <String>Connection refused: connect</String>
       <String>Connection timed out</String>
       <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.