Modifying content

A guide to using content mutations to modify content data via the BaseCMS GraphQL API.

Requirements

You'll need the following information to schedule content via the API:

• An API URL

• A BASE instance URL

• A Tenant Key

• An active BASE user with permission to read and write data

• A content ID

If you're missing any of this information, please reach out to [email protected] and we'd be happy to provide it!

Connecting to the API

Connect to the API using a the GraphQL client, programming library, or request utility of your choice. Make sure to send your tenant key along with your request in the x-tenant-key HTTP header. For a detailed example, review the Connecting to the API guide.

Authentication

To modify content, you must first authenticate to the BaseCMS GraphQL API using valid user credentials with access to read and write data. Once complete, send your authentication token along with your request in the authorization header (using the Bearer prefix). For a detailed example, review the Authenticating to the API segment of the Connecting to the API guide.

BASE instance access

In order to route to the correct environment, make sure you send your BASE instance URL along with your request in the x-base4-api-uri HTTP header. For a detailed example, review the Specifying your BASE instance segment of the Connecting to the API guide.

Chaining Requests

One handy feature of GraphQL is that you can send multiple operations in a single HTTP request, lowering the overall request overhead of communicating with the API (which is great for staying under rate limits, too!). You can send multiple operations by including them as siblings in the request body.

Sending multiple mutation operations in a single request.

Name, Teaser, and Body fields

The Name, Teaser, and Body fields all support multiple values based on the content mutation (also referred to as a revision), to allow different values to be displayed based on the viewing medium. Commonly, this functionality is used to show a different name when used in an email newsletter, or to customize the display of the content name for viewing on the website.

For all three fields, the mutated value can be removed by sending an empty string "" to the relevant mutation's value field. The default/non-mutated value for the Teaser and Body fields can be removed in the same manner, but the Name field (which is required) cannot.

When the default/non-mutated field is requested via the GraphQL API, the field will return the Website mutation value if present, and the default value if none is present. This field supports input parameters (you can see the full set by introspecting the GraphQL schema from your client!) to override this behavior.

Name

To set the name, use the contentName mutation, specifying the new value and mutation (revision) if necessary.

Setting the content name (default/non-mutated) value.

Setting the content name Email mutation value.

Removing the content name Email mutation value.

Teaser

To modify the teaser field, use the contentTeaser mutation, specifying the new value and mutation (revision) if necessary. To remove the teaser, send an empty string for the value input.

When querying for the teaser, be sure to send the minLength input to ensure the teaser is not truncated. Teasers are automatically truncated if they are under the minimum length or over the maximum length (which default to 75 and 125 characters, respectively.)

Setting the content teaser field and using the `minLength` input arguments.

Body

To modify the body field, use the contentBody mutation, specifying the new value and mutation (revision) if necessary. To remove the body, send an empty string for the value input.

Setting the content body field.

Publishing

You can use the contentPublishing mutation to affect the contents status (one of draft, active, or deleted), the published date (when the content is available for viewing), and the unpublished date (when the content is no longer available).

Content is visible on your website when the content is in active status, the published date is in the past, and the unpublished date is in the future, or not set. The textStatus Content field contains a user-friendly version of the content state, with the notable addition of the Scheduled state to indicate the content is published, but not yet visible.

Content is also visible (but not indexable) on your website when accessed via Preview mode from BASE.

To immediately publish a content item, send the active value to the status input of the contentPublishing mutation.

Immediately publishing a content item via the `contentPublishing` mutation.

Scheduling content to publish later via the `contentPublishing` mutation.

If a published date has previously been set it will be retained unless it is in the future.

If there is a future published date already set, it will be updated to now to ensure the content is immediately accessible. To override this behavior, you must explicitly send a date in the published input.

If an unpublished date has previously been set it will be retained unless it is in the past.

If there is a past unpublished date already set, it will be removed to ensure the content is immediately accessible. To override this behavior, you must explicitly send a date in the unpublished input.

To immediately unpublish a content item, send the draft or deleted value to the status input of the contentPublishing mutation.

Immediately unpublishing content by putting it in `draft` state via the `contentPublishing` mutation.

Custom Attributes

BASE supports setting custom text attributes on content items to store additional information, such as legacy/external IDs, or anything else you'd like! You can view and store any* text value via the GraphQL API by using the customAttribute query field and the contentCustomAttributes mutation.

Only pre-defined custom attributes will show up in the BASE UI. If there's an attribute you'd like to see in the BASE UI, please reach out to us and we'd be happy to add it for you!

Retrieving a custom attribute

To retrieve a custom attribute, send the path input to the customAttribute field to specify the custom attribute you'd like to retrieve. The following example returns the externalId field, and shows an example of aliasing to return it as a top-level field.

Retrieving a custom attribute via the `content` query and the `customAttribute` field.

Modifying a custom attribute

To set a custom attribute, include the path and value inputs to the contentCustomAttribute mutation. To remove a custom attribute, send an empty string "" as the value.

Setting a custom attribute via the `contentCustomAttribute` mutation.

Removing a custom attribute via the `contentCustomAttribute` mutation.

Modifying Event dates

The startDate and endDate fields are unique to the ContentEvent type and can be manipulated using the contentEventDates mutation. This mutation also supports the allDay Boolean parameter, which indicates that the times should be ignored from these dates.

As with all Date inputs available via the GraphQL API, make sure to send the value as a UNIX timestamp with millisecond precision!

Setting the `startDate` and `allDay` fields via the `contentEventDates` mutation.

Modifying Contactable fields

All of the fields of the Contactable interface can be modified with the contentContactFields mutation. To remove a value, you must explicitly send a null value to the relevant input field.

Setting Contactable fields via the `contentContactFields` mutation.

Make sure you are modifying a content item that implements the Contactable interface when using this mutation. If you attempt to modify a content item that does not support these fields, the request will fail!

Modifying Addressable fields

All of the fields of the Addressable interface can be modified with the contentAddressFields mutation. To remove a value, you must explicitly send a null value to the relevant input field.

Setting `Addressable` fields via the `contentAddressFields` mutation.

Make sure you are modifying a content item that implements the Addressable interface when using this mutation. If you attempt to modify a content item that does not support these fields, the request will fail!