k.history
Query site edit history, compare versions, perform rollbacks, and inspect remote site logs
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
Api, CodeBlock, <script env="server"> | Authenticated org-matching user for local methods (except videoLog(versionId)) | Audit CMS edits, inspect diffs, undo/restore changes, or query remote logs |
Authentication and Organization Requirement
Except for the single-argument local videoLog(versionId), every local k.history method requires an authenticated Kooboo platform user (k.account) whose current organization matches the site's organization, or it throws "An authenticated user is required".
Quick Start
k.api.get("history-recent", () => {
if (!k.account.isLogin) {
k.response.statusCode(401)
return { error: "Authentication required" }
}
const page = k.history.list(10)
return {
totalCount: page.totalCount,
items: page.list
}
})Quick Reference
| Method / Property | Description | Returns |
|---|---|---|
k.history.list(top) / list(query) | Fetch recent site edit logs (pass numeric top in scripts) | SiteLogPage |
k.history.get(logId) | Get a single local CMS edit log entry by log ID | SiteLogItem |
k.history.versions(logId) / (nameOrId, storeName?, tableName?) | List all recorded historical versions of an object | SiteLogVersion[] |
k.history.compare(id) / compare(id1, id2) | Diff a version against latest or compare two historical versions | VersionCompareViewModel |
k.history.videoLog(versionId) | Read recorded editor replay video JSON for a version | string | null |
k.history.undo(logId) | Revert a single local CMS change and log the rollback | boolean |
k.history.undoMany(logIds) | Revert multiple local CMS changes in a batch (max 1,000) | boolean |
k.history.restoreTo(logId) / restoreTo(time) | Restore the entire site state to an earlier log ID or date | number |
k.history.checkOut(options) | Provision a new org website from a historical snapshot | SiteCheckoutResult |
k.history.lastLog(pageIndex, pagesize, siteUrl) | Fetch paginated edit logs from a remote Kooboo site | RemoteLastLogResult |
k.history.versions(keyHash, storeHash, tableHash, siteUrl) | List historical versions of an object on a remote site | ItemVersionViewModel[] |
k.history.compare(id1, id2, siteUrl) | Compare two versions on a remote Kooboo site | VersionCompareViewModel |
k.history.videoLog(versionId, siteUrl) | Fetch replay video JSON for a version on a remote site | string |
Overview
k.history provides server-side script access to CMS edit logs and version history for the current website, including log pagination, object version inspection, text/image diffs, edit replay video data, change rollback, checking out a historical snapshot into a new site, and querying remote Kooboo sites. k.site.editLog exposes the exact same API surface and behavior as k.history.
| Category | Methods | Purpose |
|---|---|---|
| Read-only History | list, get, versions, compare, videoLog | Inspect local edit logs, object versions, content/image diffs, and replay data |
| Destructive Rollback & Checkout | undo, undoMany, restoreTo, checkOut | Revert site changes, restore the site to an earlier state, or fork a historical snapshot into a new site |
| Remote Site Diff & VideoLog | lastLog, versions (4 args), compare (3 args), videoLog (2 args) | Query and compare edit logs, versions, and replay videos on another siteUrl |
Read-only History
list()
Lists recent CMS edit logs for the current site, declaring two overloads:
- Numeric limit:
k.history.list(top)returns the latesttoplog entries (pageNris1; values<= 0default to50, clamped to a maximum of200). - Structured query:
k.history.list(query)corresponds to theSiteLogQueryoverload in type definitions.
Runtime Overload Resolution Note
At runtime, passing a plain JavaScript object literal (such as { pageNr: 1, pageSize: 5, storeName: "Code" }) to k.history.list(...) matches the numeric list(top) overload first with top = 0, returning the latest 50 unfiltered entries (pageSize: 50) without applying SiteLogQuery filters. In site scripts, pass a numeric top argument (1–200) to k.history.list(top) and filter page.list in JavaScript when needed.
Parameters (list(top)):
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
top | number | yes | - | Number of most recent logs to return (<= 0 falls back to 50; max 200) |
Returns: SiteLogPage.
k.api.get("history-recent", () => {
if (!k.account.isLogin) {
k.response.statusCode(401)
return { error: "Authentication required" }
}
const page = k.history.list(10)
const codeLogs = page.list.filter((item) => item.storeName === "Code")
return {
totalCount: page.totalCount,
pageSize: page.pageSize,
totalPages: page.totalPages,
recentItems: page.list,
recentCodeLogs: codeLogs
}
})get()
Gets a single local CMS edit log entry by its numeric log ID.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
logId | number | yes | Positive log ID; throws if non-positive or not found |
Returns: SiteLogItem.
k.api.get("history-detail", () => {
if (!k.account.isLogin) {
k.response.statusCode(401)
return { error: "Authentication required" }
}
const recent = k.history.list(1)
if (recent.list.length === 0) {
return { item: null }
}
const detail = k.history.get(recent.list[0].id)
return { detail: detail }
})versions()
Lists all recorded historical versions of an object (newest first), supporting two local overloads:
- By log ID:
k.history.versions(logId)looks up every recorded version of the object referenced bylogId. - By object identifier:
k.history.versions(nameOrId, storeName, tableName)looks up versions by object name or GUID. Provide eitherstoreName(such as"Page","View","Layout","Code","HtmlBlock","Label") ortableName(dynamic database table name), never both and never neither.
Querying Deleted Objects
If a CMS object whose ID is not derived from its name (such as a Page, View, or Code item) has been deleted, looking it up by name throws a not-found error. Pass its GUID string as nameOrId instead.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
logId | number | yes (overload 1) | Any log ID belonging to the target object |
nameOrId | string | yes (overload 2) | Object name or GUID string |
storeName | string | no (mutually exclusive with tableName) | CMS store name (for example "Code", "Page") |
tableName | string | no (mutually exclusive with storeName) | Dynamic table name |
Returns: SiteLogVersion[].
k.api.get("history-versions", () => {
if (!k.account.isLogin) {
k.response.statusCode(401)
return { error: "Authentication required" }
}
const recent = k.history.list(10)
const target = recent.list.find((item) => item.storeName !== "Table" && item.itemName)
if (!target) {
return { versions: [] }
}
const byLogId = k.history.versions(target.id)
const byName = k.history.versions(target.itemName, target.storeName)
return {
itemName: target.itemName,
storeName: target.storeName,
byLogId: byLogId,
sameCount: byLogId.length === byName.length
}
})compare()
Compares two versions of the same object:
- Against latest:
k.history.compare(id)compares versionidagainst the latest recorded log of the same object. - Two specific versions:
k.history.compare(id1, id2)compares two specific versions of the same object. Ifid1 > id2, the server automatically swaps them so the older version is on the left (id1/title1/source1) and the newer version is on the right (id2/title2/source2).
Runtime Value of dataType
While TypeScript IntelliSense types dataType as 'String' | 'Image', serialized JSON responses return the underlying numeric enum at runtime: 0 for String and 1 for Image.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id / id1 | number | yes | First positive log version ID |
id2 | number | no | Second positive log version ID (omit to compare against the latest version) |
Returns: VersionCompareViewModel.
k.api.get("history-compare", () => {
if (!k.account.isLogin) {
k.response.statusCode(401)
return { error: "Authentication required" }
}
const recent = k.history.list(50)
for (const item of recent.list) {
if (item.storeName === "Table") continue
const versions = k.history.versions(item.id)
if (versions.length >= 2) {
return {
withLatest: k.history.compare(versions[versions.length - 1].id),
twoVersions: k.history.compare(versions[1].id, versions[0].id)
}
}
}
return { message: "No object with multiple versions found" }
})videoLog()
Reads the recorded editor replay video JSON for a local version ID, returning null if no video exists for that version.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
versionId | number | yes | Version log ID |
Returns: string | null.
k.api.get("history-video", () => {
const versionId = Number(k.request.queryString.get("versionId") || 0)
if (!versionId) {
return { video: null }
}
const video = k.history.videoLog(versionId)
return {
hasVideo: typeof video === "string" && video.length > 0,
video: video
}
})Destructive Rollback & Checkout
Data Modification and Site Provisioning Warning
These methods mutate live website content, overwrite multiple objects, or provision brand-new websites in your organization, and rollbacks append new edit logs:
- Call them only after authenticating an authorized organization user and confirming the exact target
logId; undoMany()validates all IDs before making changes and accepts at most1,000log IDs per call;restoreTo()andcheckOut()fail if more than99,999subsequent logs exist after the target point;- Never expose rollback or checkout endpoints without strict authentication and confirmation checks.
undo()
Reverts a single local CMS change and records a new edit log for the rollback.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
logId | number | yes | Positive log ID to undo (throws if non-positive or not found) |
Returns: boolean (true on success).
undoMany()
Reverts multiple local CMS changes in a batch. All log IDs are validated and deduplicated before any state is modified.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
logIds | number[] | yes | Non-empty array of positive log IDs (maximum 1,000 items) |
Returns: boolean (true on success).
restoreTo()
Restores the entire local website to an earlier log ID or UTC Date cutoff in history, generating new edit logs for the restoration.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
logId | number | yes (overload 1) | Target log ID (at most 99,999 later logs allowed) |
time | Date | yes (overload 2) | Target cutoff date/time (restores to the latest log at or before time; throws if none exists) |
Returns: number (the restored target log ID).
checkOut()
Creates another website within the current organization containing the local site's state at a historical log ID. If checkout fails mid-way, the newly created site is cleaned up automatically.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
options | SiteCheckoutOptions | yes | Checkout options object |
options.logId | number | yes | Target historical log ID (at most 99,999 later logs allowed) |
options.siteName | string | yes | New site name (must be available in the organization) |
options.fullDomain | string | yes | Full domain binding for the new site (must not already be in use) |
options.published | boolean | yes | Whether to mark the checked-out site as published |
Returns: SiteCheckoutResult.
Remote Site Diff & VideoLog
These four methods query remote Kooboo site log endpoints over HTTP and automatically forward the current request's Cookie and Authorization headers (see TypeScript Definitions below for exact parameter and return types):
k.history.lastLog(pageIndex, pagesize, siteUrl)k.history.versions(keyHash, storeNameHash, tableNameHash, siteUrl)k.history.compare(id1, id2, siteUrl)k.history.videoLog(versionId, siteUrl)
Trailing Slash in siteUrl
Pass siteUrl without a trailing slash (for example "https://example.com" or k.site.info.baseUrl.replace(/\/+$/, "")). Passing a URL ending in / produces a double-slash endpoint path (//_api/...) and yields null fields.
Parameters:
| Method | Parameters | Description |
|---|---|---|
lastLog(pageIndex, pagesize, siteUrl) | pageIndex: number, pagesize: number, siteUrl: string | Fetch paginated edit logs from a remote Kooboo site |
versions(keyHash, storeNameHash, tableNameHash, siteUrl) | keyHash: string, storeNameHash: number, tableNameHash: number, siteUrl: string | List remote object versions using hashes from lastLog entries |
compare(id1, id2, siteUrl) | id1: number, id2: number, siteUrl: string | Compare two versions on a remote site |
videoLog(versionId, siteUrl) | versionId: number, siteUrl: string | Fetch edit-replay video JSON for a remote version ID |
Example:
k.api.get("history-remote", () => {
const siteUrl = k.site.info.baseUrl.replace(/\/+$/, "")
const remotePage = k.history.lastLog(1, 5, siteUrl)
const first = remotePage.list.length > 0 ? remotePage.list[0] : null
if (!first) {
return { totalCount: remotePage.totalCount, items: [] }
}
const remoteVersions = k.history.versions(
String(first.keyHash),
first.storeNameHash,
first.tableNameHash,
siteUrl
)
const diff = remoteVersions.length >= 2
? k.history.compare(remoteVersions[1].id, remoteVersions[0].id, siteUrl)
: null
const video = k.history.videoLog(first.id, siteUrl)
return {
totalCount: remotePage.totalCount,
firstId: first.id,
versionsCount: remoteVersions.length,
hasVideo: typeof video === "string" && video.length > 0,
diff: diff
}
})TypeScript Definitions
Show full TypeScript definitions
interface KEditLog {
// Read-only History
list(top: number): SiteLogPage;
list(query: SiteLogQuery): SiteLogPage;
get(logId: number): SiteLogItem;
versions(logId: number): SiteLogVersion[];
versions(nameOrId: string, storeName?: string, tableName?: string): SiteLogVersion[];
compare(id: number): VersionCompareViewModel;
compare(id1: number, id2: number): VersionCompareViewModel;
videoLog(versionId: number): string;
// Destructive Rollback & Checkout
undo(logId: number): boolean;
undoMany(logIds: number[]): boolean;
restoreTo(logId: number): number;
restoreTo(time: Date): number;
checkOut(options: SiteCheckoutOptions): SiteCheckoutResult;
// Remote Site Diff & VideoLog
lastLog(pageIndex: number, pagesize: number, siteUrl: string): RemoteLastLogResult;
videoLog(versionId: number, siteUrl: string): string;
versions(keyHash: string, storeNameHash: number, tableNameHash: number, siteUrl: string): ItemVersionViewModel[];
compare(id1: number, id2: number, siteUrl: string): VersionCompareViewModel;
}
interface SiteLogPage {
list: SiteLogItem[];
totalCount: number;
pageNr: number;
pageSize: number;
totalPages: number;
}
interface SiteLogQuery {
pageNr: number;
pageSize: number;
actionType: string; // "Add" | "Update" | "Delete"
storeName: string;
tableName: string;
name: string;
userId?: any;
startDate?: Date;
endDate?: Date;
}
interface SiteLogItem {
id: number;
lastModified: Date;
timeTick: number;
userId: any;
userName: string;
itemName: string;
storeName: string;
keyHash: any;
storeNameHash: number;
tableNameHash: number;
tableName: string;
actionType: string;
isAI: boolean;
hasVideo: boolean;
}
interface SiteLogVersion {
id: number;
lastModified: Date;
userId: any;
userName: string;
actionType: string;
isAI: boolean;
hasVideo: boolean;
}
type VersionDataType = "String" | "Image";
interface VersionCompareViewModel {
title1: string;
title2: string;
objectId: any;
constType: number;
id1: number;
id2: number;
source1: string;
source2: string;
dataType: VersionDataType;
}
interface SiteCheckoutOptions {
logId: number;
siteName: string;
fullDomain: string;
published: boolean;
}
interface SiteCheckoutResult {
siteId: any;
siteName: string;
fullDomain: string;
published: boolean;
}
interface RemoteLastLogResult {
list: SiteLogViewModel[];
totalCount: number;
pageNr: number;
pageSize: number;
totalPages: number;
}
interface SiteLogViewModel {
id: number;
lastModified: Date;
userName: string;
itemName: string;
storeName: string;
keyHash: any;
storeNameHash: number;
tableNameHash: number;
tableName: string;
actionType: string;
hasVideo: boolean;
}
interface ItemVersionViewModel {
id: number;
lastModified: Date;
userName: string;
hasVideo: boolean;
}Related Docs
- k.site — Versioned structured site resources (
k.site.editLogpoints to the same interface ask.history) - k.account.login — Platform user login and session authentication
- Site Logs (Admin) — Admin UI for version history, diffs, and video replay