Element

Definition

Required

<operation-name>

Specifies the name of the operation: update-incident

Yes

<arguments>

Specifies a list of arguments that are required for the create-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>

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

<query-parameters>

Specifies the input items required to find the incident record that must be updated

You can specify the following XML elements within this element:

• <incident-number>
  
• <assignee>
  
• <group>
  
• <status>
  
• <priority>
  
• <is-active>
  
• <incident-area>
  
• <configuration-item>
  
• <reported-by>
  
• <affected-end-user>
  
• <affected-end-user-id>
  
• <affected-end-user-location>
  
• <affected-end-user-organization>
  
• <summary>
  
• <description>
  
• <problem>
  
• <change>
  
• <caused-by-change-order>
  
• <incident-priority>
  
• <impact>
  
• <urgency>
  
• <severity>
  
• <earliest-open-date>
  
• <latest-open-date>
  
• <earliest-resolve-date>
  
• <latest-resolve-date>
  
• <earliest-close-date>
  
• <latest-close-date>
  
• <parent>
  
• <is-child>
  
• <root-cause>
  
• <sla-violation>
  
• <is-template>
  
• <number-of-records>
  
• <additional-search-arguments>

Yes

<incident-number>

Specifies the incident identification number  

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 a summary for the incident

Valid values: Any string value

No

<description>

Specifies a description for the incident

Valid values: Any string value 

No

<problem>

Specifies the problem record associated with the incident

Valid values: A valid problem number

No

<change>

Specifies the change record associated with 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 priority associated with the incident

Valid values: A valid incident priority

No

<impact>

Specifies the impact 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

<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

No

<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

At any time, a maximum of 250 records will be retrieved.

Valid values: Any positive integer  

Default value: -1 (Retrieves all the 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

<update-parameters>

Specifies the parameters being updated in the incident record 

You can specify the following XML elements within this element:

• <affected-end-user>
  
• <incident-area>
• <status>
• <priority>
• <assignee>
  
• <group>
  
• <configuration-item>
  
• <severity>
  
• <urgency>
  
• <impact>
• <problem>
  
• <call-back-date>
• <root-cause>
• <change>
• <caused-by-change-order>
• <outage-start-time>
• <outage-end-time>
  
• <summary>
• <description>
  
• <parent>
  
• <template-name>

Yes

<affected-end-user>

Specifies a new value for 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

<incident-area>

Specifies a new value for 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

<status>

Specifies the new value for 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 a new value for 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

<assignee>

Specifies a new value for the name of the person to whom the incident record is assigned

Note

If a group is also specified, the assignee should be a part of that group.

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 a new value for the name of the group to which the incident record is assigned

Valid values: A valid group name

No

<configuration-item>

Specifies a new value for the configuration item associated with the incident record

Valid values: A valid configuration item name

No

<severity>

Specifies a new value for 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

<urgency>

Specifies a new value for 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

<impact>

Specifies a new value for the impact 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

<problem>

Specifies a new value for the problem record associated with the incident

Valid values: A valid problem number

No

<call-back-date>

Specifies a new value for the callback date associated with the incident 

Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.

No

<root-cause>

Specifies a new value for 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

<change>

Specifies a new value for the change record associated with the incident record

Valid values: A valid change number

No

<caused-by-change-order>

Specifies a new value for the change record that caused the incident

Valid values: A valid change number

No

<outage-start-time>

Specifies a new value for the outage start time associated with the incident

Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.

No

<outage-end-time>

Specifies a new value for the outage end time associated with the incident

Valid values: DateTime in the format mm/dd/yyyy hh:mm am/pm. For example, 10/04/2011 09:27 pm.

No

<summary>

Specifies a new summary value for the incident

Valid values: Any string value

No

<description>

Specifies a new value for the description of the incident

Valid values: Any string value 

No

<parent>

Specifies a new value for the parent incident associated with the incident record

Valid values: A valid incident number

No

<template-name>

Specifies the name of the template that will be used to create the change order

No