Organization

View as Markdown

Organization

Organization builds requests against one Contentstack organization, the top level that holds stacks and users. Use this class to

  • list your organizations, or read the details, roles and stacks of one
  • invite users, remove them, and manage pending invitations
  • transfer the ownership of the organization
  • read the audit log of the organization

Get an object with the organization method of Contentstack, after login or an Open Authorization (OAuth) sign-in.

addHeader

addHeader adds one header that every request of this organization object sends.

NameTypeDescription
key (required)String

Name of the header.

Default: Not applicable
value (required)String

Value of the header.

Default: Not applicable

Returns: Organization. The same organization, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value does not throw here. execute() on the next request throws IllegalArgumentException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Every request method of this object sends the header, including inviteUser and logsDetails.
  • The header stays on the object for later requests. No public method removes it.
  • A second call with the same key replaces the value.

Example

Basic usage: send a header with a request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddOrganizationHeader {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.addHeader("x-request-id", "docs-test-1").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 every entry of a map as a header that every request of this organization object sends.

NameTypeDescription
headers (required)HashMap<String, String>

Header names and values to add.

Default: Not applicable

Returns: Organization. The same organization, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value does not throw here. execute() on the next request throws IllegalArgumentException.
  • A null map throws NullPointerException at the call.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • addHeaders copies the entries into the headers of this object. A later change to your map does not change them.
  • An entry replaces an earlier header with the same key.
  • Every request method of this object sends the headers.

Example

Basic usage: send two headers

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.HashMap;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddOrganizationHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        HashMap<String, String> headers = new HashMap<String, String>();
        headers.put("x-request-id", "docs-test-2");
        headers.put("x-team", "content-ops");


        Response<ResponseBody> response = organization.addHeaders(headers).stacks().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

addParam adds one query parameter to the requests of this organization object that accept query parameters.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter, sent as text.

Default: Not applicable

Returns: Organization. The same organization, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value does not throw here. execute() on the next request that sends the query parameters throws IllegalArgumentException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • find, fetch, roles, stacks and allInvitations send the query parameters. The other request methods do not.
  • The SDK sends the value as text, so true and 10 become true and 10 in the URL.
  • The parameter stays on the object and goes with every later request that sends query parameters. Use a new object from client.organization(...) for a request without it.
  • A second call with the same key replaces the value.

Example

Basic usage: count the stacks

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class CountOrganizationStacks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.addParam("include_count", true).stacks().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

addParams adds every entry of a map as a query parameter of the requests of this organization object that accept query parameters.

NameTypeDescription
params (required)HashMap<String, Object>

Query parameter names and values to add.

Default: Not applicable

Returns: Organization. The same organization, for chaining.

Validation

  • There is no client-side validation.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.
  • A null key or value does not throw here. execute() on the next request that sends the query parameters throws IllegalArgumentException.
  • A null map throws NullPointerException at the call.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • find, fetch, roles, stacks and allInvitations send the query parameters. The other request methods do not.
  • addParams copies the entries. A later change to your map does not change them.
  • An entry replaces an earlier parameter with the same key.

Example

Basic usage: page through the roles

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.HashMap;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class PageOrganizationRoles {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("limit", 10);
        params.put("skip", 10);
        params.put("include_count", true);


        Response<ResponseBody> response = organization.addParams(params).roles().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());
    }
}

allInvitations

allInvitations builds the request that lists the invitations that users of this organization sent.

NameTypeDescription
limitint

Maximum number of items to return.

Default: API default
skipint

Number of items to skip.

Default: API default
ascString

Field UID to sort by in ascending order.

Default: API default
descString

Field UID to sort by in descending order.

Default: API default
include_countboolean

true adds the total count to the response.

Default: API default
include_rolesboolean

true adds the roles of each invited user.

Default: API default
include_invited_byboolean

true adds the user who sent each invitation.

Default: API default
include_user_detailsboolean

true adds whether each user has two-factor authentication on.

Default: API default
typeaheadString

Text that filters invitations by email address.

Default: API default

Returns: Call<ResponseBody>. The request for the organization's invitations, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, 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 execute() sends one Get all Organization invitations request (GET /organizations/{organization_uid}/share), with the headers and query parameters of this object.
  • The response body is the raw JSON of the API. Each invitation carries a UID that resendInvitation takes.

Example

Basic usage: list the invitations

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListInvitations {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.allInvitations().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());
    }
}

All parameters: include roles, inviters and user details

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListInvitationDetails {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization
                .addParam("limit", 50)
                .addParam("skip", 0)
                .addParam("desc", "created_at")
                .addParam("include_count", true)
                .addParam("include_roles", true)
                .addParam("include_invited_by", true)
                .addParam("include_user_details", true)
                .addParam("typeahead", "example.com")
                .allInvitations()
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

fetch

fetch builds the request that reads the details of this organization.

NameTypeDescription
include_planboolean

true adds the plan details to the response.

Default: API default

Returns: Call<ResponseBody>. The request for the organization, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, 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 execute() sends one Get a single Organization request (GET /organizations/{organization_uid}), with the headers and query parameters of this object.
  • The response body is the raw JSON of the API, with the details under an organization key.

Example

Basic usage: read one organization

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchOrganization {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.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());
    }
}

All parameters: include the plan details

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchOrganizationPlan {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.addParam("include_plan", true).fetch().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

find

find builds the request that lists every organization the signed-in user belongs to, in the order of their creation.

NameTypeDescription
limitint

Maximum number of items to return.

Default: API default
skipint

Number of items to skip.

Default: API default
ascString

Field UID to sort by in ascending order.

Default: API default
descString

Field UID to sort by in descending order.

Default: API default
include_countboolean

true adds the total count to the response.

Default: API default
typeaheadString

Text that filters organizations by name.

Default: API default

Returns: Call<ResponseBody>. The request for all organizations of the user, sent when you call execute().

Validation

  • There is no client-side validation. find needs no organization UID, so it works on any Organization object.
  • 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 execute() sends one Get all Organizations request (GET /organizations), with the headers and query parameters of this object.
  • The response body is the raw JSON of the API, with the organizations in an organizations array.
  • find does not page through the results. Set limit and skip with addParam, and send one request per page.

Example

Basic usage: list your organizations

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListOrganizations {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization();

        Response<ResponseBody> response = organization.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());
    }
}

All parameters: page and search the list

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class SearchOrganizations {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization();

        Response<ResponseBody> response = organization
                .addParam("limit", 10)
                .addParam("skip", 0)
                .addParam("asc", "created_at")
                .addParam("include_count", true)
                .addParam("typeahead", "marketing")
                .find()
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

inviteUser

inviteUser builds the request that sends invitations to join this organization, with a product role and optional stack roles for each user.

NameTypeDescription
body (required)JSONObject

Request body with the invitations under a share key.

Default: Not applicable
body.share.users (required)Object

Maps each email address to a list of product role UIDs.

Default: Not applicable
body.share.stacksObject

Maps each email address to stack API keys and their stack role UIDs.

Default: Not applicable
body.share.messageString

Message in the invitation email.

Default: Not applicable

Returns: Call<ResponseBody>. The request that invites the users, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
  • inviteUser does not check body. A null body makes execute() throw IllegalArgumentException.
  • 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 execute() sends one Add users to Organization request (POST /organizations/{organization_uid}/share) with body as the JSON body.
  • inviteUser sends the headers of this object but not its query parameters.
  • Only the owner or an admin of the organization can invite users, as the API reference states.
  • Get the product role UIDs from roles.

Example

Basic usage: invite an author with a stack role

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.Arrays;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class InviteAuthor {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        JSONObject users = new JSONObject();
        users.put("[email protected]", Arrays.asList("<ROLE_UID>"));

        JSONObject stackRoles = new JSONObject();
        stackRoles.put("<API_KEY>", Arrays.asList("<ROLE_UID>"));
        JSONObject stacks = new JSONObject();
        stacks.put("[email protected]", stackRoles);

        JSONObject share = new JSONObject();
        share.put("users", users);
        share.put("stacks", stacks);
        share.put("message", "Welcome to the content team");
        JSONObject body = new JSONObject();
        body.put("share", share);


        Response<ResponseBody> response = organization.inviteUser(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());
    }
}

logItem

logItem builds the request that reads one item of the audit log of this organization.

NameTypeDescription
logUid (required)String

UID of the audit log item.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the audit log item, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
  • logItem does not check logUid. A null value makes execute() throw IllegalArgumentException.
  • 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 execute() sends one Get organization log item request (GET /organizations/{organization_uid}/logs/{log_uid}).
  • logItem sends the headers of this object but not its query parameters.
  • Get the log item UID from logsDetails.

Example

Basic usage: read one log item

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ReadOrganizationLogItem {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        String logUid = args[0]; // a log item UID from logsDetails


        Response<ResponseBody> response = organization.logItem(logUid).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());
    }
}

logsDetails

logsDetails builds the request that reads the audit log of this organization.

Returns: Call<ResponseBody>. The request for the organization's audit log, sent when you call execute().

Validation

  • logsDetails does not check the organization UID itself. On an organization without a UID, execute() throws IllegalArgumentException, 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 execute() sends one Get organization log details request (GET /organizations/{organization_uid}/logs).
  • logsDetails sends the headers of this object but not its query parameters.
  • The API returns the first 25 log items, as the API reference states.
  • Read one item in full with logItem.

Limitations

  • Does not send limit, skip or any other query parameter, so it returns only the first 25 log items. The Java Management SDK has no way to read later pages of the organization log in 1.16.0.

Example

Basic usage: read the audit log

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ReadOrganizationLog {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.logsDetails().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());
    }
}

removeUsers

removeUsers builds the request that removes users from this organization by email address.

NameTypeDescription
body (required)JSONObject

Request body with the users to remove.

Default: Not applicable
body.emails (required)List of String

Email addresses of the users to remove.

Default: Not applicable

Returns: Call<ResponseBody>. The request that removes the users, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
  • removeUsers does not check body. A null body makes execute() throw IllegalArgumentException.
  • 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

Warning The users lose access to the organization and its stacks when the request succeeds. To undo it, invite them again with inviteUser.

  • One execute() sends one Remove users from organization request (DELETE /organizations/{organization_uid}/share) with body as the JSON body.
  • removeUsers sends the headers of this object but not its query parameters.
  • Only the owner or an admin of the organization can remove users, as the API reference states.

Example

Basic usage: remove two users

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import java.util.Arrays;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class RemoveOrganizationUsers {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        JSONObject body = new JSONObject();
        body.put("emails", Arrays.asList("[email protected]", "[email protected]"));


        Response<ResponseBody> response = organization.removeUsers(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());
    }
}

resendInvitation

resendInvitation builds the request that sends a pending organization invitation again.

NameTypeDescription
shareUid (required)String

UID of the pending invitation.

Default: Not applicable

Returns: Call<ResponseBody>. The request that resends the invitation, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
  • resendInvitation does not check shareUid. A null value makes execute() throw IllegalArgumentException.
  • 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 execute() sends one Resend pending Organization invitation request (GET /organizations/{organization_uid}/share/{share_uid}/resend_invitation).
  • resendInvitation sends the headers of this object but not its query parameters.
  • Only the owner or an admin of the organization can resend an invitation, as the API reference states.
  • Get the invitation UID from allInvitations.

Example

Basic usage: resend one invitation

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ResendInvitation {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        String shareUid = args[0]; // the invitation UID from allInvitations


        Response<ResponseBody> response = organization.resendInvitation(shareUid).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());
    }
}

roles

roles builds the request that lists the roles that users hold in this organization.

NameTypeDescription
limitint

Maximum number of items to return.

Default: API default
skipint

Number of items to skip.

Default: API default
ascString

Field UID to sort by in ascending order.

Default: API default
descString

Field UID to sort by in descending order.

Default: API default
include_countboolean

true adds the total count to the response.

Default: API default
include_stack_rolesboolean

true adds the stack-level roles to the response.

Default: API default

Returns: Call<ResponseBody>. The request for the organization's roles, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, 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 execute() sends one Get all roles in an Organization request (GET /organizations/{organization_uid}/roles), with the headers and query parameters of this object.
  • The response body is the raw JSON of the API.
  • Use a role UID from the response in the body of inviteUser.

Example

Basic usage: list the roles

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListOrganizationRoles {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.roles().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());
    }
}

All parameters: include stack roles and the count

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListAllRoles {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization
                .addParam("limit", 20)
                .addParam("skip", 0)
                .addParam("desc", "created_at")
                .addParam("include_count", true)
                .addParam("include_stack_roles", true)
                .roles()
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

stacks

stacks builds the request that lists the stacks in this organization.

NameTypeDescription
limitint

Maximum number of items to return.

Default: API default
skipint

Number of items to skip.

Default: API default
ascString

Field UID to sort by in ascending order.

Default: API default
descString

Field UID to sort by in descending order.

Default: API default
include_countboolean

true adds the total count to the response.

Default: API default
typeaheadString

Text that filters stacks by name.

Default: API default

Returns: Call<ResponseBody>. The request for the organization's stacks, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, 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 execute() sends one Get all stacks in an Organization request (GET /organizations/{organization_uid}/stacks), with the headers and query parameters of this object.
  • The response body is the raw JSON of the API.

Example

Basic usage: list the stacks

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ListOrganizationStacks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization.stacks().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());
    }
}

All parameters: search the stacks by name

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class SearchOrganizationStacks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");

        Response<ResponseBody> response = organization
                .addParam("limit", 25)
                .addParam("skip", 25)
                .addParam("asc", "name")
                .addParam("include_count", true)
                .addParam("typeahead", "blog")
                .stacks()
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

transferOwnership

transferOwnership builds the request that offers the ownership of this organization to another user by email.

NameTypeDescription
body (required)JSONObject

Request body with the new owner.

Default: Not applicable
body.transfer_to (required)String

Email address of the new owner.

Default: Not applicable

Returns: Call<ResponseBody>. The request that starts the ownership transfer, sent when you call execute().

Validation

  • Throws NullPointerException if the organization has no UID, as after client.organization() without an argument, because the request path needs the UID.
  • transferOwnership does not check body. A null body makes execute() throw IllegalArgumentException.
  • 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

Warning When the new owner accepts the invitation, you lose ownership of the organization. Only the new owner can transfer it back.

  • One execute() sends one Transfer Organization ownership request (POST /organizations/{organization_uid}/transfer-ownership) with body as the JSON body.
  • transferOwnership sends the headers of this object but not its query parameters.
  • The API sends an email invitation to the user. The ownership moves when that user accepts it, as the API reference states.

Example

Basic usage: offer ownership to a colleague

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.organization.Organization;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class TransferOwnership {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        client.login("<EMAIL>", "<PASSWORD>");
        Organization organization = client.organization("<ORGANIZATION_UID>");
        JSONObject body = new JSONObject();
        body.put("transfer_to", "[email protected]");


        Response<ResponseBody> response = organization.transferOwnership(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());
    }
}