Support and Documentation

How to create and update records in Brightspot Content Management API

This guide will explain how to create and update Brightspot records via CMA GraphQL mutation APIs.

Prerequisites for using the CMA

For endpoint configuration, see Custom Content Management API development and Hello Content Management API.

Introduction to the CMA

In the Content Management API, value differences for the proposed state are used to mutate an object. Passing in state differences, rather than an entire state object, accurately represents how users input data into Brightspot.

Background to the CMA

Consider the following record classes where setters and getters are omitted for brevity:

public class Foo extends Record {

    private String title;

    private Integer number;

    private List<Integer> numbers;

    private boolean flag;

    @Recordable.Embedded
    private Bar bar;

    private Baz baz;

}
@Recordable.Embedded
public class Bar extends Record {

   private String barTitle;
}
public class Baz extends Record {

   private String bazTitle;
}

Following is a portion of the schema, concerned with mutation types and based on the aforementioned record classes, with Foo configured as a mutable entry field:

type Mutation {
    com_company_FooSave(diffs: [com_company_FooDiffInput], id: DiffId, toolUser: RefId): com_company_Foo
}

input com_company_FooDiffInput {
    com_company_BarDiff: com_company_BarInput
    com_company_FooDiff: com_company_FooInput
    id: DiffId
}

input com_company_FooInput {
    bar: DiffId
    baz: RefId
    flag: Boolean
    number: Int
    numbers: [Int]
    title: String
}

input com_company_BarInput {
    barTitle: String
}

Inputs:

  • id: diff ID to match the main diff input for the record creation or update

  • diffs: every embedded record updated by the mutation requires a diff input with its relevant changes

  • toolUser: user ID, username, or email so history for the record can be updated appropriately

DiffId inputs can be an existing UUID, new UUID, or even a random identifier. Existing UUIDs are necessary for updating existing records while new UUIDs create new records. The random identifier feature allows callers to create new records with invalid UUIDs, such as "1," to simplify record creation. Random identifiers are matched up and converted to new, valid UUIDs upon record creation.

RefId inputs are utilized for pointing to non-embedded records via their ID.

CMA examples

Below are a few examples of typical create and update CMA save mutations. They are run against a schema with Foo and Baz configured as mutable entry fields. Since Baz is not an embedded record (see @Recordable.Embedded) on Foo, and instead referenced by Foo, it needs to be an entry field in order to retrieve more data than _id and _type.

Record creation

The following example shows the creation of a Foo record. Notice that a non-embedded Baz record, already in existence, is assigned to it.

Example 61. Query
mutation MyMutation {
    com_company_FooSave(id: "1", toolUser: "jentile@brightspot.com",
        diffs: [
            {
                id: "1",
                com_company_FooDiff: {
                    title: "Hello World!"
                    flag: true
                    number: 1
                    numbers: [2, 3]
                    baz: "00000177-72e6-d6fd-a97f-76f6002a0000"
                }
            }
        ]
    ) {
        _id
        title
        flag
        number
        numbers
        baz {
            _id
            bazTitle
        }
    }
}


Example 62. Response
{
  "data": {
    "com_company_FooSave": {
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
      "title": "Hello World!",
      "flag": true,
      "number": 1,
      "numbers": [2, 3],
      "baz": {
        "_id": "00000177-72e6-d6fd-a97f-76f6002a0000",
        "bazTitle": "Hello Human!"
      }
    }
  }
}


Here's an example where embedded record data is supplied during creation. An embedded Bar record is created and assigned to the new Foo record.

Example 63. Query
mutation MyMutation {
    com_company_FooSave(id: "1", toolUser: "jentile@brightspot.com",
        diffs: [
            {
                id: "1",
                com_company_FooDiff: {
                    bar: "2"
                }
            },
            {
                id: "2",
                com_company_BarDiff: {
                    barTitle: "Hello Atom!"
                }
            }
        ]
    ) {
        _id
        bar {
            _id
            barTitle
        }
    }
}


Example 64. Response
{
  "data": {
    "com_company_FooSave": {
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
      "bar": {
        "_id": "00000177-72ea-d6fd-a97f-76fa15700001",
        "barTitle": "Hello Atom!"
      }
    }
  }
}


Record update

The following example shows an update to the existing Foo record from the previous example. Notice that the embedded Bar record does not need to be reassigned to the Foo record, yet its value can still be updated. Additionally, a different non-embedded Baz record is assigned.

Example 65. Query
mutation MyMutation {
    com_company_FooSave(id: "00000177-72ea-d6fd-a97f-76fa15700000", toolUser: "jentile@brightspot.com",
        diffs: [
            {
                id: "00000177-72ea-d6fd-a97f-76fa15700000",
                com_company_FooDiff: {
                    title: "Hello Universe!"
                    baz: "00000177-72f2-d6fd-a97f-76f281400000"
                }
            },
            {
                id: "00000177-72ea-d6fd-a97f-76fa15700001",
                com_company_BarDiff: {
                    barTitle: "Hello Quark!"
                }
            }
        ]
    ) {
        _id
        title
        bar {
            _id
            barTitle
        }
        baz {
            _id
            bazTitle
        }
    }
}


Example 66. Response
{
  "data": {
    "com_company_FooSave": {
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
      "title": "Hello Universe!",
      "bar": {
        "_id": "00000177-72ea-d6fd-a97f-76fa15700001",
        "barTitle": "Hello Quark!"
      },
      "baz": {
        "_id": "00000177-72f2-d6fd-a97f-76f281400000",
        "bazTitle": "Hello Sentient Being!"
      }
    }
  }
}