Brightspot CMS Developer Guide
Brightspot CMS Developer Guide
Developer guide
GraphQL API
Content Management API

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:

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

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

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

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
        }
    }
}
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!"
      }
    }
  }
}

Previous Topic
Hello Content Management API
Next Topic
Uploading files in Brightspot Content Management API
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.



Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Modules
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Dashboards
Publishing
Workflows
Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
Images
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Shopify
Apple News