The SOAP header contains authentication data, locale information, and other required or optional data. The SOAP header element is mandatory for calls to the BIRT iHub. Using the SOAP header, parser tools can locate key information without having to parse the entire message.
The following example shows a typical SOAP header with authentication and locale information:
The Actuate Information Delivery API extends the standard SOAP header to use the following elements.
AuthId
When the client logs in using the Actuate Information Delivery API, the system returns a system-generated, encrypted AuthId string in the Login response. All requests except Login requests must have a valid AuthId in the SOAP header. The header passes this ID to BIRT iHub for validation.
The example shows a typical AuthId. In subsequent requests in the same session, the AuthId identifier appears in the SOAP header. AuthId expires after a configurable period of time.
In the example, AuthId contains two attributes:
soapenv:actor
The value for actor, "http://schemas.xmlsoap.org/soap/actor/next", is a URI indicating that this message is for the first SOAP application capable of processing it.
soapenv:mustUnderstand
Indicates that the actor must understand and process the message and, if it cannot, the actor must return a SOAP fault containing the value specified by the attribute. The mustUnderstand attribute can have a value of 0 or False, or 1 or True.
ConnectionHandle
An optional element that supports keeping a connection open to view a persistent document. ConnectionHandle is a session ID of the object.
ConnectionHandle supports phased downloading and viewing of a persistent report in the volume to improve performance. When ConnectionHandle is present in the header, iHub System ignores the value for TargetVolume.
ConnectionHandle returns in two ways:
As an element of a document generation response when the document is transient and progressive viewing is enabled. BIRT iHub System routes subsequent viewing requests to the BIRT iHub that generated the transient document.
As a response to a viewing request, to ensure that subsequent requests by the same user go to the same View service until the report data changes. If the report name changes but the data remains the same, the View service displays the same report. If ConnectionHandle is present in the SOAP header, the system routes subsequent viewing requests to the same View service that returned the ConnectionHandle.
DelayFlush
A Boolean element that tells BIRT iHub to write updates to the disk when the value is False.
FileType
An element that specifies the file type to run, such as an HTML or BIRT design (.rptdesign) file. Specify FileType in the SOAP header for all execute, submit, and view IDAPI requests, such as ExecuteReport, SelectPage, or GetContent.
When running a design that specifies a TargetResourceGroup, specify FileType in the SOAP header. BIRT iHub System looks for a machine that can execute that file type. The default setting is for BIRT iHub System to look for any available iHub to manage a request, whether or not that iHub can run the requested file type.
Locale
BIRT iHub uses this element to format data using the language, date and time conventions, currency and other locale-specific conventions before returning the data to the client. If the client does not specify another locale, BIRT iHub System uses the client’s default locale.
TargetResourceGroup
An optional element that supports assigning a synchronous report generation request to a specific resource group at run time. When using ExecuteReport to run a BIRT design that specifies a TargetResourceGroup, you must specify FileType in the SOAP header.
TargetServer
An optional element that refers to the BIRT iHub within a cluster to which to direct the request. Use TargetServer for requests pertaining to system administration, such as GetFactoryServiceJobs and GetFactoryServiceInfo.
TargetVolume
Refers to the volume to which to direct the request. Use this optional element of the SOAP header to route a request to a volume other than the default volume for the system. In iServer Release 11 and iHub 2, the Login message required specifying the volume name using TargetVolume in the SOAP header and Domain in the SOAP message body. In iHub 3, the Login message no longer requires specifying a volume name using TargetVolume in the SOAP header or Domain in the SOAP message body.
RequestID
An optional element that represents a unique value identifying the SOAP request.
soapenv:actor