Technical Articles
ODATA API ‘Attachments’ Service in SAP S/4HANA Cloud
Introduction:
The Attachment Service API is used to manage attachments.
Technical name: API_CV_ATTACHMENT_SRV
This service allows you to manage attachments and attachment URLs for business objects such as Sales Order, Purchase Order, Purchase Requisition, Supplier Invoice, Service Order, etc..,. This API allows you to perform different operations viz create, read, rename, and deletion of attachments. It also allows you to read an existing document info record (DIR) and add attachments to it. As an output, the Attachment service returns an appropriate success or error response while performing the attachment operations.
Firstly, we need to configure the availability of the API on our SAP S/4HANA Cloud system. As part of configuration, we need to create a communication user, communication system and communication arrangement. This configuration is mandatory to implement any API services in the SAP S/4HANA Cloud System.
Pre-requisites:
Assign the below roles to your User Id to access the required Fiori apps.
Figure 1: Business Roles to access Communication Fiori Apps
Maintain Communication Users
A communication user allows you to integrate with the external system. User Name and Password will be created in communication user using which the external system can authenticate themselves and read/post data. This communication user will be assigned to the communication system for performing Inbound and outbound services with the external system.
- Access the Fiori app ‘Maintain Communication Users’ and click on ‘New’ to create new communication user.
- Input the Username and Description
- Input the Password manually or click the button ‘Propose Password’. It will generate a password.
Figure 2: Create Communication User
Communication Systems
To connect the SAP S/4HANA cloud system with the external system, we need to assign the cloud system host name and port in the Communication Systems app. The communication system will then be assigned to the communication arrangement in which all the supported inbound/outbound services can be viewed.
- Access the Fiori app ‘Communication Systems’ and click on ‘New’ to create new communication system.
- Input a unique System Id and System Name (Eg: ‘ZDEMO_SYSTEM’) and click on create option.
Figure 3: Create New Communication system
- Input the Host name and HTTP Port number (Default value: 443). Host name is the cloud system URL in which Attachment service API needs to be implemented.
Figure 4: Assign Host name in Communication System
- Go to the tab ‘Users for Inbound communication’ where we define how the external system authenticates itself when it sends business documents to SAP S/4HANA Cloud system.
- Click on the ‘+’ (Add) icon and input the communication user (‘ZDEMO_TEST’) that we have created in the above step. Click on OK.
Figure 5: Assign Inbound Communication User in the Communication System
- Similarly, assign the user in the ‘Users for outbound communication’ tab as well. Here we define how SAP S/4HANA Cloud system authenticates itself when it sends business documents to the external system.
- Click on ‘Save’.
Communication Arrangements
Communication Arrangements are created using Communication Scenarios which is pre-configured in the system and can be referred in the SAP API Hub to get the list of supported scenarios for the Attachment service API. The authorizations, inbound/outbound services and the supported authentications methods required for communication will be determined by the communication scenarios.
- Access the Fiori app ‘Communication Arrangements’ and click on ‘New’ to create new Communication Arrangements
- Input the Scenario Id (E.g., SAP_COM_0109 for Sales Order Integration) and the Arrangement Name. The list of Communication scenarios that the Attachment service API supports can be referred from the SAP API Hub – Overview | Attachments | SAP API Business Hub
- Input the Communication system that we have created in the previous step. Communication user will be populated automatically. Click on Save.
Figure 6: Create Communication Arrangement
- The Applicable API services for the selected Scenario Id can be viewed in Communication Arrangement Fiori App.
Figure 7: Supported Services for the Scenario Id
If Attachments service is not listed in the communication arrangement, then it means that the Attachment API service doesn’t support that scenario id. In the above case, Attachments API service is listed in the Inbound service which means that it supports Sales Order Integration Scenario.
Now, SAP system is ready to use the Attachment service API. Below are the Header Input parameters for the Sales order and Purchase order integration to send/receive documents.
Attach Document to Business Objects:
API Reference Entity: /AttachmentContentSet
Content-Type supported by Attachment API service: MIME Types Supported by Attachments Service | SAP Help Portal
Table 1: Header Parameters for AttachmentContentSet
Postman view:
Postman is a powerful API testing tool which can be accessed in chrome by clicking Postman.
HTTP Method: POST
URL: This can be copied from the inbound service tab of the Communication Arrangements.
Followed by the URL, add the respective API reference entity (/AttachmentContentSet). API reference entity can be viewed in SAP API hub – API Reference | Attachments | SAP API Business Hub
Input the Required Header Parameters and click on ‘Send’. It displays the Success/Error message accordingly in the below section.
Figure 8: Postman View for creating Attachment
Once Document is attached, you can view the same in the Fiori app ‘Display Sales Orders – VA03’ under ‘Services for Object’
Attach URL Document to Business Objects:
API Reference Entity: /CreateUrlAsAttachment
Table 2: Header Parameters for CreateUrlAsAttachment
Postman view:
HTTP Method: POST
URL: This can be copied from the inbound service tab of the Communication Arrangements.
Followed by the URL, add the respective API reference entity (/CreateUrlAsAttachment)
Input the Required Header Parameters and click on ‘Send’. It displays the Success/Error message accordingly in the below section.
Figure 9: Postman view to create URL as Attachment
Once URL Document is attached, you can view the same in the Fiori app ‘Display Sales Orders – VA03’ under ‘Services for Object’
Get all the Original Documents attached to the Business Objects:
API Reference Entity: /GetAllOriginals
Table 3: Header Parameters for GetAllOriginals
Postman view:
HTTP Method: GET
URL: This can be copied from the inbound service tab of the Communication Arrangements.
Followed by the URL, add the respective API reference entity (/GetAllOriginals)
Input the Required Header Parameters and click on ‘Send’. It displays the Success/Error message accordingly in the below section.
Figure 10: Postman view to Get all the Originals
It returns the below details of all the original documents attached to the Business Object.
DIR (Document Info Record) Document Type, DIR Document number, DIR Document version, Logical Document, Archive Document Id, file name and file size.
Delete Attachment:
The values to be passed in Delete Attachment entity can be fetched using /GetAllOriginals entity
Postman view:
HTTP Method: DELETE
URL: This can be copied from the inbound service tab of the Communication Arrangements.
Followed by the URL, add the below API reference entity and the values will also be passed along with the API reference entity. /AttachmentContentSet(DocumentInfoRecordDocType=’GOS’,DocumentInfoRecordDocNumber=’EXT47000000051431′,DocumentInfoRecordDocVersion=”,DocumentInfoRecordDocPart=”,LogicalDocument=’42010AEF4E0E1EECBDED7501518C35FC’,ArchiveDocumentID=’42010AEF4E0E1EECBDED7501518C55FC’,LinkedSAPObjectKey=’0000044955′,BusinessObjectTypeName=’BUS2032′)
Figure 11: Postman view to Delete the Attachment
If the document deleted successfully, it doesn’t return anything. If there is any error, it displays the error message.
Hence by using Attachment service API, documents can be uploaded, renamed, retrieved and deleted by calling different API reference Entities. For more information on the available reference entities, refer API Reference | Attachments | SAP API Business Hub
Kindly drop your valuable feedback and thoughts in the comment. Follow me for more useful insights on SAP S/4HANA Cloud.
Happy Learning!!
Prabha Subbulakshmi Arumugam thanks for that great blog post.
Is it also possible just to store a file into the archive without link it to an object? Like we can do it with function module ARCHIVOBJECT_CREATE_TABLE?
In my scenario the file first needs to be stored, and later it will be linked to a SAP Object?
Hi Florian,
If you want to attach the documents without any reference to the Business Object, then you can follow the below steps to directly attach the document to DIR (Document Info Record).
Thanks,
Prabha A
Prabha Subbulakshmi Arumugam
When I try to create attachments to an Inbound delivery, I receive following error which doesn't actually explain much of what is the problem. But when I upload the file via Fiori App in Attachment section, it works. Could you please point out the problem?
Thanks,
Tejaswi
Hi Tejaswi,
At times, Postman doesn't support URL as content. So, need to attach the original document. Please remove 'Content' field from Header parameter and try selecting 'binary' in the Body as shown in below snap > Select file > Add the document and then click on Send.
Thanks and Regards,
Prabha A
Thank you, this helped resolve my problem.
I was able to make the request ok, but the content was not sent correctly and I suspected it was because Postman was not retrieving the file from my folder. By using this binary type, I was able to send the content too and open the pdf from the relevant app.
Thanks!
David
Great blog Prabha Subbulakshmi Arumugam
I have a question, we need to send to an external application the documents associated to the below business objects in S4HANA Cloud.
Purchase Order
Sales Order
Outbound Delivery
Sales Invoice
Is there any capability in this API to retrieve the forms themselves instead of the metadata of the documents?
Many thanks!
C.
Dear Cristian Abad Chico,
Hope you are doing good!!
Using the entitiy '/GetAllOriginals', you will be able to get the metadata of all the original documents attached to the Business object. But printing the actual documents (forms) is not possible using this API.
You need to develop a new form in the external system and populate the fields with required data that you have fetched using API.
If the third party system is a SAP system, then you can use Adobe Forms service on SAP BTP to build a new Form or make use of the existing Standard Form.
Thanks and Regards,
Prabha A
Great blog Prabha Subbulakshmi Arumugam
I am trying to test creating attachment on document info record to S4HC system via Integraton Suite and have a problem.
When I use it via Postman directly using /A_DocumentInfoRecordAttch entity as you wrote in an one answer on 5.8.2022 it works, but when I try to use it via Integration Suite I get this error in Integration Suite:
org.apache.olingo.odata2.api.uri.UriNotMatchingException: Could not match segment: 'A_DocumentInfoRecordAttch(DocumentInfoRecordDocType='ZZZ',DocumentInfoRecordDocNumber='00001206109',DocumentInfoRecordDocVersion='01',DocumentInfoRecordDocPart='000')/DocumentInfoRecordToAttachmentNavigation'.
I found a SAP note: 3124442 - Message processing failed with Error "Could
not match segment:'******'" which said to use HTTP instead of ODATA adapter
When I switch to the HTTP adapter I get this error:
CSRF token validation failed
What would you suggest me to proceed?
Regards,
Mladen
Hello all,
I was able to solve a problem with following error: CSRF token validation failed using suggestions (groovy script for Cookie header, http session reuse) from the following question:
CSRF token validation failed | SAP Community
Now I am able to send a file to the document info record.
Regards,
Mladen
Hello Prabha,
Great job on this wonderful blog.
We have followed this blog (and others on the subject matter) while attempting to integrate our recently provisioned "SAP S/4HANA Cloud 2208" with an external CMIS repository; most importantly, we had used the SAP Note 3011960 to setup the communication arrangement as described thus in the note.
Using the api.hub, we can validate connectivity between our custom external repository and SAP BTP DMS.
Per the SAP Note 3011960, we completed the configuration activity "Attachment Service - Storage Repository Activation" from the SAP CBC as shown below to help route the attachments from the Standard FIORI Apps to the external CMIS repository.
Attachment Service - Storage Repository Activation
We have attempted to reproduce your example with a supplier invoice without success; we ran into the below error as shown below:
SAP Gateway Service Error
The gateway service error shows that the OriginalContentSet gets called during the attachment upload and same error manifested from postman when we called
"https://<somevalue>-api.s4hana.cloud.sap/sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/AttachementContentSet"
Per the guide here (https://help.sap.com/docs/SAP_S4HANA_CLOUD/7489fa08cede494cbdf08fa3651598af/64b4f4c0d32e49c4a741ea056bef91c7.html?profile=20020833), the DIR parameters are mandatory as part of the requests for Document Management when testing API_CV_ATTACHMENT_SRV.
Can you provide some clarity as to where to get this from? Where do we config the DIR in an S4/HANA Cloud system? What FIORI APPs to help us with this configuration for DIR?
In the blogs we have explored so far, we did not encounter the details steps to hook the attachment service in the standard FIORI apps to an external repository. The question is what to do next to "instruct" the reusable attachment component UI in the Standard SAP FIORI Apps (e.g. New Supplier Invoice, Purchase Orders, Journal Entries etc) to make use of our configuration above or more precisely, the communication arrangement addressed by SAP_COM_0597.
Lastly, do we need to configure each app communication arrangement in addition to the SAP_COM_0597 for this whole setup to work?
We need your help in these regards.
Kindest Regards,
Bakau O
Hi Bakau Onafuwa,
Could you please share the input parameters and Header data that you are passing as an input for this API (entity: /AttachmentContentSet). Please make sure that you are passing values for content and slug as per the above snap (Figure8: Postman view for creating attachment)
And yes, we need to configure each object specific communication arrangement (like SAP_COM_053 for purchase order Attachment, SAP_COM_0109 for sales order attachments) in addition to SAP_COM_0597
Thanks,
Prabha A
Hi Prabha,
Thank you for the response.
This issue is currently being discussed as an incident; once the support case is resolved, I will update here accordingly.
Regards,
Hi Prabha! Thanks for the valuable information. Please advise if you know what can be the reason I am getting error "SAP Office document ID cannot be empty; enter a valid doc ID" when I am trying to perform attachment via /sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/AttachmentContentSet ? I am trying both standard and custom Business objects.
Thanks for any hints
Hello Prabha,
Great job on this wonderful blog.
Is it possible to use this API with postman or gateway client without using the "Select File" or "Add file" function?
What I see is that the attachment is displayed correctly when using the option.
I also tested the conversion to base64 but unfortunately the file does not open
I would like to point out that the Content = file path does not work when it is added in the header as indicated on the post.
Any help or hint would be highly appreciated. Thanks a lot in advance.
Regards
Abdoulaye
Hi,
You will find the solution on the following link
https://answers.sap.com/questions/13884111/how-do-i-pass-the-raw-data-as-content-for-attachme-1.html
Best regards,
Abdoulaye
In my Case, I don't want to upload file from my C drive, but rather pass the content as Base64Str.
Passing Base64String in Content, does not work.(file is getting attached, but it is corrupted)
How do we pass Base64String content to this api?
more informative and useful. I have different use case, using attachment service ODATA api, archive/store the document in external DMS repository ( OpenText), current the attachment stored in SAP default DMS. Please let me know.
Hi,
We have an odata v4 fiori app, now it's ok to display the attachment component, and be able to click the upload button, but failed to upload an attachment with error no authority to CREATE. I found it missing two parameters in request header, objectType and objectKey, but I did offer these in the manifest. So here I have some question:
1: Does this attachment reuse component support odata v4 or not?
2: If it does, what is the correct way to config the component in manifest? (I will paste the config in my manifest)
3: Also, another function next to upload named "add a link", it's not work for us as well, the response says "message": {"lang":"en","value":"Malformed URI literal syntax"}, so I was wondering if this related to the question 1.
Thanks!
Prabha Subbulakshmi Arumugam
Hi,
I have a question for "/sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/A_DocumentInfoRecordAttch" api. I want to upload attachment on existing dir. When I use binary as a select file on body, it is work. I have binary data for pdf file and i want to added this binary data as a Content. But I got an error "File is either corrupted or file format not supported for upload." How can I passed the binary data?
Thanks and best regards.
Hi Prabha Subbulakshmi Arumugam,
We are using below Query to add an attachment to an existing DIR using SAP Gateway Client.
/sap/opu/odata/sap/API_CV_ATTACHMENT_SRV/A_DocumentInfoRecordAttch(DocumentInfoRecordDocType='DRW',DocumentInfoRecordDocVersion='00',DocumentInfoRecordDocNumber='0000000000000010000000018',DocumentInfoRecordDocPart='000')/DocumentInfoRecordToAttachmentNavigation
Header Parameters:
Content : C:\Users\<<userid>>\Downloads\abc_file_testing.tif
Content-Type : image/tiff
Slug newtifffile.tif
The Image file gets attached successfully and can be viewed in CV03N. But, When we tried with an Integration flow(CPI as Middleware) reading the file content from MS SQL Server having column data type(VARBINARY(MAX)), We are able to attach but the image is not displayed.
We would like to know, if we need to do any conversion and the HTTP Headers for it before calling the Attachment API End Point in CPI?
Also, We would like to know the file format(Base64 or Binary) supported in the HTTP Body Content when we use GW_CLIENT for testing this API locally?
Thanks,
Rishab