Creating and updating 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:

showLineNumbers

1
public class Foo extends Record {
2

3
    private String title;
4

5
    private Integer number;
6

7
    private List<Integer> numbers;
8

9
    private boolean flag;
10

11
    @Recordable.Embedded
12
    private Bar bar;
13

14
    private Baz baz;
15

16
}

showLineNumbers

1
@Recordable.Embedded
2
public class Bar extends Record {
3

4
   private String barTitle;
5
}

showLineNumbers

1
public class Baz extends Record {
2

3
   private String bazTitle;
4
}

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:

showLineNumbers

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

5
input com_company_FooDiffInput {
6
    com_company_BarDiff: com_company_BarInput
7
    com_company_FooDiff: com_company_FooInput
8
    id: DiffId
9
}
10

11
input com_company_FooInput {
12
    bar: DiffId
13
    baz: RefId
14
    flag: Boolean
15
    number: Int
16
    numbers: [Int]
17
    title: String
18
}
19

20
input com_company_BarInput {
21
    barTitle: String
22
}

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 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.

showLineNumbers

1
Query
2
mutation MyMutation {
3
    com_company_FooSave(id: "1", toolUser: "[email protected]",
4
        diffs: [
5
            {
6
                id: "1",
7
                com_company_FooDiff: {
8
                    title: "Hello World!"
9
                    flag: true
10
                    number: 1
11
                    numbers: [2, 3]
12
                    baz: "00000177-72e6-d6fd-a97f-76f6002a0000"
13
                }
14
            }
15
        ]
16
    ) {
17
        _id
18
        title
19
        flag
20
        number
21
        numbers
22
        baz {
23
            _id
24
            bazTitle
25
        }
26
    }
27
}

showLineNumbers

1
Response
2
{
3
  "data": {
4
    "com_company_FooSave": {
5
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
6
      "title": "Hello World!",
7
      "flag": true,
8
      "number": 1,
9
      "numbers": [2, 3],
10
      "baz": {
11
        "_id": "00000177-72e6-d6fd-a97f-76f6002a0000",
12
        "bazTitle": "Hello Human!"
13
      }
14
    }
15
  }
16
}

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.

showLineNumbers

1
Query
2
mutation MyMutation {
3
    com_company_FooSave(id: "1", toolUser: "[email protected]",
4
        diffs: [
5
            {
6
                id: "1",
7
                com_company_FooDiff: {
8
                    bar: "2"
9
                }
10
            },
11
            {
12
                id: "2",
13
                com_company_BarDiff: {
14
                    barTitle: "Hello Atom!"
15
                }
16
            }
17
        ]
18
    ) {
19
        _id
20
        bar {
21
            _id
22
            barTitle
23
        }
24
    }
25
}

showLineNumbers

1
Response
2
{
3
  "data": {
4
    "com_company_FooSave": {
5
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
6
      "bar": {
7
        "_id": "00000177-72ea-d6fd-a97f-76fa15700001",
8
        "barTitle": "Hello Atom!"
9
      }
10
    }
11
  }
12
}

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.

showLineNumbers

1
Query
2
mutation MyMutation {
3
    com_company_FooSave(id: "00000177-72ea-d6fd-a97f-76fa15700000", toolUser: "[email protected]",
4
        diffs: [
5
            {
6
                id: "00000177-72ea-d6fd-a97f-76fa15700000",
7
                com_company_FooDiff: {
8
                    title: "Hello Universe!"
9
                    baz: "00000177-72f2-d6fd-a97f-76f281400000"
10
                }
11
            },
12
            {
13
                id: "00000177-72ea-d6fd-a97f-76fa15700001",
14
                com_company_BarDiff: {
15
                    barTitle: "Hello Quark!"
16
                }
17
            }
18
        ]
19
    ) {
20
        _id
21
        title
22
        bar {
23
            _id
24
            barTitle
25
        }
26
        baz {
27
            _id
28
            bazTitle
29
        }
30
    }
31
}

showLineNumbers

1
Response
2
{
3
  "data": {
4
    "com_company_FooSave": {
5
      "_id": "00000177-72ea-d6fd-a97f-76fa15700000",
6
      "title": "Hello Universe!",
7
      "bar": {
8
        "_id": "00000177-72ea-d6fd-a97f-76fa15700001",
9
        "barTitle": "Hello Quark!"
10
      },
11
      "baz": {
12
        "_id": "00000177-72f2-d6fd-a97f-76f281400000",
13
        "bazTitle": "Hello Sentient Being!"
14
      }
15
    }
16
  }
17
}