Home

Welcome to the Groups Building Block wiki!

The Groups Building Block (Groups BB) is the service responsible for managing user groups in the Rokwire ecosystem. This Building Block allows users to create groups with each other and interact through forum posts, events, and polls.

API level documentation for this Building Block can be accessed by visiting https://api.rokwire.illinois.edu/gr/doc/ui/. This documentation conforms to the OpenAPI 3.0 standard. For the raw YAML documentation, you can visit https://api.rokwire.illinois.edu/gr/doc.

This Wiki provides an overview of the functionality included in the Groups Building Block. It includes the following sections:

• Groups
• Posts
• Integrations

Groups

Groups are the primary structure used in the Groups Building Block to represent a collection of users. New groups can be created by sending a request to the POST /api/groups endpoint. A list of available groups can be retrieved by making a request to the GET /api/groups endpoint with optional Category and Title filters.

Group Model

Groups contain the following data:

Name	Key	Type	Required	Description	Example
ID	id	string	true	The unique identifier generated by the system for this item.	fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75
Client ID	client_id	string	true	The ID of the client with which the group is associated	edu.illinois.rokwire
Category	category	string	true	A category that the group falls under	Community
Title	title	string	true	A unique title for the group to be displayed to users	Housing Students
Privacy	privacy	string	true	The privacy setting for the group. Can be public or private	public
Hidden For Search	hidden_for_search	boolean	true	Flag indicating whether the group should be hidden from all search results	false
Description	description	string	false	A description of the purpose of the group to be displayed to users	A group for students in campus housing
Image URL	image_url	string	false	A URL at which an image for the group can be accessed to display to users	https://example.com/groups/student-housing/image.png
Web URL	web_url	string	false	A URL for a website associated with the group to be displayed to users	https://example.com/groups/student-housing
Tags	tags	list (string)	false	A list of tags to be associated with the group	[University Housing, students, campus]
Membership Questions	membership_questions	list (string)	false	A list of questions to ask users when they request to join the group to be reviewed by admins	[What dorm do you live in?, What year are you?, What is your major?]
Members	members	list (Member)	true	The list of Members in the group
Date Created	date_created	DateTime	true	The time that this item was originally created	2022-06-01T12:21:06Z
Date Updated	date_updated	DateTime	false	The time that this item was last updated	2022-06-06T21:23:19Z
AuthMan Enabled	authman_enabled	boolean	true	Flag indicating the group is associated with an AuthMan group	false
AuthMan Enabled	authman_enabled	boolean	true	Flag indicating the group is associated with an AuthMan group	false
AuthMan Group	authman_group	string	false	The identifier of the associated AuthMan group. This should only be provided for groups where authman_enabled=true	example:authman:group:identifier
Only Admins Can Create Polls	only_admins_can_create_polls	boolean	true	Flag indicating only admins may create Polls in the group. All members can create polls if false	false
Can Join Automatically	can_join_automatically	boolean	true	Flag indicating that members can join automatically without admin approval	false
Block New Membership Requests	block_new_membership_requests	boolean	true	Flag indicating that new membership requests should be immediately rejected	false
Attendance Group	attendance_group	boolean	true	Flag indicating that the group is used for attendance purposes	false

Member Model

Members represent a member of a group. Members contain the following data:

Name	Key	Type	Required	Description	Example
ID	id	string	true	The unique identifier generated by the system for this item.	fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75
User ID	user_id	string	true	The Account ID of the member	cf8a2cc9-48cd-43b3-8003-e6f21c756db2
External ID	external_id	string	true	The External ID of the member	123456789
Name	name	string	true	The name of the member for display purposes	John Doe
Email	email	string	false	The email address of the member	[email protected]
Photo URL	photo_url	string	false	A URL where the member's profile photo can be accessed	https://example.com/users/cf8a2cc9-48cd-43b3-8003-e6f21c756db2/profile.png
Status	status	string	true	The current status of the member. Options are member, admin, pending, and rejected	member
Reject Reason	reject_reason	string	false	The reason the member was rejected by an admin to be displayed to the user	Expired membership
Member Answers	member_answers	list (string)	false	Member answers to the Membership Questions	[Main hall, Sophomore, English]
Date Created	date_created	DateTime	true	The time that this item was originally created	2022-06-01T12:21:06Z
Date Updated	date_updated	DateTime	false	The time that this item was last updated	2022-06-06T21:23:19Z
Date Attended	date_attended	DateTime	false	The time the member checked in for an Attendance Group	2022-06-01T12:21:06Z

Privacy

There are several settings that can be used to manage the privacy of a group when it is created.

• Privacy - "Public" groups are visible to all users, while users must search for the exact Title of the group to find a "private" group.
• Hidden For Search - This setting will make private groups invisible to users that are not members
• Can Join Automatically - This flag can be set to allow users to join the group automatically without requiring admin approval. If this is disabled, admins will receive a request to approve or reject new members when they attempt to join.

Joining

Joining a group involves the following steps:

1. Either select a public group from the list or find a private group by searching for it
2. Send a request to join using the POST /group/{id}/pending-members endpoint. This new member is added to the group with status=pending.
3. Check automatic approval/rejection
   1. If Can Join Automatically is true, the user is now a member
   2. If Block New Membership Requests is true, the user is rejected
4. Otherwise, admin actions
   1. Group admins are notified of the request to join
   2. Group admin approves or rejects the member request
5. The user is notified of their membership (status=member) or rejection (status=rejected)

Group Types

Managed Groups

Managed groups are groups that are associated with and managed by an external system through an External Integration. This means that rather than using the standard Joining process, group membership will be determined by the members of the associated group in the external system.

Attendance Groups

Attendance groups are groups intended to be used to take attendance. These groups may be created in advance of an event using a Managed Group. For Managed Groups, the member list will be pre-populated and the admins checking these members in can set the Date Attended to record that the member attended.

Posts

Posts can be sent to communicate with other members of the group. The default posts are visible to all members of the group, but posts may also be sent to specific members. A new post can be created by making a request to the POST /api/group/{id}/posts endpoint. The list of posts in a group can be retrieved by making a request to the GET /api/group/{id}/posts endpoint.

Post Model

Posts contain the following data:

Name	Key	Type	Required	Description	Example
ID	id	string	true	The unique identifier generated by the system for this item.	8a422ec3-75d2-4228-9f51-3eef37a38641
Client ID	client_id	string	true	The ID of the client with which the post is associated	edu.illinois.rokwire
Group ID	group_id	string	true	The ID of the group with which the post is associated	fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75
Parent ID	parent_id	string	false	The ID of parent post that this post is a reply to	b429760d-ce71-4dac-8e35-b2bf34f1b44e
Top Parent ID	top_parent_id	string	false	The ID of the original post in the thread that this post is in	44358427-bcb0-46d8-a55a-2ccbcd706986
Creator	creator	Creator	true	The Creator of this post
Subject	subject	string	true	The subject of the post	Move-in schedule
Body	body	string	true	The body of the post	Student housing locations will be open between 9:00 am and 8:00 pm CT on Jan 1 for new students to move in. Please plan to leave at least two hours to complete the move-in process.
Private	private	bool	true	Flag indicating that only members of the group can see the post	true
Use As Notification	use_as_notification	bool	true	Flag indicating that the post is intended to be used only as a notification	false
Is Abuse	is_abuse	bool	true	Flag indicating that the post has been reported for containing abusive content	false
Replies	replies	list (Post)	false	List of replies to this post. This list is constructed using the Parent ID
Image URL	image_url	string	false	URL of the image associated with the post	https://example.com/groups/student-housing/posts/8a422ec3-75d2-4228-9f51-3eef37a38641/image.png
To Member List	to_members	list (ToMember)	false	List of ToMembers indicating which group members can see this post
Date Created	date_created	DateTime	true	The time that this item was originally created	2022-06-01T12:21:06Z
Date Updated	date_updated	DateTime	false	The time that this item was last updated	2022-06-06T21:23:19Z

Creator Model

Creators represent the user that created a post.

Creators contain the following data:

Name	Key	Type	Required	Description	Example
User ID	user_id	string	true	The Account ID of the creator	cf8a2cc9-48cd-43b3-8003-e6f21c756db2
Name	name	string	true	The name of the creator for display purposes	John Doe
Email	email	string	false	The email address of the creator	[email protected]

ToMember Model

ToMembers represent a member to which a post was sent.

ToMembers contain the following data:

Name	Key	Type	Required	Description	Example
User ID	user_id	string	true	The Account ID of the member	cf8a2cc9-48cd-43b3-8003-e6f21c756db2
External ID	external_id	string	true	The External ID of the member	123456789
Name	name	string	true	The name of the member for display purposes	John Doe
Email	email	string	false	The email address of the member	[email protected]

Integrations

Rokwire Integrations

The Groups BB supports integrations with several other Rokwire Building Blocks to offer group-specific content.

Polls

The Polls Building Block is responsible for the creation and management of polls. The Groups BB is integrated with the Polls BB to allow polls to be published within a specific group for the members to see and respond to. This integration is managed in the Polls BB. See the Polls BB Wiki for more details.

Events

The Events Building Block is responsible for the creation and management of events. The Groups BB is integrated with the Events BB to allow events to be published within a specific group for the members of the group to see. Events associated with a group may be private to that group only, or be published publicly for everyone to see.

External Integrations

The Groups BB supports integrations with services external to the Rokwire ecosystem as well.

AuthMan

AuthMan is a service provided by the University of Illinois system that allows groups of people to be created and managed. The Groups BB supports automatic synchronization with AuthMan groups.

To perform this synchronization, the creator of a group must set the AuthMan Enabled flag to true and specify the AuthMan Group. The Groups BB will then periodically request the current member list for the specified AuthMan Group and process this list, adding any new members and removing any that are no longer present. This process uses the member External ID to associate the users in the AuthMan group with the members of the Group. Synchronization can be triggered by making a request to the /int/authman/synchronize endpoint.