GlobalFields
GlobalFields
A global field is a reusable field, or group of fields, that you define once and use in any content type of the stack. Use this class to
- list the global fields of a stack and read one of them
- create, update, and delete a global field, including nested global fields
- export, import, and restore a global field
stack.globalField("<GLOBAL_FIELD_UID>") returns a GlobalField for one global field. The call takes one argument:
| Name | Type | Description |
|---|---|---|
| globalFieldUid | String | UID of the global field. Leave it out to work with all global fields of the stack. |
GlobalField has no public constructor.
addHeader
addHeader adds one header to every later request from this global field object, including the api_version header for nested global fields.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header, such as api_version or branch. |
| value (required) | String | Value of the header, such as 3.2. |
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation.
- A null key or value makes execute() throw IllegalArgumentException on later requests. Retrofit rejects a header map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- A key that equals api_version, in any letter case, sets the api_version value of this object. The SDK keeps that value apart from the header map and adds it to every request as api_version. A later call replaces it.
- Any other key goes into the header map of this object. The new value replaces a header with the same name.
- Every request method of this object sends both. The stack and other global field objects do not see them.
- removeHeader removes a header from the map but not the api_version value.
Example
Basic usage: read a nested global field with api_version 3.2
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchNestedGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>")
.addHeader("api_version", "3.2");
Response<ResponseBody> response = globalField.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addHeaders
addHeaders adds several headers to every later request from this global field object.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Header names mapped to their values. |
Returns: GlobalField. The same global field, for chaining.
Validation
- Throws NullPointerException if headers is null, because the SDK reads every pair from the map.
- A null key or value in the map makes execute() throw IllegalArgumentException on later requests. Retrofit rejects a header map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- When the map holds the key api_version, written exactly so, addHeaders sets the api_version value of this object and removes that key from your map. Other spellings, such as API_VERSION, go into the header map as ordinary headers.
- Copies every other pair into the header map of this object. Each new value replaces a header with the same name.
- Every request method of this object sends the headers and the api_version value.
Example
Basic usage: add a branch and the api_version header
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class AddGlobalFieldHeaders {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, String> headers = new HashMap<>();
headers.put("branch", "<BRANCH>");
headers.put("api_version", "3.2");
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField()
.addHeaders(headers);
// headers no longer holds api_version here
Response<ResponseBody> response = globalField.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParam
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter, such as include_count. |
| value (required) | Object | Value of the parameter. The SDK sends its toString() form. |
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation.
- A null key or value makes execute() throw IllegalArgumentException on a later find or fetch request. Retrofit rejects a query map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Puts the parameter into the query parameter map of this object. The new value replaces a parameter with the same name.
- Only find and fetch send the map. The parameter stays until you call removeParam.
Example
Basic usage: list global fields with a count and the content types that use them
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindGlobalFieldsWithCount {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField()
.addParam("include_count", true)
.addParam("include_content_types", true);
Response<ResponseBody> response = globalField.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}addParams
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Parameter names mapped to their values. |
Returns: GlobalField. The same global field, for chaining.
Validation
- Throws NullPointerException if params is null, because the SDK copies every pair from the map.
- A null key or value in the map makes execute() throw IllegalArgumentException on a later find or fetch request. Retrofit rejects a query map that holds null.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Copies every pair into the query parameter map of this object. Each new value replaces a parameter with the same name.
- Only find and fetch send the map.
Example
Basic usage: read a global field with its schema and the content types that use it
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
import java.util.HashMap;
public class FetchGlobalFieldWithParams {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
HashMap<String, Object> params = new HashMap<>();
params.put("include_global_field_schema", true);
params.put("include_content_types", true);
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>")
.addParams(params);
Response<ResponseBody> response = globalField.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}create
create creates a global field in the stack from the schema you send.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the global field under a global_field key. |
| requestBody.global_field.title (required) | String | Name of the global field. |
| requestBody.global_field.uid (required) | String | UID of the global field, unique in the stack. |
| requestBody.global_field.description | String | Description of the global field. |
| requestBody.global_field.schema (required) | JSONArray | Field definitions of the global field. |
Returns: Call<ResponseBody>. The request for the new global field, sent when you call execute().
Validation
- There is no client-side validation of the body.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Create a global field request (POST /global_fields) with requestBody as the JSON body.
- create sends no query parameters. Values from addParam do not reach this request.
- Only the stack owner, administrators, and developers can create global fields, as Create a global field states.
- A nested global field holds a field whose data_type is global_field. That field names the inner global field in reference_to.
- For a nested global field, set api_version to 3.2 with addHeader.
Example
Basic usage: create a global field with one text field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").globalField();
JSONObject field = new JSONObject();
field.put("display_name", "Meta Title");
field.put("uid", "meta_title");
field.put("data_type", "text");
JSONArray schema = new JSONArray();
schema.add(field);
JSONObject details = new JSONObject();
details.put("title", "docs-test-seo");
details.put("uid", "docs_test_seo");
details.put("description", "SEO fields");
details.put("schema", schema);
JSONObject body = new JSONObject();
body.put("global_field", details);
Response<ResponseBody> response = globalField.create(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Nested global field: include another global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class CreateNestedGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField()
.addHeader("api_version", "3.2");
JSONObject inner = new JSONObject();
inner.put("display_name", "SEO");
inner.put("uid", "seo");
inner.put("data_type", "global_field");
inner.put("reference_to", "<GLOBAL_FIELD_UID>");
JSONArray schema = new JSONArray();
schema.add(inner);
JSONObject details = new JSONObject();
details.put("title", "docs-test-page-meta");
details.put("uid", "docs_test_page_meta");
details.put("schema", schema);
JSONObject body = new JSONObject();
body.put("global_field", details);
Response<ResponseBody> response = globalField.create(body).execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}delete
delete deletes a global field, even when content types use it.
Returns: Call<ResponseBody>. The request for the global field deletion, sent when you call execute().
Validation
- Throws IllegalAccessError if the global field has no UID, as after stack.globalField(), because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Delete global field request (DELETE /global_fields/{global_field_uid}?force=true).
- delete sends no other query parameter. Values from addParam do not reach this request.
Example
Basic usage: delete a global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class DeleteGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>");
Response<ResponseBody> response = globalField.delete().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Edge case: a global field object without a UID
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
public class DeleteGlobalFieldWithoutUid {
public static void main(String[] args) {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").globalField();
try {
globalField.delete();
} catch (IllegalAccessError e) {
// Fires before any request, because stack.globalField() holds no UID
System.out.println("Pass a UID to stack.globalField(): " + e.getMessage());
}
}
}export
export exports a global field and its schema as JSON.
Returns: Call<ResponseBody>. The request for the exported global field, sent when you call execute().
Validation
- Throws IllegalAccessError if the global field has no UID, as after stack.globalField(), because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Export a global field request (GET /global_fields/{global_field_uid}/export).
- export sends no query parameters. Values from addParam do not reach this request.
- The SDK does not save the response to a file. Write response.body().string() to a file yourself.
Example
Basic usage: export a global field to a file
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.FileWriter;
import java.io.IOException;
public class ExportGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>");
Response<ResponseBody> response = globalField.export().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
try (FileWriter writer = new FileWriter("<FILE_PATH>")) {
writer.write(response.body().string());
}
}
}fetch
fetch reads one global field with its schema.
Returns: Call<ResponseBody>. The request for the global field, sent when you call execute().
Validation
- Throws IllegalAccessError if the global field has no UID, as after stack.globalField(), because the request path needs the UID.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get a single global field request (GET /global_fields/{global_field_uid}).
- The request sends the query parameters of this object. The API accepts version, include_global_field_schema, include_global_fields, include_content_types, deleted, and include_branch.
- The request sends the api_version value when you set one with addHeader.
Example
Basic usage: read a global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>");
Response<ResponseBody> response = globalField.fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: read version 2 of a global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FetchGlobalFieldVersion {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>")
.addParam("version", 2);
Response<ResponseBody> response = globalField.fetch().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}find
find lists the global fields of the stack.
Returns: Call<ResponseBody>. The request for all global fields in the stack, sent when you call execute().
Validation
- There is no client-side validation.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Get all global fields request (GET /global_fields).
- The request sends the query parameters of this object. The API accepts the following five kinds:
- include_count adds the total number of global fields.
- include_global_field_schema adds the schema of nested global fields.
- include_content_types and include_global_fields add where each global field is in use.
- deleted set to true returns only deleted global fields.
- include_branch adds the _branch key.
- The request sends the api_version value when you set one with addHeader.
- find ignores the global field UID, so it works the same with or without one.
Example
Basic usage: list the global fields
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindGlobalFields {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").globalField();
Response<ResponseBody> response = globalField.find().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}Query parameters: list deleted global fields
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindDeletedGlobalFields {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField()
.addParam("deleted", true);
Response<ResponseBody> response = globalField.find().execute();
if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
System.out.println(response.body().string());
}
}Error handling: read the error code
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.models.Error;
import com.contentstack.cms.stack.GlobalField;
import com.google.gson.Gson;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class FindGlobalFieldsErrorCode {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").globalField();
try {
Response<ResponseBody> response = globalField.find().execute();
if (!response.isSuccessful()) {
// Read the error body once and map it to the SDK's Error model
Error error = new Gson().fromJson(response.errorBody().string(), Error.class);
System.out.println("API error " + error.getErrorCode() + ": " + error.getErrorMessage());
return;
}
System.out.println(response.body().string());
} catch (IOException e) {
// Thrown only when the request does not complete, such as a timeout
System.out.println("Request did not complete: " + e.getMessage());
}
}
}imports
imports sends a global field schema to the Import a global field request of the stack.
| Name | Type | Description |
|---|---|---|
| body (required) | JSONObject | The global field schema to import. |
Returns: Call<ResponseBody>. The request for the global field import, sent when you call execute().
Validation
- There is no client-side validation of the body.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one POST /global_fields/import request, the path of Import a global field.
- The SDK sends body as JSON text with the header Content-Type: multipart/form-data. It does not upload a file. Import a global field describes a JSON file uploaded in a form-data field named global_field.
- imports sends no query parameters. Values from addParam do not reach this request.
- The request sends the api_version value when you set one with addHeader.
Example
Basic usage: send a global field schema to the import request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class ImportGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").globalField();
JSONObject field = new JSONObject();
field.put("display_name", "Meta Title");
field.put("uid", "meta_title");
field.put("data_type", "text");
JSONArray schema = new JSONArray();
schema.add(field);
JSONObject body = new JSONObject();
body.put("title", "docs-test-imported-seo");
body.put("uid", "docs_test_imported_seo");
body.put("schema", schema);
Response<ResponseBody> response = globalField.imports(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}removeHeader
removeHeader removes one header from this global field object, so that later requests no longer send it.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the header to remove. |
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation. A key that the object does not hold changes nothing and does not throw.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Removes the key from the header map of this object, including a header that the object copied from the stack, such as branch.
- removeHeader("api_version") has no effect on the api_version value that addHeader or addHeaders set, because the SDK keeps that value outside the header map. Every later request still sends it. Create a new object with stack.globalField() for requests without it.
Example
Basic usage: read a global field from the stack branch again
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveGlobalFieldHeader {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>")
.addHeader("x-custom-trace", "docs-test-trace");
Response<ResponseBody> response = globalField.removeHeader("x-custom-trace").fetch().execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}removeParam
| Name | Type | Description |
|---|---|---|
| key (required) | String | Name of the query parameter to remove. |
Returns: GlobalField. The same global field, for chaining.
Validation
- There is no client-side validation. A key that the object does not hold changes nothing and does not throw.
- An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Removes the key from the map that addParam and addParams fill.
- To remove a header, use removeHeader.
Example
Basic usage: list global fields without the count after one counted request
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import retrofit2.Response;
import java.io.IOException;
public class RemoveGlobalFieldParam {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField()
.addParam("include_count", true);
Response<ResponseBody> counted = globalField.find().execute();
if (!counted.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + counted.code() + " " + counted.errorBody().string());
return;
}
System.out.println(counted.body().string());
Response<ResponseBody> plain = globalField.removeParam("include_count").find().execute();
if (!plain.isSuccessful()) { System.out.println(plain.errorBody().string()); return; }
System.out.println(plain.body().string());
}
}restore
restore sends a request to restore the schema of a deleted global field.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the global field under a global_field key. |
Returns: Call<ResponseBody>. The request for the restored global field, sent when you call execute().
Validation
- Throws IllegalAccessError if the global field has no UID, as after stack.globalField(), because the request path needs the UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one PUT /global_fields/{global_field_uid}/restore request with requestBody as the JSON body.
- restore sends no query parameters. Values from addParam do not reach this request.
- The request sends the api_version value when you set one with addHeader.
- To find deleted global fields, call find with the deleted parameter set to true.
Example
Basic usage: restore a deleted global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class RestoreGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>")
.addHeader("api_version", "3.2");
JSONObject field = new JSONObject();
field.put("display_name", "Meta Title");
field.put("uid", "meta_title");
field.put("data_type", "text");
JSONArray schema = new JSONArray();
schema.add(field);
JSONObject details = new JSONObject();
details.put("title", "docs-test-seo");
details.put("uid", "<GLOBAL_FIELD_UID>");
details.put("schema", schema);
JSONObject body = new JSONObject();
body.put("global_field", details);
Response<ResponseBody> response = globalField.restore(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}update
update replaces the schema of an existing global field.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Request body with the global field under a global_field key. |
| requestBody.global_field.title (required) | String | Name of the global field. |
| requestBody.global_field.schema (required) | JSONArray | The complete, updated field definitions. |
Returns: Call<ResponseBody>. The request for the updated global field, sent when you call execute().
Validation
- Throws IllegalAccessError if the global field has no UID, as after stack.globalField(), because the request path needs the UID.
- A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
- An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call builds one Update a global field request (PUT /global_fields/{global_field_uid}) with requestBody as the JSON body.
- update sends no query parameters. Values from addParam do not reach this request.
- For a nested global field, set api_version to 3.2 with addHeader.
Example
Basic usage: add a description field to a global field
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.GlobalField;
import okhttp3.ResponseBody;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import retrofit2.Response;
import java.io.IOException;
public class UpdateGlobalField {
public static void main(String[] args) throws IOException {
Contentstack client = new Contentstack.Builder().build();
GlobalField globalField = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.globalField("<GLOBAL_FIELD_UID>");
JSONObject metaTitle = new JSONObject();
metaTitle.put("display_name", "Meta Title");
metaTitle.put("uid", "meta_title");
metaTitle.put("data_type", "text");
JSONObject metaDescription = new JSONObject();
metaDescription.put("display_name", "Meta Description");
metaDescription.put("uid", "meta_description");
metaDescription.put("data_type", "text");
// Send every field of the global field, not only the new one
JSONArray schema = new JSONArray();
schema.add(metaTitle);
schema.add(metaDescription);
JSONObject details = new JSONObject();
details.put("title", "docs-test-seo");
details.put("schema", schema);
JSONObject body = new JSONObject();
body.put("global_field", details);
Response<ResponseBody> response = globalField.update(body).execute();
if (!response.isSuccessful()) {
// The API rejected the request. The body holds error_message, error_code and errors.
System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
return;
}
System.out.println(response.body().string());
}
}