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.

Swift:

// Create a group.
let group = KiiGroup(name: "myGroup")

do{
  // Save the group on the server.
  try group.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Get the reference URI and ID of the group.
let groupUri = group.objectURI
let groupID = group.groupID

// Create a group.
let group = KiiGroup(name: "myGroup")

// Save the group on the server.
group.save { (group : KiiGroup?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Get the reference URI and ID of the group.
  let groupUri = group!.objectURI
  let groupID = group!.groupID
}

Objective-C:

NSError *error;
NSString *groupName = @"myGroup";

// Create a group.
KiiGroup *group = [KiiGroup groupWithName:groupName];

// Save the group on the server.
[group saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Get the reference URI and ID of the group.
NSString *groupUri = [group objectURI];
NSString *groupID = [group groupID];

NSError *error;
NSString *groupName = @"myGroup";

// Create a group.
KiiGroup *group = [KiiGroup groupWithName:groupName];

// Save the group on the server.
[group saveWithBlock:^(KiiGroup *group, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }

  // Get the reference URI and ID of the group.
  NSString *groupUri = [group objectURI];
  NSString *groupID = [group groupID];
}];

The basic steps for group creation are as follows:

Create a KiiGroup instance with the KiiGroup(name:) 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 groupID() 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:

Swift:

// Create a group and set a group member.
let group = KiiGroup(name: "myGroup", andMembers: [KiiUser(id: "User ID of a member")])

do{
  // Save the group on the server.
  try group.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}

// Get the reference URI and ID of the group.
let groupUri = group.objectURI
let groupID = group.groupID

// Create a group and set a group member.
let group = KiiGroup(name: "myGroup", andMembers: [KiiUser(id: "User ID of a member")])

// Save the group on the server.
group.save { (group : KiiGroup?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Get the reference URI and ID of the group.
  let groupUri = group!.objectURI
  let groupID = group!.groupID
}

Objective-C:

NSError *error;
NSString *groupName = @"myGroup";

// Set a group member.
NSArray *members = @[KiiUser.userWithID("User ID of a member")];

// Create a group.
KiiGroup *group = [KiiGroup groupWithName:groupName
                               andMembers:members];

// Save the group on the server.
[group saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}

// Get the reference URI and ID of the group.
NSString *groupUri = [group objectURI];
NSString *groupID = [group groupID];

NSError *error;
NSString *groupName = @"myGroup";

// Set a group member.
NSArray *members = @[KiiUser.userWithID("User ID of a member")];

// Create a group.
KiiGroup *group = [KiiGroup groupWithName:groupName
                               andMembers:members];

// Save the group on the server.
[group saveWithBlock:^(KiiGroup *group, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }

  // Get the reference URI and ID of the group.
  NSString *groupUri = [group objectURI];
  NSString *groupID = [group groupID];
}];

Set the group members in the second argument.

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.

Swift:

// This example assumes that users have a custom attribute "userSequence".

do{
  // Create a group ID with the attribute.
  let groupID : String = "my-group-" + KiiUser.current()!.userID!

  // Create and save a group on the server.
  let group = try KiiGroup.registerSynchronous(withID: groupID, name: "myGroup", members: [KiiUser(id: "User ID of a member")])

  // Get the reference URI of the group.
  let groupUri = group.objectURI
}catch (let error as NSError){
  // Handle the error.
  return
}

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
let groupID : String = "my-group-" + KiiUser.current()!.userID!

// Create and save a group on the server.
KiiGroup.register(withID: groupID, name: "myGroup", members: [KiiUser(id: "User ID of a member")]) { (group : KiiGroup?, error : Error?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Get the reference URI of the group.
  let groupUri = group!.objectURI
}

Objective-C:

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
NSString *userShortID = [[KiiUser currentUser] getObjectForKey:@"userSequence"];
NSString *groupID = [@"my-group-" stringByAppendingString:userShortID];
NSString *groupName = @"myGroup";
NSArray *members = @[KiiUser.userWithID("User ID of a member")];
NSError *error = nil;

// Create and save a group on the server.
KiiGroup *group = [KiiGroup registerGroupSynchronousWithID:groupID
                                                      name:groupName
                                                   members:nil
                                                     error:&error];
if (error != nil) {
  // Handle the error.
}

// Get the reference URI of the group.
NSString *groupUri = [group objectURI];

// This example assumes that users have a custom attribute "userSequence".
// Create a group ID with the attribute.
NSString *userShortID = [[KiiUser currentUser] getObjectForKey:@"userSequence"];
NSString *groupID = [@"my-group-" stringByAppendingString:userShortID];
NSString *groupName = @"myGroup";
NSArray *members = @[KiiUser.userWithID("User ID of a member")];

// Create and save a group on the server.
KiiGroup *group =
  [KiiGroup registerGroupWithID:groupID
                           name:groupName
                        members:nil
                          block:^(KiiGroup* group, NSError* error) {
      if (error != nil) {
        // Handle the error.
        return;
      }

      // Get the reference URI of the group.
      NSString groupUri = group.objectURI;
}];

We use the register(withID:name:members:_:) 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 register(withID:name:members:_:) method.