Sample endpoint to leverage binary uploads for attachments
Overview
It describes using e-Business 6.0 services to leverage the Attachment functionality. Let's consider an example, the customer is required to upload a Date of Birth (DOB) document to their profile through e-Business 6.0.
How do we determine what a DOB document is?
You can create an Attachment Category named as DOB to determine the DOB attachment. Upload a DOB attachment to a person using Aptify Smart Client.
Learn how we can View & Download these DOB Attachments. Then use e-Business 6.0 services to upload the DOB attachment.
Also, we will see how we can Secure the endpoint.
Prerequisites
Verify that the following prerequisites are available on your system.
- e-Business 6.0 installed
- Services up
Once you have e-Business 6.0 Services up, you would need to create Endpoints.
For installing e-Business 6.0, please refer Using e-business 6.0
For information on JSON endpoints creation in e-Business 6.0, please refer Endpoint Metadata
POC Example
This will require three points as given below. All these points are discussed in detail.
DOB Attachment Category
Create a new attachment category in Aptify Smart Client (under Framework), name it as DOB, and scope it to Entity. Add Persons under Entities tab. Once DOB attachment category is created, we will need 3 JSON endpoints.
Here we can see the DOB category under persons attachment. We added one DOB attachment to it as given in below screenshot. Now, we will View and Download this attachment using our JSON endpoints.
JSON Endpoints
There are three endpoints used here as given below:
- ViewAllAttachments - View attachments based on Category, here it is DOB
- getSingleDownload - Downloads the Attachment based on ID
- Upload DOB Attachment - Uploads the DOB attachment to the Person Record
ViewAllAttachments
URL: v1/ViewAttachments/{EntityName}/{Id}/{CategoryName}?sort={sort}
Http method: GET
The URL segment includes:
- EntityName
- Entity RecordId
- CategoryName (DOB)
This endpoint returns list of attachments for a particular record for the specified category, which is DOB in this case. The business logic uses 'speBusiness6_0GetPersonRecordAttachments' Stored Procedure (SP) to fetch attachment records based on person and attachment category (You can find this in the CMPacks attached with the document). The response can be configured to return different fields by editing 'outputEntityDefintion' in JSON code given below. Also, the SP can be modified to return more or less values depending on requirement.
Here is the JSON code for the View Attachments endpoint.
This code is written in the HDEB-10 (Code + Metadata) Attachments.zip →DownloadAttachment.json file.
Below is the stored procedure for fetching attachment records.
Code in Action
When this endpoint is executed against the above person record for the DOB attachment category, we can see the result.
Here is the response as shown in POSTMAN:
getSingleDownload
URL: v1/ProfilePersons/{id}/Download/{entityName}/{recordId}/{attachmentId}
Http method: GET
This downloads the attachment of a person based on attachment ID. This action requires below URL parameters as given below:
- entityName - Persons in this case
- recordId - Entity Record ID
- attachmentId - The ID of attachment record to download
This code is also written in HDEB-10 (Code + Metadata) Attachments.zip → DownloadAttachment.json file.
Code in Action
Download the DOB attachment of the above person in Chrome browser. As we can see in the Screenshot below, we successfully downloaded the attachment which we uploaded initially through Smart Client.
The code given below provides security to this endpoint. We will discuss about this in Security.
Upload DOB Attachment
URL: v1/ProfilePersons/{id}/UploadAttachment
Http method: POST
This endpoint attaches the file to the Person's record under the DOB category.
This code is written in HDEB-10 (Code + Metadata) Attachments.zip → FileUpload.json file.
This endpoint uses the "Test Attachment PF” process flow which is under HDEB-10 (Code + Metadata) Attachments.zip → HDEB-10_PF_TestAttachment.cmpack.
Upload - Hardcoded entity and category
For the POC, Entity Name, and Category Id are hardcoded in the Business Logic.
Code in Action
Upload one more DOB attachment to the person as shown is the below screenshot, using this endpoint:
Now, refresh the Person record on Smart Client and we can see that there are two attachments. Second attachment uploaded by using JSON endpoint.
Also, when we hit 'ViewAttachments' endpoint, we can see two attachments being returned.
Security
The attachment Record is secured by a SQL function 'spSecurityeBusiness6_0CanPersonAccessAttachment'. This function makes sure that the attachment belongs to the authenticated Person Record and category DOB.
You can find the Stored Procedure under HDEB-10 (Code + Metadata) Attachments.zip → HDEB-10_SPs.cmpack.
This code block is written in "..\eBusiness\json\metadata\v1\Common\security.json". This executes the above security function with the required parameters.
"isYourAttachment": { "type": "SQLFunction", "parameters": { "functionName": "spSecurityeBusiness6_0CanPersonAccessAttachment", "functionParameters": { "@PersonId": "@request.recordId", "@AttachmentId": "@request.attachmentId", "@CategoryName": "DOB" } } }
This is written in the getSingleDownload JSON endpoint to secure with the above security.
"security": { "IsYourAttachment": { "$ref": "../../Common/security.json#/isYourAttachment" }
Example
Whenever an unauthorized person tries to fetch an attachment, this give errors as given below:
Deployment Instructions
Follow the below given steps to deploy the above mentioned POC example.
- Extract the files from HDEB-10 (Code + Metadata) Attachments.zip.
- Unpack the PF's and DBO's CMPacks using CM tool.
- Paste FileUpload.json and DownloadAttachment.json files under “..\eBusiness\json\metadata\v1\Endpoints\ProfilePersons” folder.
4. The above three endpoints are registered under HDEB-10 (Code + Metadata) Attachments.zip → ProfilePersonEndpoint.json file.
5. Add the class 'AttachmentComponent.cs' from HDEB-10 (Code + Metadata) Attachments.zip under 'MultipartFormDataProcessFlows' project in Visual Studio.
This class Implements “IProcessComponent” interface. This component is responsible for attaching the Attachment to the entity record specified by the Input Parameters.
Copyright © 2014-2019 Aptify - Confidential and Proprietary