Create draft of Chapter 4 #15

CunliangGeng · 2024-04-23T14:58:12Z

Linked to issue #6: manage v6 projects with UI. 3 exercises are included.

Since I'm using a markdown formatter, ending spaces are automatically removed from the markdown files I changed.

github-actions · 2024-04-23T14:58:28Z

NOTE: This Pull Request (#15) was previously merged

bartvanb

I like the structure, I have a lot of minor comments. And unfortunately, I think part of the screenshots will need to be redone as we are currently changing the menu structure in the UI - see comments.

bartvanb · 2024-04-25T07:05:41Z

episodes/chapter4.md

@@ -0,0 +1,242 @@
+---
+title: "Using UI"


I would not abbreviate UI in the title, and put emphasis on that we want to manage the server. Maybe "Managing a vantage6 server via the user interface"?

bartvanb · 2024-04-25T07:08:32Z

episodes/chapter4.md

+
+- **User**: a person who can perform certain actions in Vantage6.
+    - A user can only belong to one **organization**.
+    - A user can have multiple **roles**.


Note that it is also possible to assign extra rules to a user - this is useful if they need one extra rule that isn't in a role (I used this feature for instance for you and Hector on Cotopaxi ;-) )

bartvanb · 2024-04-25T07:11:36Z

episodes/chapter4.md

+    - An organization can have zero and more **users**.
+    - An organization can have multiple **nodes**.
+- **Collaboration**: a collection of one or more **organizations**.
+    - Each participating **organization** needs a **node** to compute **tasks** for the **collaboration**.


Maybe clarify: "So if a collaboration has 3 organizations in it, there are also 3 nodes: one for each organization. If one of the organizations participates in another collaboration, they need a separate node for that collaboration" (this is often something people struggle with at the start)

bartvanb · 2024-04-25T07:12:18Z

episodes/chapter4.md

+    - A **study** is a subset of organizations from the collaboration that are involved in a specific research question. By setting up studies, it can be easier to send tasks to a subset of the organizations in a collaboration and to keep track of the results of these analyses.
+- **Role**: a collection of rules that define the permissions of a user.
+    - A user can have multiple roles.
+    - The permissions of the user are defined by the assigned **rules**.


I would clarify a bit more what rules are.

bartvanb · 2024-04-25T07:15:21Z

episodes/chapter4.md

+- **Role**: a collection of rules that define the permissions of a user.
+    - A user can have multiple roles.
+    - The permissions of the user are defined by the assigned **rules**.
+- **Node**: a server that can execute **tasks**.


I would call the node an application rather than a server to avoid confusion

bartvanb · 2024-04-25T07:32:30Z

episodes/chapter4.md

+![Create a new collaboration](fig/create_collab_01.png)
+
+4. Click on the `Submit` button to create the new collaboration.
+    * After submitting the form, you will see a dialog box to ask you to download the API key. The API key is used to authenticate the nodes in the collaboration. Later we will see how to reset the API key for a node.


The dialog will not ask you to download them but points out that they have been downloaded :-)

Wait, I guess the difference is that on Windows I don't get this box asking me to set the filename, but is just downloads it
Too bad I'm stuck with windows

I added the scenario for Windows.

bartvanb · 2024-04-25T07:35:27Z

episodes/chapter4.md

+    * You can also see the algorithm store available for the collaboration. You can add a algorithm store for the collaboration by clicking the `Add algorithm store` button.
+    * You can also see the studies of the collaboration. You can add a study by clicking the `Add study` button.
+
+![Collaboration details](fig/create_collab_03.png)


In my mind this figure shows a very minor bug: there are 2 organizations in the collaboration and 2 nodes, so the 'Register missing nodes' button should not be shown.
I put this on my list to fix this soon

bartvanb · 2024-04-25T07:38:36Z

episodes/chapter4.md

+>
+> Your API key has been reset. Please read your new key in the file that has been downloaded.
+
+


Add a short message like "At this point, put the new API key in your node configuration file and restart the node to connect to the server again.

bartvanb · 2024-04-25T07:48:52Z

episodes/chapter4.md

+::::::::::::::::::::::::::::::::::::: keypoints
+
+- Understand Vantage6 entities including `Users`, `Organizations`, `Collaborations`, `Roles`, `Nodes`, and `Tasks`
+- Understand Vanatge6 permission system and default roles such as `Root`, `Collaboration Admin`, `Organization Admin`, `Researcher`, and `Viewer`


vanatge6 is misspelled

bartvanb · 2024-04-25T07:53:18Z

episodes/chapter4.md

+- Understand Vanatge6 permission system and default roles such as `Root`, `Collaboration Admin`, `Organization Admin`, `Researcher`, and `Viewer`
+- Be able to create a new organization, a new user, and a new collaboration using the Vantage6 UI
+- Be able to reset an api key for a node
+


These key points are basically the same as the objectives. For key points, aren't we supposed to say stuff like 'The main vantage6 entities are ...'?

CunliangGeng

@bartvanb Thanks for your great comments! I have updated the material accordingly in one commit.

hcadavid

Apologies for the slow response to the pull request-review, but I needed to finish the previous episode to see to what extent these two overlap. As you will see in my comments, there is one part that I think could be moved to episode 3. My other comments are more in the line of how to use the steps in these challenges to reiterate on some conceptual stuff.

hcadavid · 2024-05-21T08:55:44Z

episodes/chapter4.md

+### Where are the entities in the UI?
+
+After logging in to the vantage6 UI, you will see the start page.
+
+![vantage6 UI start page](fig/ui_start_page.png)
+
+There are some collbarations displayed on the start page. Clicking one of the collaborations will show the tasks of that collaboration.
+
+![vantage6 UI tasks page](fig/ui_task_page.png)
+
+The start page also contains a button `Administration` in the top right corner. Clicking on this button will redirect you to the administration page.
+
+In the administration page, you can manage the entities of vantage6. The entities are divided into tabs: `Organizations`, `Collaborations`, `Roles`, `Users`, and `Nodes`. You can click on an entity to see more details or to edit the entity. We will get back to this later in more detail.
+
+![vantage6 UI administration page](fig/ui_admin_page.png)
+
+::::::::::::::::::::::::::::::::::::: challenge
+
+## Challenge 1: Get familiar with the vantage6 UI
+
+Log in to the vantage6 UI and navigate to the `Administration` page. Familiarize yourself with the entities in the administration page.
+
+Can you find the `Organizations`, `Collaborations`, `Roles`, `Users`, and `Nodes` tabs?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+


As expected, chapters 3 and 4, have some overlap as both require the participants to use the UI.

In particular, the previous chapter (Chapter 3) requires the participant to run an algorithm, which, in turn, requires them to understand which nodes belong to an existing collaboration. I think this first part could be moved to the beginning of Chapter 3. There is a review comment from @frankcorneliusmartin on Chapter 3 about basic UI explanation for which @CunliangGeng description/screenshots would fit perfectly.

Makes sense! You can move this part Where are the entities in the UI? to chapter 3, and then I'll remove it from chapter 4.

Sure! I'll take care of moving this to chapter 3.

hcadavid · 2024-05-21T09:19:05Z

episodes/chapter4.md

+Go the administration page in the vantage6 UI, check the permissions that you have, and answer the following questions:
+
+1. What is your role in vantage6?
+2. Can you create a new organization, a new user or a new collaboration?


To prevent misinterpretations (this question could be interpreted by participant as 'try to create an organization') I'd rephrase with something like:

Does the currently logged-in user have the privileges required to create:

An organization?

A new user?

A new collaboration?

I think it may be worth including more challenging questions. For instance, questions with scenarios that require participants to analyze also their 'edit' and 'delete' privileges (based on a user previously configured for this purpose). Something like ... 'Can you remove the collaboration after creating it?'

hcadavid · 2024-05-21T09:53:52Z

episodes/chapter4.md

+## Challenge 3: Manage vantage6 project using the UI
+
+Go the administration page in the vantage6 UI and try to create a new organization, a new user, and a new collaboration. Also, try to reset the API key for a node.


I think this challenge should make participants aware of what kind of privileges are they using time, in particular that the first steps are performed with 'root' privileges. Also, the participants should switch from this 'root' user to other less 'powerful/risky' ones as soon as possible.

For example, these steps could include the creation (as root) of an organization and then the creation of an administrator with collaboration-admin and organization-admin privileges. Once they have this user, they should use it for creating the collaborations, adding alg. stores. What do you think @bartvanb?

In my limited experience, there are issues if you create everything (in particular collaborations) with a root user and then try to do something with the other users.

hcadavid · 2024-05-21T10:18:54Z

episodes/chapter4.md

+### Create a new collaboration
+A collaboration is a collection of one or more organizations. Let's create a new collaboration between two organizations. Here are the steps:
+
+1. Click on the `Collaborations` tab in the administration page.
+2. Click on the `Create collaboration` button.
+3. Fill in the details of the new collaboration.
+    * For `Encrypted` box, you can select whether the collaboration should be encrypted or not.
+    * You can select the organizations that will participate in the collaboration by selecting them from the `Organizations` dropdown.
+    * By default, we select the `Register nodes` box. This will ensure the nodes of the organizations are registered in the collaboration. If you don't select this box, you will have to register the nodes manually later.


I think this part should make clear that this action is only the first step in creating a collaboration, and that enabling it needs participant nodes to register their corresponding keys on a v6-node. For learning purposes, it could also elaborate more on what the keys are for, and how are they related to the ER diagram above: each organization has a unique key for each collaboration; if an organization has multiple collaborations, it needs multiple nodes, each one with its corresponding key.

I think the ideal way of 'closing' this episode would be for the participants to set up a collaboration with working nodes and run an algorithm like they did in episode 3. However, that would require that somehow they register the keys on the nodes configuration. @CunliangGeng and @bartvanb just to open the discussion, as editing YAML files on a server terminal may be too advanced for this module, maybe this can be done by having a person or process dedicated to setup 'dummy' data nodes as needed by the participants' collaborations (who would simple provide the keys they got in the process)?

The chapter 4 targets at newbie, focusing on the UI. The setup of v6 node is described in chapter 6. I can add a few words here to redirect to chapter 6.

hcadavid · 2024-05-21T10:21:30Z

episodes/chapter4.md

+### Reset API key for a node
+If you want to reset the API key for a node, you can do so by following these steps:
+
+1. Click on the `Nodes` tab in the administration page.
+2. Click on the tab of the node you want to reset the API key for in the list of nodes.
+
+![Reset API key for a node](fig/reset_api_key_01.png)
+
+3. Click on the `Reset API key` button.
+    * You will see a dialog box to ask you to download the new API key.
+
+![Download new API key](fig/reset_api_key_02.png)
+


Based on my previous comment, I think more context should be given on what the implications of resetting the key are, and why or under which circumstances you would do that.

Auto-generated via {sandpaper} Source : 6d47321 Branch : main Author : Djura <djura.smits@gmail.com> Time : 2024-06-04 09:09:37 +0000 Message : Merge pull request #15 from vantage6/chapter4 Create draft of Chapter 4

Auto-generated via {sandpaper} Source : b1a9208 Branch : md-outputs Author : GitHub Actions <actions@github.com> Time : 2024-06-04 09:10:20 +0000 Message : markdown source builds Auto-generated via {sandpaper} Source : 6d47321 Branch : main Author : Djura <djura.smits@gmail.com> Time : 2024-06-04 09:09:37 +0000 Message : Merge pull request #15 from vantage6/chapter4 Create draft of Chapter 4

CunliangGeng self-assigned this Apr 23, 2024

CunliangGeng requested review from dsmits, hcadavid and bartvanb and removed request for dsmits April 23, 2024 14:58

github-actions bot pushed a commit that referenced this pull request Apr 23, 2024

differences for PR #15

85e408f

bartvanb reviewed Apr 25, 2024

View reviewed changes

github-actions bot pushed a commit that referenced this pull request Apr 25, 2024

differences for PR #15

a8cbfbc

CunliangGeng commented Apr 25, 2024

View reviewed changes

frankcorneliusmartin linked an issue May 14, 2024 that may be closed by this pull request

[Feature Request] Draft episode 4: Be able to manage v6 projects with the UI #6

Closed

hcadavid reviewed May 21, 2024

View reviewed changes

github-actions bot pushed a commit that referenced this pull request May 21, 2024

differences for PR #15

172f053

CunliangGeng added 4 commits June 4, 2024 11:09

Update config.yaml

d30da6c

create chatper4.md

64c8173

update chapter4 to solve reviewer's comments

7d667dd

rephrase challenge 2

dd3db6b

dsmits force-pushed the chapter4 branch from fa6cb30 to dd3db6b Compare June 4, 2024 09:09

dsmits merged commit 6d47321 into main Jun 4, 2024
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create draft of Chapter 4 #15

Create draft of Chapter 4 #15

CunliangGeng commented Apr 23, 2024 •

edited

Loading

github-actions bot commented Apr 23, 2024 •

edited

Loading

bartvanb left a comment

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

CunliangGeng Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

bartvanb Apr 25, 2024

CunliangGeng left a comment

hcadavid left a comment

hcadavid May 21, 2024

CunliangGeng May 21, 2024

hcadavid May 21, 2024

hcadavid May 21, 2024 •

edited

Loading

hcadavid May 21, 2024

hcadavid May 21, 2024

CunliangGeng May 21, 2024

hcadavid May 21, 2024

		>
		> Your API key has been reset. Please read your new key in the file that has been downloaded.

		## Challenge 3: Manage vantage6 project using the UI

		Go the administration page in the vantage6 UI and try to create a new organization, a new user, and a new collaboration. Also, try to reset the API key for a node.

Create draft of Chapter 4 #15

Create draft of Chapter 4 #15

Conversation

CunliangGeng commented Apr 23, 2024 • edited Loading

github-actions bot commented Apr 23, 2024 • edited Loading

bartvanb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CunliangGeng left a comment

Choose a reason for hiding this comment

hcadavid left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hcadavid May 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CunliangGeng commented Apr 23, 2024 •

edited

Loading

github-actions bot commented Apr 23, 2024 •

edited

Loading

hcadavid May 21, 2024 •

edited

Loading