SetupSectionSlackChannelsJob.java
package edu.ucsb.cs156.frontiers.jobs;
import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.CourseStaff;
import edu.ucsb.cs156.frontiers.entities.RosterStudent;
import edu.ucsb.cs156.frontiers.entities.Section;
import edu.ucsb.cs156.frontiers.enums.RosterStatus;
import edu.ucsb.cs156.frontiers.errors.SlackApiException;
import edu.ucsb.cs156.frontiers.models.SlackChannel;
import edu.ucsb.cs156.frontiers.models.SlackUser;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseStaffRepository;
import edu.ucsb.cs156.frontiers.repositories.RosterStudentRepository;
import edu.ucsb.cs156.frontiers.repositories.SectionRepository;
import edu.ucsb.cs156.frontiers.services.CanvasApiTokenSecurityService;
import edu.ucsb.cs156.frontiers.services.SlackService;
import edu.ucsb.cs156.frontiers.utilities.CanonicalFormConverter;
import edu.ucsb.cs156.jobs.services.JobContext;
import edu.ucsb.cs156.jobs.services.JobContextConsumer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.stream.StreamSupport;
import lombok.Builder;
/**
* Makes the public Slack channels of a course's sections match the roster.
*
* <ol>
* <li>For each row of the sections table that has a Slack channel name, creates a public channel
* with that name, unless it already exists. (Several sections may share a channel.)
* <li>Adds each roster student (status ROSTER or MANUAL) to the channel of their section, unless
* they are already in it. Students are matched to Slack users by email; students without an
* active Slack account cannot be added, and are only counted, by reason (invited but not
* accepted yet, account deactivated, or not in the workspace).
* <li>Removes from each of those channels every person who is neither a roster student of one of
* the channel's sections, nor a member of the course staff, nor the instructor. Bots
* (including the bot this job acts as) and members that are not users of the workspace are
* never removed. Whether the bot may remove members from public channels is a workspace
* setting; if Slack refuses (restricted_action), the log says how to change the setting and
* no further removals are attempted in that run.
* </ol>
*
* A problem with one channel or one person is logged, and the job carries on with the rest.
*/
@Builder
public class SetupSectionSlackChannelsJob implements JobContextConsumer {
/** Only these roster students are considered: in particular, not dropped students. */
public static final List<RosterStatus> ENROLLED_STATUSES =
List.of(RosterStatus.ROSTER, RosterStatus.MANUAL);
Course course;
CourseRepository courseRepository;
SectionRepository sectionRepository;
RosterStudentRepository rosterStudentRepository;
CourseStaffRepository courseStaffRepository;
SlackService slackService;
CanvasApiTokenSecurityService tokenSecurityService;
@Override
public String getScopeType() {
return "course";
}
@Override
public Long getScopeId() {
return course.getId();
}
@Override
public void accept(JobContext ctx) throws Exception {
Course currentCourse = courseRepository.findById(course.getId()).orElseThrow();
String token = tokenSecurityService.decrypt(currentCourse.getSlackBotToken());
if (token == null || token.isEmpty()) {
throw new IllegalStateException(
"No Slack token has been set for this course; enter one on the Settings tab.");
}
List<SlackUser> slackUsers = slackService.listUsers(token);
Map<String, SlackUser> slackUsersById = new HashMap<>();
Map<String, String> activeSlackIdByEmail = new HashMap<>();
// For people whose account is not active: true if they have been invited but have not accepted
// yet, false if their account has been deactivated. As on the Slack tab, an invitation wins
// over a deactivated account with the same email.
Map<String, Boolean> invitedByEmail = new HashMap<>();
for (SlackUser user : slackUsers) {
slackUsersById.put(user.getId(), user);
if (user.isActivePerson() && user.email() != null) {
activeSlackIdByEmail.put(canonical(user.email()), user.getId());
} else if (user.isPerson() && user.email() != null) {
invitedByEmail.merge(canonical(user.email()), !user.getDeleted(), Boolean::logicalOr);
}
}
if (activeSlackIdByEmail.isEmpty()) {
// Without emails nobody can be matched, and everybody would be removed from the channels.
throw new IllegalStateException(
"Slack did not provide the email of any user. Add the users:read.email scope to the Slack app, reinstall it to the workspace, and save the new token on the Settings tab.");
}
ctx.log("Creating Section Channels");
Map<String, Set<String>> sectionsByChannelName = sectionsByChannelName(currentCourse.getId());
Map<String, List<String>> channelNamesBySection = channelNamesBySection(sectionsByChannelName);
Map<String, String> channelIdByName =
createChannels(ctx, token, sectionsByChannelName.keySet());
List<RosterStudent> students = enrolledStudents(currentCourse.getId());
Set<String> staffSlackIds = staffSlackIds(currentCourse, activeSlackIdByEmail);
// Members of each channel before this job changes anything; null if they could not be listed
Map<String, List<String>> membersByChannelName = new HashMap<>();
// Slack ids of the students that belong in each channel
Map<String, Set<String>> studentSlackIdsByChannelName = new HashMap<>();
ctx.log("Adding Students to Channel");
int studentsInvited = 0;
int studentsDeactivated = 0;
int studentsNotInWorkspace = 0;
for (RosterStudent student : students) {
List<String> matchingChannels =
channelNamesBySection.getOrDefault(student.getSection(), List.of());
if (matchingChannels.isEmpty()) {
ctx.log(
"Student %s is in untranslated roster section %s"
.formatted(describe(student), describeSection(student.getSection())));
ctx.log(
"Could not add %s to a section Slack channel because no configured channel matches untranslated roster section %s."
.formatted(describe(student), describeSection(student.getSection())));
} else {
ctx.log(
"Student %s is in untranslated roster section %s and maps to %s"
.formatted(
describe(student),
describeSection(student.getSection()),
describeChannelNames(matchingChannels)));
}
}
for (Map.Entry<String, String> channel : channelIdByName.entrySet()) {
String channelName = channel.getKey();
String channelId = channel.getValue();
List<String> members;
try {
members = slackService.listChannelMembers(token, channelId);
} catch (SlackApiException e) {
ctx.log("Error listing members of #%s: %s".formatted(channelName, e.getMessage()));
continue;
}
membersByChannelName.put(channelName, members);
Set<String> studentSlackIds = new HashSet<>();
List<RosterStudent> toAdd = new ArrayList<>();
for (RosterStudent student : students) {
if (sectionsByChannelName.get(channelName).contains(student.getSection())) {
String slackId =
student.getEmail() == null
? null
: activeSlackIdByEmail.get(canonical(student.getEmail()));
if (slackId == null) {
Boolean invited =
student.getEmail() == null
? null
: invitedByEmail.get(canonical(student.getEmail()));
if (invited == null) {
studentsNotInWorkspace++;
} else if (invited) {
studentsInvited++;
} else {
studentsDeactivated++;
}
} else {
studentSlackIds.add(slackId);
if (!members.contains(slackId)) {
toAdd.add(student);
}
}
}
}
studentSlackIdsByChannelName.put(channelName, studentSlackIds);
addStudents(ctx, token, channelName, channelId, toAdd, activeSlackIdByEmail);
}
// Students who cannot be added are not logged one by one (the Slack tab lists them), but the
// log does say why: most often, they have not accepted their invitation yet.
List<String> reasons = new ArrayList<>();
if (studentsInvited > 0) {
reasons.add(
"%d invited to the Slack workspace but not accepted yet".formatted(studentsInvited));
}
if (studentsDeactivated > 0) {
reasons.add("%d with a deactivated Slack account".formatted(studentsDeactivated));
}
if (studentsNotInWorkspace > 0) {
reasons.add("%d not in the Slack workspace".formatted(studentsNotInWorkspace));
}
if (!reasons.isEmpty()) {
ctx.log(
"%d student(s) in these sections could not be added: %s. See the Slack tab. Run this job again once they have joined."
.formatted(
studentsInvited + studentsDeactivated + studentsNotInWorkspace,
String.join(", ", reasons)));
}
ctx.log("Removing Channel Members Who Are Not In The Section");
channels:
for (Map.Entry<String, String> channel : channelIdByName.entrySet()) {
String channelName = channel.getKey();
List<String> members = membersByChannelName.get(channelName);
if (members == null) {
continue;
}
for (String memberId : members) {
SlackUser member = slackUsersById.get(memberId);
boolean belongs =
staffSlackIds.contains(memberId)
|| studentSlackIdsByChannelName.get(channelName).contains(memberId);
// Bots (including this one) and members who are not users of the workspace are left alone
if (!belongs && member != null && member.isPerson()) {
try {
slackService.removeFromChannel(token, channel.getValue(), memberId);
ctx.log("Removed %s from #%s".formatted(describe(member), channelName));
} catch (SlackApiException e) {
ctx.log(
"Error removing %s from #%s: %s"
.formatted(describe(member), channelName, e.getMessage()));
if (SlackService.RESTRICTED_ACTION.equals(e.getMessage())) {
// A workspace setting forbids it, so every other removal would fail the same way
ctx.log(SlackService.REMOVAL_RESTRICTED_ADVICE);
break channels;
}
}
}
}
}
ctx.log("Done");
}
/**
* @return for each (normalized) channel name, in order of section, the sections that use it
*/
private Map<String, Set<String>> sectionsByChannelName(Long courseId) {
Map<String, Set<String>> result = new LinkedHashMap<>();
for (Section section : sectionRepository.findByCourseIdOrderBySectionAsc(courseId)) {
String channelName = normalizeChannelName(section.getSlackChannelName());
if (!channelName.isEmpty()) {
result.computeIfAbsent(channelName, name -> new HashSet<>()).add(section.getSection());
}
}
return result;
}
private Map<String, List<String>> channelNamesBySection(
Map<String, Set<String>> sectionsByChannelName) {
Map<String, List<String>> result = new HashMap<>();
for (Map.Entry<String, Set<String>> entry : sectionsByChannelName.entrySet()) {
for (String section : entry.getValue()) {
result.computeIfAbsent(section, unused -> new ArrayList<>()).add(entry.getKey());
}
}
return result;
}
private List<RosterStudent> enrolledStudents(Long courseId) {
return StreamSupport.stream(
rosterStudentRepository
.findByCourseIdOrderByFirstNameAscLastNameAscIgnoreCase(courseId)
.spliterator(),
false)
.filter(student -> ENROLLED_STATUSES.contains(student.getRosterStatus()))
.toList();
}
/**
* Slack channel names are lowercase, and are written with a leading # that is not part of the
* name.
*
* @param name the name as entered for the section; may be null
* @return the name to use with the Slack API, or an empty string if there is none
*/
public static String normalizeChannelName(String name) {
if (name == null) {
return "";
}
String stripped = name.strip();
if (stripped.startsWith("#")) {
stripped = stripped.substring(1).strip();
}
return stripped.toLowerCase(Locale.ROOT);
}
/**
* Creates the channels that do not exist yet, and makes the bot a member of the ones that do.
*
* @return the id of each channel that is ready to be used, by name
*/
private Map<String, String> createChannels(
JobContext ctx, String token, Set<String> channelNames) {
Map<String, SlackChannel> existingByName = new HashMap<>();
for (SlackChannel existing : slackService.listPublicChannels(token)) {
existingByName.put(existing.getName(), existing);
}
Map<String, String> channelIdByName = new LinkedHashMap<>();
for (String channelName : channelNames) {
SlackChannel existing = existingByName.get(channelName);
try {
if (existing == null) {
SlackChannel created = slackService.createPublicChannel(token, channelName);
channelIdByName.put(channelName, created.getId());
ctx.log("Created channel #%s".formatted(channelName));
} else if (existing.getArchived()) {
ctx.log(
"Channel #%s already exists, but is archived; unarchive it in Slack, then run this job again. Skipping it."
.formatted(channelName));
} else {
slackService.joinChannel(token, existing.getId());
channelIdByName.put(channelName, existing.getId());
ctx.log("Channel #%s already exists".formatted(channelName));
}
} catch (SlackApiException e) {
ctx.log(
"Error setting up channel #%s: %s. Skipping it."
.formatted(channelName, e.getMessage()));
}
}
return channelIdByName;
}
/**
* Adds the students with one call to Slack. Slack adds all or none, so if that fails, they are
* added one at a time, so that one problem student does not keep the others out.
*/
private void addStudents(
JobContext ctx,
String token,
String channelName,
String channelId,
List<RosterStudent> toAdd,
Map<String, String> activeSlackIdByEmail) {
if (toAdd.isEmpty()) {
return;
}
List<String> slackIds = new ArrayList<>();
for (RosterStudent student : toAdd) {
slackIds.add(activeSlackIdByEmail.get(canonical(student.getEmail())));
}
try {
slackService.inviteToChannel(token, channelId, slackIds);
for (RosterStudent student : toAdd) {
ctx.log("Added %s to #%s".formatted(describe(student), channelName));
}
return;
} catch (SlackApiException e) {
ctx.log(
"Could not add %d student(s) to #%s in one step (%s); adding them one at a time."
.formatted(toAdd.size(), channelName, e.getMessage()));
}
for (int i = 0; i < toAdd.size(); i++) {
try {
slackService.inviteToChannel(token, channelId, List.of(slackIds.get(i)));
ctx.log("Added %s to #%s".formatted(describe(toAdd.get(i)), channelName));
} catch (SlackApiException e) {
ctx.log(
"Error adding %s to #%s: %s"
.formatted(describe(toAdd.get(i)), channelName, e.getMessage()));
}
}
}
/** Slack ids of the staff of the course and of its instructor, who belong in every channel. */
private Set<String> staffSlackIds(Course currentCourse, Map<String, String> slackIdByEmail) {
Set<String> result = new HashSet<>();
for (CourseStaff staff : courseStaffRepository.findByCourseId(currentCourse.getId())) {
if (staff.getEmail() != null) {
// null (staff member not in Slack) is harmless in this set: no channel member has id null
result.add(slackIdByEmail.get(canonical(staff.getEmail())));
}
}
if (currentCourse.getInstructorEmail() != null) {
result.add(slackIdByEmail.get(canonical(currentCourse.getInstructorEmail())));
}
return result;
}
private static String describe(RosterStudent student) {
return "%s %s (%s)"
.formatted(student.getFirstName(), student.getLastName(), student.getEmail());
}
private static String describe(SlackUser user) {
return "%s (%s)".formatted(user.getRealName(), user.email());
}
private static String describeSection(String section) {
return section == null ? "(blank)" : section;
}
private static String describeChannelNames(List<String> channelNames) {
return "#" + String.join(", #", channelNames);
}
private static String canonical(String email) {
return CanonicalFormConverter.convertToValidEmail(email.strip());
}
}