Skip to Content

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

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

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.

 

To report this post you need to login first.

10 Comments

You must be Logged on to comment or reply to a post.

  1. Former Member

    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

    (0) 
    1. Knut Heusermann 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

      (0) 
  2. Former Member

    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.

    (0) 
  3. 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?

     

    (0) 
  4. 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

     

    (0) 
  5. 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

    (0) 
    1. Knut Heusermann 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

       

      (0) 
      1. 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

        (0) 

Leave a Reply