Management SDK field examples

Please note that a lot of the examples shown here rely on a previously created schema and cannot be used as standalone information. This document merely aims at offering users easy access to examples on how to create different field types using the Management SDK.

All the examples shown here use example values, which you need to replace with your own. For instance, <your_model> could be replaced with any model name of your choice, like Author.

All Create, Update, and Delete actions require Update and Delete Existing Fields permissions set in the auth token.

#Models

#Create models

client.createModel({
  apiId: '<your_api_id>',
  apiIdPlural: '<your_api_id_plural>',
  description: `<your_model_description>`,
  displayName: '<Your model name>',
});

apiId: String. The model apiId.
apiIdPlural: String. The models plural apiId. This is used for lists.
description: Optional - String. Description of the model.
displayName: String. Display name that is used to render the model in the webapp.

#Update models

client.updateModel({
  apiId: '<your_api_id>',
  apiIdPlural: '<your_api_id_plural>',
  description: `<your_model_description>`,
  displayName: '<Your model name>',
  newApiId: `<your_new_api_id>`,
});

apiId: String. The model apiId.
apiIdPlural: Optional - String. The model's plural apiId. This is used for lists.
description: Optional - String. Description of the model.
displayName: Optional - String. Display name that is used to render the model in the webapp.
newApiId: Optional - String. The model's new apiId.

#Delete models

client.deleteModel({
  apiId: '<your_api_id>',
});

apiId: String. The apiId of the model you wish to delete.

#Simple fields

#Create simple fields

client.createSimpleField({
  apiId: `<your_api_id>`,
  description: `<your_description>`,
  displayName: `<your_display_name>`,
  embeddableModels: `<embeddable_models>`,
  embedsEnabled: `<boolean>`,
  formConfig: `<form_config_json>`,
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  isHidden: `<boolean>`,
  isList: `<boolean>`,
  isLocalized: `<boolean>`,
  isRequired: `<boolean>`,
  isTitle: `<boolean>`,
  isUnique: `<boolean>`,
  migrationValue: `<migration_value>`,
  modelApiId: `<model_api_id>`,
  parentApiId: `<parent_api_id>`,
  position: `<int>`,
  tableConfig: `<table_config_json>`,
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  type: SimpleFieldType,
  validations: `<SimpleFieldValidationsInput>`,
  visibility: `<VisibilityTypes>`,
});

apiId: String Your simple field apiId.
description: Optional - String. Simple field description.
displayName: String. Display name that is used to render the field in the webapp.
embeddableModels: Optional - String.
embedsEnabled: Optional - Boolean.
formConfig: Optional - JSON.
formExtension: Optional - String.
formRenderer: Optional - String.
isHidden: Optional - Boolean. Makes the field hidden if true.
isList: Optional - Boolean.
isLocalized: Optional - Boolean.
isRequired: Optional - Boolean. Makes the field required if true.
isTitle: Optional - Boolean. Makes the field a title if true.
isUnique: Optional - Boolean. Makes the field unique if true.
migrationValue: Optional - String. Value which will go in place of null if the field is later made required.
modelApiId: Optional - String. Model apiId.
parentApiId: Optional - String. Parent apiId.
position: Optional - Integer.
tableConfig: Optional - JSON.
tableExtension: Optional - String.
tableRenderer: Optional - String.
type: SimpleFieldType,
validations: Field validations.
visibility: Field visibility, for example VisibilityTypes.ReadWrite.

#Update simple field

client.updateSimpleField({
  apiId: `<your_api_id>`,
  description: `<your_description>`,
  displayName: `<your_display_name>`,
  embeddableModels: `<embeddable_models>`,
  embedsEnabled: `<boolean>`,
  formConfig: `<form_config_json>`,
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  initialValue: `<initial_value>`,
  isHidden: `<boolean>`,
  isList: `<boolean>`,
  isLocalized: `<boolean>`,
  isRequired: `<boolean>`,
  isTitle: `<boolean>`,
  isUnique: `<boolean>`,
  migrationValue: `<migration_value>`,
  modelApiId: `<model_api_id>`,
  newApiId: `<new_api_id>`,
  parentApiId: `<parent_api_id>`,
  position: `<int>`,
  tableConfig: `<table_config_json>`,
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  validations: `<SimpleFieldValidationsInput>`,
  visibility: `<VisibilityTypes>`,
});

apiId: String Your simple field apiId.
description: Optional - String. Simple field description.
displayName: String. Display name that is used to render the field in the webapp.
embeddableModels: Optional - String.
embedsEnabled: Optional - Boolean.
formConfig: Optional - JSON.
formExtension: Optional - String.
formRenderer: Optional - String.
initialValue: Optional - String.
isHidden: Optional - Boolean. Makes the field hidden if true.
isList: Optional - Boolean.
isLocalized: Optional - Boolean.
isRequired: Optional - Boolean. Makes the field required if true.
isTitle: Optional - Boolean. Makes the field a title if true.
isUnique: Optional - Boolean. Makes the field unique if true.
migrationValue: Optional - String. Value which will go in place of null if the field is later made required.
modelApiId: Optional - String. Model apiId.
newApiId: Optional - String. New apiId.
parentApiId: Optional - String. Parent apiId.
position: Optional - Integer.
tableConfig: Optional - JSON.
tableExtension: Optional - String.
tableRenderer: Optional - String.
validations: Field validations.
visibility: Field visibility, for example VisibilityTypes.ReadWrite.

#Delete field

client.deleteField({
  apiId: `<your_api_id>`,
  modelApiId: `<model_api_id>`,
  parentApiId: `<parent_api_id>`,
});

apiId: String. Thr apiId of the field you wish to delete.
modelApiId: Optional - String. The modelApiId of the field you wish to delete.
parentApiId: Optional - String. The parentApiId of the field you wish to delete.

#Specific examples

#Title field of type string

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.String,
  apiId: '<your_title>',
  displayName: '<Your Title>',
  isTitle: true,
  isRequired: true,
  visibility: VisibilityTypes.ReadWrite,
});

#Simple field of type string

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.String,
  apiId: '<your_api_id>',
  displayName: '<Your Display Name>',
  isRequired: true,
  visibility: VisibilityTypes.ReadWrite,
});

#Slug field

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.String,
  apiId: '<your_api_id>',
  displayName: '<Your Display Name>',
  description:
    '<Enter the slug for this page, such as about, blog, or contact>',
  isRequired: true,
  isUnique: true,
  tableRenderer: 'GCMS_SLUG',
  formRenderer: 'GCMS_SLUG',
});

#Hidden integer field with custom field validation

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.Int,
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  visibility: VisibilityTypes.Hidden,
  validations: {
    Int: {
      range: {
        max: 1000,
        min: 0,
        errorMessage: '<Counter has to be between 0 and 1000>',
      },
    },
  },
});

#Required & unique string field with custom regex validation for emails

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.String,
  apiId: '<email>',
  displayName: '<Email>',
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
      },
    },
  },
});

#Richtext field

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.Richtext,
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  description:
    '<Enter the content for this page. The content uses the rich-text editor, giving you a better visual representation.>',
  isRequired: true,
});

#Richtext with embeds and single allowed embeddable model

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.Richtext,
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  embedsEnabled: true,
  embeddableModels: ['<model>'],
});

#List of date times

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.Datetime,
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  isRequired: true,
  isList: true,
});

#Relational fields

#Create relational field

client.createRelationalField({
  apiId: '<api_id>',
  description: `<your_description>`,
  displayName: '<Your Display Name>',
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  isHidden: `<boolean>`,
  isList: `<boolean>`,
  isRequired: `<boolean>`,
  modelApiId: `<model_api_id>`,
  parentApiId: '<parent_api_id>',
  reverseField: {
    apiId: '<api_id>',
    description: `<description>`,
    displayName: '<Your Display Name>',
    isHidden: `<boolean>`,
    isList: `<boolean>`,
    isUnidirectional: `<boolean>`,
    modelApiId: '<model_api_id>',
    visibility: `<visibility_types>`,
  },
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  type: `<relational_field_type>`,
  visibility: `<visibility_types>`,
});

apiId: String. Your relational field apiId.
description: Optional - String. Relational field description.
displayName: String. Display name that is used to render the relational field in the webapp.
formExtension: Optional - String.
formRenderer: Optional - String.
isHidden: Optional - Boolean. The relational field is hidden if true.
isList: Optional - Boolean.
isRequired: Optional - Boolean. The relational field is required if true. Only supported for RelationalFieldType.Asset.
modelApiId: Optional - String. Model apiId.
parentApiId: Optional - String. Parent apiId.
reverseField: Reverse relational field input.
- apiId: String. Your reverse relational field apiId.
- description: Optional - String. Description.
- displayName: String. Reverse field display name.
- isHidden: Optional - Boolean. The field is hidden if true.
- isList: Boolean.
  
  Pro Tip
  Relation cardinality can only be set when creating a relational field and cannot be updated later.
  In components and one-way references in models, the reverse side of a relation must have isList: true set for it to be possible to reconnect an entry to the same component instance.
  Misconfiguring this as isList:false might lead to failure and having to recreate the relation due to the inability to change the relation cardinality.
- isUnidirectional: Optional - Boolean. The field is unidirectional if true.
- modelApiId: String. Reverse field model apiId.
- visibility: Visibility types.
tableExtension: Optional - String.
tableRenderer: Optional - String.
type: Relational field type. For example RelationalFieldType.Asset.
visibility: Optional. Visibility types.

#Update relational field

client.updateRelationalField({
  apiId: '<api_id>',
  description: `<your_description>`,
  displayName: '<Your Display Name>',
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  isHidden: `<boolean>`,
  isList: `<boolean>`,
  isRequired: `<boolean>`,
  modelApiId: `<model_api_id>`,
  parentApiId: '<parent_api_id>',
  reverseField: {
    apiId: '<api_id>',
    description: `<description>`,
    displayName: '<Your Display Name>',
    isHidden: `<boolean>`,
    isList: `<boolean>`,
    isUnidirectional: `<boolean>`,
    modelApiId: '<model_api_id>',
    visibility: `<visibility_types>`,
  },
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  type: `<relational_field_type>`,
  visibility: `<visibility_types>`,
});

apiId: String. Your relational field apiId.
description: Optional - String. Relational field description.
displayName: String. Display name that is used to render the relational field in the webapp.
formExtension: Optional - String.
formRenderer: Optional - String.
isHidden: Optional - Boolean. The relational field is hidden if true.
isList: Optional - Boolean.
isRequired: Optional - Boolean. The relational field is required if true. Only supported for RelationalFieldType.Asset.
modelApiId: Optional - String. Model apiId.
parentApiId: Optional - String. Parent apiId.
reverseField: Reverse relational field input.
- apiId: String. Your reverse relational field apiId.
- description: Optional - String. Description.
- displayName: String. Reverse field display name.
- isHidden: Optional - Boolean. The field is hidden if true.
- isList: Optional - Boolean.
- isUnidirectional: Optional - Boolean. The field is unidirectional if true.
- modelApiId: String. Reverse field model apiId.
- visibility: Visibility types.
tableExtension: Optional - String.
tableRenderer: Optional - String.
type: Relational field type. For example RelationalFieldType.Asset.
visibility: Optional. Visibility types.

#Delete relational field

Use deleteField method.

#Specific examples

#Required uni-directional asset field

client.createRelationalField({
  parentApiId: '<parent_api_id>',
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  type: RelationalFieldType.Asset,
  isRequired: true,
  reverseField: {
    isUnidirectional: true,
    apiId: '<api_id>',
    displayName: '<Your Display Name>',
    modelApiId: '<model_api_id>',
  },
});

#M-n relation

client.createRelationalField({
  parentApiId: '<parent_api_id>',
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  type: RelationalFieldType.Relation,
  isList: true,
  reverseField: {
    modelApiId: '<model_api_id>',
    apiId: '<api_id>',
    displayName: '<Your Display Name>',
    isList: true,
  },
});

#Union fields

#Create union field

client.createUnionField({
  apiId: '<api_id>',
  description: `<description>`,
  displayName: '<Your Display Name>',
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  isHidden: `<boolean>`,
  isList: `<boolean>`,
  modelApiId: `<model_api_id>`,
  parentApiId: '<parent_api_id>',
  reverseField: {
    apiId: '<api_id>',
    description: `<description>`,
    displayName: '<Your Display Name>',
    isHidden: `<boolean>`,
    isList: `<boolean>`,
    modelApiIds: ['<model_api_id_1>', '<model_api_id_2>'],
    visibility: `<visibility_types>`,
  },
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  visibility: `<visibility_types>`,
});

apiId: String. Union field apiId.
description: Optional - String. Union field description.
displayName: String. Display name that is used to render the union field in the webapp.
formExtension: Optional - String.
formRenderer: Optional - String.
isHidden: Optional - Boolean. The relational field is hidden if true.
isList: Optional - Boolean.
modelApiId: Optional - String. Model apiId.
parentApiId: Optional - String. Parent apiId.
reverseField: Reverse union field input.
- apiId: Optional - String.
- description: Optional - String.
- displayName: Optional - String.
- isHidden: Optional - Boolean. The reverse relational field is hidden if true.
- isList: Optional - Boolean.
- modelApiIds: String. Model apiIds.
- visibility: Visibility types.
tableExtension: Optional - String.
tableRenderer: Optional - String.
visibility: Visibility types.

#Update union field

client.updateUnionField({
  apiId: '<api_id>',
  description: `<description>`,
  displayName: '<Your Display Name>',
  modelApiId: `<model_api_id>`,
  parentApiId: '<parent_api_id>',
  reverseField: {
    modelApiIds: ['<model_api_id_1>', '<model_api_id_2>'],
  },
  visibility: `<visibility_types>`,
});

apiId: String. Union field apiId.
description: Optional - String. Union field description.
displayName: String. Display name that is used to render the union field in the webapp.
modelApiId: Optional - String. Model apiId.
parentApiId: Optional - String. Parent apiId.
reverseField: updateReverseUnionField. Update reverse union field input.
- modelApiIds: String. Model apiIds.
visibility: Visibility types.

#Delete union field

Use deleteField method.

#Components

#Create component

client.createComponent({
  apiId: '<api_id>',
  apiIdPlural: '<api_id_plural>',
  description: `<your_description>`,
  displayName: '<Your Display Name>',
});

apiId: String. Your component apiId.
apiIdPlural: String. The component's plural apiId. This is used for lists.
description: Optional - String. Your component description.
displayName: String. Display name that is used to render the component in the webapp.

#Update component

client.updateComponent({
  apiId: '<api_id>',
  apiIdPlural: '<api_id_plural>',
  description: `<your_description>`,
  displayName: '<Your Display Name>',
  newApiId: `<new_api_id>`,
});

apiId: String. Your component apiId.
apiIdPlural: Optional - String. The component's plural apiId. This is used for lists.
description: Optional - String. Your component description.
displayName: Optional - String. Display name that is used to render the component in the webapp.
newApiId: Optional - String. New apiId.

#Delete component

client.deleteComponent({
  apiId: '<api_id>',
});

apiId: String. The apiId of the component you wish to delete.

#Create component field

client.createComponentField({
  apiId: '<api_id>',
  componentApiId: `<component_api_id>`,
  description: `<your_component_field_description>`,
  displayName: '<Your Display Name>',
  formExtension: `<form_extension>`,
  formRenderer: `<form_renderer>`,
  isList: `<boolean>`,
  isRequired: `<boolean>`,
  parentApiId: `<parent_api_id>`,
  position: `<int>`,
  tableExtension: `<table_extension>`,
  tableRenderer: `<table_renderer>`,
  visibility: `<visibility_types>`,
});

apiId: String. Your component field apiId.
componentApiId: String. Your component apiId.
description: Optional - String. Your component field description.
displayName: String. Display name that is used to render the component field in the webapp.
formExtension: Optional - String.
formRenderer: Optional - String.
isList: Optional - Boolean.
isRequired: Optional - Boolean. If true, the component field is required.
parentApiId: String. Parent apiId.
position: Optional - Integer.
tableExtension: Optional - String.
tableRenderer: Optional - String.
visibility: Optional. Visibility types.

#Update component field

client.updateComponentField({
  apiId: '<api_id>',
  description: `<your_component_field_description>`,
  displayName: '<Your Display Name>',
  isList: `<boolean>`,
  isRequired: `<boolean>`,
  newApiId: `<new_api_id>`,
  parentApiId: `<parent_api_id>`,
  visibility: `<visibility_types>`,
});

apiId: String. Your component field apiId.
description: Optional - String. Your component field description.
displayName: Optional - String. Display name that is used to render the component field in the webapp.
isList: Optional - Boolean.
isRequired: Optional - Boolean. If true, the component field is required.
newApiId: Optional - String. New apiId.
parentApiId: String. Parent apiId.
visibility: Optional. Visibility types.

#Delete component field

Use deleteField method.

#Specific examples

#Add a field to a component

client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.String,
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
});

#Create basic component field

client.createComponentField({
  parentApiId: '<parent_api_id>',
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  description: '<Your description>',
  componentApiId: '<component_api_id>',
});

#Create a component union field

client.createComponentUnionField({
  parentApiId: '<parent_api_id>',
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  componentApiIds: ['<component_api_id_1>', '<component_api_id_2>'],
});

#Remove VideoBlock from a component union field

client.createComponentUnionField({
  parentApiId: '<parent_api_id>',
  apiId: '<api_id>',
  displayName: '<Your Display Name>',
  componentApiIds: [
    '<contributor_component_api_id>',
    '<videoblock_component_api_id>',
  ],
});

#Remote sources

#Create GraphQL remote sources

client.createGraphQlRemoteSource({
  debugEnabled: `<boolean>`,
  description: `<your_description>`,
  displayName: `<Your Display Name>`,
  headers: `<json>`,
  introspectionHeaders: `<json>`,
  introspectionMethod: `<get_or_post>`,
  introspectionUrl: `<introspection_url>`,
  prefix: `<prefix>`,
  remoteTypeDefinitions: {
    sdl: `<CreateRemoteTypeDefinition>`,
  },
  url: `<url>`,
});

debugEnabled: Optional - Boolean.
description: Optional - String. GraphQL remote source description.
displayName: String. Display name that is used to render the GraphQL remote source in the webapp.
headers: Optional - JSON.
introspectionHeaders: Optional - JSON. HTTP headers that will be used for introspection.
introspectionMethod: GraphQlRemoteSourceIntrospectionMethod. HTTP method that will be used for introspection.
introspectionUrl: Optional - String. Specific URL that will be used for introspection if the introspection is available on a URL other than the regular URL. Can be ignored if the introspection URL is the same as the URL of the remote source.
prefix: String.
remoteTypeDefinitions: Optional. CreateRemoteTypeDefinition. Custom GraphQL input types that can be used as arguments in remote fields that belong to this remoteSource.
- sdl: String
url: String

#Update GraphQL remote sources

client.createGraphQlRemoteSource({
  debugEnabled: `<boolean>`,
  description: `<your_description>`,
  displayName: `<Your Display Name>`,
  headers: `<json>`,
  introspectionHeaders: `<json>`,
  introspectionMethod: `<get_or_post>`,
  introspectionUrl: `<introspection_url>`,
  prefix: `<prefix>`,
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: `<remote_type_definitions_to_create>`,
    remoteTypeDefinitionsToDelete: `<remote_type_definitions_to_delete>`,
    remoteTypeDefinitionsToUpdate: `<remote_type_definitions_to_update>`,
  },
  url: `<url>`,
});

debugEnabled: Optional - Boolean.
description: Optional - String. GraphQL remote source description.
displayName: Optional - String. Display name that is used to render the GraphQL remote source in the webapp.
headers: Optional - JSON.
introspectionHeaders: Optional - JSON. HTTP headers that will be used for introspection.
introspectionMethod: GraphQlRemoteSourceIntrospectionMethod. HTTP method that will be used for introspection.
introspectionUrl: Optional - String. Specific URL that will be used for introspection if the introspection is available on a URL other than the regular URL. Can be ignored if the introspection URL is the same as the URL of the remote source.
prefix: String. Unique prefix that will be prepended to all of the remote types. This value cannot be changed.
remoteTypeDefinitionsToUpsert: Optional. CreateRemoteTypeDefinition. Custom GraphQL input types that can be used as arguments in remote fields that belong to this remoteSource.
- remoteTypeDefinitionsToCreate: Optional Remote type definitions to create.
- remoteTypeDefinitionsToDelete: Optional Remote type definitions to delete.
- remoteTypeDefinitionsToUpdate: Optional Remote type definitions to update.
url: Optional - String

#Create REST remote sources

client.createRestRemoteSource({
  debugEnabled: `<boolean>`,
  description: `<your_description>`,
  displayName: `<Your Display Name>`,
  headers: `<json>`,
  prefix: `<prefix>`,
  remoteTypeDefinitions: {
    sdl: `<CreateRemoteTypeDefinition>`,
  },
  url: `<url>`,
});

debugEnabled: Optional - Boolean.
description: Optional - String. REST remote source description.
displayName: String. Display name that is used to render the REST remote source in the webapp.
headers: Optional - JSON.
prefix: String. Unique prefix that will be prepended to all of the remote types. This value cannot be changed.
remoteTypeDefinitions: Optional. CreateRemoteTypeDefinition. Remote type definitions that the remote source supports, or input types that can be used by any remote field of this remote source.
- sdl: String
url: String

#Update REST remote sources

client.updateRestRemoteSource({
  debugEnabled: `<boolean>`,
  description: `<your_description>`,
  displayName: `<Your Display Name>`,
  headers: `<json>`,
  prefix: `<prefix>`,
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: `<remote_type_definitions_to_create>`,
    remoteTypeDefinitionsToDelete: `<remote_type_definitions_to_delete>`,
    remoteTypeDefinitionsToUpdate: `<remote_type_definitions_to_update>`,
  },
  url: `<url>`,
});

debugEnabled: Optional - Boolean.
description: Optional - String. REST remote source description.
displayName: String. Display name that is used to render the REST remote source in the webapp.
headers: Optional - JSON.
prefix: String. Unique prefix that will be prepended to all of the remote types. This value cannot be changed.
remoteTypeDefinitionsToUpsert: Optional. CreateRemoteTypeDefinition. Remote type definitions that the remote source supports, or input types that can be used by any remote field of this remote source.
- remoteTypeDefinitionsToCreate: Optional Remote type definitions to create.
- remoteTypeDefinitionsToDelete: Optional Remote type definitions to delete.
- remoteTypeDefinitionsToUpdate: Optional Remote type definitions to update.
url: String

#Delete remote source

client.deleteRemoteSource({
  prefix: `<prefix>`,
});

prefix: String. The prefix of the remote source you wish to delete.

#Enumerations

#Create enumeration

client.createEnumeration({
  apiId: `<your_app_id>`,
  description: `<description>`,
  displayName: `<display_name>`,
  values: {
    apiId: `<api_id>`,
    displayName: `<display_name>`,
  },
});

apiId: String. Enumeration apiId.
description: Optional - String. Enumeration description.
displayName: String. Display name that is used to render the enumeration in the webapp.
values: CreateEnumerationValue. Enumeration values.
- apiId: String. Enumeration value apiId.
- displayName: String. Display name that is used to render the enumeration value in the webapp.

#Update enumeration

client.updateEnumeration({
  apiId: `<your_app_id>`,
  description: `<description>`,
  displayName: `<display_name>`,
  newApiId: `<new_api_id>`,
  valuesToCreate: {
    apiId: `<api_id>`,
    displayName: `<display_name>`,
  },
  valuesToDelete: [`<value_1>`, `<value_2>`],
  valuesToUpdate: {
    apiId: `<api_id>`,
    displayName: `<display_name>`,
    newApiId: `<new_api_id>`,
  },
});

apiId: String. Enumeration apiId.
description: Optional - String. Enumeration description.
displayName: String. Display name that is used to render the enumeration in the webapp.
newApiId: Optional - String. New apiId.
valuesToCreate: Optional - String. createEnumerationValue. Enumeration values to be created.
- apiId: String. Enumeration value apiId.
- displayName: String. Display name that is used to render the enumeration value in the webapp.
valuesToDelete: Optional - String. Values to delete.
valuesToUpdate: Optional - String. updateEnumerationValue. Enumeration values to be updated..
- apiId: String. Enumeration value apiId.
- displayName: Optional - String. Display name that is used to render the enumeration value in the webapp.
- newApiId: Optional - String. New apiId.

#Delete enumeration

client.deleteEnumeration({
  apiId: `<your_app_id>`,
});

apiId: String. apiId of the enumeration you wish to delete.

#Create enumerable field

client.createEnumerableField({
  apiId: 'enumField',
  description: 'Description',
  displayName: 'Enum Field',
  parentApiId: 'Post',
  enumerationApiId: 'Variation',
});

apiId: String. Enumerable field apiId.
description: Optional - String. Enumerable field description.
displayName: String. Display name that is used to render the enumerable field in the webapp.
parentApiId: String. Parent apiId.
enumerationApiId: String. Enumeration apiId.

#Update enumerable field

client.updateEnumerableField({
  apiId: 'enumField', // required
  parentApiId: 'Test', // required
  description: 'Description',
  displayName: 'Enum Field Update',
  initialValue: 'Value 1',
  isHidden: false,
  isList: false,
  isLocalized: false,
  isRequired: false,
  isTitle: false,
  isUnique: false,
  migrationValue: 'Value 1',
  position: 0,
  visibility: 'READ_WRITE',
});

apiId: Required - String. Enumerable field apiId.
parentApiId: Required - String. Parent apiId.
description: Optional - String. Enumerable field description.
displayName: String. Display name that is used to render the enumerable field in the webapp.
initialValue: String. Initial value of the field.
isHidden: Optional - Boolean. Makes the field hidden if true.
isList: Optional - Boolean.
isLocalized: Optional - Boolean.
isRequired: Optional - Boolean. Makes the field required if true.
isTitle: Optional - Boolean.
isUnique: Optional - Boolean.
migrationValue: String. Migration value of the enumerable field.
position: Optional - Integer.
visibility: Field visibility, for example VisibilityTypes.ReadWrite.

#Delete enumerable field

Use deleteField method.

#Locales

#Create locale

client.createLocale({
  apiId: `<your_app_id>`,
  description: `<description>`,
  displayName: `<Display Name>`,
});

apiId: String. Locale apiId.
description: Optional - String. Locale description.
displayName: String. Display name associated with the locale.

#Update locale

client.updateLocale({
  apiId: `<your_app_id>`,
  description: `<description>`,
  displayName: `<Display Name>`,
  isDefault: `<boolean>`,
  newApiId: `<new_api_id>`,
});

apiId: String. Locale apiId.
description: Optional - String. Locale description.
displayName: Optional - String. Display name associated with the locale.
isDefault: Optional - Boolean. If true, this is the default locale.
newApiId: Optional - String. New apiId.

#Delete locale

client.deleteLocale({
  apiId: `<your_app_id>`,
  force: `<boolean>`,
});

apiId: String. Locale apiId.
force: Optional - Boolean. If true, deletion is forced.

#Stages

#Create stage

client.createStage({
  apiId: `<your_app_id>`,
  color: `<color>`,
  description: `<description>`,
  displayName: `<Display Name>`,
  position: `<int>`,
});

apiId: String. Your stage apiId.
color: Select from ColorPalette.
description: Optional - String. Your stage description.
displayName: String. Display name associated with the stage.
position: Optional - Integer.

#Update stage

client.updateStage({
  apiId: `<your_app_id>`,
  color: `<color>`,
  description: `<description>`,
  displayName: `<Display Name>`,
  newApiId: `<new_api_id>`,
  position: `<int>`,
});

apiId: String. Your stage apiId.
color: Optional. Select from ColorPalette.
description: Optional - String. Your stage description.
display: Optional - String. Display name associated with the stage.
newApiId: Optional - String. New apiId.
position: Optional - Integer.

#Delete stage

client.deleteStage({
  apiId: `<your_app_id>`,
});

apiId: String. apiId of the stage you wish to delete.

#Apps

#Create app

This example shows how to create an app installation in an environment.

// config can be any valid object used to configure the app. This will change from app to app. Refer to the app's documentation, if available, for the shape of this object.
client.createAppInstallation({
        config: {
            apiKey: "",
            telemetry: false,
        },
        appApiId: "app.api.id",
    });

appApiId: String. The unique API ID of the app to install.
config: Object (Optional). The app's configuration settings.
- apiKey: String (Nullable). API key for authentication, if required.
- telemetry: Boolean. A flag indicating whether to enable or disable telemetry (tracking of usage data). false means telemetry is disabled.

When an app is installed via the createAppInstallation method, it is always installed with the INCOMPLETE status. Users with the necessary permissions (usually the ADMIN or DEVELOPER roles) must complete the app installation process in Hygraph Studio.

Currently, to use the createAppInstallation method, the app needs to exist in at least one environment within the project. Users can't use this method to install new apps, only apps that they've previously installed in an existing environment.

#Delete app

This example shows how to remove an app installation from an environment.

client.deleteAppInstallation({ appApiId: "app.api.id" });

appApiId: String. The unique API ID of the app to uninstall.

#Custom renderers and app fields

This example demonstrates how to create a simple field with custom table and form renderers in an environment.

client.createSimpleField({
  environmentId: "<your-environment-id>",
  parentApiId: "Car",
  apiId: "appField",
  type: "STRING",
  displayName: "App Field",
  description: null,
  initialValue: null,
  tableRenderer: "CUSTOM",
  formRenderer: "CUSTOM",
  tableExtension: null,
  formExtension: null,
  formConfig: {
    alg_text_name: "Some custom text",
    appApiId: "myapp-test",
    appElementApiId: "myAppField"
  },
  tableConfig: {
    appApiId: "myapp-test",
    appElementApiId: "myAppField"
  },
  isList: false,
  isLocalized: false,
  isRequired: false,
  isUnique: false,
  isHidden: false,
  embeddableModels: [],
  visibility: "READ_WRITE",
  isTitle: false,
  position: 8,
  validations: null,
  embedsEnabled: null,
  visibilityCondition: null
});

environmentId: String. The ID of the environment where the field will be created.
parentApiId: String. The API ID of the parent model (e.g., "Car").
apiId: String. The unique API ID for the field.
type: String. Defines the field type (e.g., "STRING").
displayName: String. The human-readable name of the field.
description: String (Optional). A description of the field, if applicable.
initialValue: String (Optional). The default value of the field.
tableRenderer: String. Specifies how the field is rendered in the table view ("CUSTOM" in this case).
formRenderer: String. Specifies how the field is rendered in the form view ("CUSTOM" in this case).
tableExtension: String (Optional). Extension used for the table renderer.
formExtension: String (Optional). Extension used for the form renderer.
formConfig: Object (Optional). Configuration for the form renderer.
- alg_text_name: String. Custom text for the form field.
- appApiId: String. The API ID of the related app.
- appElementApiId: String. The API ID of the related app field.
tableConfig: Object (Optional). Configuration for the table renderer.
- appApiId: String. The API ID of the related app.
- appElementApiId: String. The API ID of the related app field.
isList: Boolean. Determines if the field supports multiple values.
isLocalized: Boolean. Determines if the field supports multiple locales.
isRequired: Boolean. Determines if the field is mandatory.
isUnique: Boolean. Determines if the field value must be unique.
isHidden: Boolean. Determines if the field is hidden from editors.
embeddableModels: Array. A list of models that can be embedded in this field.
visibility: String. Defines the field's visibility ("READ_WRITE", "READ_ONLY", etc.).
isTitle: Boolean. Determines if this field is used as the model's title field.
position: Integer. The position of the field in the schema.
validations: Object (Optional). Contains validation rules for the field.
embedsEnabled: Boolean (Optional). Determines if embedded content is allowed.
visibilityCondition: Object (Optional). Defines conditional visibility rules for the field.

#Manage sidebar elements

You can manage sidebar elements using the updateModel method on the client.

The following example shows how to create, update and delete both system & custom sidebar elements:

client.updateModel({
  apiId: "modelApiId",
  sidebarElementsToUpsert: {
    systemSidebarElementsToCreate: [{
      type: SystemSidebarElementType.PreviewUrls,
      position: 2,
      // config: Only required for the PreviewUrls SystemSidebarElementType
      config: {
          preview_urls: [{
              name: "Staging web",
              template: "https://staging.example.com/{id}"
          }]
      },
    }, {
      type: SystemSidebarElementType.Versions,
      position: 3,
    }],
    customSidebarElementsToCreate: [{
      appApiId: "apiId for the app",
      appElementApiId: "apiId for the specifi app element",
      displayName: "Display name for the sidebar element",
      description: "Description",
      position: 3,
      // any config required by the app that owns/renders this sidebar element
      config: {},
    }],
    sidebarElementsToUpdate: [{
      displayName: "existing sidebar element",
      newDisplayName: "new name for the sidebar element",
      description: "changed description of the sidebar element",
      // any config required by the app that owns/renders this sidebar element
      config: {},
      position: 4,
    }],
    customSidebarElementsToDelete: [{
      appApiId: "apiId of the app",
      appElementApiId: "apiId of the appElement",
    }],
    systemSidebarElementsToDelete: [{
      type: SystemSidebarElementType.Releases,
    },
        {
      type: SystemSidebarElementType.Localizations,
    }],
  },
});

apiId: String. The unique API ID of the model to update.
sidebarElementsToUpsert: Object. The object containing arrays of sidebar elements to create, update, or delete.
- systemSidebarElementsToCreate: Array. An array of system sidebar elements to add to the model.
  - type: SystemSidebarElementType. The type of system sidebar element (e.g., PreviewUrls, Versions, etc.).
  - position: Number. The position where the sidebar element will be displayed.
  - config: Object. Only required for PreviewUrls type. Contains URL configuration details.
    - preview_urls: Array. A list of preview URLs to add, including:
      - name: String. The display name for the URL.
      - template: String. The URL template, including placeholders like id.
- customSidebarElementsToCreate: Array. An array of custom sidebar elements to add to the model.
  - appApiId: String. The API ID of the app to which the sidebar element belongs.
  - appElementApiId: String. The API ID of the specific app element.
  - displayName: String. The display name for the sidebar element.
  - description: String. A description of the sidebar element.
  - position: Number. The position where the sidebar element will be displayed.
  - config: Object. Any configuration required by the app that renders this sidebar element.
- sidebarElementsToUpdate: Array. An array of existing sidebar elements to update.
  - displayName: String. The current display name of the sidebar element.
  - newDisplayName: String. The updated display name of the sidebar element.
  - description: String. The updated description of the sidebar element.
  - config: Object. Any configuration required by the app that renders this sidebar element.
  - position: Number. The updated position where the sidebar element will be displayed.
- customSidebarElementsToDelete: Array. An array of custom sidebar elements to delete.
  - appApiId: String. The API ID of the app to which the sidebar element belongs.
  - appElementApiId: String. The API ID of the specific app element to delete.
- systemSidebarElementsToDelete: Array. An array of system sidebar elements to delete.
  - type: SystemSidebarElementType. The type of system sidebar element to delete (e.g., Releases, Localizations, etc.).

#Remote fields

#Create remote field

This example shows how to create a remote field for fetching product reviews from an external API.

client.createRemoteField({
  environmentId: "<your-environment-id>",
  parentApiId: "Product",
  apiId: "productReviews",
  displayName: "Product Reviews",
  description: "Fetches reviews for a product from an external API",
  remoteSourceId: "<your-remote-source-id>",
  method: "GET",
  path: "/api/reviews/product/{{doc.productId}}",
  returnType: "ReviewMeta",
  inputArguments: [
    {
      apiId: "productId",
      type: "STRING",
      isRequired: true
    }
  ],
  visibility: "READ_WRITE",
  isList: false,
  isLocalized: false,
  isRequired: false,
  isUnique: false,
  isHidden: false,
  position: 5
});

environmentId: String. The ID of the environment where the remote field will be created.
parentApiId: String. The API ID of the parent model (e.g., "Product").
apiId: String. The unique API ID for the remote field.
displayName: String. The human-readable name of the field.
description: String (Optional). A brief explanation of the field's purpose.
remoteSourceId: String. The ID of the remote source where data will be fetched from.
method: String. The HTTP method used to fetch data ("GET", "POST", etc.).
path: String. The API endpoint path where data is retrieved.
returnType: String. The expected return type of the remote field (e.g., "ReviewMeta").
inputArguments: Array of Objects. The parameters required for the remote request.
- apiId: String. The API ID of the input argument.
- type: String. The data type of the argument (e.g., "STRING").
- isRequired: Boolean. Defines whether the argument is mandatory.
visibility: String. Defines the field's visibility ("READ_WRITE", "READ_ONLY", etc.).
isList: Boolean. Determines if the field can store multiple values.
isLocalized: Boolean. Determines if the field supports multiple locales.
isRequired: Boolean. Defines whether the field must always have a value.
isUnique: Boolean. Defines whether values must be unique across entries.
isHidden: Boolean. Determines if the field is hidden from the UI.
position: Integer. The position of the field in the schema.

#Update remote field

This example shows how to update an existing remote field.

client.updateRemoteField({
  environmentId: "<your-environment-id>",
  parentApiId: "Product",
  apiId: "externalStock",
  newConfig: {
    remoteFieldPath: "data.stock",
    type: "INTEGER"
  }
});

environmentId: String. The ID of the environment where the remote field exists.
parentApiId: String. The API ID of the parent model (e.g., "Product").
apiId: String. The unique API ID of the remote field to update.
newConfig: Object. The updated configuration settings for the remote field.
- remoteFieldPath: String. Specifies the new data path within the remote source.
- type: String. Defines the updated data type of the remote field (e.g., "INTEGER").

#Delete remote field

This example shows how to delete a remote field from a model.

client.deleteRemoteField({
  environmentId: "<your-environment-id>",
  parentApiId: "Product",
  apiId: "legacyPrice"
});

environmentId: String. The ID of the environment where the remote field exists.
parentApiId: String. The API ID of the parent model (e.g., "Product").
apiId: String. The unique API ID of the remote field to delete.

#Conditional visibility

We can modify the visibility conditions for a number of field types, such as: SIMPLE_FIELD, RELATIONAL_FIELD, ENUMERABLE_FIELD, UNION_FIELD and COMPONENT_FIELD.

The visibilityCondition property is available on the createXXXField and updateXXXField methods for these field types.

#Change visibility condition

This example shows how to change the visibility condition of a field with an enumeration or a boolean:

// For an enumerable baseField
client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "buildingMaterial", // apiId of the baseField (in this case an enumerable field)
    operator: FieldConditionOperator.Is,
    booleanValue: null,
    enumerationValues: ["plexiGlass"], // an array of apiId for the referenced enumerationValues
  },
});

// OR with a boolean baseField
client.updateSimpleField({
  apiId: "conditionalFieldTwo",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "isMobileApp", // apiId of the baseField (in this case a boolean field)
    operator: FieldConditionOperator.Is,
    booleanValue: true,
    enumerationValues: null,
  },
});

apiId: String. The unique API ID of the simple field to update.
parentApiId: String. The API ID of the parent model to which the simple field belongs.
visibilityCondition: Object. Defines the condition that determines when this field should be visible. Contains the following properties:
- baseField: String. The API ID of the base field that triggers visibility.
  - For enumerations: The base field must be an enumerable field.
  - For booleans: The base field must be a boolean field.
- operator: FieldConditionOperator. The operator used to evaluate the visibility condition. Example: "Is".
- booleanValue: Boolean (Nullable). Specifies the value to trigger visibility if the base field is boolean. Set to null if the base field is an enumerable.
- enumerationValues: Array (Nullable). An array of API IDs representing the enumeration values that trigger visibility if the base field is enumerable. Set to null if the base field is boolean.

#Remove visibility condition

This example shows how to remove the visibility condition of a field.

client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: null,
});

apiId: String. The unique API ID of the simple field to update.
parentApiId: String. The API ID of the parent model to which the simple field belongs.
visibilityCondition: Nullable. If Null, no visibility condition is applied and the field is always visible.