ODATA API ‘Attachments’ Service in SAP S/4HANA Cloud

[Prabha_A]

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!!