1. REST API for Oracle CX Sales and B2B ServiceREST API for Sales and Fusion Service in Oracle Fusion Cloud Customer Experience
  2. Use Cases
  3. Variable Substitution for Smart Texts using REST API

Variable Substitution for Smart Texts using REST API

You can manage smart texts using the Smart Texts REST API. A smart text entry is a reusable fragment of text that you can use in service request (SR) messages. In this use case, we will demonstrate how to substitute variable for smart texts with unique public identifier (PUID) and with an alternate identifier. It also explains how to use the smart text in an SR by user-defined variable value. To understand how to use Smart Texts, let's go through these tasks:
  • Create a Smart Text
  • Get the SrId and the SrNumber
  • Smart Text Variable Substitution with the PUID
  • Smart Text Variable Substitution with Alternate Identifier
  • Use the Smart Text in an SR by User-Defined Variable Value

Create a smart text

You can use the Smart Texts resource to create a smart text by submitting a POST request on the REST resource using cURL. Alternatively, you can create a Smart Text in the UI too by navigating to Tools > Smart Texts

URL

https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts

Method: POST

ContentType:application/vnd.oracle.adf.resourceitem+json

Request Body

{
   "StdtxtName":"Customer Smarttext Example",
   "UniqueNumber":"CUST_0001",
   "HtmlFlag":"Y",
   "Scope":"ORA_SVC_GLOBAL",
   "FolderId":"300100543810122",
   "Object":"ServiceRequestVO",
   "BuOrgId":204,   
"Text":"RGVhciBbW1NlcnZpY2VSZXF1ZXN0Vk8uUHJpbWFyeUNvbnRhY3RQYXJ0eU5hbWVdXTo8YnIgLz48YnIgLz5Zb3VyIGNvZGUgcmVxdWVzdCBOdW1iZXIgW1tTZXJ2aWNlUmVxdWVzdFZPLlNyTnVtYmVyXV0gaXMgYmVpbmcgYXR0ZW5kZWQuPGJyIC8+PGJyIC8+UmVnYXJkcyw=",
   "Language":"US"
}

Note the following:

In the above request body:

  • UniqueNumber is optional, it will default a sequenced generated value as CDRM_0001 type format.
  • Text is the Base64 encoded value of the following text: 
Dear
        [[ServiceRequestVO.PrimaryContactPartyName]]:<br /><br />Your code request Number
        [[ServiceRequestVO.SrNumber]] is being attended.<br /><br />Regards,

Note: The above example uses Rest-Framework-Version prior to v8. If you are using Rest-Framework-Version v8 and above, then there is no need for base64 encoding.

  • FolderId must be a valid public folder with a Domain of ORA_GENERIC.
  • BuOrgId must match the value of the BuOrgId on the Folder.
    • NOTE: This is for multi-business unit support. It can be null if you are using one business unit. Depending on the version of the application, the BuOrgId may not exist in the smartTextFolders resource. If the attribute does not exist, then the value of the BuOrgId can be ignored.

      To see if it exists, you must send a describe request on the smartTextFolders resource:

      https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/describe

  • Object is a required value and is mostly the ServiceRequestVO. You can find other values in the svc_std_txt_objects table.
Response Body
{
    "StdTxtId": 300100547184758,
    "CreatedBy": "SALES_ADMIN",
    "CreationDate": "2021-05-06T15:01:35+00:00",
    "LastUpdatedBy": "SALES_ADMIN",
    "LastUpdateDate": "2021-05-06T15:01:35.040+00:00",
    "LastUpdateLogin": "C1790815EA079FCAE053773AF80ABE96",
    "StdtxtName": "Customer Smarttext Example",
    "HtmlFlag": true,
    "FolderId": 300100543810122,
    "Scope": "ORA_SVC_GLOBAL",
    "UserPartyId": null,
    "EnabledFlag": true,
    "StartDate": "2021-05-06",
    "EndDate": null,
    "Domain": "ORA_GENERIC",
    "Object": "ServiceRequestVO",
    "StripeCd": "ORA_SVC_CRM",
    "BuOrgId": 204,
    "Language": "US",
    "StandardTextId": null,
    "UniqueNumber": "CUST_0001",
    "links": [
        {
            "rel": "self",
            "href": "https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876",
            "name": "smartTexts",
            "kind": "item",
            "properties": {
                "changeIndicator": "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200116A6176612E6C616E672E496E746567657212E2A0A4F781873802000149000576616C7565787200106A6176612E6C616E672E4E756D62657286AC951D0B94E08B02000078700000000178"
            }
        },
        {
            "rel": "canonical",
            "href": "https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876",
            "name": "smartTexts",
            "kind": "item"
        },
        {
            "rel": "action",
            "href": "https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876/action/processSmartText",
            "name": "processSmartText",
            "kind": "other"
        },
        {
            "rel": "enclosure",
            "href": "https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876/enclosure/Text",
            "name": "Text",
            "kind": "other"
        }
    ]
}

Get the SrNumber and the SrId

You can now use the smart text created above in an SR either by using the SrNumber or the SrId and substitute the smart text variable with the data obtained from the reference object.

You can get the SrNumber and SrId by getting all service requests using the below REST call:

GET /crmRestApi/resources/11.13.18.05/serviceRequests

Response Body
{
    "items": [
        {
            "SrId": 300100543019031,
            "SrNumber": "SR121191658536",
            "Title": "SR121191658536",
            "ProblemDescription": null,
            "SeverityCdMeaning": "High",
            "SeverityCd": "ORA_SVC_SEV1",
            "AssigneeResourceId": null,
            "AssigneeResourceNumber": null,
            "AssigneePartyId": null,
            "AssigneePersonName": null,
            "AssigneeEmailAddress": null,
            "AssigneeFormattedPhoneNumber": null,
            "AssigneeFormattedAddress": null,
            "CreatedBy": "SALES_ADMIN_ACC",
            "CreationDate": "2021-07-21T12:28:43.482+00:00",
            "LastUpdateDate": "2021-07-21T12:28:43.810+00:00",
            "LastUpdateLogin": "C7A0D3BB80F065EFE0530740F00A9B11",
            "LastUpdatedBy": "SALES_ADMIN_ACC",
            "LastUpdatedByDisplayName": "LeeACC,GabrielleACC",
            "LastUpdatedByEmailAddress": null,
...
}

Smart Text Variable Substitution with the PUID

The processSmartText action accepts a jsonString with the primary keys of the smart text and the referenced object. The action then substitutes the variables in the smart text with the data obtained from the referenced object. You can also use the primary key instead of the PUID to reference the smart text.

Use the public unique identifier SrNumber obtained from the GET call above and substitute the smart text variable with a POST request using the following URL:

Method: POST

URL: https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876

Content-Type:application/vnd.oracle.adf.action+json

Note:

The URL above is the canonical value which uniquely identifies the smart text being used.

Request Body
{
    "name": "processSmartText",
    "parameters": [
        {
            "paramsValuesJson": "{puid: SR0000128147}"
        }
    ]
}
Response Body
{
   "result":"{\"status\":\"Success\",\"smartText\":\"Dear FirstName_a6c87992392 LastName_a6c87992392:<br /><br />Your code request Number SR0000128147 is being attended.<br /><br />Regards,\"}"
}

Smart Text Variable Substitution with Alternate Identifier

You can also use the alternate identifier such as SrId from the GET call above for smart text variable substitution.

URL: https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876

Method: POST

Content-Type: application/vnd.oracle.adf.action+json

Request Body
{
    "name": "processSmartText",
    "parameters": [
        {
            "paramsValuesJson": "{primaryKey: 300100547166949}"
        }
    ]
}
Response Body
{
    "result": "{\"status\":\"Success\",\"smartText\":\"Dear FirstName_a6c87992392 LastName_a6c87992392:<br /><br />Your code request Number SR0000128147 is being attended.<br /><br />Regards,\"}"
}

Use the Smart Text in an SR by User-Defined Variable Value

You can prompt the user for a user-defined attribute value. You can then fetch the service request based on the primary key or PUID (SrId or SrNumber), and substitute a value for the user defined variable through the payload.

Note:

Before you can prompt the user, you must create a user-defined attribute using tools and smart text. The user-defined attribute variable would be MySignatureName and the type will be Prompt.

Now you can update the smart text and append the variable to the existing text using REST API.

The smart text is updated to the following using PATCH: 

   Dear [[ServiceRequestVO.PrimaryContactPartyName]]:<br
        /><br />Your code request Number [[ServiceRequestVO.SrNumber]] is being attended.<br /><br
        />Regards,<br />[[StandardTextUserVariableVO.MySignatureName]]

You can now use the processSmartText method using any value for the MySignatureName variable:

URL: https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876

Method: POST

Content-Type: application/vnd.oracle.adf.action+json

Request Body
{
    "name": "processSmartText",
    "parameters": [
        {
            "paramsValuesJson": "{puid: SR0000128147,StandardTextUserVariableVO.MySignatureName:Jane Smith Esq.}"
        }
    ]
}
Response Body
{
    "result": "{\"status\":\"Success\",\"smartText\":\"Dear FirstName_a6c87992392 LastName_a6c87992392:<br /><br />Your code request Number SR0000128147 is being attended.<br /><br />Regards,<br />Jane Smith Esq.\"}"
}

Optionally, you can also substitute the party name value in the smart text with another value. In this example, we will override the derived value of ServiceRequestVO.PrimaryContactPartyName: "FirstName_a6c87992392 LastName_a6c87992392":

URL: https:/myapplicationdomain.com:port/crmRestApi/resources/11.13.18.05/smartTexts/00020000000255530000000EACED00057708000110F09A830876

Method: POST

Content-Type: application/vnd.oracle.adf.action+json

Request Body
{
    "name": "processSmartText",
    "parameters": [
        {
            "paramsValuesJson": "{puid: SR0000128147,StandardTextUserVariableVO.MySignatureName:Jane Smith Esq., ServiceRequestVO.PrimaryContactPartyName: Dwayne Johnson}"
        }
    ]
}
Response Body
{
    "result": "{\"status\":\"Success\",\"smartText\":\"Dear Dwayne Johnson:<br /><br />Your code request Number SR0000128147 is being attended.<br /><br />Regards,<br />Jane Smith Esq.\"}"
}

This demonstrates that the derived values from the service request is substituted into the body of the smart text only if there is no value provided in the request payload.