7EAI HTTP Transport
EAI HTTP Transport
This chapter discusses EAI HTTP Transport, its methods, and workflow examples illustrating using EAI HTTP Transport with different methods. This chapter includes the following topics:
About the EAI HTTP Transport
The use of the Internet protocols and technologies for business (such as HTTP, HTML, and XML) has created a requirement for automatically sending Siebel data to external sites, either on the Internet or outside the enterprise firewall to external Web sites. To meet this need, the technologies built into Siebel EAI provide a way to send and receive messages over HTTP. Siebel EAI HTTP Transport business service lets you send XML messages over HTTP to a target URL (Web site). The Siebel Application Interface (AI) serves as the transport to receive XML messages sent over the HTTP protocol to a Siebel application.
The EAI HTTP Transport business service is based on the CSSHTTPTransService class. You can use one of the following two methods with this transport:
Send. This method supports outbound messages (XML documents sent from a Siebel application to an external system). The Send method means that the response coming back from the external application is not interpreted by the Siebel application, but the Web server returns a correct HTTP response.
SendReceive. This method supports outbound messages (XML documents sent to a Siebel application from an external system). This method is called Send and Receive a Response and the HTTP response body is the response for the request.
Each method has its own arguments, techniques, and applications. The EAI HTTP Transport allows you to send messages across the Internet using the standard HTTP protocol. Using this transport, you can send messages to any URL. The XML document sent can then be acted upon by any Web-based application, including those written in Java, JavaScript, VBScript, or any other Web-enabled technology.
System Requirements for Using the EAI HTTP Transport
To use the EAI HTTP Transport, you must install and configure the following components of Siebel Business Applications, and make sure that they are operational:
Siebel Application Interface (AI). To provide the necessary HTTP listening services and invoke the requisite workflow through a business service method.
Workflows. To accept incoming XML documents and pass them through an integration object into the business object to update Siebel data.
Business services. To execute the necessary actions.
Selecting the Appropriate Business Service for HTTP
The business service required to process a given XML document that is received from an external system using the EAI HTTP Transport depends on the processing you perform on the data. The way to approach this is to accept the output of the EAI HTTP Transport and store it as a process property that you define, and process it later in the workflow based on the format of the data.
For example, you could pass the string into a custom business service that you build to parse the input, query some data in a Siebel application based on the data, and then update the appropriate field in the Siebel application. If the data is formatted as a SiebelMessage, then you could use the EAI XML Converter business service with the XMLDocToIntObjHier method to pass an integration object instance to the EAI Siebel Adapter for further processing.
Using POST and GET
The HTTP protocol supports the GET and POST methods. You might be familiar with these methods if you have ever built a Web-based CGI form:
GET. Requests a representation of the specified resource. GET is the most common method used on the Web today.
POST. Submits data to be processed, such as from an HTML form, to the identified resource. The data is included in the body of the request. This might result in the creation of a new resource, updates to existing resources, or both.
The EAI HTTP Transport imposes certain restrictions on your use of transport features when using the POST or GET method. The following table identifies restrictions on these HTTP methods.
| Method | Restriction |
|---|---|
Get |
The HTTP Body has no significance when using GET. During a GET process, only the universal resource locator (URL) is used for the request.
Note: Passing user credentials in the URL is not supported in Siebel CRM.
|
Post |
The HTTP Body is relevant only when using POST. The HTTP Body is encoded with a default mechanism used to encode URLs. The HTTP Content-Type |
EAI HTTP Transport Named Subsystems
The EAI HTTP Transport, like every other Siebel transport, reads required parameters from a named subsystem instead of the configuration (.cfg) file. The eai.cfg file entries list the external service name and the name of the named subsystem to be used. For example:
SiebelQuery = SiebelQueryDispatch
There is no [Properties] section for SiebelQueryDispatch in the .cfg file. The name is used to look up the named subsystem list and dispatch accordingly. Use named subsystems for property specification. Predefined named subsystems have been created for you already, such as:
SiebelQueryDispatch
SiebelExecuteDispatch
SiebelUpsertDispatch
For a discussion of named subsystems for Siebel EAI, see EAI Transports and Interfaces Overview. For more information about named subsystems, see Siebel System Administration Guide.
EAI HTTP Transport Method Arguments
In addition to the method arguments (data handling parameters) in Common EAI Transport Parameters, EAI HTTP Transport methods take the arguments presented in the following table. Parameters are optional unless specified as required.
| Parameter | Display Name | Description |
|---|---|---|
|
User-Defined Message Text |
Input and Output data passed as a string. This is the value stored in the Value field of the property set, either input or output. If you specify the HTTPRequestBodyTemplate, then the |
CharSetConversion |
Character Set Conversion for Text Data |
Character set conversion from the external system. The default is None. |
ConnectionSubsystem |
Connection Subsystem |
Subsystem containing connection parameters. |
ConverterService |
Converter Service |
Business service used to serialize and unserialize hierarchical data to raw buffer and the reverse. Must implement the DocToHier and HierToDoc methods. The default is EAI XML Converter. |
DataHandlingSubsystem |
Data Handling Subsystem |
Subsystem containing data handling parameters. |
EndOfData |
End of Data |
Output parameter whose value is True if the end of the data has been reached. |
HTTPAccept |
HTTP Accept |
Default is |
HTTPAllowCaching |
Allow Caching |
Default is N. By default, the responses for specific URL addresses are not cached by the EAI HTTP Transport. Set this flag to Y to enable caching. Note that this can lead to undesirable side effects, as old data from earlier requests can be exposed from the cache buffer. |
HTTPAllowPersistentCookies |
Allow Persistent Cookies |
Default is N. A session cookie is used to tie requests and logoff operations to the user session started at the login, when communicating with any session-cookie-based system. Leaving this flag set to N leaves the persistence of cookies in the control of the EAI HTTP transport, which is the default behavior. All session cookies persist in memory only as long as the current session. Session cookies are not written to disk. If you want to use persistent cookies, that is, if persistence between logins is required and you want cookies to be written to disk, then set the parameter to Y. |
HTTPCertAuthority |
HTTP Cert Authority |
The name of the authority that issues the mutual authentication certificate, in RDN (Relative Distinguished Name) format. For example: CN=ServerName123, OU=Department, O=organization, L=Location, C=Country, E=email@example.com represents a certificate issued by Microsoft Certificate Authority running on the server ServerName123. RDN notation is case insensitive. For information about configuring client TLS authentication, see Siebel Security Guide. |
HTTPCertSerialNo |
HTTP Cert Serial No |
The mutual authentication certificate serial number, in hexadecimal format as a string without space characters in between. For example, the serial number 198b11d13f9a8ffe69a0 Serial numbers are case insensitive. For information about configuring client TLS authentication, see Siebel Security Guide. |
HTTPContentType |
HTTP Content Type |
Default is |
HTTPImplicitCharsetDetection |
Implicit Character Set Detection |
Default is False. This is the implicit character set detection for incoming data. Do not set it to True for self-describing documents such as XML. If set to True, then this overrides the CharSetConversion parameter. |
HTTPLoginBodyTemplate |
Login Body Template |
Specifies the HTTP request body that is used when HTTPLoginURLMethod is POST. By putting login information into the HTTP body (as opposed to putting it into the URL) for sending, this method provides stronger security than sending the login information in the URL. Generally, the login parameters in a login query are specified in the body of the request that uses the POST method. Required for session mode only if the HTTPLoginMethod parameter is set to POST. |
HTTPLoginMethod |
Login Method |
HTTP method to be used for logging in. If no Login Method is specified, then this parameter defaults to the HTTPRequestMethod value. Required for session mode. |
HTTPLoginURLTemplate |
Login URL Template |
Template for the URL used for the login operation. This operation is separate from the request operation and assumes communication mode is session mode. If there is a separate login, then one or more request and response messages are expected. Required for session mode. |
HTTPLogoffMethod |
Log Off Method |
Defaults is HTTPLoginMethod. HTTP method to be used for logging off. Required for session mode. |
HTTPLogoffURLTemplate |
Log Off URL Template |
Template for the URL that is used for the logoff operation. This operation is separate from the request operation and assumes that the mode of communication is session mode. If it is set, then the logoff operation is completed. Otherwise, logoff is skipped. The purpose of the logoff operation is to end a session that was started with the corresponding login. Required for session mode. |
HTTPMaxIdleSeconds |
Max Idle Seconds |
Maximum number of seconds to allow connections to be idle. After the elapsed max idle time, the connection is invalidated and restarted. |
HTTPNoAutoRedirect |
No Auto Redirect |
Default is N. This means auto-redirect is enabled. Setting this parameter to Y disables auto-redirection of messages to other URLs. |
HTTPRequestBodyTemplate |
Request Body Template |
HTTP Body to use with the POST method. This overrides any request body specified in the Value field of the input property set. |
HTTPRequestMethod |
Request Method |
HTTP method to use with the data request, such as POST or GET. Required for both session and sessionless modes. |
HTTPRequestURLTemplate |
Request URL Template |
Template for the request URL, which is the address to which the data is sent or from which a response is requested. Required for both session and sessionless modes. |
HTTPSleepTime |
Sleep Time |
Default is 120000 milliseconds. The timeout interval on login, send, and logoff requests in milliseconds. |
HTTPUserAgent |
HTTP User Agent |
Default is |
IgnoreCharSetConvErrors |
Ignore Character Set Conversion Errors |
Ignore character set conversion errors if True. Else, propagate the errors to the caller (default behavior). |
TimedOut |
Timed Out |
True if receive timed out and no data was available. False if request completed. |
Sending a Message Using the EAI HTTP Transport
The following procedure demonstrates how to send information from a Siebel application to another Web-based application using the EAI HTTP Transport.
To send a message
Create an integration object in Siebel Tools based on a given business object.
Refine the integration object created in the previous step to specify just those business components and fields that you want to exchange with the external application.
Note: For details about integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.-
Set up a workflow in Siebel Tools containing the following steps, as shown in the following image, to send this information to an external system:
EAI Siebel Adapter
EAI XML Converter
EAI HTTP Transport
Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.Create the following process properties:
Name Data Type In/Out Value Account Message
Integration Object
In/Out
Not applicable
Account XML
Binary
In/Out
Not applicable
Error Code
String
In/Out
Not applicable
Error Message
String
In/Out
Not applicable
Object Id
String
In/Out
Row Id of an account
Siebel Operation Object Id
String
In/Out
Not applicable
Set up the first step of the workflow after Start to use the EAI Siebel Adapter with the Query method to query the information from the Siebel Database, using the following input and output arguments:
Input Argument Type Value Property Name Property Data Type OutputIntObjectName
Literal
Sample Account
Not applicable
Not applicable
PrimaryRowId
Process Property
Not applicable
Object Id
String
Property Name Type Output Argument Account Message
Output Argument
SiebelMessage
Set up the second step to use the EAI XML Converter with the IntObjHierToXMLDoc method to convert the data extracted from the Siebel Database to XML format, using the following input and output arguments:
Input Argument Type Property Name Property Data Type SiebelMessage
Process Property
Account Message
Integration Object
Property Name Type Output Argument Account XML
Output Argument
<Value>
Set up the third step to use the EAI HTTP Transport with the Send method to send the information to the external system, using the following input and output arguments:
Input Argument Type Value Property Name Property Data Type <Value>
Process Property
Not applicable
Account XML
String
HTTPRequestMethod
Literal
POST
Not applicable
Not applicable
HTTPRequestURLTemplate
Literal
http://$web_address$/$request_param$
Not applicable
Not applicable
Property Name Type Output Argument Account XML
Output Argument
<Value>
Save the workflow and run it from the Workflow Simulator.
Specify how this workflow is invoked, using one of the following methods:
Configure the RunTime Events to trigger the workflow.
Create a button on the appropriate view in the Siebel application to call this workflow.
Use workflow policies on the opportunity business object to trigger the workflow.
Using the EAI HTTP Transport for Inbound Integration
The EAI HTTP Transport uses the Siebel Application Interface (AI) to provide inbound messaging from an application that uses HTTP. The EAI HTTP Transport can be used in session or sessionless mode.
The following topics are discussed:
Preparing to Use the EAI HTTP Transport for Inbound Integration
To use the EAI HTTP Transport for inbound integration, you must perform certain tasks that might not be required when using the EAI HTTP Transport for outbound integration:
Install and configure the Siebel Application Interface (AI), Siebel Gateway, and Siebel Server.
Start the Siebel Application Interface (AI), Siebel Gateway, and Siebel Server.
Start the Siebel Application Interface (AI) to be able to use the EAI HTTP Transport.
Configure AI to run the EAI HTTP Transport for inbound integration. See Specifying HTTP Parameters for Inbound Integration.
Set certain configuration parameters for whatever Siebel Server you are using.
The server component you are running must be a Siebel Application Object Manager component.
http://Web_Server_Name/siebel/app/eai-/lang in a Web browser on any computer that has connectivity to the Application Interface to check the connectivity between the computer issuing the URL (for the EAI HTTP Transport) and AI. This URL brings up the login page of the Siebel application corresponding to
ObjectManager_lang, confirming the connectivity between AI and the URL-issuing computers.
Specifying HTTP Parameters for Inbound Integration
The EAI HTTP Transport is built into Siebel Application Interface (AI). To use it, you set certain configuration parameters of the AI profile of the application interface. Your Siebel application installation includes a configuration file called AI profile. Review the configuration file to make sure that the parameters are set properly. Use named subsystems to dispatch to a workflow as described in Using Named Subsystems for Transport Parameters.
To configure AI to run the EAI HTTP Transport for inbound integration
Launch Siebel Management Console (SMC).
Open the AI profile deployed to AI.
Look for the application
eai (lang). Where lang is the three-letter language code for the language you are using, such as enu for U.S. English.If this application does not exist then add one with name as eai and Object Manager as
EAIObjmgr_lang.In the Basic Information section of the
eai (lang)application, select Configure EAI HTTP Inbound Transport parameter to enable the HTTP inbound transport.Submit the AI profile.
Using the EAI HTTP Transport in Session Mode
The session mode uses the HTTP session cookie to retain the session information between the HTTP requests. The session mode can be viewed when a sequence of calls is supported from an HTTP application into the EAI HTTP Transport.
To use the EAI HTTP Transport in session mode
Log in to the Siebel application. If successful, then an HTTP session cookie named _sn is returned in an HTTP set-cookie header.
Submit one or more subsequent requests.
Each request is intended as a call to a Siebel business service or workflow depending on the configuration of the named subsystem in use. Requests must contain the session cookie (_sn) from the previous step in either the HTTP cookie header or the URL string as a parameter.
Log off. The request must contain the session cookie from Step 1. The cookie refers to the session to be closed.
Example Requests for the HTTP Protocol in Session Mode
HTTP protocol requests can be represented as URLs for HTTP GET, and as a combination of URL and request body for HTTP POST. The following topics explain in detail how each of the session mode calls is configured.
The following table describes each of the Login HTTP Request variables for session mode.
| Variable | Description |
|---|---|
webserver |
URL of the Web server that has Siebel Application Interface (AI) installed, such as www.myserver.com. |
path |
Virtual path on the server referring to the specific AI profile configuration. The default is |
source |
Named subsystem as specified in the |
username |
Siebel user name for the Application Object Manager login.
Note: Passing user credentials in the URL is not supported in Siebel CRM.
|
password |
Password for the login user name. |
Login HTTP Request Example
In this example, if the call completes successfully, then it returns a session cookie:
- Using HTTP POST:
URL = http://webserver/path HTTP Body = SWEExtSource=source&SWEExtCmd=ExecuteLogin&UserName=username&Password=password
Example Login URL:
http://www.example.com/siebel/app/eai/enu
Data Exchange HTTP Request Example
In this example, for the call to complete successfully, it must include the session cookie from the login:
Using HTTP GET:
URL = http://webserver/path?SWEExtData=data text
where data text is the business service input data. Most of the time, this is the text of an XML document that on the server side is converted to a property set and passed to the business service.
With GET requests, the XML document is included in the URL. Therefore the XML document must be URL-encoded. For example, the URL encoding for a space is %20.
To make sure that the decoded XML document passed to the XML Converter is valid, use an escape code for any special characters (that is, use an ampersand, followed by the special character’s escape characters, followed by a semi-colon) before encoding them for the URL. For more information, see the topic on special (escape) characters in XML Reference: Siebel Enterprise Application Integration
Using HTTP POST:
URL = http://webserver/path HTTP Body = data text
where data text is the business service input data. Most of the time, this is the text of an XML document that on the server side is converted to a PropertySet and passed to the business service.
Data that is sent as part of the URL must be in Unicode format before it is encoded for the URL. POST requests can send the data without URL encoding but must include the Content-Type HTTP header. The Content-Type must specify the character set of the incoming data, for example:
Content-Type=text/xml;charset="UTF-8"
Note: For XML messages being received by way of the Inbound HTTP Transport, only a Unicode (UTF-8 or UTF-16) format (with accordant encoding XML-processing header attribute and encoded XML data) is allowed. No ISO or Windows code pages are accepted.Example Request URL:
http://www.exampleserver.com/siebel/app/eai/enu?SWEExtData=<?xml version="1.0" encoding="UTF-8"?> <SiebelMessage MessageId="" MessageType="Integration Object" IntObjectName="Sample Account"> <ListofSampleAccount> <Account> <Name>A. K. Parker Distribution</Name> <ListOfContact> <Contact> <FirstName>Stan</FirstName> <LastName>Graner</LastName> </Contact> </ListOfContact> </Account> </ListofSampleAccount> </SiebelMessage>
Logoff HTTP Request
This request must include the session cookie from the login request.
Using HTTP GET:
URL = http://webserver/path?SWEExtCmd=LogoffNote: Always use HTTP GET for the Logoff HTTP Request.Example Logoff URL:
http://www.example.com/siebel/app/eai/enu?SWEExtCmd=Logoff
Using the EAI HTTP Transport in Sessionless Mode
Using the EAI HTTP Transport in sessionless mode allows you to use one URL to perform Login, Request, and Logoff in a single HTTP request. This mode does not use session cookies because there is no login session between the HTTP requests. The disadvantage of this mode is the overhead incurred by the Application Object Manager needing to log in with every request.
The following table describes each of the variables for sessionless mode.
| Variable | Description |
|---|---|
webserver |
URL of the Web server that has Siebel Application Interface (AI) installed, such as www.myserver.com. |
path |
Virtual path on the server referring to the specific AI profile configuration. The default is |
source |
Named subsystem as specified in the |
username |
Siebel user name for the Siebel Application Object Manager login.
Note: Passing user credentials in the URL is not supported in Siebel CRM.
|
password |
Password for the login user name. |
data text |
Business service input data. Most of the time, this is the text of an XML document that on the server side is converted to a PropertySet and passed to the business service. For more information about how to pass Properties and PropertySet to Business Services, see Siebel Business Process Framework: Workflow Guide. |
Example Request for the HTTP Protocol in Sessionless Mode
In this example using HTTP POST, the URL describes the parameters for the HTTP Inbound Transport call over HTTP. Unlike session mode, the SWEExtCmd is Execute, not ExecuteLogin.
URL = http://webserver/path HTTP Body = SWEExtSource=source&SWEExtCmd=Execute&UserName=username&Password=password&SWEExtData=data text
When using the sessionless mode with the POST method, the data text includes the login credentials as well as the XML document. Therefore, it is recommended that the data text be URL-encoded and that the Content-Type header be set to application/x-www-form-urlencoded without specifying the character set (for example, ;charset=UTF-8).
Use an escape code for any special characters (that is, use an ampersand, followed by the special character’s escape characters, followed by a semi-colon) before encoding them for the URL. For more information, see the topic on special (escape) characters in XML Reference: Siebel Enterprise Application Integration.
Example for Sessionless Mode
URL = http://www.example.com/siebel/app/eai/enu
HTTP Body =
SWEExtSource=SiebelQuery&SWEExtCmd=Execute&UserName=user1&Password=login123
&SWEExtData=<?xml version="1.0" encoding="UTF-8"?>
<SiebelMessage MessageId="" MessageType="Integration Object" IntObjectName="Sample
Account">
<ListofSampleAccount>
<Account>
<Name>A. K. Parker Distribution</Name>
<ListOfContact>
<Contact>
<FirstName>Stan</FirstName>
<LastName>Graner</LastName>
</Contact>
</ListOfContact>
</Account>
</ListofSampleAccount>
</SiebelMessage>
Process of Using the EAI HTTP Transport for Inbound Messages
To use the EAI HTTP Transport for inbound messages, you complete two tasks:
Both tasks are explained in this topic. This scenario assumes incoming XML. Your business requirements dictate whether and how you adapt these steps to fit your needs.
Setting Up the Business Service
First you set up the business service for use in the workflow.
To set up the business service
Start Siebel Tools, connecting to the server.
Create or open a workspace.
Find the business service named Workflow Process Manager.
Copy this record and rename the copy EAITEST.
In the Business Service User Props list, add a new record as shown in the following image:
Enter ProcessName in the Name column.
Enter EAITEST in the Value column.
Deliver the workspace.
Note: You can also deploy the business service to the run-time database to make it available. For more information, see Integration Platform Technologies: Siebel Enterprise Application Integration.Restart the Siebel Server.
Verify that the EAI Object Manager has started.
Creating the Workflow to Receive Messages
After you set up the business service, you create a workflow to receive messages.
To create the new workflow to receive messages
Set up a new workflow in Siebel Tools containing the following steps, as shown in the following image, and give it a unique name such as EAITEST:
Incoming XML
UpdateSiebel
For information about the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.
Create the following process properties:
Name Data Type Default String In/Out Description IncomingXML
Binary
<Value>
In/Out
By creating the IncomingXML process property, anything that is sent as data is placed in this variable. This allows you to then perform a given action on that data. If the POST method was used, then the data sent in the Body is stored in this property. If the GET method was used, then the data sent in the URL is stored in this property.
Account Message
Hierarchy
Not applicable
In/Out
This is hierarchy format of the incoming XML.
<Value>
Binary
Not applicable
In/Out
Used to get the XML string that has been read or converted.
Content-Type
String
text/html
Out
It indicates the content type of the response body. If you want to see the response in the same Web page, then you must set the Default String parameter to text/html.
Set up the Incoming XML step to use the EAI XML Converter with the XMLDocToIntObjHier method. This step converts the message, using the following input and output arguments:
Input Argument Type Property Name Property Data Type <Value>
Process Property
IncomingXML
Hierarchy
Property Name Type Output Argument Account Message
Output Argument
SiebelMessage
Set up the UpdateSiebel step to use the EAI Siebel Adapter with the Insert or the Update method and the following input and output arguments to update the Siebel Database.
Input Argument Type Property Name Property Data Type SiebelMessage
Process Property
Account Message
Hierarchy
Property Name Type Value Output Argument <Value>
Literal
<h1>Update Completed</h1>
Not applicable
Note: The HTTP response for inbound requests is determined by looking at the<Value>portion of the output property set. HTTP response headers can be set by setting properties on the output property set. If the process properties are set as In/Out (the default), then the values appear as HTTP headers on the HTTP response from the Siebel Server. Set each process property that you do not want as an HTTP header to In or None (the latter if the process property is only for use inside the workflow).Save your workflow and test it using the Workflow Simulator.
For information about the Workflow Simulator, see Siebel Business Process Framework: Workflow Guide.
Handling EAI HTTP Transport Business Service Errors
A business service that is called by the EAI HTTP Transport might return an error when standard HTTP headers are used to send error information back to the caller. Each of the headers has a sequence number at the end to support the return of multiple errors. The text of each error message is captured in the Siebel-Error-Message header, and the Siebel error symbol is set in the Siebel-Error-Symbol header as follows:
Siebel-Error-Message-1: Error: error message text Siebel-Error-Symbol-1: ERR_SYMBOL ... Siebel-Error-Message-n: Siebel-Error-Symbol-n:
Inbound HTTP also returns HTTP Error 500 (Internal Server Error) to indicate that there was an error from a business service. Examine the error headers for additional error information.
Processing and Sending Outbound XML Documents
This topic explains how to use Siebel Tools and the Siebel application to set up the EAI HTTP Transport to process and send outbound XML documents. When you want to send XML messages based on Siebel integration objects to an external system across Internet-support protocols, you use the EAI HTTP Transport business service.
You can specify the parameters that control the behavior of transports in the following ways:
Specifying Parameters as Business Service User Properties
You specify parameters as business service user properties in Siebel Tools. These parameters go into effect after you have delivered the changes or deployed the business service to the run-time database. When using this method, keep the following in mind:
These parameters stay in effect as long as you continue to use the same run-time business service and do not create a newer specification for the business service parameters.
If you define the same parameter as a subsystem parameter or as a run-time property, then the subsystem parameter or run-time property overrides any values you have defined in Siebel Tools and delivered or deployed to the run-time database.
For more information about deploying business services to the run-time database, see Integration Platform Technologies: Siebel Enterprise Application Integration.
Specifying Parameters as Subsystem Parameters
You specify parameters in the Siebel client.
To specify the subsystem parameters
In the Siebel client, navigate to the Administration - Server Configuration screen, Enterprises view.
In the first list applet, select the Enterprise Server that you want to configure.
In the middle applet, click the Profile Configuration tab.
Click New to create a new component profile, then set the following parameters:
Name Value Profile
HTTP_test
Alias
HTTP_test
Subsystem Type
HTTPSubSys
In the Profile Parameters list applet (the last applet), specify the parameters required for the type of operations the subsystem supports:
Name Value HTTPRequestURLTemplate
"http://www.example.com"
HTTPRequestMethod
"GET"
Then, in the workflow on the Siebel Web Client, you specify the Connection Subsystem input argument to the HTTP Transport, and the value is the named subsystem that you created. For the case given here, it is HTTP_test. You can test the workflow in the Workflow Simulator.
About Parameters as Run-Time Properties
You specify HTTP parameters as run-time properties by passing them as values in an input property set to the EAI HTTP Transport business service. You can pass the values to the business service by way of a workflow or through a program that calls the EAI HTTP Transport business service directly.
About Parameters in Parameter Templates
Parameter templates allow you more flexibility in specifying parameters. You can use variables to specify certain elements of a given parameter value. The following example shows how to specify a variable for a login password, rather than hard-coding a password into the parameter.
HTTPLoginURLTemplate = http://www.example.com/
login.jsp?Username=ronw&Password=$PWD$
where
PWD is 421ax7 (for example)
The business service, EAI HTTP Transport in this case, receives the parameter template. The token, shown here as $PWD$, indicates that the business service looks for a parameter called PWD from a user property or run-time parameter. Dollar signs ($) delimit the token in the template definition. The token specifies the actual password variable. The token is case-sensitive: Pwd is different from PWD or pwd.
The token must be defined as either a business service user property or as a run-time parameter in the input property set. For example, you could specify the HTTPLoginURLTemplate as a user property of the business service, and username and password as run-time properties. Any logins that specify the template always use the same template, but different users can specify unique user names and passwords at run time.
Sending and Receiving Messages with the EAI HTTP Transport
You can use the EAI HTTP Transport to send and receive messages. The following procedure illustrates how you can use EAI HTTP Transport with the SendReceive method to query employee information from the Siebel Database, send it out, echo it using the Workflow Utilities ECHO service, and send it back to the workflow to write the response back to a file.
To create a workflow to send and receive messages
Create a named subsystem HTTPsendreceive_conn for subsystem HTTPSubSys using the following lines:
HTTPLoginMethod=GET HTTPLoginURLTemplate="http://websrvr.example.com:16007/myapplication/ login.jsp?usr=V1&psw=v2" HTTPLogoffMethod=GET HTTPLogoffURLTemplate="http://websrvr.example.com:16007/myapplication/ logoff.jsp" HTTPRequestMethod=POST HTTPRequestURLTemplate="http://websrvr.example.com:16007/myapplication/ data.jsp"
Create a named subsystem MyEchoSubsys for subsystem EAITransportDataHandlingSubsys using the following lines:
DispatchService="Workflow Utilities" DispatchMethod=ECHO
In your eai.cfg file, add the following line in the [HTTP Services] section:
MyEcho = MyEchoSubsys
Set up a new workflow in Siebel Tools containing the following steps, as shown in the following image:
Get Employee
Convert to XML
Send and Receive
Write to File
Note: For details on the Business Process Designer, see Siebel Business Process Framework: Workflow Guide.Create the following process properties:
Name Data Type In/Out Employee Message
Hierarchy
In/Out
Employee XML
Binary
In/Out
Error Code
String
In/Out
Error Message
String
In/Out
Object Id
String
In/Out
Response
Binary
In/Out
Retrieve the employee message using the EAI Siebel Adapter with the Query method to query the information from the database using the following input and output arguments.
Input Argument Type Value Property Name Property Data Type OutputIntObjectName
Literal
Sample Employee
Not applicable
Not applicable
PrimaryRowId
Process Property
Not applicable
Object Id
String
Property Name Type Output Argument Employee Message
Output Argument
SiebelMessage
Convert the message to XML using the EAI XML Converter with the Integration Object Hierarchy to XML Document method and the following input and output arguments to convert the message.
Input Argument Type Property Name Property Data Type SiebelMessage
Process Property
Employee Message
Hierarchy
Property Name Type Output Argument Employee XML
Output Argument
<Value>
Send and receive the converted XML message using the EAI HTTP Transport with the Send and Receive Response method and the following input and output arguments.
Input Argument Type Value Property Name Property Data Type <Value>
Process Property
Not applicable
Employee XML
String
ConnectionSubsystem
Literal
HTTPsendreceive_conn
Not applicable
Not applicable
Property Name Type Output Argument Response
Output Argument
<Value>
Write the message to the file using the EAI File Transport with the Send method and the following input arguments.
Input Argument Type Value Property Name Property Data Type <Value>
Process Property
Not applicable
Response
Binary
FileName
Literal
C:\SendRec.txt
Not applicable
Not applicable
Save your workflow and test it using the Workflow Simulator.
Examples Using HTTP Request
This topic provides the following examples of using the EAI HTTP Transport business service:
Controlling Login Sessions with Session Mode
The session mode allows control over login sessions. In this mode you log in first and open a session. Any message can be exchanged without having to log in again until you explicitly log off.
The following example shows parameters for Request and Logoff in a session mode HTTP request. Session cookies are required in a case such as this.
The following URL passes a query string as the SWEExtData value along with the GET request:
HTTPRequestURLTemplate = "http://$ServerPath$/ start.swe?SWEExtData=<Prop>somedata</Prop>HTTPRequestMethod='GET'"The following URL logs off from the server:
HTTPLogoffURLTemplate = "http://$ServerPath$/start.swe?SWEExtCmd=Logoff"
In these URL examples, the following parameter is used:
ServerPath = "siebel1/eai"
In the examples, the ServerPath variable value of siebel1/eai is substituted for the token $ServerPath$.
Any XML document represented by the entry for SWEExtData can be put into the body. This would change the sample code so that HTTPRequestURLTemplate would read as:
HTTPRequestURLTemplate = "http://$ServerPath$/start.swe?"
Sending Requests in Sessionless Mode
The following example includes a Request Method, a Request, and a Login for a sessionless mode request. In this example, the request is simply passed to the secure server using the POST command. Unlike the Session Mode example, this request sends data in the body of the request. This request does not require cookies.
HTTPRequestMethod = "POST"
HTTPRequestURLTemplate = "https://accounts.mypartnerexample.com/server/login.asp"
HTTPRequestBodyTemplate = "Acct=ABCIntl&User=$Username$&pwd=$Password$"
Username = "acctuser"
Password = "123456789abcdefg"
Accessing a URL Protected by Basic Authentication
Siebel Business Applications support server, or basic, authentication. You can use basic authentication with the EAI HTTP Transport to send messages. For more information about authentication, see Siebel Security Guide.
The format for accessing a URL protected by basic authentication with HTTP Outbound is:
http://username:password@host/rest of the URL
For example:
http://Administrator:manage@127.0.0.1:5555/example.com/stuff
Providing Client Certificate Information for TLS Mutual Authentication
In certain versions, Siebel Business Applications support client authentication for TLS-based communications (also known as mutual authentication) using the EAI HTTP Transport business service, and for workflows and outbound Web service calls that call the EAI HTTP Transport business service.
If client authentication is enabled, then the Siebel Server presents a client certificate to an external Web server by supplying values for the EAI HTTP Transport parameters HTTPCertSerialNo and HTTPCertAuthority.
If the EAI HTTP Transport business service is invoked directly by Siebel eScript or a workflow, then you can specify the HTTPCertSerialNo and HTTPCertAuthority parameters by setting input properties (business service method arguments).
The following is an example of the code used to call the EAI HTTP Transport business service using Siebel eScript:
var oService = TheApplication().GetService("EAI HTTP Transport");
var oInputs = TheApplication().NewPropertySet();
var oOutputs = TheApplication().NewPropertySet();
oInputs.SetProperty("HTTPRequestMethod", "GET");
oInputs.SetProperty("HTTPRequestURLTemplate", sUrl);
// Set the Serial Number of the Client Certificate
oInputs.SetProperty("HTTPCertSerialNo", "00d802dc387dd867b9");
// Set the RDN for the CA of the certificate
oInputs.SetProperty("HTTPCertAuthority","E=cacert@oracle.com,CN=somecertcomputer,
OU=ca,O=oracle,L=boston,C=usa");
// Invoke EAI HTTP Transport
oService.InvokeMethod("SendReceive", oInputs, oOutputs);
For more information about configuring TLS mutual authentication using the EAI HTTP Transport, see Siebel Security Guide.
Creating Custom Headers for the EAI HTTP Transport Service
Custom headers can be created when sending a request through the EAI HTTP Transport service using a script or a workflow.
To create custom headers for the EAI HTTP Transport service
Create a new input property in the input to the HTTP transport.
The name of the property must have a prefix of HDR. or HDR_ followed by the name of the custom header, for example:
httpIn.SetProperty("HDR.CustomHttpHeader","MyValue"); httpSvc.InvokeMethod("SendReceive", httpIn, httpOut);
A custom HTTP header with a name of "CustomHttpHeader" and a value of "MyValue" is the result.
About Sending and Receiving Messages Through HTTP
To send and receive messages through HTTP, you set up a workflow with the SendReceive method.
The Receive part of that method receives the response in an output argument of that method. You can then use the response to perform an upsert operation using an integration object and EAI Siebel Adapter, or display the response to your user. In this scenario, none of your quote integration design uses the eai.cfg or the Application Interface. You are performing an outbound HTTP call and waiting for a response synchronously.
You can then communicate the response to the user by displaying the returned error message in a browser alert or use the new User Interact step of the workflow to refresh the view and show any new updates to fields to the user. The User Interact step can run synchronously or asynchronously, in the local Siebel Application Object Manager or on the server.
About Transport Headers and HTTP Response Headers
This topic describes how transport headers and HTTP response headers work with HTTP Transport (outbound) to form a cookie handling system. HTTP Transport handles the cookie it receives from the server by storing and then creating a valid request transport header that it sends back to the server as a part of the request.
By exposing all the HTTP response headers as a part of output property set, you can handle the response accordingly. You can have all the HTTP response headers, as well as HTTP Status code, as part of the output property set.
Transport headers are preserved across various connections and are a part of the transport service and not the HTTP connection.
Features of Transport Headers
Transport headers have the following features:
Every connection has its own transport header.
The transport header separately stores each cookie sent by the server during a connection.
For example, each name, domain, value pair, along with path, and other attributes (if present) are stored as a separate cookie in the transport header.
Each cookie in the transport header has a distinct name.
Two cookies with the same name cannot be present in the transport header at the same time. The second cookie overwrites the first one. Therefore, since the transport header is implemented as a CSSMapStringToPtr class, each cookie is hashed in the transport header based on its name.
The transport header classifies cookies into two categories:
Type HTTP Version 1 and later.
Preliminary Netscape cookie spec type.
When a ToString function is called on the transport header, it scans through the header and collects all the cookies in the header and creates a request transport header (based on the cookie category).
The transport header is cleared when the connection is terminated.
During SendReceive, the HTTP response has HTTP headers associated with it. Expose those response HTTP headers as properties of the output property set.
All of these HTTP header properties are distinguished from other properties by adding the prefix HDR. in front of the property (header) name.
Also, HTTP Status code for the HTTP request sent by way of EAI HTTP Transport is exposed as a property in the output property set. The property is called StatusCode.