CRM and CX Blogs by SAP
Stay up-to-date on the latest developments and product news about intelligent customer experience and CRM technologies through blog posts from SAP experts.
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

How to Use 'document-service' API to Upload Documents into Sales & Service Cloud Version 2

manideepsatya
Product and Topic Expert
Product and Topic Expert
3 weeks ago

Sales & Service Cloud v2 offers REST APIs for all the entities(Ex : "case", "opportunity", "account" etc) supported in its business model. One of them is "document-service" which is used to handle the attachments in the system. Document-Service offers an API which can be used to create and link the documents as attachments to the standard entities(Ex : "case" ; "appointment" ; "account" etc) in the system.

In this blog, let's check how to use document-service api offered by Sales & Service Cloud v2 to upload the documents into the tenant and then link them to the entity of your choice.

Below is the pictorial view of how the API works.

document_service.jpg

 

Step 1 : Do a POST Call with file name and category
Request URL : https://*****crm.cloud.sap/sap/c4c/api/v1/document-service/documents 
Json Body :

 

{
"fileName": "Document_service.png",
"category": "DOCUMENT"
}

 

Response : 
Response will return the metadata object , with ID & Upload url. You can observe the "hostObjectType" as user which means the document is first uploaded into "user" space. 

 

{
	"value": {
		"id": "933cc1e0-2199-11ef-ac53-5b1803e1f4b0",
		"title": "Document_service.png",
		"fileName": "Document_service.png",
		"category": "DOCUMENT",
		"status": "OPEN",
		"thumbnailStatus": "NOT_PROCESSED",
		"fileSize": 0,
		"uploadUrl": "https://***************amazonaws.com/documents/5d94e446cd3cdc6f7c324c50/user/abf4a353-ea15-11e9-8fa7-f92a516fe752/933cc1e0-2199-11ef-ac53-5b1803e1f4b0/Document_service.png?***********",
		"adminData": {
			"createdBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"createdOn": "2024-06-03T11:08:15.572Z",
			"updatedBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"updatedOn": "2024-06-03T11:08:15.572Z"
		},
		"hostObjectId": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
		"hostObjectType": "user",
		"icon": "file_general",
		"color": "grey"
	}
}

 

Step 2 : Next you have to do PUT Call to the above URL - to upload the file. No need of any authentication, just upload the file.
Request URL: 
https://***************amazonaws.com/documents/5d94e446cd3cdc6f7c324c50/user/abf4a353-ea15-11e9-8fa7... 

Response  : Document will be uploaded into user space - status would be 200K with NO RESPONSE. 

STEP 3 (Optional) : You can do GET call again to verify the status of document 

Request URL : https://*****crm.cloud.sap/sap/c4c/api/v1/document-service/documents/933cc1e0-2199-11ef-ac53-5b1803e...

Response : Observe the document status changed from "OPEN" to "ACTIVE" , thumbnail status(only relevant for attachments of image type) changed from "NOT_PROCESSED" to "PROCESSED".

 

{
	"value": {
		"id": "933cc1e0-2199-11ef-ac53-5b1803e1f4b0",
		"title": "Document_service.png",
		"fileName": "Document_service.png",
		"category": "DOCUMENT",
		"status": "ACTIVE",
		"thumbnailStatus": "PROCESSED",
		"contentType": "image/png",
		"fileSize": 311675,
		"adminData": {
			"createdBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"createdOn": "2024-06-03T11:08:15.572Z",
			"updatedBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"updatedOn": "2024-06-03T11:08:15.572Z"
		},
		"hostObjectId": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
		"hostObjectType": "user"
	}
}

 

Step 4 : Next you have to do PATCH call on the service of respective entity to link the document. I have taken "case-service" as example, so that i can link the uploaded document to an existing case in the system.

Request URL : https://*****crm.cloud.sap/sap/c4c/api/v1/case-service/cases/4449a27a-1819-11ef-a2df-7982199a6240

Json Body : 

 

{
	"attachments": [
		{
			"id": "933cc1e0-2199-11ef-ac53-5b1803e1f4b0"
		}
	]
}

 

Response : Looks like below ***trimmed to only show case details and attachments node*** 

 

{
	"value": {
		"id": "4449a27a-1819-11ef-a2df-7982199a6240",
		"displayId": "505",
		"subject": "Timeline Testing on Case",
		"priority": "03",
		"priorityDescription": "Medium",
		"origin": "MANUAL_DATA_ENTRY",
		"originDescription": "Manual Data Entry",
		"caseType": "ZCASE",
		"caseTypeDescription": "Z Case Type",
		"statusSchema": "01",
		"partyScheme": "CASE_GENERAL",
		"status": "02",
		"statusDescription": "In Process",
		"escalationStatus": "NOT_ESCALATED",
		"communicationLanguage": "en",
		"isRecommendedCommunicationLanguage": false,
		"attachments": [
			{
				"id": "933cc1e0-2199-11ef-ac53-5b1803e1f4b0",
				"category": "DOCUMENT",
				"title": "Document_service.png",
				"fileName": "Document_service.png",
				"fileSize": 311675,
				"contentType": "image/png",
				"status": "ACTIVE",
				"adminData": {
					"createdOn": "2024-06-03T11:08:15.572Z",
					"createdBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
					"updatedOn": "2024-06-03T11:08:15.572Z",
					"updatedBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752"
				}
			}
		]
	}
}

 

Step 5(Optional) : You can now do a GET call with document id to ensure it is linked to the case and moved from user space to destination entity space. 

Request URL : https://*****crm.cloud.sap/sap/c4c/api/v1/document-service/documents/933cc1e0-2199-11ef-ac53-5b1803e...

Response : You can observe hostObjectType is changed as 2886 which means case. 

 

{
	"value": {
		"id": "933cc1e0-2199-11ef-ac53-5b1803e1f4b0",
		"title": "Document_service.png",
		"fileName": "Document_service.png",
		"category": "DOCUMENT",
		"status": "ACTIVE",
		"thumbnailStatus": "PROCESSED",
		"contentType": "image/png",
		"fileSize": 311675,
		"adminData": {
			"createdBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"createdOn": "2024-06-03T11:08:15.572Z",
			"updatedBy": "abf4a353-ea15-11e9-8fa7-f92a516fe752",
			"updatedOn": "2024-06-03T11:08:15.572Z"
		},
		"hostObjectId": "4449a27a-1819-11ef-a2df-7982199a6240",
		"hostObjectType": "2886"
	}
}

 

Important Points to Consider : 

  • Without uploading the document(PUT call) one should not do the patch call to particular entity - the call fails
  • "uploadURL" returned from the first POST call is presigned and is valid only for 10 mins. There is no need of authentication while you PUT this.
  • Mime types and Document size of attachments are configurable in the system at User Menu => Settings => Data Administration under "MIME Types for Attachments" & "Attachment Configuration". Check this whole section of Data Administration for more useful information before you start using attachments.
  • The header parameter "Content-Type"  is automatically added if the PUT call happens via Postman or Insomnia. If programmatically done, this needs to be passed manually
  • Header parameter "If-Match" is mandatory while you do PATCH call mentioned in STEP 4.  To get this value, you need to do GET call to the "case-service" with case id and in the response header parameters, you can find this value as "etag" (which is basically the last modified date on that particular record)
3 Comments
Popular Blog Posts