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 support@parameter1.com 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.
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.
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.)
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.
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.
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.
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.
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.
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!
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.
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.
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!
Last updated