8Using Attachments with Web Services On Demand

Using Attachments with Web Services On Demand

This chapter describes how to exchange attachments using Web services On Demand. It contains the following topics:

• About Attachments

• About The Attachment Element

• Specifying File Attachment Content

• Retrieving or Querying File Attachments

• Specifying URL Attachments

About Attachments

Attachments can be exchanged for a number of objects using Web Services On Demand. The parent objects that have Attachment child objects are: Account, Accreditation, Activity, Campaign, Contact, Course, Custom Object 01 - 03, Dealer, Event, Exam, Lead, Opportunity, Service Request, and Solution. Attachments can also be exchanged for sales stages.

File Attachments can be exchanged as text or as binary data. In the case of binary data, the data must be encoded as inline Base64 encoded data, which ensures that the binary data is in a printable format. Binary files must therefore be encoded into Base64 format in the content provided in SOAP requests.

File attachments added through Web services requests are limited to 20MB in size just as they are for the Oracle CRM On Demand UI. Attachments greater than 20MB in size are therefore rejected. To accommodate Base64 encoding of binary files, the request size limit for SOAP requests with attachment files is 28800 KB.

You can develop client applications that allow attachment files to be added or updated for multiple records. SOAP requests contain multiple records; the first record contains the attachment as well as a Content ID value. However, other records in the SOAP request do not need to contain the same attachment, they need only reference the Content ID value from the first record.

When adding attachment files to Oracle CRM On Demand through Web services, it is better for performance reasons to send requests sequentially. For more information about best practices when using attachments, see API Calls.

About The Attachment Element

In a Web services call, the content of an attachment must be contained in the <Attachment> element, which has the complex data type SiebelXmlAttachmentType, as shown in the following sample WSDL for an Attachment child object:

<xsd:complexType name="ListOfAttachment">
		<xsd:sequence>
				<xsd:element name="Attachment" maxOccurs="unbounded" minOccurs="0" type="xsdLocal1:Attachment" /> 
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="Attachment">
			<xsd:sequence>
				<xsd:element name="Id" maxOccurs="1" minOccurs="0" type="xsdLocal1:string30"/> 
				<xsd:element name="DisplayFileName" maxOccurs="1" minOccurs="0"type="xsdLocal1:string200" /> 
				<xsd:element name="FileNameOrURL" maxOccurs="1" minOccurs="0" type="xsdLocal1:string200" /> 
				<xsd:element name="FileExtension" maxOccurs="1" minOccurs="0" type="xsdLocal1:string10" /> 
				<xsd:element name="FileDate" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="FileSize" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="ContactId" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="ExternalSystemId" maxOccurs="1" minOccurs="0"	type="xsdLocal1:string30" /> 
				<xsd:element name="AttachmentTag" maxOccurs="1" minOccurs="0" type="xsd:string"/> 
				<xsd:element name="Description" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="CreatedDate" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="CreatedById" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="CreatedBy" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="ModId" maxOccurs="1" minOccurs="0" type="xsdLocal1:string30"/> 
				<xsd:element name="ModifiedDate" maxOccurs="1" minOccurs="0" type="xsd:string"/> 
				<xsd:element name="ModifiedById" maxOccurs="1" minOccurs="0" type="xsd:string"/> 
				<xsd:element name="ModifiedBy" maxOccurs="1" minOccurs="0" type="xsd:string" /> 
				<xsd:element name="Attachment" maxOccurs="1" minOccurs="0" type="xsdLocal1:SiebelXmlAttachmentType"/> 
			</xsd:sequence>
	</xsd:complexType>
				...
	<xsd:complexType name="SiebelXmlAttachmentType">
			<xsd:simpleContent>
				<xsd:extension base="xsd:base64Binary">
					<xsd:attribute name="ContentId" type="xsd:string" /> 
					<xsd:attribute name="AttachmentIsTextData" type="xsd:string" /> 
				</xsd:extension>
			</xsd:simpleContent>
	</xsd:complexType>

As the WSDL sample indicates. the <Attachment> child element can have the following optional attributes:

• ContentId. Uniquely identifies the attachment content. If the attribute is not specified, the Web Services framework creates one for internal processing and to identify the content. This attribute is also used to achieve content reuse within a SOAP message, as described in Attaching a File to Multiple Records.

• AttachmentIsTextData. Indicates that the content is plain text and that no Base64 decoding needs to be performed on it. The default value for this attribute is false. This attribute must be specified when text content is being specified.

Specifying File Attachment Content

The following topics describe the different ways in which you can specify the attachment content and how you can attach the same file to multiple records.

Sample SOAP requests are included to illustrate the use of the attributes of the <Attachment> element.

Attaching Binary Data

The following SOAP sample shows how the Base64 encoded attachment file must be embedded within the SOAP document:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/
2001/XMLSchema">
<soap:Body>
		<AccountWS_AccountInsert_Input xmlns="urn:crmondemand/ws/account/10/2004">
			<ListOfAccount>
				<Account>
					<Description>This is for missing fields test</Description>
					<Location>Bangalore</Location>
					<AccountName>Atach_Test1</AccountName>
					<NumberEmployees>300</NumberEmployees>
						<ListOfAttachment>
							<Attachment>
								<FileNameOrURL>Attached</FileNameOrURL>
								<FileExtension>doc</FileExtension>
								<DisplayFileName>A Doc Attachment</DisplayFileName>
								<Attachment ContentId="content_doc">0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAA
								........
								........
								AAAAAAAAAAAAAAAAAAAAAAAAAA=</Attachment>
								</Attachment>
						</ListOfAttachment>
				</Account>
			</ListOfAccount>
		</AccountWS_AccountInsert_Input>
</soap:Body>
</soap:Envelope>

The attachment content is specified within the <Attachment> element which has the data type SiebelXmlAttachmentType.

Note: It is not required to specify the ContentId attribute.

Attaching a Text File

When attaching a text file (a nonbinary file in printable ASCII format), no Base64 encoding is required.

The following SOAP request illustrates how a text file can be attached:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/
2001/XMLSchema">
	<soap:Body>
		<AccountWS_AccountInsert_Input xmlns="urn:crmondemand/ws/account/10/2004">
				<ListOfAccount>
					<Account>
						<Description>Account with text attachment</Description>
						<Location>Bangalore</Location>
						<AccountName>Attach Text</AccountName>
						<NumberEmployees>300</NumberEmployees>
						<ListOfAttachment>
							<Attachment>
								<FileNameOrURL>Attach Text</FileNameOrURL>
								<FileExtension>txt</FileExtension>
								<DisplayFileName>My Rantings</DisplayFileName>
								<Attachment AttachmentIsTextData="true">
								The quick brown fox jumps over the lazy dog.. 
								</Attachment>
							</Attachment>
						</ListOfAttachment>
					</Account>
				</ListOfAccount>
		</AccountWS_AccountInsert_Input>
	</soap:Body>
</soap:Envelope>

The AttachmentIsTextData attribute of the <Attachment> element has the value true to indicate that the content is plain text and that no Base64 encoding or decoding is required to be performed by the Web Services framework.

Attaching a File to Multiple Records

The ContentId attribute of the <Attachment> element is used to uniquely identify attachment content. The ContentID argument is optional and the Web services framework generate ones for its internal processing, if it is not provided.

The ContentID attribute allows you to reuse the content contained in another <Attachment> element so that you can specify the same attachment content for multiple records.

When reusing the content in this way, you must only specify the ContentID value, and the attachment content must be empty. Values of the ContentID attribute must be unique.

The following SOAP request shows how a file can be attached to two records:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/
2001/XMLSchema">
<soap:Body>
		<AccountWS_AccountInsert_Input xmlns="urn:crmondemand/ws/account/10/2004">
					<ListOfAccount>
							<Account>
								<Description>Account for attachment and resuse test</Description>
								<Location>Bangalore</Location>
								<AccountName>Attach Test Reuse</AccountName>
								<NumberEmployees>300</NumberEmployees>
								<ListOfAttachment>
									<Attachment>
										<FileNameOrURL>Attached</FileNameOrURL>
										<FileExtension>doc</FileExtension>
										<DisplayFileName>To be reused</DisplayFileName>
										<Attachment ContentId="reuse">0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAAAAAACAAAA+AAAAAAAAAAAEAAA+gAAAAEAAAD+////AAAAAPYAAAD3AAAA///////////////////////////
										.......... The Base64 encoded stream goes here ..........
										AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</Attachment>
									</Attachment>
								</ListOfAttachment>
							</Account>
							<Account>
								<Description>This copying the attachment</Description>
								<Location>San Mateo</Location>
								<AccountName>Attach Test Copy</AccountName>
								<NumberEmployees>300</NumberEmployees>
								<ListOfAttachment>
									<Attachment>
										<FileNameOrURL>Attach Reuse</FileNameOrURL>
										<FileExtension>doc</FileExtension>
										<DisplayFileName>Reused</DisplayFileName>
										<Attachment ContentId="reuse"></Attachment>
									</Attachment>
								</ListOfAttachment>
							</Account>
					</ListOfAccount>
		</AccountWS_AccountInsert_Input>
</soap:Body>
</soap:Envelope>

The SOAP request above shows how you can attach the same file to two different Account records:

• The ContentId value Content_01 is specified for the attachment child of the first Account.

• The same ContentId value is specified for the attachment child of the second account, with the result that the same file is attached to both accounts. You must only specify the ContentId attribute for the second account record.

Retrieving or Querying File Attachments

When performing a query operation to retrieve attachment content, the response must contain Base64 encoded content. This is true even if the attached file is a simple text file. The attachment content must therefore be decoded back from Base64 to the binary or text format in all cases.

No content reuse is supported when performing a query. Even though the same file has been attached to multiple records, the response always generates unique ContentId values and the <Attachment> elements contain the attachment content.

The following SOAP response illustrates a query response for an attachment child:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/
2001/XMLSchema">
<SOAP-ENV:Body>
<ns:AccountWS_AccountQueryPage_Output mlns:ns="urn:crmondemand/ws/account/10/
2004">
<ns:LastPage>true</ns:LastPage>
<ListOfAccount xmlns="urn:/crmondemand/xml/account">
<Account>
   <AccountId>1QA2-L9DZG</AccountId>
   <Description>Account with attachment</Description>
   <Location>Toronto</Location>
   <AccountName>Test Account</AccountName>
   <ListOfAttachment>
      <Attachment>
         <DisplayFileName>My sales analysis</DisplayFileName>
         <FileNameOrURL>Analysis</FileNameOrURL>
         <FileExtension>xml</FileExtension>
         <AttachmentTag>FILE</AttachmentTag>
         <Description></Description>
         <Attachment AttachmentIsTextData="false" Extension="xml" ContentId="1QA2-RTX3">PD94bWwgdiVVRGLTgiPz48P1NpZWJlbC1Qcm9wZXJ0eS1TZXQgRXNjYXBl
         <Base 64 encoded attachment data ........>
         </Attachment>      
      </Attachment>
   </ListOfAttachment>
</Account>
</ListOfAccount>
</ns:AccountWS_AccountQueryPage_Output>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

There are two additional attributes of the <Attachment> element:

• EndOfData. Indicates that the data is the complete content. Always true.

• TimedOut. Indicates whether a time-out occurred when obtaining the data. Always false.

Specifying URL Attachments

Web Services also supports the exchange of URL attachments as well as file attachments.

The handling of URL attachments differs from file attachments in the following ways:

• The FileNameOrURL field must specify the actual URL. The URL must begin with one of the following: HTTP, HTTPS, FTP or WWW (case-insensitive).

• The FileNameOrURL and FileExtension fields form a user key for Attachment child objects, however, FileExtension is not a required field for URL attachments and is ignored.

The <Attachment> element is not required to have any content, and any content is ignored if provided.

The following example SOAP request shows a URL attachment.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/
2001/XMLSchema">
<soap:Body>
		<AccountWS_AccountInsert_Input xmlns="urn:crmondemand/ws/account/10/2004">
			<ListOfAccount>
					<Account>
						<Description>Account with URL attachment</Description>
						<Location>Bangalore</Location>
						<AccountName>Atach URL</AccountName>
						<NumberEmployees>300</NumberEmployees>
						<ListOfAttachment>
							<Attachment>
								<FileNameOrURL>www.pingpong.com</FileNameOrURL>
							</Attachment>
						</ListOfAttachment>
					</Account>
			</ListOfAccount>
		</AccountWS_AccountInsert_Input>
</soap:Body>
</soap:Envelope>