Skip to Content
Technical Articles
Author's profile photo Knut Heusermann

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

/wp-content/uploads/2015/10/2015_10_08_15_44_09_806288.jpg

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

/wp-content/uploads/2015/10/2015_10_08_15_48_09_806301.jpg

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

/wp-content/uploads/2015/10/2015_10_08_15_52_14_806302.jpg

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:

/wp-content/uploads/2015/10/2015_10_08_16_01_59_806367.jpg

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)./wp-content/uploads/2015/10/2016_07_08_11_39_10_991498.png
  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.

 

Assigned Tags

      19 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Yan Pang
      Yan Pang

      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

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      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):

      /wp-content/uploads/2015/12/2015_12_17_09_51_51_853530.jpg

      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

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Added a section how to configure web service ManageAttachmentFolderIn.

      Author's profile photo Ahmed Zaidi
      Ahmed Zaidi

      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.

      Author's profile photo Pieter-Jan Vidts
      Pieter-Jan Vidts

      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?

       

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      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

      Author's profile photo David Thorne
      David Thorne

      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

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      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

       

      Author's profile photo Christoph Strobelt
      Christoph Strobelt

      Is there any chance, that the OutputRelevanceIndicator will be available using SOAP services in near future?

       

      Best Regards,

      Chris

      Author's profile photo Gareth Eade
      Gareth Eade

      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.

      Author's profile photo Hanumath Kanamarlapudi
      Hanumath Kanamarlapudi

      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

       

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Hanumath,

      basically you have two options:

      1. If the image can be accessed via a Web URL, then you can add the link to the image as Attachment of type "Link". You see an example in one of the screenshots in my blog post above.
      2. If you want to store the image as a copy in ByD, then you need to base-64 encode the file content and add the result as attachment of type "File" to the respective business object. This can be done via SOAP API as described above or using OData APIs. In the GitHub repository GitHub - ByD API Samples you find examples for creating attachments using OData.

      Best regards,
      Knut

      Author's profile photo Benny Huang
      Benny Huang

      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 &lt;default> &lt;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

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Benny,

      you require a "communication user" to access web service ManageAttachmentFolderIn.

      You get the communication user following the steps:

      1. Create a communication system that represents the external application or system that consumes the web service. The communication user is associated to the comm. system.
      2. Create a communication scenario as described in section "Configuration of Web Service ManageAttachmentFolderIn".
      3. Create a communication arrangement using the communication scenario of step 2 and the communication system of step 1. This step assigns the required web service authorizations to the communication user.

      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

       

      Author's profile photo Benny Huang
      Benny Huang

      Hi Knut,

      Thanks for your help.

      1. I use the user and password, it raise “Authorization role missing for service” as yesterday. Maybe I miss something.
      2. I want to use the SSL Client Certificate, but in soapUI, I don’t know how to config?   I had download the .pfx file or .p12 file, try many time as the help, Could you help me the step to run in the soapUI?

      Best Regards,

      Benny Huang

      Author's profile photo Jayash Joshi
      Jayash Joshi

      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

       

      Author's profile photo Yan Gerzon
      Yan Gerzon
      "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
              + "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:glob=\"http://sap.com/xi/SAPGlobal20/Global\" >    <soapenv:Header/>"
              + "<soapenv:Body>" + "<glob:SupplierBundleMaintainRequest_sync_V1>"
              + "<Supplier ActionCode=\"06\">        " + "<InternalID>" + supplierID
              + "</InternalID>               "
              + "<AttachmentFolder DocumentListCompleteTransmissionIndicator=\"true\" ActionCode=\"06\">"
              + "<Document PropertyListCompleteTransmissionIndicator=\"true\" ActionCode=\"01\">" +
              "<VisibleIndicator>true</VisibleIndicator>" +
              "<CategoryCode>2</CategoryCode>" +
              "<TypeCode>10001</TypeCode>" +
              "<MIMECode>image/tiff</MIMECode>" +
              "<Name>" +filename + "</Name>" +
              "<AlternativeName>"+filename+"</AlternativeName>" +
              "<Description languageCode=\"EN\">"+filename+"</Description>" +
              "<FileContent ActionCode=\"01\">" +
              "<BinaryObject mimeCode=\"image/tiff\" characterSetCode=\"\" format=\"\" fileName=\"\" uri=\"\">"
              + binaryAttachment
              + "</BinaryObject>" +
              "</FileContent>" +
              "</Document>"
              + "</AttachmentFolder>"
              + "</Supplier>"
              + "</glob:SupplierBundleMaintainRequest_sync_V1>" + "</soapenv:Body>"
              + "</soapenv:Envelope>")

      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

      DocumentListCompleteTransmissionIndicator be equal false it throw an error:

      Only list complete transmission (LCTI) allowed for SUPPLIER-ATTACHMENT_FOLDER-DOCUMENT - LIST_CTI001

      Author's profile photo Knut Heusermann
      Knut Heusermann
      Blog Post Author

      Hi Yan,

      please try the following pattern (works for me):

      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:glob="http://sap.com/xi/SAPGlobal20/Global">
         <soapenv:Header/>
         <soapenv:Body>
            <glob:SupplierBundleMaintainRequest_sync_V1>
               <BasicMessageHeader>
               </BasicMessageHeader>
               <Supplier actionCode="06">
                  <InternalID>KH-S01</InternalID>
                  <AttachmentFolder DocumentListCompleteTransmissionIndicator="false" ActionCode="06">
                     <!-- Provide the UUID of the attachment folder -->
                     <!-- optional: <UUID>00163ec9-1f9c-1eeb-bc89-905a65a997e9</UUID> -->
                     <Document ActionCode="01">
                        <!-- required for updates and deletion: <UUID>?</UUID> -->
                        <!-- <LinkInternalIndicator>?</LinkInternalIndicator> -->
                        <VisibleIndicator>true</VisibleIndicator>
                        <CategoryCode>2</CategoryCode>
                        <!-- Type code: 10001 Standard attachment, 10015 Technical drawing, 10016 Business 
                             partner image, 10082 Supplier-specific attachment -->
                        <TypeCode>10001</TypeCode>
                        <MIMECode>text/plain</MIMECode>
                        <Name>Business_partner_note.txt</Name>
                        <!-- Document title: -->
                        <AlternativeName>Business partner note</AlternativeName>
                        <Description languageCode="EN">Some comment</Description>
                        <!-- <ExternalLinkWebURI></ExternalLinkWebURI> -->
                        <FileContent ActionCode="01">
                           <BinaryObject>c29tZSBidXNpbmVzcyBwYXJ0bmVyIG5vdGVzIC4uLg==</BinaryObject>
                        </FileContent>
                     </Document>
                  </AttachmentFolder>
               </Supplier>
            </glob:SupplierBundleMaintainRequest_sync_V1>
         </soapenv:Body>
      </soapenv:Envelope>

      Best regards,
      Knut

      Author's profile photo Yan Gerzon
      Yan Gerzon

      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.