SetupTeamSlackChannelsJob.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.Team;
import edu.ucsb.cs156.frontiers.entities.TeamMember;
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.TeamRepository;
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 lombok.Builder;
/**
* Makes the public Slack channels of a course's teams match the teams.
*
* <ol>
* <li>For each team, works out a channel name: "team-" followed by the team name in the form
* Slack requires (see {@link #sanitizeChannelName}). If two teams end up with the same
* channel name, the job stops with an error naming them, before touching Slack.
* <li>Creates each channel, unless it already exists.
* <li>Adds each member of each team, and the instructor of the course, to the team's channel,
* unless they are already in it. People are matched to Slack users by email; those without an
* active Slack account cannot be added, and are only counted.
* <li>Removes from each channel every person who is neither a member of the team, nor the
* instructor, nor a member of the course staff. Bots (including the bot this job acts as) and
* members that are not users of the workspace are never removed.
* </ol>
*
* A problem with one channel or one person is logged, and the job carries on with the rest. The
* last line of the log is a summary of how many channels were created or already existed, and how
* many members were added, already present, or removed.
*/
@Builder
public class SetupTeamSlackChannelsJob implements JobContextConsumer {
public static final String CHANNEL_PREFIX = "team-";
Course course;
CourseRepository courseRepository;
TeamRepository teamRepository;
CourseStaffRepository courseStaffRepository;
SlackService slackService;
CanvasApiTokenSecurityService tokenSecurityService;
@Override
public String getScopeType() {
return "course";
}
@Override
public Long getScopeId() {
return course.getId();
}
/**
* Turns a team name into the form Slack requires of channel names: all lowercase, spaces replaced
* by hyphens, and every character other than letters, numbers, hyphens and underscores replaced
* by a hyphen.
*
* @param teamName the team name; may be null
* @return the sanitized name (without the "team-" prefix)
*/
public static String sanitizeChannelName(String teamName) {
if (teamName == null) {
return "";
}
return teamName.toLowerCase(Locale.ROOT).replace(' ', '-').replaceAll("[^a-z0-9_-]", "-");
}
/**
* @param teamName the team name
* @return the name of the team's Slack channel
*/
public static String channelNameFor(String teamName) {
return CHANNEL_PREFIX + sanitizeChannelName(teamName);
}
@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.");
}
// Work out the channel names first, and stop if any two teams collide, before calling Slack
Map<String, Team> teamByChannelName = new LinkedHashMap<>();
Map<String, List<String>> teamNamesByChannelName = new LinkedHashMap<>();
for (Team team : teamRepository.findByCourseIdOrderByNameAsc(currentCourse.getId())) {
String channelName = channelNameFor(team.getName());
teamByChannelName.putIfAbsent(channelName, team);
teamNamesByChannelName
.computeIfAbsent(channelName, name -> new ArrayList<>())
.add(team.getName());
}
List<String> collisions = new ArrayList<>();
for (Map.Entry<String, List<String>> entry : teamNamesByChannelName.entrySet()) {
if (entry.getValue().size() > 1) {
collisions.add(
"#%s (teams %s)".formatted(entry.getKey(), String.join(", ", entry.getValue())));
}
}
if (!collisions.isEmpty()) {
throw new IllegalStateException(
"Two or more teams would get the same Slack channel name: %s. Rename the teams so that their channel names differ, then run this job again. Nothing was changed in Slack."
.formatted(String.join("; ", collisions)));
}
ctx.log(
"Creating Team Channels (%d team(s), channel names start with %s)"
.formatted(teamByChannelName.size(), CHANNEL_PREFIX));
List<SlackUser> slackUsers = slackService.listUsers(token);
Map<String, SlackUser> slackUsersById = new HashMap<>();
Map<String, String> activeSlackIdByEmail = new HashMap<>();
for (SlackUser user : slackUsers) {
slackUsersById.put(user.getId(), user);
if (user.isActivePerson() && user.email() != null) {
activeSlackIdByEmail.put(canonical(user.email()), user.getId());
}
}
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.");
}
Summary summary = new Summary();
Map<String, String> channelIdByName = createChannels(ctx, token, teamByChannelName, summary);
String instructorSlackId =
currentCourse.getInstructorEmail() == null
? null
: activeSlackIdByEmail.get(canonical(currentCourse.getInstructorEmail()));
if (currentCourse.getInstructorEmail() != null && instructorSlackId == null) {
ctx.log(
"The instructor (%s) does not have an active account in the Slack workspace, so cannot be added to the channels."
.formatted(currentCourse.getInstructorEmail()));
}
Set<String> staffSlackIds = new HashSet<>();
for (CourseStaff staff : courseStaffRepository.findByCourseId(currentCourse.getId())) {
if (staff.getEmail() != null) {
staffSlackIds.add(activeSlackIdByEmail.get(canonical(staff.getEmail())));
}
}
ctx.log("Adding Team Members to Channels");
Map<String, List<String>> membersByChannelName = new HashMap<>();
Map<String, Set<String>> belongingIdsByChannelName = new HashMap<>();
int membersNotInSlack = 0;
for (Map.Entry<String, String> channel : channelIdByName.entrySet()) {
String channelName = channel.getKey();
String channelId = channel.getValue();
Team team = teamByChannelName.get(channelName);
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);
// who belongs, with a label for the log; the instructor first
Map<String, String> belonging = new LinkedHashMap<>();
if (instructorSlackId != null) {
belonging.put(instructorSlackId, "instructor " + currentCourse.getInstructorEmail());
}
for (TeamMember member :
team.getTeamMembers() == null ? List.<TeamMember>of() : team.getTeamMembers()) {
RosterStudent student = member.getRosterStudent();
String slackId =
student == null || student.getEmail() == null
? null
: activeSlackIdByEmail.get(canonical(student.getEmail()));
if (slackId == null) {
membersNotInSlack++;
} else {
belonging.putIfAbsent(slackId, describe(student));
}
}
belongingIdsByChannelName.put(channelName, belonging.keySet());
List<Map.Entry<String, String>> toAdd = new ArrayList<>();
for (Map.Entry<String, String> person : belonging.entrySet()) {
if (members.contains(person.getKey())) {
summary.membersAlreadyPresent++;
} else {
toAdd.add(person);
}
}
addMembers(ctx, token, channelName, channelId, toAdd, summary);
}
if (membersNotInSlack > 0) {
ctx.log(
"%d team member(s) could not be added, because they do not have an active account in the Slack workspace; see the Slack tab. Run this job again once they have joined."
.formatted(membersNotInSlack));
}
ctx.log("Removing Channel Members Who Are Not On The Team");
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 =
belongingIdsByChannelName.get(channelName).contains(memberId)
|| staffSlackIds.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);
summary.membersRemoved++;
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. Channels created: %d, already existed: %d. Members added: %d, already present: %d, removed: %d."
.formatted(
summary.channelsCreated,
summary.channelsExisting,
summary.membersAdded,
summary.membersAlreadyPresent,
summary.membersRemoved));
}
/** The counts reported at the end of the log. */
private static class Summary {
int channelsCreated;
int channelsExisting;
int membersAdded;
int membersAlreadyPresent;
int membersRemoved;
}
/**
* 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, Map<String, Team> teamByChannelName, Summary summary) {
Map<String, SlackChannel> existingByName = new HashMap<>();
for (SlackChannel existing : slackService.listPublicChannels(token)) {
existingByName.put(existing.getName(), existing);
}
Map<String, String> channelIdByName = new LinkedHashMap<>();
for (Map.Entry<String, Team> entry : teamByChannelName.entrySet()) {
String channelName = entry.getKey();
String teamName = entry.getValue().getName();
SlackChannel existing = existingByName.get(channelName);
try {
if (existing == null) {
SlackChannel created = slackService.createPublicChannel(token, channelName);
channelIdByName.put(channelName, created.getId());
summary.channelsCreated++;
ctx.log("Created channel #%s for team %s".formatted(channelName, teamName));
} else if (existing.getArchived()) {
ctx.log(
"Channel #%s for team %s already exists, but is archived; unarchive it in Slack, then run this job again. Skipping it."
.formatted(channelName, teamName));
} else {
slackService.joinChannel(token, existing.getId());
channelIdByName.put(channelName, existing.getId());
summary.channelsExisting++;
ctx.log("Channel #%s for team %s already exists".formatted(channelName, teamName));
}
} catch (SlackApiException e) {
ctx.log(
"Error setting up channel #%s for team %s: %s. Skipping it."
.formatted(channelName, teamName, e.getMessage()));
}
}
return channelIdByName;
}
/**
* Adds the people 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 person does not keep the others out.
*
* @param toAdd Slack id and description of each person to add
*/
private void addMembers(
JobContext ctx,
String token,
String channelName,
String channelId,
List<Map.Entry<String, String>> toAdd,
Summary summary) {
if (toAdd.isEmpty()) {
return;
}
List<String> slackIds = toAdd.stream().map(Map.Entry::getKey).toList();
try {
slackService.inviteToChannel(token, channelId, slackIds);
for (Map.Entry<String, String> person : toAdd) {
summary.membersAdded++;
ctx.log("Added %s to #%s".formatted(person.getValue(), channelName));
}
return;
} catch (SlackApiException e) {
ctx.log(
"Could not add %d member(s) to #%s in one step (%s); adding them one at a time."
.formatted(toAdd.size(), channelName, e.getMessage()));
}
for (Map.Entry<String, String> person : toAdd) {
try {
slackService.inviteToChannel(token, channelId, List.of(person.getKey()));
summary.membersAdded++;
ctx.log("Added %s to #%s".formatted(person.getValue(), channelName));
} catch (SlackApiException e) {
ctx.log(
"Error adding %s to #%s: %s".formatted(person.getValue(), channelName, e.getMessage()));
}
}
}
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 canonical(String email) {
return CanonicalFormConverter.convertToValidEmail(email.strip());
}
}