Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
Prabha_A
Product and Topic Expert
Product and Topic Expert
14,314
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!!

 
22 Comments
Florian_Kube
Participant
0 Kudos
prabhasubbulakshmi 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?
Prabha_A
Product and Topic Expert
Product and Topic Expert

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

  1. Make sure that the DIR exists in system. If not, you can create it manually using CV01n (Create Document). As an alternate option, you can also create DIR using API 'Document Info Record (Technical name: API_DMS_PROCESS_SRV)' with the POST entity '/A_DocumentInfoRecord' as below. Refer API hub API Reference | Document Info Record | SAP API Business Hub for more details.
  2. Then using Attachment service API, attach the original document to the existing DIR with the POST entity '/A_DocumentInfoRecordAttch'. Refer API hub API Reference | Attachments | SAP API Business Hub for more details.
  3. Later, this DIR with original document can be linked to the SAP Objects manually using CV02n (Change Document) or from the respective SAP object transaction.

Thanks,

Prabha A

0 Kudos

prabhasubbulakshmi

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

Prabha_A
Product and Topic Expert
Product and Topic Expert

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

Cristian
Participant
0 Kudos
Great blog prabhasubbulakshmi

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.
Prabha_A
Product and Topic Expert
Product and Topic Expert
0 Kudos

Dear cachico,

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

Mladen
Explorer
0 Kudos
Great blog prabhasubbulakshmi

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
Mladen
Explorer
0 Kudos
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
daviddasilva
Active Contributor
0 Kudos
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
bonafuwa7678
Explorer
0 Kudos

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

 

Prabha_A
Product and Topic Expert
Product and Topic Expert
0 Kudos

Hi bonafuwa7678,

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

bonafuwa7678
Explorer
0 Kudos

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,

 

 

 

0 Kudos

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

0 Kudos
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
0 Kudos
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
sreeni_kadiri
Discoverer
0 Kudos
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.
0 Kudos

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!

Jaman
Participant
0 Kudos
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?
RishabJain
Associate
Associate
0 Kudos
Hi prabhasubbulakshmi,

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

 
sven_w
Discoverer
0 Kudos

Hi prabhasubbulakshmi


Thanks a lot for this Blog!

How do i find the correct BusinessObjectTypeName?

I would like to get all attachment from a BillingDocument but i dont know the BusinessObjectTypeName for this Object.

Thanks,

Sven

Sriram961
Discoverer
0 Kudos

Hi Prabha,

Thank you for a detailed blog.

We want to create a PO and add attachments using standard API's in S/4 Hana on Premise system. We have found below 2 API's

API_PURCHASEORDER_PROCESS_SRV

API_CV_ATTACHMENT_SRV

 

Our requirement to attach the documents at the time of PO creation. Kindly let me know is it possible to call these API's  in sequence or any other alternative approach is there.

 

aoime02
Explorer
0 Kudos

Hi Prabha,

 I tried the instruction for Attach Document to Business Objects and successfully uploaded an attachment in the method using the binary. My additional question is, what is the process when I want the two attachments to be on two different document number because as I have tried uploading file again, the new file was uploaded to the initial document created.

Thank you in advance.