Skip to content

Home

Jump to bottom
Stephen Hurwit edited this page Jun 29, 2022 · 5 revisions

Welcome to the Polls Building Block wiki!

The Polls Building Block (Polls BB) is the service responsible for managing polls in the Rokwire ecosystem. This Building Block allows users to create polls for other users to vote on.

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

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

Polls

Polls are simple questions with a set of predefined answers that participants can choose from. Polls can be created by making a request to the POST /polls endpoint. Users may then vote on this poll using the POST /polls/{id}/vote endpoint. Once everyone has voted, the poll can be ended by its original creator making a request to the POST /polls/{id}/end endpoint.

To search for existing polls, users may make a request to the GET /polls endpoint using the Poll Filter.

Poll Model

Polls contain the following data:

Name Key Type Required Description Example
ID id ObjectId true The unique ObjectId for this item 507f1f77bcf86cd799439011
Organization ID org_id string true The unique identifier of the Organization with which the item is associated. fc6ab5f8-84ef-414b-b979-c1c7611a4c43
User ID user_id string true The Account ID of the user who created this poll cf8a2cc9-48cd-43b3-8003-e6f21c756db2
User Name user_name string true The name of the user who created this poll John Doe
To Member List to_members list (ToMember) false List of ToMembers that this poll was sent to. If this list is empty, anyone may access this poll.
Question question string true Question to be displayed to users What time are you available?
Options options list (string) true List of response options to be selected by users [9:00 am, 10:00 am, 1:00 pm, 3:00pm]
Group ID group_id string false The unique identifier of the Group that this poll is associated with, if any fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75
Pin pin int true The automatically generated four-digit PIN required to access this poll 7264
Multiple Choice multi_choice bool true Flag indicating whether multiple options can be selected when voting false
Repeat repeat bool true Flag indicating whether one user may vote multiple times false
Show Results show_results bool true Flag indicating whether the results of the poll should be shown to the participants while the poll is still active false
Stadium stadium string false The identifier of the stadium region for Stadium Polls 5bac59a8-562b-4cf9-89a8-b5e3bce62609
Geo geo_fence bool true Flag indicating if the poll is geo-fenced to the stadium
Status status string true Current status of the poll. Options are created, started, terminated, stadium created
Responses responses list (PollVote) false List of PollVotes responding to this poll
Results results list (int) false List of response Options counts from Responses. The count at each index corresponds with the same index in Options. [0, 3, 2, 2]
Date Created date_created DateTime true The time that this item was originally created 2022-06-01T12:21:06Z
Date Updated date_updated DateTime true The time that this item was last updated 2022-06-06T21:23:19Z

To Member Model

ToMembers represent the specific users allowed to access a poll. 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 john.doe@example.com

Poll Vote Model

PollVotes represent an individual user's vote in response to the poll. PollVotes contain the following data:

Name Key Type Required Description Example
User ID userid string true The Account ID of the member cf8a2cc9-48cd-43b3-8003-e6f21c756db2
Answer answer list (int) true List of indices of the Options selected by this user John Doe
Created created DateTime true The time that this item was originally created 2022-06-01T12:21:06Z

Poll Filter Model

The PollFilter is a model containing filter parameters for use when searching for polls. PollFilters contain the following data:

Name Key Type Required Description Example
Pin pin int false A poll Pin used to filter polls 7264
Poll IDs poll_ids list (string) false List of poll ID values used to filter polls [fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75]
My Polls my_polls bool false Flag indicating that filter should include only polls that the requesting user has created or participated in previously created
Group Polls group_polls bool false Flag indicating that filter should include only Group Polls created
Responded Polls responded_polls bool false Flag indicating that filter should include only polls that the requesting used has previously responded to created
Group IDs group_ids list (string) false List of Group IDs used to filter polls [fbef4bd3-1ca0-4cc0-aaa3-38b1a7f50b75]
Statuses statuses list (string) false List of Status values used to filter polls [created]
Offset offset int false Number of records to offset when retrieving paginated results 20
Limit limit int false Number of records to return when retrieving paginated results 10

Visibility

The visibility of a poll may be limited in several ways.

  • Standard: Standard polls are available to all users and can be accessed by using the poll's PIN
  • Group: Group polls are associated with a specific Group ID and can only be accessed by its members. See Groups Integration for more information.
  • Stadium: Stadium polls are geo-fenced polls that can only be accessed by users in the geo-fence region of the associated Stadium
  • Private: Private polls are only accessible to a specific set of users set in the To Members List

Integrations

The Polls BB is provides integrations with other services to offer additional functionality.

Groups Integration

The Polls BB is integrated with the Groups BB to enable Group Poll functionality. The Polls BB makes requests to the Groups BB to ensure that only other members of the group are accessing and creating Group Polls.

Clone this wiki locally