Analytics and Product Recommendations

About Denylists and Allowlists for Recommendation Tasks

You can define which products are available to recommendation tasks by uploading a CSV file that contains a list of products. That CSV file can be used as either an allowlist or a denylist.

A recommendation allowlist details which products are approved for use in recommendation tasks. After an allowlist is uploaded to SAS Customer Intelligence 360 , recommendation tasks can recommend only the products that exist in the list.

A recommendation denylist details which products are excluded from use in recommendation tasks. After a denylist is uploaded to SAS Customer Intelligence 360 , recommendation tasks cannot recommend any products that exist in the list.

For example, you might create a denylist that prevents the recommendation of any product that is not in your inventory. Alternatively, you might use a denylist to prevent winter-themed products from displaying during summer months.

Process Overview

To establish an allowlist or denylist for recommendations tasks, follow these steps:

1. Create and upload a data descriptor for recommendations using a POST call to the REST API. This call returns a temporary, signed URL where you upload your CSV file.
2. Upload the CSV file to the temporary URL.

After the CSV file is uploaded, recommendation tasks start using the denylist or allowlist when they deliver recommendations. User-centric tasks might take up to one day to begin using the imported list. Product-centric tasks might take up to one week to begin using the list.

Prerequisites

In order to use a denylist or allowlist with recommendation tasks, you will need to upload some files to SAS Customer Intelligence 360 using the Marketing Data REST API. Ensure that you satisfy these requirements before you begin:

1. Create an access point so that you can generate a static JWT.

   When you create the access point, make note of the External gateway host field on the Access Points page. This value is used as part of the URL for API calls that go through the external API gateway. Use this value when you see the variable <external gateway host> in the documentation.

2. Make note of the value of the token that you need to use. The static JWT or access token must be specified in the Authorization header as a bearer token when you make calls to the REST API.
3. Create the CSV file that lists the products that are either allowlisted or denylisted.
   Note: Note: Only one type of list is supported at a time – either an allowlist or a denylist. Take time to determine which type is more beneficial to you before you continue.
4. Create a data descriptor for recommendations. This descriptor specifies whether you are uploading an allowlist or a denylist and defines the structure of your CSV file.

Create the CSV File for Recommendations

You must have a CSV file that contains the list of products that you want to denylist or allowlist. These are the requirements for the CSV file:

• The CSV file must contain a column named either PRODUCT_ID or PRODUCT_SKU to be valid. The file can contain both columns.
• Use UTF-8 encoding.
• Ensure that there are no empty data items.

Here is an example of a short CSV file:

PRODUCT_ID,PRODUCT_SKU,CATEGORY
1234,1234990,Sport
1235,1235993,Sport
1236,12365995,Baby

Create the Data Descriptor for Recommendations

Data descriptors are JSON objects that describe the structure and the type of data items that are contained in a data set. In this case, your descriptor describes the structure of your CSV file.

1. Open a text editor and create a basic template. You can use text similar to this example:
   { "listType": "", "columns": [ { "name": "", "type": "", "length": "" }, { "name": "", "type": "", "length": "" } ] }

   {
     "listType": "",
     "columns": [
       {
         "name": "",
         "type": "",
         "length": ""
       },
       {
         "name": "",
         "type": "",
         "length": ""
       }
     ]
   }

2. Define whether you are uploading an allowlist or a denylist by entering the appropriate value for the listType attribute. Valid values are allowlist or denylist.
3. Describe the structure of your CSV file by adding information in the columns attribute. Add an item in the columns list for each corresponding column in your CSV file. For example, if you have three columns in the CSV file, the columns attribute should have three children.

   Add details about each of your columns using these attributes:

   CSV File Structure

   Name	Type	Description
   Name	String	The name of the column in your CSV file. One column must be named PRODUCT_ID or PRODUCT_SKU .
   Type	String	SAS data type of your column. Valid values are CHARACTER or NUMBER .
   Length	Integer	The length of the column field in your CSV file.

This example data descriptor is for a denylist:

{ 
  "listType":"denylist",
  "columns":[
    {"name":"PRODUCT_ID", "type":"CHARACTER","length":80},
    {"name":"PRODUCT_SKU", "type":"CHARACTER","length":90},
    {"name":"CATEGORY", "type":"CHARACTER","length":100}
  ]
}

Upload the Data Descriptor for Recommendations

1. To authenticate with the external API gateway, specify the JWT as the value for the Authorization header in the REST API call.
   Note: Use the term “Bearer” as a prefix and add a space before the value of the JWT.

   The header should be similar to this example:

   Using a JWT as the Authorization Header

   Header Attribute	Header Value
   Authorization	Bearer eyJ0eXAiOGciO.DAxMGFhODEJ9.BRv_nD6v

2. In the body of the REST call, enter the JSON code for the data descriptor.
3. Send a POST call to the REST API:
   https://<external gateway host>/marketingData/analytic/transfers

   https://<external gateway host>/marketingData/analytic/transfers

   TipThe response status is 201 when the descriptor is created successfully.
4. Notice the URL that is included in the response. This is a temporary location that you can use to upload the corresponding CSV file.
   Note: Temporary URLs can be accessed for about 15 minutes before they expire. You can use temporary URLs more than once, but you can always request a new URL if you do not start your upload in the 15-minute window.

   In addition to the URL, the response includes the transferId attribute. You can use this ID with a GET call to review the details of the transfer request (or see the temporary URL again):

   https://<external gateway host>/marketingData/analytic/transfers/<transferId>

   https://<external gateway host>/marketingData/analytic/transfers/<transferId>

Upload CSV File for Recommendations

Each time that a new file is uploaded, the existing list is replaced. Use curl or a similar application to upload the CSV file to the temporary URL. After your file is uploaded, note the value of the transferId attribute that is returned. This can be used to verify whether your file uploaded successfully.

This is an example of a curl command to upload a file from your local machine:

curl -v --upload-file "c:\temp\myfile.csv" "https://<temporary_URL>"

If the curl command is successful, the response includes the string “HTTP/1.1 200 OK”.

Validate Your Recommendation Upload

You can validate that your file uploaded correctly by using one of these methods:

• Review the notifications in SAS Customer Intelligence 360. A notification appears after your upload succeeds.
• Send a GET call to the REST API using the transferID attribute that was returned after you uploaded the file.
  https://<external gateway host>/marketingData/analytic/transfers/<transferId>

  https://<external gateway host>/marketingData/analytic/transfers/<transferId>

  The response status is 200 when the file uploaded successfully. If the response status is 400, the file did not upload successfully.