Communication

Request

The Post method should be used when a Communication is requested. The Get method can be used to query a previously requested Communication.

Note:

The Delete and Put methods are not supported at this time.

The API endpoint is as follows:

"https://environmentname/tenancy/api/Communication/v1/CommunicationRec".

Replace the environmentname with your specific URL information specific to your Service endpoint.

Replace tenancy with the target tenancy (non-prod, pre-prod or prod) within the environment.

Example: https://futurabank/non-prod/api/Communication/v1/CommunicationRec

For additional information on the environment and three tenancies provided by the Service, Refer to Financial Services Cloud Documentation.

Note:

For complete syntax please refer to the Swagger which can be obtained by calling "https://environmentname/tenancy/api/Communication/v1/CommunicationRec/swagger.json"

Headers

There are several headers that may be required by the methodology utilized to call the Post method on the API. The intention here is to identify those that have special consideration or maybe considered optional for other API calls.

The standard "Content-Type" header should be set to "application/json".

The standard "Authorization" header must be set to "Bearer token" where Token is the authentication token provided by a call to the OAuth access API.

For more information, refer to the Authorization topic.

Post Request

Body

The body of the post is JSON and must identify the configuration and the data to be used to create and distribute the Communication. The body may also contain optional elements as described below.

{      
        "CommunicationRec": {
        "CommunicationId": "String (Max: 1024)",
        "CommunicationInfo": {
            "CommunicationConfigUuid": "UUID String (36)",
            "MarketingCompanyConfigUuid": "UUID String (36)",
            "MarketingCompanyShortName": "String (Max: 30)",
            "CommunicationData": "{Escaped JSON}",
            "Language": "en_US",
            "CommunicationConfigEffDt": " yyyy-MM-dd ",
            "CommunicationTransactionEffDt": " yyyy-MM-dd ",
            "CommunicationTransactionType": "Enum",
            "CommunicationUserDefinedTransactionType": "String (Max: 255)"
            }
           }
          }

Elements

CommunicationId: Optional. A client specified unique identifier for the Communication. If not provided nothing is stored and an empty value is returned for the matching element in the response. This can be used for the calling application for its own purposes. The value is stored and returned in the response.

Note:

At least one of CommunicationConfigUuid or MarketingCompanyShortName or MarketingCompanyConfigUuid is required (see the note on Short Name or UUID below).

MarketingCompanyShortName: The Marketing Company Short Name is the name of the Marketing Company whose Communication Configuration should be used. The value is not stored and not returned in the response.

CommunicationConfigUuid: The UUID of the Communication Configuration to use with this execution. A UUID is a unique identifier the Service attaches to every configuration when created and is often returned in other API responses. The Configuration holds the settings that control what processes the execution will perform. The value is stored and returned in the response.

MarketingCompanyConfigUuid: The Marketing Company Config UUID is the specific UUID of the Marketing Company whose Communication Configuration should be used. The value is not stored and not returned in the response.

Note:

The decision to use a Short Name or UUID will depend on the use case being implemented. Both should be unique within the system. If the client is implementing a standard communication pattern it most likely should use the Short Name of the Marketing Company. If the client is implementing a complex flow where in it creates, searches, or otherwise calls another API to determine which Marketing Company to use the UUID is more likely to be used.

CommunicationData: Required. Escaped JSON data used by the Package Assembly Template logic to include documents and map data into output, metadata and/or addresses. The minimal JSON that is required “{}”; however, it is also dependent on the data required based on the Assembly Template (see the Assembly Template Reference). The value is stored but is not returned in the response.

Language: Optional.

CommunicationTransactionEffDt: Optional. Reserved for future implementation. It is stored and is returned in the response. If not provided the current system date and time will be used. Format is yyyy- MM-dd (e.g. 2022-05-17).

CommunicationConfigEffDt: Optional. Used to find configuration that is active on the specified date and time. The date and time provided is compared against the Active Status Date on the Configuration entity Versions and their children (Email, Storage, Package, Document Version, Layout, etc.) to identify the correct assets to use. This allows the client to produce output based on future or past dated configuration. If not provided the current system date and time is used. Format is yyyy-MM- dd (e.g. 2022-05-17).

CommunicationTransactionType: Required. Used to identify the specific Communication Detail Configuration for the Communication. Allowed values are “Origination” and “User Defined”. The value is not stored and not returned in the response.

CommunicationUserTransactionType: Is required only when Communication Transaction Type = "User Defined". It is used to identify the specific Communication Detail Configuration for the Communication. The value is not stored and not returned in the response.

Response

The response will return an appropriate status code (201, 404, etc.) but will also include a body that contains additional information that may be useful to the client.

4xx Error Response

Error responses will differ depending on the nature of the error. Generally, errors can be associated with one of several categories:

Authorization
Invalid Post
Invalid Data
Invalid Configuration
System

Invalid Post

If the Post does not include a required element.

{
     "executionId": "aac9cb4c-f643-447b-a75d-02c7b9e96a27",
     "responsePayload": null,
     "message": "Please provide CommunicationTransactionType in the request",
     "statusCode": 400,
     "failureReason": null,
     "messageCode": "Communication_DT_E_CR_1018",
     "success": false,
     "exceptionOnFail": null 
        }

Invalid Data

If the CommunicationData is not valid a typical response may appear as follows.

{ 
            "executionId": "3e91b7cc-3611-4793-92a0-155c218aaf6d",
            "responsePayload": null,
            "message": "AssemblyData is empty",
            "statusCode": "500",
            "execptionOnFail": null,
            "failureReason": null,
            "messageCode": "ERR_BAD_DATA",
            "success": false,
            "Messages": [
             {
                "Message": "ExecutionId: 3e91b7cc-3611-4793-92a0-155c218aaf6d" 
             },
             { 
               "Message": "Assembly version: 2.0.74" 
             },
            { 
              "Message": "Error code 500. AssemblyData is empty"
             }
         ]
     }

Elements

executionId is the unique id of this request's execution and can be used by Oracle Support to review logs not accessible by users. The message is the general description of the overall issue.
statusCode is the standard HTTP error code and will be in the 400 or 500 series for most failures.
Messages is an array of one or more detailed messages that provide more insight into the issue.
The number and value of the messages will vary depending on the error(s) found that led to the failure and are typically only provided when there is an Assembly related issue.
messageCode is an internal code that maybe useful to support.

2xx Success Response

{
          "CommunicationRec":{
             "CommunicationUuid": "CDA5FF69B32D4E87A9A3635433806FE5",
          "CommunicationInfo": {
             "CommunicationConfigUuid": "9628DE6255864B4CB421416BB11682D9" 
            }
         }, "CommunicationDetailRec": {
            "CommunicationDetailUuid": "9B7AD84F8F5B4AA4A9E0079B949C59B7",
            "CommunicationDetailInfo": {
            "CommunicationDetailConfigUuid": "13D530C4B70B49AE95D5C7F200A032C6",
            "CommunicationUuid": "CDA5FF69B32D4E87A9A3635433806FE5",
            "ConsolidatedStandardResponse": {
            "ConsolidatedManualReviewRequiredInd": false,
            "ConsolidatedResponseStatus": "Complete" 
            } 
        }

Elements

The response elements that mirror the request body elements are as described above in the Request Body section. Additional response items are as follows:

CommunicationUuid: The unique internal identifier of this Communication.

CommunicationDetailConfigUuid: The unique internal identifier of the Communication Configuration Detail that was used to produce the result.

ConsolidatedManualReviewRequiredInd: Boolean indicating if a Manual Review of the Communication is recommended based on the configuration and result. Generally this is true only when ConsolidatedResponseStatus is not Complete.

ConsolidatedResponseStatus: Indicates whether all the expected processes configured for the communication were completed or not. Possible values:

Complete: All processes that were called responded with a 'Complete' status.
Complete With Error: One or more of the processes that were called returned an 'Error' or Complete With Error' and one or more returned a 'Complete' status.
Error: All the processes returned an 'Error' status.
Incomplete: One or more processes returned an 'Incomplete' status. This occurs when an asynchronous call is still processing.

Get Request

The Get request can be used with several inline parameters or can be called with no parameters to return a list of all Communications. Calling without any qualifiers should be used with caution as the list of records could be extensive.

Options

CommunicationRec/

CommunicationRec/Id where the Id is the CommunicationId provided in the original Post request.

CommunicationRec/Uuid where the UUID is the CommunicationUuid returned from the original Post request.

Parameters

The following inline parameters can be added to the Get request.

depth: A Boolean value that when set to true will provide a more verbose response when used with an Id or UUID.

totalResults: A Boolean value that when set to true will provide a more verbose response when used with an Id or UUID.

whr: Can be used when Get is called without a UUID or Id to filter the results. Any attribute of a Communication can be used in the whr clause.

limit: A numeric that can be used to limit the number of results returned.

offset: A numeric that can be used with limit to affect paging of the results with multiple calls.

4xx Error Response

If no record is found with the UUID or the Id the response will be similar to the following. Other error responses will look like those from the Post.

{
         "executionId": "f4e32efb-2f43-44ee-b0d0-550e9c7f2a4d",
         "responsePayload": null,
         "message": "No Records Match Selection Criteria -
         No records match the selection criteria of the request.",
         "statusCode": 404,
         "failureReason": null,
         "messageCode": null,
         "success": false,
         "exceptionOnFail": null 
        }