Read and Write ByDesign Attachments using Web Services

[knutheusermann]

SAP Business ByDesign standard business objects as well as custom business objects (built using SAP Cloud Applications Studio) store attachments like documents, pictures and other files in attachments folders. The business object to which the attachment folder belongs to is called "host business object".

You can read, create, change and delete attachments using web services of the corresponding host business object.

However, query and read services of host business objects do not return file contents, but you can read the file content using web service ManageAttachmentFolderIn.

 

Create, Change and Remove Attachments

You can create, change and delete attachments incl. file content and external links using the web services of the host business object. Furthermore you can create your own web services for standard and custom business objects incl. attachment folders using SAP Cloud Applications Studio.

Here are some examples:

 

Use Case 1: Replace all existing attachments by a new attachment

Note that I used the attribute values DocumentListCompleteTransmissionIndicator="true" and ActionCode="04" in xml node AttachmentFolder. Furthermore I did not provide the attachment folder and document UUIDs as key elements.

DocumentListCompleteTransmissionIndicator="true" means that the list of documents included in the xml request is complete and  all documents not included in this list shall be removed. As I did not provide the key of the single document with the picture, the system cannot identify the target document and hence the system removes all existing attached documents and creates a single new document attachment.

 

Use Case 2: Add two new attachments

Note:

• I use action code "06 - No action" on Material-level and AttachmentFolder-Level, because I don't want to change any data on these levels


• On AttachmentFolder-Level I use DocumentListCompleteTransmissionIndicator="false" because I want to act on the listed documents only and do not want to change or remove any other attached documents.


• On Document-Level I use action code "01 - Create" because I want to add these documents to the attachment folder.

Use Case 3: Update an existing attachment

Note:

• I use action code "06 - No action" on Material-level and AttachmentFolder-Level, because I don't want to change any data on these levels


• On AttachmentFolder-Level I use DocumentListCompleteTransmissionIndicator="false" because I want to update the listed document only and do not want to change or remove any other attached documents.


• On Document-Level I use action code "02 - Update" and I provide the document key Document/UUID because I want to update the given document only. If the document does not exist in the system, I want receive an error message (if I would use action code "04 - Save" on document level, then the system would create the document if not existing).

You find more information about action codes and list complete transmission indicators in the ByD web service documentation:
SAP Business ByDesign – SAP Help Portal Page >> Open the documentation of Web Service APIs >> Open the documentation of a web service, e.g. Manage Accounts >> Follow the link Web Services in Section More Information.

Read Attachments

You can read ByD business object attachments using query and read web services of the corresponding host business object. The query/read response contains the attachments in node element AttachmentFolder.

The query response returns information and characteristics about the attachment folder documents and the document UUID, but no file content itself.

Example response xml with attachment folder and 3 documents: a picture, a text document and an external link:



The file content binary object can be loaded using interface ManageAttachmentFolderIn, operation ReadDocumentsFileContent.

In the web service request you have to enter the DocumentUUID as provided by the host object query/read response and the maximum file size to be returned (element QueryFileSizeMaximumNumberValue in Byte (= AD)).

Attachments that exceed the max file size are not returned.

Remark: Because of security reasons the file content cannot be loaded using the FileContentURI.

 

Attachment File Content Encoding

Attachment folder document file contents are transferred as Base64 encoded strings in both directions:

• In web services to create and change business objects incl. attachment folder, documents are to be provided in the web service request as Base64 encoded string in element //AttachmentFolder/Document/FileContent/BinaryObject


• The web service ManageAttachmentFolderIn returns the file content as Base64 encoded string.

Base64 decoder/encoder (to convert file <> string):

For test purposes I used the Notepad++ plug-in MIME Tools to encode and decode my attachment folder documents. However, there are plenty other free Base64 decoder/encoder in the World Wide Web.

 

Configuration of Web Service ManageAttachmentFolderIn

You can configure web service ManageAttachmentFolderIn by creating communication scenarios and communication arrangements via ByD work center Application and User Management:

1. Create a Communication Scenario and assign the operation "Read attachment folder documents" (service name "ManageAttachmentFolderIn").


2. On the popup "Select Business Object" you can choose for which ByD business object your communication user will have authorizations to read attachment content.
   Create multiple communication scenarios to read attachments for multiple business objects (one comm. scenario per business object).


3. Create Communication Systems and Communication Arrangements to configure web service credentials and download web service WSDL.

Remarks:

• Using SAP Cloud Application Studio is not possible to create communication scenarios for web service ManageAttachmentFolderIn and assign required business object authorizations to the scenario.


• The web service interface ManageAttachmentFolderIn has three operations; make sure you are using operation ReadDocumentsFileContent with UI name "Read attachment folder documents" (note the plural of "documents") and assign the same operation to your communication arrangement.


• In the web service request ManageAttachmentFolderIn/ReadDocumentsFileContent you have to enter the DocumentUUID as provided by the host object query/read response and the maximum file size to be returned (element QueryFileSizeMaximumNumberValue in Byte (= AD)). Attachments that exceed the max file size are not returned.

 

Document Category Codes, Type Codes and MIME Codes

My favorite way to get attachment characteristics like CategoryCode, TypeCode and MIMECode is to create a corresponding attachment via ByD UI, query/read the corresponding host business object incl. attachment folder via web service and pick the attachment characteristics from the query response xml.

However, most web service documentations contain detailed information about attachment folders as well, and you could extract ByD code lists using web service QueryCodeListIn (compare blog post: How to get ByDesign Code Lists via Web Service QueryCodeListIn).

Some examples:

Document category codes (element: CategoryCode, type: DocumentCategoryCode, namespace: http://sap.com/xi/AP/Common/GDT😞

• 2 - Document


• 3 - Link

Document type codes (element: TypeCode, type: DocumentTypeCode, namespace: http://sap.com/xi/AP/Common/GDT😞

• 10001 - Standard Attachment


• 10011 - Product Image


• 10015 - Technical Drawing


• 10016 - Business Partner Image


• 10018 - Product Specification


• …

MIME codes (element: MIMECode, type: MIMECode, namespace: http://sap.com/xi/AP/Common/GDT😞

• text/csv - Comma Separated Values


• text/xml - XML-File


• text/html - HTML Document


• text/plain - Text Document


• image/gif - GIF Image


• image/jpg - JPEG Image


• image/png - PNG Image


• application/pdf - Adobe PDF Document


• application/x-latex - LaTeX-File


• application/vnd.openxmlformats-officedocument.presentationml.presentation - Microsoft Office PowerPoint-Presentation (pptx)


• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - Microsoft Office Excel-Sheet (xlsx)


• application/vnd.openxmlformats-officedocument.wordprocessingml.document - Microsoft Office Word-Document (docx)


• …

Note: The supported document type codes are specific for every host business object. Check the corresponding web service documentation or ByD UI to find out which document type codes are supported for your host business object.

 

Some Trouble Shooting

Business partner, customer and supplier attachments

Issue: Web service ManageAttachmentFolderIn returns no content for a business partner, customer or supplier attachment

If you create the communication scenario for web service ManageAttachmentFolderIn in order to read business partner, customer or supplier attachments, you have to enter the business object BUSINESS_PARTNER_TMPL (BusinessPartner_Template).

Note: The value help does not offer/return the business object BusinessPartner_Template. You need to manually enter "BUSINESS_PARTNER_TMPL" in field Business Object Proxy Name.

Please note: Using this communication scenario, the communication user gets access to attachments of all kind of business partners in the system.

 

Web service ManageAttachmentFolderIn returns no content in element BinaryObject:

Web service response of operation ReadDocumentsFileContent contains empty BinaryObject:

<AttachmentFolderDocumentFileContent>

   <DocumentUUID>00163e0e-4644-1ed5-9b84-a3ff9e4391f9</DocumentUUID>

   <BinaryObject/>

</AttachmentFolderDocumentFileContent>

Check the following possible root causes:

• The web service interface ManageAttachmentFolderIn has three operations; make sure you are using operation ReadDocumentsFileContent with UI name "Read attachment folder documents" (note the plural of "documents") and assign the same operation to your communication arrangement.


• In the web service request ManageAttachmentFolderIn/ReadDocumentsFileContent you have to enter the DocumentUUID as provided by the host object query/read response and the maximum file size to be returned (element QueryFileSizeMaximumNumberValue in Byte (= AD)). Attachments that exceed the max file size are not returned.

In ByD releases 1605 and earlier, communication users do not have sufficient authorizations to read attachments using web service ManageAttachmentFolderIn. SAP provides a solution in release 1608; before please create an incident to add required authorizations to the communication user and refer to this blog post.

 

Why is the interface operation ManageAttachmentFolderIn.MaintainAttachmentFolderFile for write access to attachments not released?

The attachment folder is a so-called "dependent object" that is always bound to an host business object. As user authorizations are based on the host object, we allow write access to attachments only in context of the host object; a generic write access to attachments is not possible.

You can create, change and remove attachments using the web services of the corresponding host object (for example ManageMaterialIn) or you can create web services with write access to attachment folders using SAP Cloud Applications Studio.