Technical Articles
Read and Write ByDesign Attachments using Web Services
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:
- Create a Communication Scenario and assign the operation “Read attachment folder documents” (service name “ManageAttachmentFolderIn“).
- 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). - 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.
hi Knat,
Could you give me the actioncode list or reference link?
when I write boum2 script usually use A2X or direct XML as TDC template.
thanks!
Best Regards,
Jimmy Pang
Hi Jimmy,
in ByD web services we support 6 action codes: 01 - create, 02 - update, 03 - delete, 04 - save, 05 - remove and 06 - no action with the following semantics (from our web service documentation):
You find the full documentation with all details on SAP help: Web Services.
With regards to code lists in general: we have a web service QueryCodeListIn that can be used to extract ByD code lists. You find a description here on SCN: How to get ByDesign Code Lists via Web Service QueryCodeListIn.
Best regards,
Knut
Added a section how to configure web service ManageAttachmentFolderIn.
If we Create Communication Scenario and Arrangement in 1605+ releases then we don't need to ask SAP support for User Authorizations.
I create Communication System, Arrangement and Scenario based on the Above said "Read attachment folder documents" and its working fine. The reason is SAP automatically assigns user to the Communication Arrangement while creating it. If we use that user then we can Query Attachments easily.
In my case MSight was my Communication system and SAP Created _MSIGHT_0 user automatically which i used for authorizations.
Hello Knut,
Very userful blogpost, thanks!
I have been able to create an attachment to a customer quote, but I haven't found how to set the output relevance indicator. Can this be done with the web service as well?
Hi Pieter-Jan,
unfortunately the element AttachmentFolder.Document.OutputRelevanceIndicator is missing in the web service signature today, such that there is no possibility to set this indicator. Please consider to create an improvement request for ByD: https://influence.sap.com/SAPByDesignImprovements.
Best regards,
Knut
I'd really like this element to be made available as attachments to invoices from 3rd party systems almost always need to be sent to the customer as support for the billed amount. The only way to do this at the moment is to open new invoice requests and check the include in output flag manually.
So I raised an improvement request: https://influence.sap.com/sap/ino/#/idea/240207
Hi Thorne,
Thanks for creating the improvement request. As you noted you can create and read attachments using SOAP services, but the OutputRelevanceIndicator is not yet supported. Details and example: Read and Write ByDesign Attachments using Web Services
However, you can create and read attachments using custom OData services as well and this approach supports the OutputRelevanceIndicator. You find examples in the Github-repository https://github.com/SAP-samples/sapbydesign-api-samples in Postman collection “Sales and Commerce Scenarios”, folder “Create Sales Order with Attachments”.
As workaround you could as well set the OutputRelevanceIndicator via a ByD add-in using the SAP Cloud Applications Studio.
Best regards,
Knut
Is there any chance, that the OutputRelevanceIndicator will be available using SOAP services in near future?
Best Regards,
Chris
This is desperately needed via the SOAP Web Service. There is essentially no point in attaching documents that need to be forwarded on via the web service as the number of unnecessary navigation and clicks that are needed to then go into the invoice request, click edit, get to the attachment and tick the box, save and then invoice. The ability to attach is made redundant by all the extra steps and for something which is actually so simple. This is a prime case of MVP not being up to scratch of what a customer actually needs.
Secondly, adding in the extra steps to request to be able to access the improvements section when you are already registered is another way of limiting the dialogue with customers and reducing the ability for users to register their support for issues.
Hi Knut,
I have read the blog and I see many interesting things been here which I have been searching for a quite long time.
I have a very specific case where I will be having the image as a URL in the response from Concur and that image I wanted to attach in to ByDesign. Here the URL from Concur system if I am attaching it in ByD what is the mime code and other context types I need to pass on to make sure the image is accessible as a PDF or PNG or JPG file in ByDesign for the end user in later point of time.
Can you please help me out in getting this done.
Regards
Hanumath K
Hi Hanumath,
basically you have two options:
Best regards,
Knut
Hi Knut,
When run the webservcie in soapUI, it raise:
<faultstring xml:lang="en">Authorization role missing for service "ServiceInterface http://sap.com/xi/DocumentServices/Global ManageAttachmentFolderIn <default> <default>", operation "Operation http://sap.com/xi/DocumentServices/Global MaintainAttachmentFolderFile" (UTC timestamp 20180104070122; Transaction ID 00163E0F423E1ED7BCA3A244F29701DE)</faultstring>
I don't know how to create the communication user, could you tell me which step I need to do?
(I have a user, it can run the webservice for business, but the user can't run the webservice.)
Thanks a lot.
Best Regards,
Benny Huang
Hi Benny,
you require a "communication user" to access web service ManageAttachmentFolderIn.
You get the communication user following the steps:
You can edit the comm. user credentials in the comm. system or in the communication arrangement. You find more details in the ByD help center.
Best regards,
Knut
Hi Knut,
Thanks for your help.
Best Regards,
Benny Huang
Hello Knut,
As always your blogs are very informative!
This question isn't specifically about Web Services...
I have an issue when building a .CSV file in ABSL (SAP ByDesign) with Finnish characters that use umlauts, etc.
When the file is downloaded the .CSV file has added characters as follows (in header description row):
Tekijä when it should be Tekijä
Työsuhde-alkupvm when it should be Työsuhde-alkupvm
Do I need to change something in the CreateFile statement?
exports.CreateFile(documentType, documentName, documentName, documentDescription, binaryObject);
Best Regards
Jay Joshi
I am trying to update the attachment folder and add more files and instead it uploads a file then replaces it with the next one i upload.
If i make the
Only list complete transmission (LCTI) allowed for SUPPLIER-ATTACHMENT_FOLDER-DOCUMENT - LIST_CTI001
Hi Yan,
please try the following pattern (works for me):
Best regards,
Knut
This works, thanks a lot.
For anyone curious If you want to upload many files into the folder(or folders of multiple Suppliers) by sending POST requests repeatedly(one per file) you have to remove the UUID data and choose 04 for the AttachmentFolder ActionCode.