Find Incident operation for the CA Service Desk adapter

The Find Incident operation retrieves incident records from the CA Service Desk application.

The following table describes the <items> XML elements for the Find Incident operation.

Note

Use the <items> element when you call an adapter from an out-of-the-box process in BMC Atrium Orchestrator Development Studio. Use the adapter request XML when you create a custom process by using the Call Adapter activity in BMC Atrium Orchestrator Development Studio.

Elements for the <items> XML element and adapter request for the Find Incident operation

Element	Definition	Required
`<operation-name>`	Specifies the name of the operation: `find-incident`	Yes
`<arguments>`	Specifies a list of arguments that are required for the `find-incident` operation	Yes
`<target>`	Specifies the connection information for the target where the request will be executed If this element is not specified, the adapter uses the configuration information specified in the Grid Manager. You can specify the following XML elements within this element: `<soap-url>` `<host>` `<user-name>` `<password>` `<port>` `<protocol>` `<install-certificate>` `<allow-unsigned-certificate>` `<passphrase>`	Conditional; required if adapter configuration is left empty.
`<soap-url>`	Specifies the URL for the remote SOAP service The `<soap-url>` element has the following formats: For insecure communication: `<soap-url>http://` <IPAddress or hostname> `:` portNumber `</soap-url>` For secure communication: `<soap-url>https://` <IPAddress or hostname> `:` portNumber `</soap-url>` IPAddress is the IP address of the computer where the application server is installed. hostName is the name of the computer where the application server is installed. portNumber specifies the port on which the application server is running, even if it is the default (otherwise, the adapter fails to install the certificate and adapter requests fail). Default value (for secure communication): 443 Sample URL: `https://machine_name.domain_name.com: 8443/axis/services/USD_R11_WebService?wsdl`	Conditional; required if `<host>` is not specified. If both `<soap-url>` and `<host>` are specified, `<soap-url>` takes precedence.
`<host>`	Specifies the host name or IP address of the server where CA Service Desk is installed	Conditional; required if `<soap-url>` is not specified. If both `<soap-url>` and `<host>` are specified, `<soap-url>` takes precedence.
`<user-name>`	Specifies the user name for the CA Service Desk server authentication	No
`<password>`	Specifies the password that corresponds to the user name The password element can contain an `encryption-type` attribute.	No
`encryption-type`	Indicates whether the password specified is encrypted Valid values: Base64, Plain (default)	No
`<port>`	Specifies the communication port for the CA Service Desk application Valid values: Any positive number greater than 0 Default values: 8080 for http, 8443 for https	No
`<protocol>`	Specifies the communication protocol for the CA Service Desk application Valid values: http, https (default)	No
`<install-certificate>`	Specifies whether to install security certificates automatically If you prefer to have security certificates installed automatically (a common practice), set the value of this element to true. If you prefer to manually export the security certificate from the CA Service Desk server and manually import it into the BMC Atrium Orchestrator's local peer's cacerts file (a rare practice), set the value of this element to false. Valid values: true, false (default)	No
`<allow-unsigned-certificate>`	Specifies whether to allow unsigned certificates from trusted zones If you are using self-signed SSL certificates (a common practice), set the value of this element to true. On ecommerce sites or military installations, if you need to use signed certificates such as Verisign or Thawte (a rare practice), set the value of this element to false. Valid values: true, false (default)	No
`<passphrase>`	Specifies the password to the keystore file (cacerts) local to the BMC Atrium Orchestrator peer Default value: changeit Warning The value of the `<passphrase>` element is the passphrase for the cacerts certificate stored on the BMC Atrium Orchestrator local peer (CDP or AP) and not the CA Service Desk target host. Changing the passphrase can be difficult and might destroy the integrity of the cacerts security file. Verify the cacerts passphrase using the following command in UNIX or Linux: $ /opt/bmc/ao/cdp/jvm/bin/keytool -list -keystore /opt/bmc/ao/cdp/jvm/lib/security/cacerts	No
`<incident-number>`	Specifies the incident number to be retrieved Valid values: A valid incident number	No
`<assignee>`	Specifies the name of the person to whom the incident record is assigned Valid values: A valid name in the format - lastName,firstName,middleName For example: If last name, first name, and middle name exist, the value is - lastName,firstName,middleName. If only last name exists, the value is - lastName. If last name and middle name exist, the value is - lastName,,middleName.	No
`<group>`	Specifies the name of the group to which the incident record is assigned Valid values: A valid group name	No
`<status>`	Specifies the status associated with the incident record Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list. Adding new values is also supported.	No
`<priority>`	Specifies the priority associated with the incident record Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list.	No
`<is-active>`	Specifies whether the incident is active Valid values: true, false	No
`<incident-area>`	Specifies the incident area associated with the incident Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list.	No
`<configuration-item>`	Specifies the configuration item associated with the incident record Valid values: A valid configuration item name	No
`<reported-by>`	Name of the contact who reported the incident Valid values: A valid name in the format - lastName,firstName,middleName For example: If last name, first name, and middle name exist, the value is - lastName,firstName,middleName. If only last name exists, the value is - lastName. If last name and middle name exist, the value is - lastName,,middleName.	No
`<affected-end-user>`	Specifies the name of the end user who is affected by the incident Valid values: A valid name in the format - lastName,firstName,middleName For example: If last name, first name, and middle name exist, the value is - lastName,firstName,middleName. If only last name exists, the value is - lastName. If last name and middle name exist, the value is - lastName,,middleName.	No
`<affected-end-user-id>`	Specifies the user ID of the end user who is affected by the incident Valid values: A valid user ID	No
`<affected-end-user-location>`	Specifies the location of the end user who is affected by the incident Valid values: A valid location name	No
`<affected-end-user-organization>`	Specifies the organization of the end user who is affected by the incident Valid values: A valid organization name	No
`<summary>`	Specifies the summary associated with the incident record Valid values: Any String value	No
`<description>`	Specifies the description text associated with the incident record Valid values: Any String value	No
`<problem>`	Specifies the problem record associated with the incident record Valid values: A valid problem number	No
`<change>`	Specifies the change record attached to the incident record Valid values: A valid change number	No
`<caused-by-change-order>`	Specifies the change record that caused the incident Valid values: A valid change number	No
`<incident-priority>`	Specifies the incident priority associated with the incident Valid values: A valid incident priority	No
`<impact>`	Specifies the impact associated with the incident record Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list.	No
`<urgency>`	Specifies the urgency associated with the incident Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list.	No
`<severity>`	Specifies the severity associated with the incident Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list.	No
`<earliest-open-date>`	Retrieves all incident records with `<open-date>` greater than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<latest-open-date>`	Retrieves all incident records with `<open-date>` less than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<earliest-resolve-date>`	Retrieves all incident records with `<resolve-date>` greater than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<latest-resolve-date>`	Retrieves all incident records with `<resolve-date>` less than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<earliest-close-date>`	Retrieves all incident records with `<close-date>` greater than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<latest-close-date>`	Retrieves all incident records with `<close-date>` less than or equal to the value specified Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.	No
`<parent>`	Specifies the parent incident associated with the incident record Valid values: A valid incident number
`<is-child>`	Specifies whether the incident record has a parent incident assigned Valid values: true, false	No
`<root-cause>`	Specifies the root cause associated with the incident record Valid values: See the Administration section of the CA Service Desk application for a complete list of supported values. Note You can customize the existing default list. Adding new values is also supported.	No
`<sla-violation>`	Specifies whether the incident record is associated with a service level agreement (SLA) violation Valid values: true, false	No
`<is-template>`	Specifies whether the incident record is a template Valid values: true, false	No
`<number-of-records>`	Specifies the number of records to retrieve Valid values: Any positive integer Default value: -1 (Retrieves a maximum of 250 records)	No
`<additional-search-arguments>`	Specifies the custom search query involving one or more attributes Valid values: See the CA Service Desk application and its Technical Reference Guide for valid search query.	No

The following figure illustrates a sample adapter request for the Find Incident operation:

Sample adapter request for the Find Incident operation


<casd-request>
  <operation-name>find-incident</operation-name>
  <arguments>
    <target>
      <host>172.11.11.111</host>
      <user-name>username</user-name>
      <password>password</password>
      <port>8080</port>
      <protocol>http</protocol>
    </target>
    <incident-number>48</incident-number>
    <assignee>l1,f1 f2,m1</assignee>
    <group />
    <status>Open</status>
    <priority>None</priority>
    <is-active />
    <incident-area />
    <configuration-item />
    <reported-by>ServiceDesk</reported-by>
    <affected-end-user>Gupta,Shankar,Kumar</affected-end-user>
    <affected-end-user-id />
    <affected-end-user-location />
    <affected-end-user-organization />
    <problem />
    <change />
    <caused-by-change-order />
    <incident-priority />
    <impact>None</impact>
    <urgency />
    <severity />
    <earliest-open-date>10/28/2011 03:03 PM</earliest-open-date>
    <latest-open-date />
    <earliest-close-date />
    <latest-close-date />
    <parent />
    <earliest-resolve-date />
    <latest-resolve-date />
    <is-child />
    <root-cause />
    <sla-violation />
    <is-template />
    <number-of-records>-1</number-of-records>
    <additional-search-arguments />
  </arguments>
</casd-request>

The following figure illustrates the adapter response for the sample request:

Sample adapter response for the Find Incident operation


<casd-response>
  <metadata>
    <status>success</status>
    <response-count>1</response-count>
  </metadata>
  <responses>
    <response>
      <metadata>
        <status>success</status>
        <count>1</count>
      </metadata>
      <items>
        <item>
          <Handle>cr:400003</Handle>
          <description></description>
          <is-active>YES</is-active>
          <configuration-item></configuration-item>
          <assignee>l1,f1 f2,m1</assignee>
          <call-back-date></call-back-date>
          <call-back-flag>0</call-back-flag>
          <incident-area></incident-area>
          <caused-by-change-order></caused-by-change-order>
          <change></change>
          <charge-back-id></charge-back-id>
          <close-date></close-date>
          <created-via>3554</created-via>
          <affected-end-user>Gupta,Shankar,Kumar</affected-end-user>
          <event-token></event-token>
          <group></group>
          <event-token></event-token>
          <extern-ref></extern-ref>
          <extern-token></extern-token>
          <id>400003</id>
          <impact>None</impact>
          <incident-priority>0</incident-priority>
          <reported-by>ServiceDesk,,</reported-by>
          <macro-predicted-violation>0</macro-predicted-violation>
          <open-date>10/28/2011 03:03 PM</open-date>
          <outage-end-time></outage-end-time>
          <outage-start-time></outage-start-time>
          <parent></parent>
          <persistent-id>cr:400003</persistent-id>
          <predicted-sla-violation>0</predicted-sla-violation>
          <priority>None</priority>
          <problem></problem>
          <incident-number>48</incident-number>
          <resolve-date></resolve-date>
          <root-cause></root-cause>
          <severity></severity>
          <sla-violation>0</sla-violation>
          <base-template></base-template>
          <status>Open</status>
          <string1></string1>
          <string2></string2>
          <string3></string3>
          <string4></string4>
          <string5></string5>
          <string6></string6>
          <summary></summary>
          <template-name></template-name>
          <support-lev></support-lev>
          <time-spent-sum>00:00:43</time-spent-sum>
          <type>Incident</type>
          <urgency></urgency>
        </item>
      </items>
    </response>
  </responses>
</casd-response>

Find Incident operation for the CA Service Desk adapter

Comments