Automating Adobe Analytics Classifications – Classification API
Adobe Classifications
Adobe Classifications, formerly known as SAINT classifications (Site Catalyst Attribution and Naming tool) allow users to classify their report suite data on metadata related to products, campaigns, or any other attributes which are tagged on site. Classifications serve as a mapping table, for example say that you are bringing product SKU’s into Adobe Analytics, but metadata relating to this product SKU (color, size, production cost, etc.) is absent from your report suite. Classifications will allow you to bring an outside mapping table into Adobe Analytics, to join metadata onto the product SKU. Upon a successful Classification job, Analytics users will for example be able able to see for each product SKU, what the color, size, and production cost is inside of familiar tools like Workspace.
Live Use Case
Classifications are useful when important metadata relating to products or campaigns needs to be brought into the report suite for reporting or visualization. In one client’s case, a marketing department was keeping blog content metadata inside of an Airtable instance. This Airtable instance stored data such as content author, business verticals, publishing date, etc. This served as a convenient way to collaborate and track metadata across the organization, and was being updated manually on a consistent but nonstandard cadence. With the Adobe Classification API, and Python’s Requests package, we can engineer a classification pipeline that can be standardized, automated, and scheduled, saving many hours of manual classification work.
General Process Flow
The process here is straightforward. Our team will develop a program which extracts classification data from the source, apply any aggregation or business rules that are required and then format the data to meet the needs of the adobe classification API’s upload file. AWS Lambda Serverless Compute wraps this all up and serves as the engine at each step of the process. Allowing clients to access their classified data within Adobe Analytics in an accurate and timely fashion.
API Setup in the Adobe I/O Console
Although Classifications is one of the few API’s that has not been transitioned to API 2.0 and remains on the 1.4 platform, it is still best to set up a modern API integration via the Adobe I/O Console. As Legacy OAuth Applications within the old Admin tab will be going away in the near future.
Given the layers of added security, setting up the API integration in the Adobe I/O Console takes more time and a little bit more know-how than the legacy API. I will outline the steps to create a new API integration below.
Adobe’s new home for everything Application Programming Interface (and more) is the Adobe I/O Console, we will start here. You may need developer access within your Analytics environment to create a new integration. This documentation might be helpful for that. Press Launch Console and log in. You’ll want to click on Create Integration to get started.
Then choose “Access an API” and select Adobe Analytics as the service you wish to integrate with.
You will now be prompted to enter some integration details. An integration name and description will be helpful and it is useful to be explicit and descriptive when entering this information. As different API’s can be given access to different product profiles within your Analytics Instance, and in order to access any specific integration you must have the private key which matches the integrations public key.
In order to generate your public and private keys you can run the command below. I do most of my engineering work in a Windows Subsystem for Linux running Ubuntu, but you should be able to use your favorite command line tool to generate these files. Where you see adobe_private_key_example.key and adobe_public_key_example.crt you should enter the desired name of your key files.
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout
adobe_private_key_example.key -out adobe_public_key_example.crt
You’ll then be prompted to enter some information that will be incorporated into your certificate. Follow the instructions and enter the fields as they pertain to you, or leave them blank. These files will be placed into your current working directory, and you can browse, or drag your public key into the file bin.
Generating a RSA private key
………………..+++++
…………………………+++++
writing new private key to ‘adobe_private_key_example.key’
—–
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
—–
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Georgia
Locality Name (eg, city) []:Atlanta
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Softcrylic, LLC
Organizational Unit Name (eg, section) []:Advanced Analytics
Common Name (e.g. server FQDN or YOUR name) []:Morgan DiPietro
Email Address []:morgan.d@softcrylic.com
Authentication
Previously, authentication with the Adobe Analytics API 1.4 supported Authentication via a users Web Service Credentials (shared secret and shared access). This will be deprecated in the near future and I highly recommend you set up a process to authenticate via JWT (JSON Web Token) if you are creating an application that needs to programaticallly authenticate. While that is outside the scope of this post, there are some Python packages that will be extremely helpful in doing this, such as the Requests and JWT.
Classification API process and Methods
The Adobe Classification API offers the full functionality that you will find in the Adobe Analytics UI, but wrapping this process into a script allows flexibility with your input data and automation. If you’ve had to import classification files in the past you will see how the methods outlined below provide full flexibility to do this same classification within a scripting language. Below you will see the JSON key’s and data types that values must take for each method.
Essential Methods
Classifications.CreateImport:
To successfully submit a classifications Import, call Classifications.CreateImport to specify the parameters for the Import job and the header columns to be classified.
{
"check_divisions": true,
"description": "string",
"element": "string",
"email_address": "string",
"export_results": true,
"header": [
"string"
],
"overwrite_conflicts": true,
"rsid_list": [
"string"
]
}
Classifications.PopulateImport:
Appends row data to a previously created classifications import job (we created the job above but have not added any data to it).
{
"job_id": 0,
"page": 0,
"rows": [
{
"row": [
"string"
]
}
]
}
Classifications.CommitImport:
Submits a classification import file for processing. Finalizes Job.
{
"job_id": 0
}
Helpful Methods
Classifications.GetCompatabilityElements:
This method will return the available relation ID’s which is the unique ID associated with a report element in your report suite.
{
"rsid_list": [
"string"
]
}
Classifications.GetStatus
This method will return a job status for a given Job ID which is contained in the Classifications.CreateImport response JSON.
{
"job_id": 0
}
Conclusion
Having the ability to create integrations in the new Adobe I/O console will pay dividends for any data driven marketing team or analyst. Here we automated a Classification job that allows marketing teams to have their data classified in Adobe Analytics and available for all users in Analysis Workspace on a timely and accurate cadence. Once a process like this is in place, human errors as consequence of manually updating a classification file daily or weekly are eliminated and the technician who was previously doing this work will have more time to do important analysis.
