9Siebel EAI and File Attachments
Siebel EAI and File Attachments
Siebel EAI supports file attachments for exchanging business documents such as sales literature, activity attachments, and product defect attachments with another Siebel instance or an external system such as Oracle Applications. It includes the following topics:
About File Attachments
For example, if you are exchanging service requests with another application or partner, then you can include attachments such as screen captures, email, log files, and contract agreements that are associated with the service request in the information being exchanged. Siebel EAI support for file attachments allows comprehensive integration.
To use file attachments you first must create integration objects. For information, see Integration Objects, and Creating and Maintaining Integration Objects.
Siebel EAI offers the choice of integrating file attachments using MIME (the industry standard for exchanging multipart messages), or including the attachment within the body of the XML document, referred to as an inline XML attachment. Consider using inline XML attachments when integrating two instances of Siebel Business Applications using file attachments.
Exchanging Attachments with External Applications
Siebel EAI supports bidirectional attachment exchange with external applications using the following two message types:
MIME (Multipurpose Internet Mail Extensions). MIME is the industry standard for exchanging multipart messages. The first part of the MIME message is an XML document representing the business object being exchanged and attachments to the object are included as separate parts of the multipart message. MIME is the recommended choice for integrating Siebel Business Applications with other applications. For more information, see Using MIME Messages to Exchange Attachments.
Inline XML attachments (Inline Extensible Markup Language). With inline XML attachments, the entire business object you are exchanging, including any attachments, is sent as a single XML file. Consider using inline XML attachments when integrating two instances of Siebel Business Applications using file attachments. For more information, see Using Inline XML to Exchange Attachments.
Using MIME Messages to Exchange Attachments
To send or receive file attachments using MIME messages, Siebel EAI uses the MIME Hierarchy Converter and MIME Doc Converter.
You must perform the following procedures to use MIME to exchange attachments between Siebel Business Applications and another external system:
Create an attachment integration object using the EAI Siebel Wizard business service.
For information, see Creating an Attachment Integration Object.
Create an inbound or outbound workflow.
For information, see Creating Workflow Examples.
Test your workflow using the Workflow Simulator.
For information, see Business Processes and Rules: Siebel Enterprise Application Integration.
Creating an Attachment Integration Object
The following procedure guides you through the steps of creating an attachment integration object.
To create a new attachment integration object
In Siebel Tools or Web Tools, create a new workspace.
From the File menu, choose New Object to display the New Object Wizards dialog box.
Select the EAI tab, and then double-click Integration Object.
The Integration Object Builder wizard appears.
Follow the procedure in Creating Integration Objects Using the EAI Siebel Wizard Business Service to create the new integration object, for example SourceObject Attachment.
Note: When creating your integration object you must select the Attachment integration component. The following figure illustrates this when the source object is Account.
In the Object Explorer, select Integration Object, and then select your new integration object in the Object List Editor.
In the Object Explorer, expand the Integration Object tree to show the Integration Component object.
Select the SourceObject Attachment integration component, and set its External Sequence and XML Sequence properties so that they are greater than those of the other integration components (that is, last in sequence), if not already set.
If they are not last, the situation can arise where the attachment is processed successfully (and the file system is physically updated). Then a subsequent integration component causes a failure (for example, an attempt to insert to the database causes a duplicate error). In this case, the database transaction is rolled back, but the file system is not restored.
With the SourceObject Attachment integration component selected, expand the Integration Component object, and then select the Integration Component Field object.
The Integration Components and Integration Component Fields lists appear.
Inactivate all integration component fields except the following:
SourceObject Attachment Id, for example, Accnt Attachment Id
SourceObjectFileExt, for example, AccntFileExt
SourceObjectFileName, for example, AccntFileName
Comment
Select the SourceObject Attachment Id component field, and then verify that its Data Type property is set to
DTYPE_ATTACHMENT.Deliver the workspace.
Creating Workflow Examples
Depending on whether you are preparing for an outbound or an inbound attachment exchange, design different workflows as described in the following two procedures.
For more information on creating workflows, see Siebel Business Process Framework: Workflow Guide.
Outbound Workflow
To process the attachment for an outbound request you must create a workflow to query the database, convert the integration object and its attachments into a MIME hierarchy, and then create a MIME document to send to the File Transport business service.
To create an outbound workflow
In Siebel Tools, select the Workflow Process object in the Object Explorer.
Right-click, then choose New Record.
Give the new workflow a name and associate it with a locked project.
Right-click, and then choose Edit Workflow Process.
The Workflow Process Designer appears.
Create a workflow consisting of Start, End, and four Business Services. Set up each Business Service according to the task it must accomplish.
Define your process properties.
Set process properties when you need global properties for the entire workflow.
Name Data Type Default String SiebelMessage
Hierarchy
Leave blank.
Error Message
String
Leave blank.
Error Code
String
Leave blank.
Object Id
String
Leave blank.
Process Instance Id
String
Leave blank.
Siebel Operation Object Id
String
Leave blank.
MIMEHierarchy
Hierarchy
Leave blank.
SearchSpec
String
[Account.Name] = 'Sample Account'
<Value>
String
Default output is binary.
The first business service queries the Account information from the database using the EAI Siebel Adapter business service with the Query method. This step requires the following input and output arguments.
Input Argument Type Value Property Name Property Data Type Output Integration Object Name
Literal
Sample Account
not applicable
not applicable
SearchSpec
Process Property
not applicable
SearchSpec
String
Property Name Type Output Argument SiebelMessage
Output Argument
Siebel Message
Note: For more information on using the EAI Siebel Adapter, see EAI Siebel Adapter Business Service.The second business service in the workflow converts the Account integration object and its attachments to a MIME hierarchy using the EAI MIME Hierarchy Converter business service with the SiebelMessage to MIME Hierarchy method. This step requires the following input and output arguments.
Input Argument Type Property Name Property Data Type Siebel Message
Process Property
SiebelMessage
Hierarchy
Note: For more information on the EAI MIME Hierarchy Converter, see About the EAI MIME Hierarchy Converter.The third business service of the workflow converts the MIME hierarchy to a document to be sent to File Transport business service. This step uses the EAI MIME Doc Converter business service with the MIME Hierarchy To MIME Doc method. This step requires the following input and output arguments.
Property Name Type Output Argument MIMEHierarchy
Output Argument
MIME Hierarchy
Input Argument Type Property Name Property Data Type MIME Hierarchy
Process Property
MIMEHierarchy
Hierarchy
Property Name Type Output Argument <Value>
Output Argument
MIME Message
Note: For more information on the EAI MIME Doc Converter, see About the EAI MIME Doc Converter.For the final step, set up the last business service of the workflow to write the information into a file using the EAI File Transport business service with the Send method. This step requires the following input arguments.
Input Argument Type Value Property Name Property Data Type Message Text
Process Property
not applicable
<Value>
String
File Name
Literal
c:\temp\account.txt
not applicable
not applicable
Note: For information on File Transport, see Transports and Interfaces: Siebel Enterprise Application Integration.
Inbound Workflow Example
To process the attachment for an inbound request, you must create a workflow to read the content from a file, convert the information into a Siebel Message, and send to the EAI Siebel Adapter to update the database accordingly.
To create an inbound workflow
In Siebel Tools, select the Workflow Process object in the Object Explorer.
Right-click, and then choose New Record.
Give the new workflow a name and associate it with a locked project.
Right-click, then choose Edit Workflow Process.
The Workflow Process Designer appears.
Create a workflow consisting of Start, End and four Business Services. Set up each Business Service according to the task it must accomplish.
Define your process properties.
Set process properties when you need global properties for the entire workflow:
Name Data Type SiebelMessage
Hierarchy
Error Message
String
Error Code
String
Object Id
String
Siebel Operation Object Id
String
MIMEHierarchy
Hierarchy
MIMEMsg
Binary
The first business service in the workflow reads the Account information from a file using the EAI File Transport business service with Receive method. This step requires the following input and output arguments.
Input Argument Type Value File Name
Literal
c:\temp\account.txt
Property Name Type Output Argument <Value>
Output Argument
Message Text
Note: For information on File Transport, see Transports and Interfaces: Siebel Enterprise Application Integration.The second business service of the workflow converts the Account information to a MIME hierarchy using the EAI MIME Doc Converter business service with the MIME Doc to MIME Hierarchy method. This step requires the following input and output arguments.
Input Argument Type Property Name Property Data Type MIME Message
Process Property
<Value>
Binary
Property Name Type Output Argument MIMEHierarchy
Output Argument
MIME Hierarchy
The third business service of the workflow converts the MIME hierarchy to a document, and sends it to the EAI Siebel Adapter business service. This step uses the EAI MIME Hierarchy Converter business service with the MIME Hierarchy to Siebel Message method. This step requires the following input and output arguments.
Input Argument Type Property Name Property Data Type MIME Hierarchy
Process Property
MIMEHierarchy
Hierarchy
Property Name Type Output Argument SiebelMessage
Output Argument
Siebel Message
The last step of the workflow writes the information into the database using the EAI Siebel Adapter business service with the Insert or Update method. This step requires the following input argument.
Input Argument Type Property Name Property Data Type Siebel Message
Process Property
SiebelMessage
Hierarchy
About the EAI MIME Hierarchy Converter
The EAI MIME Hierarchy Converter transforms the Siebel Message into a MIME (Multipurpose Internet Mail Extensions) hierarchy for outbound integration. For inbound integration, it transforms the MIME Hierarchy into a Siebel Message.
Outbound Integration
The EAI MIME Hierarchy Converter transforms the input Siebel Message into a MIME Hierarchy. The following figure illustrates the Siebel Message of a sample Account with attachments. This figure represents both input and output to the MIME Hierarchy Converter.
The output of this process is illustrated in the following figure.
The first child of a MIME Hierarchy is the XML format of the Sample Account Integration Object instance found in the Siebel Message. The remaining two children are the corresponding children found under Attachments. If there is no child of type Attachments in the Siebel Message, then the output is just a MIME Hierarchy with a child of type Document. This document will contain the XML format of the Sample Account integration object instance.
Inbound Integration
The MIME Hierarchy Converter transforms a MIME Hierarchy input into a Siebel Message. For the inbound process, the first child of the MIME Hierarchy has to be the XML format of the Integration Object instance; otherwise, an error is generated. The following figure illustrates the incoming hierarchy.
The output of this process is illustrated in the figure in the previous topic. The output for this process is the same as the input.
About the EAI MIME Doc Converter
The MIME Doc Converter converts a MIME Hierarchy into a MIME Message and a MIME Message into a MIME Hierarchy. A MIME Hierarchy consists of two different types of property sets, as shown in the following table.
Table Property Sets in a MIME Hierarchy
| Property | Description |
|---|---|
MIME Hierarchy |
Mapping to a MIME multi-part |
Document |
Mapping to MIME basic-part |
EAI MIME Doc Converter Properties
The following table illustrates some examples of how a MIME Message maps to a MIME Hierarchy.
Table Examples of MIME Message and MIME Hierarchy
| MIME Message | MIME Hierarchy |
|---|---|
MIME-Version: 1.0 Content-Type: application/xml Content-Transfer-Encoding: 7bit This is a test. |
Type: Document Value: This is a test |
MIME-Version: 1.0 Content-Type: multipart/related; type="application/xml"; boundary=--abc ----abc Content-Type: application/xml Content-Transfer-Encoding: 7bit This is test2. ----abc-- |
Type: MIMEHierarchy Type: Document Value: This is a test2 |
The business service needs the following properties on the child property set as shown in the following table. These properties reflect the most accurate information on the data contained in the child property set.
Table Properties for EAI MIME Doc Converter
| Property | Possible Values | Type | Description |
|---|---|---|---|
ContentId |
Any value |
Document |
No Default. The ContentId is the value used to identify the file attachment when the receiver parses the MIME message. When importing attachments, use a unique value for this property and not repeat it for the rest of the file attachments. This is required in the actual document. This property is automatically populated when you are exporting an attachment from a Siebel application. |
Extension |
txt, java, c, C, cc, CC, h, hxx, bat, rc, ini, cmd, awk, html, sh, ksh, pl, DIC, EXC, LOG, SCP, WT, mk, htm, xml, pdf, AIF, AIFC, AIFF, AU, SND, WAV. gif, jpg, jpeg, tif, XBM, avi, mpeg, ps, EPS, tar, zip, js, doc, nsc, ARC, ARJ, B64, BHX, GZ, HQX |
Document |
No Default. If ContentType and ContentSubType are not defined, then Extension is used to retrieve the appropriate values from this property. If all three values are specified, then ContentType and ContentSubType values override the values retrieved from the Extension. If either the Extension or both ContentType and ContentSubType are not specified, then ContentType will be set to application and ContentSubType will have the value of octet-stream. |
ContentType |
application, audio, image, text, video |
Document |
Default is application. The ContentType value has to be specified if you want to set the content type of the document instead of using the extension to get a value from the MIME utility function. If the value is not provided, then the default value is used. The ContentType of multipart is used to represent file attachments in a MIME message. Other values to describe a multipart message are not supported. |
ContentSubType |
plain, richtext, html, xml (used with ContentType of Text) octet-stream, pdf, postscript, x-tar, zip, x-javascript, msword, x-conference, x-gzip (used with ContentType of application) aiff, basic, wav (used with ContentType of audio) gif, jpeg, tiff, x-xbitmap (used with ContentType of image) avi, mpeg (used with ContentType of video) |
Document |
Default is octet-stream. The ContentSubType value has to be specified if you want to set the content subtype of the document instead of using the extension to get a value from the MIME utility function. If the value is not provided, then the default value is used.
Note: Octet-stream is transparent and uses nonencoded 8-bit bytes. The MIME message will contain the binary file data as is, which might cause issues in data transmission over networks that remove bit number 8 (the hi-bit) for special needs.
|
Using Inline XML to Exchange Attachments
To exchange attachments between applications, you use the EAI Siebel Adapter business service:
To send a message to an external application, call the EAI Siebel Adapter with an integration object that has an integration component from an attachment business component. The EAI Siebel Adapter generates the integration object hierarchy and then converts it to an XML document. The attachment is included in the XML in the SourceObjectFileBuffer element.
To insert an attachment into a Siebel Business Application, the external application uses the same integration object hierarchy, making sure the required fields are present, and puts the base64 string corresponding to the attachment into this message. The XML converter converts the message into an integration object hierarchy, and the EAI Siebel Adapter inserts the attachment.
Perform the following tasks to create and test inline XML attachments using an integration object and a workflow:
Creating an attachment integration object using the EAI Siebel Wizard business service
For information, see Creating an Attachment Integration Object.
Caution: To avoid SQL errors, you must inactivate all integration component fields in the integration object except those in Step 9.Testing your workflow using the Workflow Simulator
For information, see Business Processes and Rules: Siebel Enterprise Application Integration.
Creating an Attachment
You create an attachment to a record in the Siebel client whose row ID you know.
To create the attachment
In the Siebel client, navigate to a record that can take an attachment, for example, an account.
Choose Help, then About Record from the application-level menu to obtain the row ID of the record.
Drill down on the record, then select the Attachments tab.
Add an attachment to the record if none exists.
Creating a Test Workflow
You create a workflow in Siebel Tools to do the following:
Query the Siebel database for the record with the attachment.
Convert the integration object and its attachment into a Siebel Message.
Read an external XML file (containing an attachment) and convert it into a Siebel Message.
Note: The XML file must use the exact integration object hierarchy as the attachment integration object you created.Insert the record into the Siebel database.
To create a test workflow to exchange attachments
Create the following workflow:
Define the process properties as shown in the following table.
Name Data Type Error Code
String
Error Message
String
Object Id
String
Process Instance Id
String
Siebel Operation Object Id
String
SiebelMessage
Hierarchy
The first business service step queries the database using the EAI Siebel Adapter business service with the Query method. This step requires the following input and output arguments:
Input Argument Type Value OutputIntObjectName
Literal
Attachment integration object you created, for example, Account Attachment
PrimaryRowId
Literal
Row ID of the record to which you added an attachment
Property Name Type Output Argument SiebelMessage
Output Argument
SiebelMessage
The second business service step writes the integration object hierarchy to an XML file using the EAI XML Write to File business service with the WriteEAIMsg method. This step requires the following input arguments:
Input Argument Type Value FileName
Literal
File to write, for example, d:\temp\AttachmentTest_write.xml
SiebelMessage
Process Property
SiebelMessage
The third business service step reads an XML hierarchy and converts it into a Siebel Message using the EAI XML Read From File business service with the ReadEAIMsg method. This step requires the following input and output arguments:
Input Argument Type Value FileName
Literal
File to read, for example, d:\temp\AttachmentTest_read.xml
Note: For testing purposes, you can use a modified form of the file written in the second business step, which will automatically have the correct hierarchy.The fourth business service step reads the Siebel Message and inserts the record into the Siebel database using the EAI Siebel Adapter business service with the Insert method. This step requires the following input argument:
Property Name Type Output Argument SiebelMessage
Output Argument
SiebelMessage
Input Argument Type Value SiebelMessage
Process Property
SiebelMessage