Draft Using the Hub Admin Interface
Introduction
The Hub's purpose is:
- To invite people to the new services, and set up the user's logins on them, i.e. on Mattermost, UK Forum and UK Cloud - as well as then giving the user the ability to use the button 'Login Using the UK Hub' button on the Rebellion Academy, Rebel Toolkit, UK Forum and UK Cloud
- To set up Hub Groups on the new services, making sure all the complex permissions, etc., are set correctly, and that people invited on are joined to the right things.
- As a database of users, and what Hub Groups they are in.
To achieve this, the Hub has a database of users, and their connections to Hub Groups & to the other services. A background task tries to keep the database in sync with the services, so every Team and Channel on Mattermost, every Group and Category on Discourse, and every Group on Nextcloud has a database record in the Hub. Every user has a Login record which keeps track of their identity on each service, and a series of PersonIn<something> records which links their Login Record to each Team/Group/Whatever database record.
When someone accepts an invite, or logs in, a batch job runs in the Hub web server which joins them to everything they should be joined to on the other services.
When an admin creates a new Hub Group, a batch job runs to create the necessary stuff on the services.
Batch jobs show a progress bar on the web page while they are running.
In addition, there is a background job which periodically checks everything has been transferred correctly, picks up new channels, etc., which have been created on the services, and makes sure everyone is joined to the right things, and has the right permissions.
Your responsibilities
As a Hub Admin, you have the power to help people and groups who are having difficulties. Please use this power carefully, and lightly. Do not interfere in any way with anything belonging to a Hub Group without proper authorisation from the Hub Group's Coordinators. Do not move Hub Groups around, or link them, unless you have received proper authorisation from both the Hub Group's Coordinators, and the Coordinators of its existing parent and those of its proposed new parent.
To invite a person to the Hub
Admin/Create invites
This is usually done by Group Admins, from the XR Group display but there is a Hub Admin version here.
You can put a list of emails in the Emails box (1 per line), change the subject, add explanatory text, set the access level, and choose the Hub Group the user will be joined to.
Clicking Save will send invite emails to all the emails listed. Invites expire after 14 days (or whatever is set in Admin/Settings).
You don't have to fill in the message box unless you want to personalise the invites. The standard message will include your name and handles.
To invite a Group Admin (formally Tech Champion) to create a new Hub Group
New groups are normally created by the Group Admin of the parent group. The facility to create groups without a parent is here because when we originally started, many parent groups weren't yet on the tools. It should only be used in exceptional circumstances. When checking any new Hub Group form submitted by this method, please ensure that the parent group has given permission for the new group to be a child of theirs.
To check invites outstanding, or resend an invite
Admin/List Invites
This lists all the invites on the system (Group Admins will only see their own invites, Hub Admin sees all). Use the search box to find the one you want. Click on it to edit it. Check Resend Now to get the mail system to resend it when you click Save. The Password Reset checkbox tells you if it is a password reset invite the user has asked for. The Copy button copies the invite url to the clipboard, so you can paste it into another communications channel (e.g. if the user did not get the email).
To find a user
Admin/Users
This lists all the users who have accepted an invite. The Search box at the top right locates people by any of the fields. Click on a user to see details. Note that this list contains only details of the user's Hub login, name and email. If they have different logins on other services, and you don't know their email address, only their login on another service, you might be better searching in Maintenance/Logins.
Edit User screen
You can change anything here. The edit pencil next to Login and Email Address allow you to change those on all the services, but you will need the user's Mattermost Password to change things on Mattermost. The user has access to a similar screen under Admin/My Settings.
- Password You can reset a user's password to anything, by typing in Password and Repeat Password and clicking Save.
- Access Level should be
- None - Please do not set Access Level to None
- User - ordinary user. Can change their own details, but not others. Cannot invite people.
- Group Admin - of one or more Hub Groups. Can invite people to those Hub Groups. Given trust level 3 in Discourse.
- Creator - a creator can create Hub Groups without Hub Admin intervention
- All Groups Admin - has Group Admin rights to every Hub Group
- Admin - Can do anything.
- Trusted in Discourse (Forum) is a flag to say a Group Admin's permissions have been set in Discourse (Forum). If they are wrong, it is worth resetting this flag.
The Hub Groups button shows you what Hub Groups the user is in, see below.
The Impersonate button makes you that user, and sends you to the home screen, logged in as them (useful for seeing the screen the way they do). Do not impersonate people for any other reason.
You can delete a user here - do not delete users without their permission or other authority (e.g. if there has been a conflict resolution process agreeing to expel the user from XR). There are two delete buttons - both will delete the user from the Hub, Forums and Cloud. The Delete From Mattermost Too button will also send a message to the Mattermost admins asking them to delete the user from Mattermost. This can take a day or two to be done.
Hub Groups a user is in screen
Clicking on one of the Hub Groups currently takes you to the Edit Hub Group screen, but this may change.
You can add the user to more Hub Groups using the Join Hub Group button. Please do not do this except with the express permission of the person concerned, and the Hub Group you are joining them to.
To find or update a Hub Group
Maintenance/Hub Groups
This screen lists all the existing Hub Groups. Use the search box to find the one you want. Click on it to edit. There is a New Hub Group button to create a new Hub Group from scratch - do not do this.
Edit Hub Group screen
There are two Edit Hub Group screens - the one the Group Admins have access to, and the Admin Edit screen (available from a button on the first Hub Group Edit screen). This describes the Admin Edit functionality.
Be careful in this screen - changing any of the auto-complete boxes (e.g. team, channel, forum, group names) does not rename the thing - it links the Hub Group to the newly selected thing (creating it if it doesn;t already exist). If you want to rename something, use the ordinary Group Admin's Edit Hub Group screen.
You can change any of the fields. If you check the Update Now box, the system will attempt to update the Hub Group on all the services when you click Save. Most of the text boxes are auto-complete, and will offer you existing records as you type. If you want to create a new item, just type a new name - you will get a confirmation box when you leave the field.
When you complete this screen, existing users who are members of this Hub Group will get their memberships of Teams, Channels, Groups, etc. updated.
Note that this screen is more flexible than the Edit Hub Group screen that the Group Admins (Tech Champions) fill in, allowing you to do some customisation which doesn't adhere to the standard guidelines (e.g. not give a group a Reception, put a group in a team which is not their parent's, etc.). Use these powers sparingly and wisely!
For existing Hub Groups, there is a Users button, see below.
Note the Linked to Map tickbox shows whether or not this group has a pin on the XR UK regions map linked back to this group.
You can change existing Hub Groups in this screen, but be aware that major changes like changing the Team will leave the old channels in the old team, as there is no way to move channels to a different team. There are other, similar limitations in Discourse and Nextcloud, and the only way to tidy them up is by hand, in the individual tools.
Note on changing Parent
Please be aware that changing a Hub Group's Parent mave have unforeseen consequences, like loss of user access to channels/forums/cloud files and joining users to other Hub Groups without invitation. Do not change Parent until you have fully determined the effects of the change and discussed these with the Coordinators of both the existing and proposed Hub Group Parent, together with the members and Coordinators of the Hub Group in question.
Note on changing the default channels
The main Reception channel, and the main private channel can be changed. Just start typing the replacement channel name.
If it is an existing channel, a drop down box will appear - select the correct channel. If it is a new channel, when you move off the field you will be asked to confirm you want to create a new channel.
Note on changing the Team of a Hub Group
If you want to change the Team of a Hub Group (I'm assuming it was in the UK Team, and you want to give it its own Team), you have to do it in both tools. Go into the Hub Group, and select the new team. Tick the box to Create Now and Save it. This will connect to the new Team, and create the private channel in the new team. To finally tidy up, you may want to find the old channel in Maintenance/Channels, and delete it.
Note on changing whether forums are public or private
You can do this in Discourse (Forum) (as Discourse Admin). Find the forum you want to change, Edit it, choose the Security tab, edit permissions. Remove the public (or private) group from the list by clicking the x, and add the private (or public) group instead. Click Save. Job done.
To change the name of a Hub Group after it's been created
You can do this in the Group Admins version of the Edit Hub Group screen - it will also help you by suggesting new names for channels and forums.
Users in Hub Group screen
Lists the Users in the Hub Group, and whether they are a Group Admin of that particular Hub Group (you can be a Group Admin on the hub, and of some Hub Groups but not others).
Click on a user to change whether they are Group Admin or not.
To change whether a user is Group Admin of a Hub Group
See Users in Hub Group screen above.
To create a new Hub Group
There are three ways to create a Hub Group. The usual way is for the parent group to click the Create Child Group button.
The second way is for a Hub Admin to invite a Group Admin (Tech Champion) to create a new Hub Group on the hub (above).
For either of the above, they will then fill in a Hub Group Form, which you can review in Maintenance/Hub Group Forms.
The other way is to create a Hub Group yourself from scratch (not recommended) by clicking New Hub Group in the Maintenance/Hub Groups screen.
Role Support Group Auto Join facilities
You can create Role Support Groups as children of UK Working Groups or Regional/National Groups.
New button on the XR Groups page
For Hub Admins Only a new "Auto Join Roles" appears in the XR Groups display for these groups. It takes you to a screen like this:
This is the list of roles (or group admin permissions) that are auto invited to this group.
The three selection fields are:
- The role (or Group Admin permission) that a person must hold to be invited.
- The type of Hub Group that the role must be in for the person to be invited.
- The root Hub Group. The person must be in this Hub Group, or one of its descendants to be invited.
So, in the screenshot, all Group Admins (Tech Champions) in Cymru Wales or any of its working groups, districts, local groups, etc. will be sent an invite to "Cymru Tech Champions".
To help Hub Admins work out who will be invited to what, there are buttons on the following displays:
| Display | Button | Purpose |
|---|---|---|
| Group Display | List People Auto Joined | Shows everyone with a role on this Hub Group that causes them to be auto invited to another Hub Group |
| Auto Join Roles | List People | Shows everyone invited to this Hub Group because they are in a role in another one |
| Role Display | List People Auto Joined | Shows who is in this role, and what Hub Groups they will be invited to because of it |
| Member Display | List Auto Joins | Shows all the auto join roles this person holds, and what Hub Groups they are invited to as a result |
How it works
When someone does one of the following things:
- Edits the Auto Join Roles screen
- Edits the people in a role
- Edits the roles a person is in (+)
- Deletes a role
- Steps a person back from a role (+)
- Creates a Hub Group
- Deletes a Hub Group
- Admin edits a Hub Group
- Removes someone from a Hub Group (+)
When saving the change, the Hub makes a list of all the people who would be invited to a role support type Hub Group using the settings before the change, then makes the change, then makes a list of all the people who would be invited after the change.
Then it invites all the people who are in the after list but not the before list, and removes all the people who are in the before list but not the after.
Note that the actual removals are first listed in a screen with tickboxes against each one, so the person making the change has a chance to untick people they do not want to be removed. Note also that people who are in a role in the group support Hub Group are not shown in this list, or removed automatically.
(+) The removal screen is simpler in these cases, because only a single person is affected, so it just shows a list of Hub Groups the person will be removed from. In the other cases, it has to show both person and Hub Group, as there is no reason why the same person might not be joined to two or more Hub Groups - e.g. all the Cymru Tech Champions will be joined to the UK level Tech Champions Hub Group, as well as the Cymru one.
Here is the simple screen:
And the more complicated one:
Please click Save in this screen to carry out the removals. If you think a person should not be removed, first untick the corresponding Confirm box.
Maintenance/Hub Group Forms
This lists all the current Hub Group forms Group Admins (Tech Champions) have filled in. By default, it only lists the forms where people have ticked the "Tick Here When Complete" box. You can see all the forms, including incomplete ones, by clicking "Show all" above the list.
Click on one to edit it. Check it makes sense from your knowledge of the Hub Group, and check back with the Group Admin (Tech Champion) if there is anything you think they have not understood, or if you don't understand why they have asked for something (or not asked for something).
If you make changes, click the Apply button to save the changes before proceeding.
There is a Create Hub Group button. This will pre-fill an Edit Hub Group screen with the information from the form (and invisibly attach extra information which is on this form). You can make any final custom changes there, and click Save on that form to actually create everything on the new services, and make the original tech champion Group Admin of the Hub Group.
Admin/Batch Jobs
Lists running batch jobs. Not really needed, comes with the framework.
Admin/Web Logs
This lets you see the web server log file for today. To see a different day, use the Yesterday and Tomorrow buttons, or edit the url to add ?date=yyyy-mm-dd. Can be useful to see what went wrong if a user forgets what the error message said!
Admin/Job Logs
This lets you see the background job log file for today. To see a different day, use the Yesterday and Tomorrow buttons, or edit the url to add ?date=yyyy-mm-dd.
Admin/Search Logs
Allows you to search the log files (either Web or Job) back a specified number of days, and shows you the found lines, with a link to click on to go to that day.
Admin/Server Stats
Shows you performance stats for the server. There is a separate link for each day which takes you to a screen where you can view graphs of various server statistics (e.g. how busy the disk is, how much memory is in use, etc.)
Admin/My Settings
Everyone gets this -- change your name, role and how often you get error emails.
Maintenance/Logins
Shows all the Login records. Each email address that has used the hub, or that has contributed to something transferred from Basecamp, will have an entry here. Login shows their login in the hub (if they have one - they may be a Basecamp user that hasn't accepted an invite). Mattermost, Discourse and Nextcloud show their login names on each of those services. Click on one for the Edit Login screen.
Edit Login screen
This shows the user's login information for the services (a tick means they have a login). It also shows their Team, Channel and Group memberships. The Transferred checkbox indicates whether these have been update on the corresponding service - if you untick it, the background job will try to join them again. The Delete checkbox will delete that membership on the Hub (only - does not affect the services). None of these are actioned until you click Save.
Ticking the Update Now checkbox will attempt update their tool accounts right away when you click Save.
You can only delete Logins if the Login does not correspond to a User, and there is something wrong with it. If you want to delete a user, you need to do that in the Edit User screen. There is a User button above this Login screen which will take you there.
Maintenance/Sessions
This shows who has active login cookies. Mostly for xrukadmin to see if it is safe to shut down the server.
Maintenance/Teams
Shows the Mattermost Team records on the local database. Public Teams that have nothing to do with XR UK will appear here too. The Checked column indicates when the Team was last found on Mattermost. An old date may indicate that the team has been deleted from Mattermost. If so, after double checking on Mattermost, you may want to click on it, then delete it. Note that if the team is in use by something, you won't be allowed to delete it -- you need to read the message, go and find where it is used, and fix that first.
You can click on one to edit it (not recommended - you can break the connection between it and the service if you are not careful).
Maintenance/Channels
Shows the Mattermost Channel records on the local database. Public Channels that have nothing to do with XR UK will appear here too. The Checked column indicates when the Team was last found on Mattermost. An old date may indicate that the channel has been deleted from Mattermost. If so, after double checking on Mattermost, you may want to click on it, then delete it. Note that if the channel is in use by something, you won't be allowed to delete it -- you need to read the message, go and find where it is used, and fix that first.
The main Reception channel, and the main private channel belonging to each group cannot be deleted. If you want to change which channel is the main private channel, you can do that in Edit Hub Group/Admin Edit.
You can click on one to edit it (not recommended - you can break the connection between it and the service if you are not careful).
To make a channel Broadcast Only, or join a whole Team to it
In Maintenance/Channels, Hub Admins see an extra button Edit Broadcast Settings, which takes you to this screen:
Tick the Broadcast button if you only want members of the group that owns the channel to post to it. Every night, the Hub will check for posts from other users, remove them, and send them a DM explaining that this is a broadcast only channel and to contact the group if they want something posted to it.
Tick the Auto Join button if you want everyone in the Mattermost Team joined to the channel automatically. Please do not do this without serious thought. Many rebels are already overloaded with too much information.
Maintenance/DsGroups
Shows the Discourse Group records on the local database. The Checked column indicates when the Group was last found on Discourse. An old date may indicate that the group has been deleted from Discourse. If so, after double checking on Discourse, you may want to click on it, then delete it. Note that if the group is in use by something, you won't be allowed to delete it -- you need to read the message, go and find where it is used, and fix that first.
You can click on one to edit it (not recommended - you can break the connection between it and the service if you are not careful). In the edit screen, you can click on Categories to see what Categories the group gives permission for.
Maintenance/DsCategories
Shows the Discourse (Sub-)Category records on the local database. The Checked column indicates when the category was last found on Discourse. An old date may indicate that the category has been deleted from Discourse. If so, after double checking on Discourse, you may want to click on it, then delete it. Note that if the category is in use by something, you won't be allowed to delete it -- you need to read the message, go and find where it is used, and fix that first.
You can click on one to edit it (not recommended - you can break the connection between it and the service if you are not careful). In the edit screen, you can click on Groups to see what Groups give permission for the category.
Maintenance/NxGroups
Shows the Nextcloud Group records on the local database. The Checked column indicates when the group was last found on Nextcloud. An old date may indicate that the group has been deleted from Nextcloud. If so, after double checking on Nextcloud, you may want to click on it, then delete it. Note that if the group is in use by something, you won't be allowed to delete it -- you need to read the message, go and find where it is used, and fix that first.
You can click on one to edit it (not recommended - you can break the connection between it and the service if you are not careful).
Maintenance/Forum Permissions
Shows all the Discourse Groups and Categories, and the permissions connecting the two.
Maintenance/Hub Group Types
This allows you to edit the types of Hub Group shown in the New Hub Group screen. Please do not add or edit Hub Group Types without first agreeing the changes with SOS and DDAT.
XR Groups
Everyone gets this - shows your Hub Groups. Clicking on one shows the group.
XR Groups/Default Roles
This shows the default roles that a Group Admin creating a new role can choose from - e.g. External Coordinator, Internal Coordinator. They are templates prefilled with standard purpose and accountabilities, so the Group Admin knows what the standard form looks like.
Click on one to edit it, or click Add Role to add a new one.
Default Roles have an additional tickbox Standard. If this is ticked, then every new group being created will get one of these roles automatically.
Please do not add or edit Default Roles without first agreeing the changes with SOS.