Attachment and Comments Service

4.19 Attachment and Comments Service

This ECM service allows clients to post attachments and comments from an external application to a case in Oracle’s Enterprise Case Management application.

This is useful when there are external processes that create evidence for a case and that information needs to automatically be attached to the case. For example, a client may have an RPA process which creates a customer profile for an investigator which will assist in the investigation. This service can post that profile to the case. It is then viewable from the Evidence tab within the case. The process is also recorded in the audit history of the case. The receipt of the attachment or comment may also be a status changing action. This allows for the status of the case to be updated when the document/comment is received.

Note:

This service is only available in ECM release 8.0.7 and beyond.

With this service, you can associate attachments or comments with a case, a business entity, or both. At this time, attachments can only be viewed through a case. The ability to view a business entity and see attachments and comments related to that entity will be provided in a future release. If you intend these attachments and comments to be for an entity, Oracle recommends you associate to both cases and entities in preparation for this future functionality. Each request can only associate a document or comment with one case or one entity.

This topic contains the following sections:

Service Definition

This section includes the following topics:

Service URL

In the following example, a customer profile document created on customer John Doe (Customer ID CA12345) is being attached to case CA54321. The source of the document is from an RPA application. When the attachment is received, the status of the case will update to the status associated with action code CA986 as defined in PMF.

http://<<webserver IP or name>>/<<application context>>/rest- api/ECMService/
CaseManagementService/ecmUploadFile?entityId=CA54321&caseId=
CA54321&entityType=case&comments=Customer Profile for John Doe&docDesc=Customer
Profile from RPA Process&docType=Customer Profile&source=RPA Process ID
1234&senderId=RPAUser1234&actionCode=CA986

Note:

Here, & is used for separating the parameters in the above URL. The document or file has to be attached as multipart/form-data while calling the service. Authentication information has to be provided with Bas64 encoded format of <username>:<password>. Any space or special characters in the URL query parameters need to be ‘Percent-encoded’

Service Method

The service method is POST for the enhanced security.

Request/Query Parameters

The following table describes the details of the parameters.

Table 4-37 Request/ Query Details

Name	Parameter Name	Description	Required
Entity ID	entityId	It can be the Case ID or the Business Entity ID to which the document/comment is associated. If entity type is ‘CASE’, then entityId will be validated against the valid case IDs in the system. No validation for other entity types.	Y
Entity Type	entityType	Entity type is the type of entity against which this action is performed. By default, entity type ‘CASE’ is defined in the system. User needs to configure the other entity type in the system. For configuring new entity type, see Configuring Entity Types. If entity type is other than CASE, then provide an entity ID in the entityId parameter. You can also provide a case ID in the caseId parameter, so the document/comment will be associated with both case and the entity.	Y
Comments	comments	Comments to be stored against the Case/Entity. You can enter up to 64k characters.	Y
Sender ID	senderId	Thiscan be a valid ECM user ID or a valid AAI user ID. If it is a valid ECM user ID, this will be displayed in the audit history and Evidence tab. If it is a valid AAI ID, then ‘SYSTEM’ will be displayed in the Audit History and Evidence tabs. If using an ECM user ID it will go against the client’s ECM licensed user count. If using an AAI ID, it is recommended that some user identifier is also included in either the Document Description or Comment parameters.	N
Document Description	docDesc	Description of document attached.	N
Document Type	docType	Used to categorize the type of document being sent.	N
Case ID	caseId	ID for the case in which the document or comment should be associated.	N
Action Code	actionCode	Defines the code for the action that is to be performed. This should be a valid action as defined in KDD_ACTION and/or PMF. Action Code is only validated against KDD_ACTION. It is not validated that it is a valid action for the case in the current status. Action Code for external document attach is CA985. Action Code for external comment is CA986	N
Source	source	Where the document/comment came from.	N

Along with the above mentioned parameters, if document/file is to be sent, attach the document/file as multipart/form-data. For more information, see Sample Java Code for the Service Call.

Service Response

This service responds with a JSON object as the response data. The following is a sample response data:

{
status: “Success”,
description: “The request has been successfully processed”
}

For the possible response messages, see the Response Messages section.

Sample Java Code for the Service Call

This section shows an example of how to write a REST client in Java to call this service.

Create a URL (java.net.URL) object and Open the Connection:
```
URL url = new URL(<SERVER_URL>);
HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
```
Note:
<SERVER_URL>: It is the end point URL for the service. For example, see the Service URL section.
Set the request Headers:
```
urlConnection.setRequestMethod("POST"); urlConnection.setRequestProperty("Authorization",
<basicAuthEncryptedString>);
urlConnection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" +
<boundaryString>);
```
Note:
<basicAuthEncryptedString> : It is a Base64 (org.apache.commons.codec.binary.Base64) encrypted credentials in String format. <boundaryString> : Define your boundary String.

Write the File/Document to the URL Connection Output Stream:

OutputStream outputStream = urlConnection.getOutputStream();
BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream));
// Include the section to describe the file
String LINE_FEED = "\r\n";
for(int i=0; i< <FILE_PATHS>.length; i++){
File fileToUpload = new File(<FILE_PATHS>[i]); String fileName = fileToUplod.getName();
writer.append("--" + boundaryString).append(LINE_FEED);
writer.append( "Content-Disposition: form-data; name=\"file\"; filename=\"" + fileName +
"\"").append(LINE_FEED);
writer.append(URLConnection.guessContentTypeFromName(fileName)).appen d(LINE_FEED);
writer.append("Content-Transfer-Encoding: binary").append(LINE_FEED);
writer.append(LINE_FEED);
writer.flush();
FileInputStream inputStream = new FileInputStream(<fileToUpload>);
byte[] buffer = new byte[4096]; int bytesRead = -1;
while ((bytesRead = inputStream.read(buffer)) != -1) { outputStream.write(buffer, 0, bytesRead);
}
outputStream.flush(); inputStream.close();
writer.append(LINE_FEED); writer.flush();
}
// Mark the end of the multipart http request
writer.write("\r\n--" + boundaryString + "--\r\n"); writer.flush();
// Close the streams outputStream.close(); writer.close();

Note:

<FILE_PATHS>: Array of File paths to be uploaded.

Reading the Service Response:

BufferedReader httpResponseReader = new BufferedReader(new
InputStreamReader(urlConnection.getInputStream()));

Changing Case Status upon Service Execution

The status of a case can be updated when a document or comment is received. This is achieved through the Action Code parameter.

If no Action Code is defined, the action seen on the Evidence tab is Added External Document / Added External Comments and the Resulting Status is not updated.
If the Action Code sent is only defined in KDD_ACTION and not in PMF, then the action on the Evidence tab will be what was provided in the Action Code parameter, and the Resulting Status is not updated (and the status of the case does not change).
If the Action Code sent is defined in both KDD_ACTION and in PMF, then two records are recorded in the Audit History. One, for the receipt of the document, and the other for the case status change. Both records have the same Action name but the Resulting Status will be different.

Response Messages

The following table shows the list of possible Response Messages.

Table 4-38 Response Messages

Scenario	Status	Description
On Success	Success	The request has been successfully processed.
Missing mandatory parameters (entityId, entityType, comments)	Failed	Missing mandatory parameters. Please make sure you send these parameters : entityId, entityType, comments.
Invalid value for a parameter (entityType, entityId/caseId)	Failed	Invalid value for the parameter. Please make sure you send valid value for : <parameter-name>.
PMF Workflow call fails	Failed	Request has been failed : Unable to start workflow.
INSERT query fails for FCC_CM_DOC_S ERVICE	Failed	Request has been failed : Unable to INSERT the record to the service table.
saveCaseAttachment procedure fails	Failed	Request has been failed : Unable to INSERT the record to attachment table.
saveCaseComment procedure fails	Failed	Request has been failed : Unable to INSERT the record to comment table.
Document upload fails from AAI api (includes invalid file extension)	Failed	Request has been failed : Unable to upload selected files.

Configuring Entity Types

By default, the configuration for the entity type ‘CASE’ is defined in the system. Any further Entity Type configuration needs an entry in the table FCC_CM_DOC_SRVCE_CONF. The following table lists the Entity Type- related Column Name, Data Type, and Description.

Table 4-39 Configuring Entity Types

Column Name	Data Type	Description
V_ENTITY_TYPE	VARCHAR2(1000 CHAR)	Defines an Entity Type.
V_MANDATORY _PARAMS	VARCHAR2(4000 CHAR)	Set of parameter to be made mandatory for the Entity Type (Comma separated).
V_ALLWD_DOC UMENT_TYPE	CLOB	For Future Use.
V_ALLWD_ACTI ON_CD	VARCHAR2(4000 CHAR)	For Future Use.
V_ALLWD_SOURCE	CLOB	For Future Use.
V_ALLWD_USER_IDS	CLOB	For Future Use.

For example, if you want to define/configure a new entity type as “CUSTOMER” with senderId and actionCode as mandatory along the default mandatory parameters mentioned in the Request/Query Parameters section, then make the entries in FCC_CM_DOC_SRVCE_CONF table as shown in the following table:

Table 4-40 FCC_CM_DOC_SRVCE_CONF Table Details

V_ENTITY_TYPE	V_MANDATORY_PARAMS	V_ALLWD_DOCUMENT_TYPE	V_ALLWD_ACTION_CD	V_ALLWD_SOURCE	V_ALLWD
CUSTOMER	senderId,actionCode	(null)	(null)	(null)	(null)