The User Role Matrix of Invantive Studio holds every user of the repository against every role, so that the roles of a user and the users of a role can be granted and withdrawn in one place. It shows the same rows as "User Roles" under a user and under a role, which show one user or one role at a time. Which role a user holds decides what that user may reach; what a role itself may reach is set in the [[Invantive Studio/Role Function Matrix|Role Function Matrix]]. ## Opening the matrix Select "User Role Matrix" under "Security" in the tree. A window opens for the matrix; it is not a dialog, so it stays open beside the tree while other work goes on, and selecting the node again brings it to the front rather than opening a second one. It closes with Invantive Studio. Opening it needs the function right "User Role List". Changing a cell needs the right "User Role Details" granted for changes; without it the matrix opens for reading and the "Save" button is not shown. ## The matrix A row is a user and a column is a role. The users stand in the order of their code, and the name of a user carries the code as well as the full name. The column on the left names the row and stays in view while the roles are scrolled past. A cell says whether the user holds the role: - `-`: the user does not hold the role. - `Y`: the user holds the role. A click turns the one into the other, and the two states are told apart by their letter as well as by their colour. A cell which differs from what the repository holds is outlined until it is saved. ## Setting a block of cells at once Press the mouse on a cell and drag to select an area; `Ctrl` adds a second area to the first and `Shift` extends one from the keyboard. A click inside a selected area moves every cell of it to the state after the one the cell pointed at moved to, so an area of mixed states ends up in one state - which is how a role is given to a whole department, or taken away from it. The right mouse button offers "Granted" and "Not Granted" by name, plus "Next Level" for the same step a click makes. A menu entry acts on the selected area when it is opened inside it, and otherwise on the one cell it was opened on. The toolbar carries the same two states as buttons: "Not Granted" and "Granted". A button sets the selected cells to its state, or the current cell when no cell is selected. The buttons make the matrix usable from assistive technology such as a screen reader, which reaches neither a click on a cell nor the menu of the right mouse button. They are not shown when the matrix is opened for reading only. A selected cell whose row or column has been left out of view is not changed, whichever of these ways sets the area. ## Finding a user or a role The search box narrows the matrix to what its text names, matched against the names of the users and of the roles at once. A text which names a role keeps every user and only the columns of that role; a text which names a user keeps every role and only the row of that user. The Escape key empties the box and shows the whole matrix again. Narrowing the matrix changes nothing about the roles: a cell which was changed and is no longer shown keeps its new value and is saved along with the rest. ## Leaving out what is granted nowhere The matrix is mostly empty: a user holds a handful of roles, so most of what stands on the screen is a row of `-`. Two boxes in the toolbar leave that out. - "Hide Columns Without a Value" leaves out every role which no user holds. - "Hide Rows Without a Value" leaves out every user who holds no role. The boxes work on what the search box leaves standing, so searching one role and leaving out the empty rows shows the users who hold that role and nobody else. What is left out keeps whatever was changed in it and is saved along with the rest. Nothing is recomputed while cells are being changed, so a cell which is set to nothing does not take its row away from under the mouse; clearing the box and ticking it again asks for a fresh answer. ## Saving "Save" writes the cells which differ from what the repository holds; the others cost no statement. Granting a role creates a user role, and withdrawing it deletes that user role again, which is also what the list under a user or a role does. Saving a large matrix takes a statement per changed cell and can be ended while it runs. The cells written before it was ended keep their new value; pressing "Save" again writes the remainder. ## Closing with Unsaved Cells Closing the window while some cells are not saved asks whether to save them. "Yes" saves the cells and then closes the window, "No" closes the window without saving, and "Cancel" keeps the window open. "Cancel" is the default answer, so pressing `Enter` neither saves nor discards anything. When saving is ended or fails, the window stays open and shows the cells which were not written. In release 27.0 closing the window discards the unsaved cells without asking. Also, a cell which is withdrawn, saved, granted again and saved in the same window shows as granted, but the grant is not created again; opening the matrix again shows the cell as not granted. Release 28.0 and its BETA release 27.1 correct both.