iQ Revisions

iQ Revisions

by on ‎06-20-2016 02:36 PM - edited on ‎03-15-2018 09:11 AM by Community Manager (2,693 Views)

This article describes how to use the iQ Revisions API. A revision is a saved version of your iQ profile. The revision status contains information about the version, such as published environments, user comments, timestamps, and checksums for the JavaScript files generated. A zip file containing the published files related to the revision is called a revision bundle.

In this article:

Table of Contents Placeholder 

Prerequisites

Before you begin, the iQ Revisions API must be activated to enable the ability to return data. If this API is not activated, contact your account manager to activate this endpoint.

How it Works

A new revision is created each time a Save as action is performed. As each version is updated or published, the status is reflected in the revision. 

Revision Fields

Revisions are returned as JSON objects that contain the following fields:

Object Name Type Description
revision_id string The timestamp of the revision represented as a string in the format of YYYYMMDDHHMMSS
created_by email The email of the user that created the revision
comment string The comment left by the user at the time the revision was created
targets_published array An array of the environment names for the publish targets used
 name string The name given to the revision
 time_created string

A string representation of the time of creation, for example:

 Tue 2017.12.13 19:54 GMT

 account string The account name for the revision
 profile string The profile name for the revision
 checksums object

The values in targets_published is a key factor in the checksums object.

The values contain a checksums value for each JavaScript file published to that target, as shown in the following example:

"targets_published" : ["dev"],
"checksums" : {
  "dev": {
    "manifest.json" : "",
    "bundle.zip" : "",
    "utag.js" : "",
    "utag.1.js" : ""
  }
}

Example

{
    "account": "tealium",
    "profile": "main",
    "name": "Full Release - 2017/12/13 19:53",
    "time_created": "Tue 2017.12.13 19:54 GMT",
    "checksums": {
        "prod": {
            "manifest.json": "df8bb8bdb8bc34f9d70d98ff49fdcf53e7f286520747001538b74357418178a2",
            "bundle.zip": "9309364527db38cd33538ca239929c3ed89b7b6990e99b4a41d16b50dd519e35",
            "utag.sync.js": "7cdc832b67612bb053f2e4a91ea9eab2aeb4bd26bae9668cbf5bb58bb6a2e9a1",
            "utag.js": "3c34236708b14e8fd8a82e5c363d006793fd59fc6f6a6f0367634cf245d16861",
            "utag.1.js": "9b911570ac0685a50a3a32ef780a2570b16725779b7336bdbfca2838eea6d216"
        }
    },
    "revision_id": "201712131954",
    "comment": "up to date publish",
    "created_by": "user@example.com",
    "targets_published": ["prod"]
} 

Get Revisions

You can use the GET command to returns an array of revision IDs.  The revision ID is the timestamp of the revision in the form of YYYYMMDDHHMM. This ID is used to fetch the revision details.

Use the following GET command to list revisions:

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions

Curl Request

Use the following cURL command to return a list of Revision IDs:

curl -H 'Authorization: Bearer {token}' \
https://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions

Example Response

The following example shows a typical response generated from the cURL command:

["201508181719",
 "201508181718",
 "201508181717"]

Revision IDs are listed in reverse chronological order with the newest revision listed first.

Error Messages

Potential error messages for this task are:

Error Message Description

404 Not Found

{
"returnCode" : 1240, "message" : "Account was not found"
}
{
"returnCode" : 1250, "message" : "Profile was not found"
}
 

Get Revision Details

Get Revision Details returns the details for the revision specified.

Use the following GET command to return details about a revision:

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/details

Curl Request

Use the following cURL command to return details for a specified Revision ID:

curl -H 'Authorization: Bearer {token}' \
https://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/details

Example Response

The following example shows a typical response generated from the cURL command:

{
    "account": "tealium",
    "profile": "profile",
    "name": "Full Release - 2016/12/13 19:53",
    "time_created": "Tue 2016.12.13 19:54 GMT",
    "checksums": {
        "prod": {
            "manifest.json": "df8bb8bdb8bc34f9d70d98ff49fdcf53e7f286520747001538b74357418178a2",
            "bundle.zip": "9309364527db38cd33538ca239929c3ed89b7b6990e99b4a41d16b50dd519e35",
            "utag.js": "3c34236708b14e8fd8a82e5c363d006793fd59fc6f6a6f0367634cf245d16861",
            "utag.1.js": "9b911570ac0685a50a3a32ef780a2570b16725779b7336bdbfca2838eea6d216",
            "utag.2.js": "0d3cbf8b3d275d181c2140c2eab88ead3c9f2002b5260d9ebd9f23cb7b60de9a"
        }
    },
    "revision_id": "201612131954",
    "comment": "up to date publish",
    "created_by": "user@example.com",
    "targets_published": ["prod"]
} 

Error Messages

Potential error messages for this task are:

Error Message Description
404 Not Found
{ 
   "returnCode" : 1240,
   "message" : "Account was not found" 
}
{ 
   "returnCode" : 1250,
   "message" : "Profile was not found" 
}
{ 
   "returnCode" : 1260,
   "message" : "Revision details do not exist"
}

Get Revision Bundle

A revision bundle is the deployable combination of published JavaScript files for the target environment in the form of a .zip file. If a revision was published, the value from targets_published is used in this endpoint to retrieve the desired files, such as prod.

GET /v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/environments/{environment}

Curl Request

Use the following cURL command to retrieve a revision bundle .zip file:

curl -H 'Authorization: Bearer {token}' \ 
http://api.tealiumiq.com/v2/manifest/accounts/{account}/profiles/{profile}/revisions/{revision_id}/environments/{environment}

Example Response

The response for the cURL command is the return of a .zip file containing the following individual files:

 File Name Contents
 utag.js  The main loader file
 utag.*.js   The vendor tag files, such as utag.13.js
 utag.sync.js

(Optional) Contains the synchronous loader file 

 mobile.html 

(Optional) Contains the mobile library configuration

 manifest.json

A JSON file containing the  information returned by the Revision Details endpoint

The SHA256 for the bundle is not included

Error Messages

Potential error messages for this task are:

Error Message Description
400 Not Found
{ 
   "returnCode" : 1270,
   "message" : "The revision bundle requested is not the latest" 
}