Creating a Group

Any authenticated user can create a new group. The creator of a group becomes the group owner by default.

The following options can be combined for creating a group.

Whether the group ID is automatically assigned by Kii Cloud or specified on the client
Whether group members are specified or not when the group is created

This topic contains sample code for creating a group in the following three combinations of the options. Code parameters enable these combinations.

Creating a group with automatic ID assignment
Creating a group with members
Creating a group with a specified ID

Creating a group with automatic ID assignment

The following sample code shows how to create a group.

var groupName = "myGroup";

// Create a group.
var group = KiiGroup.groupWithName(groupName);

// Save the group on the server.
group.save().then(
  function(theGroup) {
    // Get the reference URI and ID of the group.
    var groupUri = theGroup.objectURI();
    var groupID = theGroup.getID();
  }
).catch(
  function(error) {
    var theGroup = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var groupName = "myGroup";

// Create a group.
var group = KiiGroup.groupWithName(groupName);

// Save the group on the server.
group.save({
  success: function(theGroup) {
    // Get the reference URI and ID of the group.
    var groupUri = theGroup.objectURI();
    var groupID = theGroup.getID();
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

The basic steps for group creation are as follows:

Create a KiiGroup instance with the groupWithName() method.
Register this KiiGroup instance with the save() method.

The group name can be up to 190 characters. There is no restriction on the characters you can use. The group name can duplicate with the existing ones. You cannot retrieve (reinstantiate) the existing group with its name; the group name is merely for debugging and displaying purposes.

After you create a group, you can get its URI and ID by executing the objectURI() and getID() methods. You can use them to retrieve the group later.

Creating a group with members

When you create a new group, you can also set its group members at the same time.

See the next sample code:

var groupName = "myGroup";
var members = [];

// Set a group member.
members.push(KiiUser.userWithID("User ID of a member"));

// Create a group.
var group = KiiGroup.groupWithNameAndMembers(groupName, members);

// Save the group on the server.
group.save().then(
  function(theGroup) {
    // Get the reference URI and ID of the group.
    var groupUri = theGroup.objectURI();
    var groupID = theGroup.getID();
  }
).catch(
  function(error) {
    var theGroup = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var groupName = "myGroup";
var members = [];

// Set a group member.
members.push(KiiUser.userWithID("User ID of a member"));

// Create a group.
var group = KiiGroup.groupWithNameAndMembers(groupName, members);

// Save the group on the server.
group.save({
  success: function(theGroup) {
    // Get the reference URI and ID of the group.
    var groupUri = theGroup.objectURI();
    var groupID = theGroup.getID();
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

Set the group members in the second argument of the groupWithNameAndMembers() method.

You can also add group members later.

Creating a group with a specified ID

In the previous sample code, the group ID is automatically assigned. You can also specify the group ID explicitly when you create the group.

The next sample is creating a new group, this time with its ID.

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
var userShortID = KiiUser.getCurrentUser().get("userSequence");
var groupId = "my-group-" + userShortID;
var groupName = "myGroup";

// Create and save a group on the server.
KiiGroup.registerGroupWithID(groupId, groupName, null).then(
  function(theGroup) {
    // Get the reference URI of the group.
    var groupUri = theGroup.objectURI();
  }
).catch(
  function(error) {
    var theGroup = error.target;
    var errorString = error.message;
    var addMembersArray = error.addMembersArray;
    // Handle the error.
  }
);

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
var userShortID = KiiUser.getCurrentUser().get("userSequence");
var groupId = "my-group-" + userShortID;
var groupName = "myGroup";

// Create and save a group on the server.
KiiGroup.registerGroupWithID(groupId, groupName, null, {
  success: function(theGroup) {
    // Get the reference URI of the group.
    var groupUri = theGroup.objectURI();
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

We use the registerGroupWithID() method for creating a group with its group ID. The group ID can contain alphanumeric (lower-case only), period (.), dash (-), and underscore (_). The maximum length of the group ID is 30 characters. You will get an error if you try to set a group ID that duplicates with the existing one.

In the above sample code, we are concatenating a unique value which represents a user with the prefix "my-group-" and using it as the group ID. This will allow spotting IDs of groups owned by a certain user. This naming method is useful, for instance, if you are managing Twitter-like followers with the group feature. The above sample code assumes that a short unique value such as a sequence number has been configured as a custom attribute. You cannot use the user ID as a part of the group ID because it would exceed the maximum length of 30 characters for the group ID.

You can also set the group members at the same time. Set the group members in the third argument of the registerGroupWithID() method.