Creating and managing bookmarks

Create a Bookmark

Bookmarks are a critical developer tool that enables the creation of a namable time reference to a snapshot of a VDB or VDB group. Bookmarks for single VDBs can be created from the DCT UI by selecting a VDB and expanding into its detailed view. From the Active Timeline view, users can select the ellipsis in the top right corner and "Create Bookmark". 

Selecting the "Create Bookmark" button will open a window that enables bookmark naming, setting the custom retention period for that bookmark, and assigning any relevant tags. Creating bookmarks this way will initiate a new snapshot operation that will then be associated with that bookmark. 

Bookmarks relating to a specific VDB can be found under the bookmarks tab in a VDBs details page. This provides a curated list of actionable snapshots that represent anything from a relevant test result to a transformed set of schema that can be associated with a specific branch of code. 

Create a bookmark from an existing snapshot

Starting in version 7.0, the UI has an option to create bookmarks from existing snapshots.

On the VDB detail page, under the Active Timeline tab for each snapshot, a Create Bookmark action is available. This opens a dialogue that shows a list of inputs for the user to select from, to create a bookmark. 

Once the user clicks Create Bookmark in the dialogue, the bookmark will be created for that particular snapshot (if all the mandatory fields are completed), else errors will be shown.

Create a bookmark at the current data and time.

Create a bookmark based on the selected date and time.

Create a bookmark based on SCN Number.

Bookmark API Documentation

Some advanced bookmark operations are only available via API at present, formal documentation can be found via DCT's swagger docs or the Developer resources section. This portion of the bookmarks documentation will discuss examples of advanced use-cases. 

Create a Bookmark at the current time for multiple VDBs

DCT (version 6.0 and above) can create bookmarks from existing snapshots. This is particularly useful for users looking to migrate Self-Service bookmarks to DCT or any developer looking to retroactively create a bookmark reference.

In cases such as integration testing, bundling multiple VDBs together to represent a complete set of data that a complex application would run on is helpful. This API example shows how a single bookmark reference can be created off of multiple VDBs, to provide a provision point for new testing sets or the creation of a VDB Group that can be used to maintain referential synchronicity from that bookmark point. 

curl -X 'POST' \
  'https://<APPLIANCE_ADDRESS>/v3/bookmarks' \
  -H 'accept: application/json' \
  -H 'Authorization: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "MyBookmark1",
  "vdb_ids": [
    "1-ORACLE_DB_CONTAINER-2",
    "2-ORACLE_DB_CONTAINER-2"
  ]
}'

These API calls will return a DCT job to track the creation process. This job ID can then be used to poll the status via the jobs API. Example response:

{
  "bookmark": {
    "id": "9e8c7223f1af4694a19ac2c2f7696eda",
    "name": "MyBookmark1",
    "creation_date": "2023-03-27T20:56:13.916857Z",
    "vdb_ids": [
      "1-ORACLE_DB_CONTAINER-2",
      "2-ORACLE_DB_CONTAINER-2"
    ],
    "retention": 30,
    "expiration": "2023-04-26"
  },
  "job": {
    "id": "8fe825f5635d45299915c3cb88a17623",
    "status": "PENDING",
    "type": "BOOKMARK_CREATE",
    "target_id": "9e8c7223f1af4694a19ac2c2f7696eda",
    "start_time": "2023-03-27T20:56:14.363549Z"
  }
}

Creating a bookmark from a chosen timepoint

Now bookmarks can be created at a chosen snapshot timepoint using new properties in the request payload. Some properties are mutually exclusive, so be sure to use a valid request payload.

Here are some examples of a valid request payload:

{
  "name": "my-bookmark-123",
  "vdb_ids": [
    "vdb-123"
  ],
  "location": "112233",
  "expiration": "2021-07-04",
  "retain_forever": false,
  "tags": [
    {
      "key": "key-1",
      "value": "value-1"
    },
    {
      "key": "key-2",
      "value": "value-2"
    }
  ],
  "make_current_account_owner": true
}

{
  "name": "my-bookmark-123",
  "timeflow_ids": [
    "timeflow-1"
  ],
  "location": "112233",
  "expiration": "2021-07-04",
  "retain_forever": false,
  "tags": [
    {
      "key": "key-1",
      "value": "value-1"
    },
    {
      "key": "key-2",
      "value": "value-2"
    }
  ],
  "make_current_account_owner": true
}

{
  "name": "my-bookmark-123",
  "timeflow_ids": [
    "timeflow-1"
  ],
  "timestamp": "2021-05-01T08:51:34.148000+00:00",
  "expiration": "2021-07-04",
  "retain_forever": false,
  "tags": [
    {
      "key": "key-1",
      "value": "value-1"
    },
    {
      "key": "key-2",
      "value": "value-2"
    }
  ],
  "make_current_account_owner": true
}

Properties

• timestamp

• location

• timestamp_in_database_timezone

• timeflow_ids

Rules

• timestamp , location and timestamp_in_database_timezone are mutually exclusive.

• If any of the properties from timestamp , location and timestamp_in_database_timezone are provided then:

  • At least one property for vdb_ids or timeflow_ids must be provided.

  • The snapshot_ids property is not allowed to be set.