Using the Hub Admin Interface

Introduction

The Hub's purpose is:

  • To invite people to the new services, and set up logins on them all.
  • To set up 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 organisations they are in.

To achieve this, the Hub has a database of users, and their connections to organisations & 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 organisation, 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 group without proper authorisation from the group. Do not move groups around, or link them, without proper authorisation from the group, its old parent and its 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 organisation 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 tech champion to create a new organisation on the hub

New groups are normally created by the Group Adminof 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 organisation 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 Organisations. Can invite people to those organisations. Given trust level 3 in Discourse.
    • Creator - a creator can create organisations without Hub Admin intervention
    • All Groups Admin - has Group Admin rights to every organisation
    • Admin - Can do anything.
  • Trusted in Discourse is a flag to say a Group Admin's permissions have been set in Discourse. If they are wrong, it is worth resetting this flag.

The Organisations button shows you what organisations the user is in, see below.

The More Info button shows you the user's Login details, 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 messaqge to the Mattermost admins asking them to delete the user from Mattermost. This can take a day or two to be done.

Organisations a user is in screen

Clicking on one of the organisations currently takes you to the Edit Organisation screen, but this may change.

You can add the user to more Organisations using the Join Organisation button. Please do not do this except with the express permission of the person concerned, and the organisation you are joining them to.

To find or update an Organisation

Maintenance/Organisations

This screen lists all the existing organisations. Use the search box to find the one you want. Click on it to edit. There is a New Organisation button to create a new organisation from scratch - do not do this.

Edit Organisation screen

There are two Edit Organisation screens - the one the Group Admins have access to, and the Admin Edit one (available from a button on the first one). This describes the Admin Edit one.

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 organisation 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 Organisation screen.

You can change any of the fields. If you check the Update Now box, the system will attempt to update the organisation 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 organisation will get their memberships of Teams, Channels, Groups, etc. updated.

Note that this screen is more flexible than the one the 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 organisations, there is a Users](#bkmrk-users-in-organisatio) button, see below.

You can change existing organisations 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 the Team of an Organisation

If you want to change the Team of an Organisation (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 organisation, 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 (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 an organisation after it's been created

You can do this in the Group Admins version of the Edit Organisation screen - it will also help you by suggesting new names for channels and forums.

Users in organisation screen

Lists the Users in the organisation, and whether they are a Group Admin of that particular organisation (you can be a Group Admin on the hub, and of some organisations 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 an organisation

See Users in organisation screen above.

To create a new Organisation

There are three ways to create an organisation. 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 tech champion to create a new organisation on the hub (above).

For either of the above, they will then fill in an Organisation Form, which you can review in Maintenance/Organisation Forms.

The other way is to create an organisation yourself from scratch (not recommended) by clicking New Organisation in the Maintenance/Organisations screen.

Maintenance/Organisation Forms

This lists all the current organisation forms 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 organisation, and check back with the 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 Organisation button. This will pre-fill an Edit Organisation 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 organisation.

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

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 Organisation/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).

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/Organisation Types

This allows you to edit the types of organisation shown in the New Organisation screen. Please do not add or edit Organisation Types without first agreeing the changes with SOS and DDAT.

XR Groups

Everyone gets this - shows your organisations. 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.