This chapter describes the technical format of E-Bonding Runbook messages. In the following chapters, the structure of E-Bonding Runbook messages is described.

E-Bonding Runbook Messages SOAP Header

A message which is sent via SOAP web services either from E-Bonding Runbook to a partner or from a partner to E-Bonding Runbook must contain beside the XML body with the content of the message mandatory a defined XML format and control header data.
A E-Bonding Runbook XML message consists of various parts. In basic there are three blocks:

• The BAO ORCA header
• The E-Bonding Runbook XML header
• The E-Bonding Runbook body content

This chapter describes the first two blocks. The body block is explained in the following chapters.

Atrium Orchestrator ORCA WSDL

For inbound communication of a partner to E-Bonding Runbook using SOAP web services the BAO ORCA WSDL must be utilized.
ORCA WSDL:
 http(s)://AO-SERVER:AO-SERVER-PORT/baocdp/orca?wsdl
Detailed information of requesting the BMC Atrium Orchestrator ORCA services can be found in the BMC software documentation.

Atrium Orchestrator ORCA Header

The request of a E-Bonding Runbook message from a partner using SOAP web services is always done with the BAO ORCA "executeProcess" Web Service operation. It requires a defined XML format for the message which is shown below.
E-Bonding Runbook Message Sample XML: ORCAHeader.xml
<soapenv:Envelope xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-AABE8C2CC2F89FBB8014066361859212">
<wsse:Username>BAO USER NAME</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">BAO USER PASSWORD</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<soa:executeProcess>
<soa:gridName>BAO GRID NAME</soa:gridName>
<soa:processName>BAO E-BONDING RUNBOOK PROCESS NAME</soa:processName>
<soa:parameters/>
</soa:executeProcess>
</soapenv:Body>
</soapenv:Envelope>
Figure 6 ORCA XML Header
The following table describes the dynamic components of the AO ORCA Header:

Below the tag "<soa:parameters>" the second part of the message is generated, the E-Bonding Runbook header. It is described in chapter 5.1.4.
 Detailed information of requesting the BMC Atrium Orchestrator ORCA services can be found in the BMC software documentation.

E-Bonding Runbook BAO Process Names

Any E-Bonding Runbook operation is represented by a BMC Atrium Orchestrator process. The inbound processes can be used by E-Bonding Runbook partner systems.
 Complete lists of process names are available in the E-Bonding Runbook Message Library guides.

E-Bonding Runbook XML Header

The E-Bonding Runbook header contains the needed control data for the communication with the E-Bonding Runbook platform. The E-Bonding Runbook header is identical for in- and outbound messages. It can be found within the message below the tag "<soa:parameters>". The structure of the E-Bonding Runbook header is shown below:
E-Bonding Runbook Message Sample XML: Header.xml
<soa:parameters>
<soa:Input>
<soa:Parameter>
<soa:Name required="true">MessageID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>MESSAGE ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">TransactionID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>TRANSACTION ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">PartnerID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>PARTNER ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">Operation</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>E-BONDING MESSAGE NAME</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">ITSMTicketID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>ITSM TICKET ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">PartnerTicketID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>PARTNER TICKET ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">Timestamp</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>ACTUAL TIMESTAMP</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">Body</soa:Name>
<soa:Value soa:type="xs:anyType">
<soa:XmlDoc />
</soa:Value>
</soa:Parameter>
</soa:Input>
</soa:parameters>
Figure 7 E-Bonding Runbook XML Header
The following table describes the dynamic components of the AO ORCA Header:

Below the tag "<soa:xmlDoc>" the third part of the message is generated, the E-Bonding Runbook Body Content. The content of the body is – depending of the E-Bonding Runbook message – structured differently and is described in the following chapters.
Important:
The content, which can be delivered from the partner system within the E-Bonding Runbook Body Content, is displayed below the header "XML Request Format (Body Part)".

E-Bonding Runbook System Messages

This chapter describes the E-Bonding Runbook system acknowledges DACK and PACK. For a general description see chapter 3.9.

DACK (E-Bonding Runbook Response)

E-Bonding Runbook sends a synchronous DACK response for every inbound message.
 The format of the DACK message is static and displayed below.
E-Bonding Runbook Message Sample XML: DACK.xml
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns1:executeProcessResponse xmlns:ns1="http://bmc.com/ao/xsd/2008/09/soa">
<ns1:Output>
<ns1:Output>
<ns1:Parameter>
<ns1:Name>MessageID</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<MessageID>MESSAGE ID</MessageID>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>Operation</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<Operation>E-BONDING MESSAGE NAME</Operation>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>PartnerID</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<PartnerID>PARTNER ID</PartnerID>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>PartnerTicketID</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<PartnerTicketID>PARTNER TICKET ID</PartnerTicketID>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>

Figure 8 DACK – E-Bonding Runbook Response (Part 1)
<ns1:Parameter>
<ns1:Name>ITSMTicketID</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<PartnerTicketID>ITSM TICKET ID</PartnerTicketID>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>Timestamp</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<Timestamp>ACTUAL TIMESTAMP</Timestamp>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>TransactionID</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<TransactionID>TRANSACTION ID</TransactionID>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>Status</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<Status>DACK STATUS</Status>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
<ns1:Parameter>
<ns1:Name>StatusText</ns1:Name>
<ns1:Value ns1:type="xs:anyType">
<ns1:XmlDoc>
<StatusText>DACK STATUS TEXT</StatusText>
</ns1:XmlDoc>
</ns1:Value>
</ns1:Parameter>
</ns1:Output>
</ns1:Output>
</ns1:executeProcessResponse>
</S:Body>
</S:Envelope>
Figure 9 DACK – E-Bonding Runbook Response (Part 2)
The following table describes the dynamic components of the system message DACK:

DACK (Partner Response)

E-Bonding Runbook expects a synchronous response to messages sent to a partner system. Outbound messages are generated by E-Bonding Runbook within the partner outbound "enabler". The expected DACK of the partner must contain at least the information that the message has been received un-/ successful (asynchronous link) or has been processed un-/ successful (synchronous link).
The response format of the DACK message is not defined strict but can be defined per partner interface separately.

PACK Outbound Message (E-Bonding Runbook Request)

E-Bonding Runbook send an asynchronous PACK request for every inbound message that has been processed.
The PACK is generated within the partner outbound "enabler" and contains the information that the inbound message has not only been received but also un-/ successful processed.
The response format of the PACK message is not defined strict but can be defined per partner interface separately.
The following values are available and can be used to define a E-BONDING RUNBOOK PACK request within the partner outbound "enabler":

Important:
The content which can be delivered for response from the partner system within the E-Bonding Runbook Body Content is displayed below the header "XML Response Format (Body Part PACK)".

PACK Inbound Message (Partner Request)

E-Bonding Runbook expects an asynchronous PACK request for every sent message.
 The PACK confirms that a message (sent from E-Bonding Runbook to the partner) has not only been received but also un-/ successful processed. The format of the PACK message must be processed in E-Bonding Runbook automatically is static and displayed below.
E-Bonding Runbook Message: incPACK
E-Bonding Runbook Message Sample XML: incPACK.xml
<soa:parameters>
<soa:Input>
<soa:Parameter>
<soa:Name required="true">MessageID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>MESSAGE ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">TransactionID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>TRANSACTION ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">PartnerID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>PARTNER ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">Operation</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>E-BONDING MESSAGE NAME</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">ITSMTicketID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>ITSM TICKET ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">PartnerTicketID</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>PARTNER TICKET ID</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">Timestamp</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>ACTUAL TIMESTAMP</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="true">Status</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>STATUS</soa:Text>
</soa:Value>
</soa:Parameter>
<soa:Parameter>
<soa:Name required="false">StatusText</soa:Name>
<soa:Value soa:type="xs:string">
<soa:Text>STATUS TEXT</soa:Text>
</soa:Value>
</soa:Parameter>
</soa:Input>
</soa:parameters>
Figure 10 incPACK Request XML Sample
The following table described the dynamic components of the system message PACK:

BGIFault

Resend Messages

As a part of the interface recovery strategy, E-Bonding Runbook contains a special operation sysResendMessages. The operation can be called by partner systems.
E-Bonding Runbook Message XSD: sysResendMessages.xsd
E-Bonding Runbook Message Sample XML: sysResendMessages.xml

XML Request Format (Body Part):
<?xml version="1.0" encoding="UTF-8"?>
<bgi:sysResendMessages xmlns:bgi="http://www.vipcon.com/BGI/sysResendMessages"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.vipcon.com/BGI/sysResendMessages sysResendMessages.xsd ">
<bgi:From>0</bgi:From>
<bgi:Unit>ms</bgi:Unit>
</bgi:sysResendMessages>

Figure 12 sysResendMessages Request XML Sample
Besides the well-known E-Bonding Runbook header information, the body offers attributes that must be provided.
 The following table describes the values of the system message:

The result is, that all E-Bonding Runbook outbound requests/ responses in status ERROR are re-send to the partner system newer as the "bgi:From" filter.
 Additional information for this operation is provided in the whitepaper VIPCON E-Bonding Runbook Unavailability Scenarios.
Hint: With version 2.0, a re-send of a failed message can be triggered within the E-Bonding Runbook Log Console by an administrator.

E-Bonding Runbook Custom Field Handling

E-Bonding Runbook supports customer ITSM Suites that have been extended by additional fields (custom Fields).
This means, E-Bonding Runbook can handle custom fields that have been created on the following ITSM forms:

• HPD:Help Desk
• HPD:WorkLog
• CHG:Infrastructure Change
• CHG:WorkLog
• TMS:Task

This listing shows the E-Bonding Runbook messages that support the transfer of custom field data:

• incCreateTicket (Request)
• incUpdateTicket (Request)
• incCreateTask (Request)
• incUpdateTask (Request)
• incCreateWorkInfo (Request)
• incGetTicketDetails (PACK Response)
• incGetTaskDetails (PACK Response)
• incGetWorkInfoDetails (PACK Response)
• incGetCIBasicDetails (PACK Response)
• chgCreateTicket (Request)
• chgUpdateTicket (Request)
• chgCreateTask (Request)
• chgUpdateTask (Request)
• chgCreateWorkInfo (Request)
• chgGetTicketDetails (PACK Response)
• chgGetTaskDetails (PACK Response)
• chgGetWorkInfoDetails (PACK Response)
• chgGetCIBasicDetails (PACK Response)

The feature custom Fields enables customers to make use of ITSM fields that are not covered by the E-Bonding Runbook.
 The request/ response XML structures contain an element block that is used to send/ request custom field data:
<CustomAttributes>
<!-- 0 to many-->
<CustomAttribute ARID="SAMPLEFIELDID" Name="SAMPLEFIELDNAME" />
</CustomAttributes>
Figure 13 CustomAttributes XML Sample
The element "CustomAttribute" can be used many times. The table below shows information about the element attributes:

In addition, custom fields must be configured within the VIP_BGI_Core_Configuration module configuration.

Figure 14 BAO Custom Fields Configuration
Additional note for validations: Custom field values are not validated by E-Bonding Runbook.