Update documentation for tutorial, fusion and jira (#3265)

* Minor fixes to tutorial documentation

* Update studio screenshots and instructions

* Add Jira documentation

* Update additional studio screenshots

Co-authored-by: Dhanesh Neela Mana <[email protected]>

docs/src/main/paradox/docs/faq.md

@@ -13,7 +13,7 @@ Yes, Nexus is a free, Open Source platform released under @link:[Apache Licence
 
 ### How do I run Blue Brain Nexus?
 
-There are many ways to run Nexus. Our public Sandbox is running @link:[here](https://sandbox.bluebrainnexus.io/web/){ open=new } 
+There are many ways to run Nexus. Our public Sandbox is running @link:[here](https://sandbox.bluebrainnexus.io){ open=new } 
 and you can use it to test Nexus on small, non-sensitive data. Our @ref:[tutorial](getting-started/try-nexus.md) can 
 help you to run Nexus step by step.
 
@@ -24,7 +24,7 @@ Blue Brain Nexus has also been deployed and tested on AWS using @link:[Kubernete
 
 ### How can I try Blue Brain Nexus without installing it? 
 
-The @link:[Sandbox](https://sandbox.bluebrainnexus.io/web/){ open=new } provides a public instance that can serve as a 
+The @link:[Sandbox](https://sandbox.bluebrainnexus.io){ open=new } provides a public instance that can serve as a 
 testbed. Be aware that the content of the Sandbox is regularly purged.
 
 ### What is the difference with a relational database like PostgreSQL?

docs/src/main/paradox/docs/fusion/plugins.md

@@ -140,11 +140,47 @@ The following will show `nexus-plugin-test` for any resource of type `File` but
 
 ## Default Plugins
 
-Default plugins are part of Fusion. They define the default presentation of resources.
+Default plugins are part of Fusion.
 
-### Admin Plugin
+### Advanced View Plugin
 
-Admin Plugin displays JSON-LD in a code editor. If the user has edit access to the document, they can update the 
+The Advanced View Plugin displays JSON-LD in a code editor. If the user has edit access to the document, they can update the 
 resource in the editor. It also has few additional tabs. History, Links and Graph. History tab displays the edit 
 history of the resource. A user can explore the graph view of the resource in Graph tab. They can also view the 
-incoming and out going links of the resource in Links tab.
+incoming and outgoing links of the resource in Links tab.
+
+### Jira
+
+The Jira plugin enables integration with an instance of Jira to facilitate discussions about resources. The Jira plugin must be enabled in Nexus Delta and configured in the Fusion Deployment. Links between a Jira issue and a Nexus resource (or project) are stored in custom fields in Jira which are required to be configured before usage. It is the Nexus URL that is used to link to the resource. Issues created with the Jira plugin have a discussion label applied to them in Jira.
+
+#### Configuration
+
+See the accompanying Delta Jira documentation for configuration of the Jira plugin in Delta and linking it with a Jira instance. In Fusion, there are several environment variables related to Jira that must be specified in order to configure its usage.
+
+* JIRA_URL - URL of jira instance
+* JIRA_RESOURCE_FIELD_NAME - the name of the custom field in Jira to use for storing the link to the Nexus resource
+* JIRA_RESOURCE_FIELD_LABEL (defaults to `Nexus Resource`) - the label of the custom field in Jira being used for storing the link to the Nexus resource
+* JIRA_PROJECT_FIELD_NAME - the name of the custom field in Jira to use for storing the link to the Nexus project
+* JIRA_PROJECT_FIELD_LABEL (defaults to `Nexus Project`) - the label of the custom field in Jira being used for storing the link to the Nexus project
+
+The custom fields in Jira should be created as `URL` type field and should be added to the required Jira screens and projects that you want to use with Nexus.
+
+#### Authorization
+
+The user will be required to authorize access to Jira prior to being able to use the Jira plugin in Fusion. From the Jira plugin the user is instructed to click the link to authorize access in Jira and then will be required to enter the provided verification code in Fusion to complete the authorization.
+
+![Jira Authorization](../assets/jira-resource-plugin-authenticate.png)
+
+#### Usage
+
+The Jira plugin is displayed for all resources, given that it's enabled. A resource can be linked to an issue in Jira from within the Jira plugin in Fusion by either choosing to create a new issue or by linking to an existing Jira issue.
+
+Multiple issues can be associated with a resource and they will display in the table of linked resources in the Jira plugin. Issues can be removed from here also.
+
+![Nexus Resource with linked Jira issue](../assets/jira-resource-plugin-with-issue.png)
+
+#### Project view
+
+Besides the Jira plugin displaying in the Resource view, there is also a Jira plugin at the level of the project. It can be accessed via the Jira tab in the project view. In the Jira project view, all issues linked to resources within the project are listed along with their associated resource. Similar functionality to the Jira plugin on the resource is available here with the option to add/remove issues. Note that issues created within the Jira plugin at the project level are associated with the project only.
+
+![Jira Project plugin](../assets/jira-project-plugin.png)

docs/src/main/paradox/docs/fusion/studio.md

@@ -184,7 +184,7 @@ To remove an unwanted `Studio`, deprecate it in the Resource View of your projec
 
 ### Workspace Creation
 
-Inside any `Studio`, click the `Add Workspace` button.
+Inside any `Studio`, click the `Workspace` button followed by `Add` to add a new workspace.
 
 Fill in a form providing the following:
 
@@ -208,14 +208,10 @@ You can also find your `Workspaces` as raw `JSON` configurations in the `Resourc
 
 #### Updating a Workspace
 
-Inside any `Studio`, under a `Workspace` tab label, click on the `Edit` link. Then you'll be provided with a dialog where 
-you can review and edit the `Workspace` configuration.
+Inside any `Studio`, with the desired `Workspace` selected from the menu, click on `Workspace`, then the `Edit` button. Then you'll be provided with a dialog where you can review and edit the `Workspace` configuration.
 
-- `Select View`: The view of which to pair with _each `Dashboard` inside the follow transfer list_. The `Dashboard` 
-- queries will be run against the `View` listed inside this box. For now, using this Edit form, you can only pair one 
-- `View` for all `Dashboards`. If you were to create the configurations manually, you can pair each `Dashboard` with a different `View`.
 - `Add or Remove Dashboards`: Add or remove a `Dashboard` to the collection in your `Workspace` configuration. The `Dashboards` listed are all the available non-deprecated ones in the project.
-- `Name`: the name of your new `Workspace` (required field).
+- `Label`: the name of your new `Workspace` (required field).
 - `Description` for your `Workspace`.
 
 @@@ div { .half .center }
@@ -226,11 +222,11 @@ After your forms have been edited, simple click `Save` to submit your changes.
 
 #### Removing a Workspace
 
-You can remove a `Workspace` by deprecating it from the `Resource View`.
+You can remove a `Workspace` by navigating to the workspace and then clicking the `Workspace` button followed by `Remove`. Click `OK` in the dialog to confirm removal.
 
 ### Dashboard Creation
 
-Inside any `Studio View`, under a selected `Workspace`, click the `Add Dashboard` button.
+Inside any `Studio View`, under a selected `Workspace`, click the `Dashboard` button followed by `Add`.
 
 Fill in the Create Dashboard form providing the following:
 
@@ -312,55 +308,6 @@ WHERE {
 LIMIT 20
 ```
 
-## Configuring the Studios index page
-
-The Studios space lists all the `Studios` you have permissions to view or edit.
-
-@@@ div { .half .center }
-![Studios Index Page](../assets/fusion-studio-index-page.png)
-@@@
-
-To enable this feature, the following should be done:
-
-1. If you don't have a project to store the application data, create one.
-
-2. Create an `Aggregated Elastic Search View` inside this project, and add all projects that contain Studio resources to the list. For example:
-
-```json
-{
- "@context": "https://bluebrain.github.io/nexus/contexts/view.json",
- "@id": "nxv:studioList",
- "@type": ["View", "AggregateElasticSearchView"],
- "views": [
- {
- "project": "c7d70552-4305-111a-trtr-75d757ed9a49",
- "viewId": "nxv:defaultElasticSearchIndex"
- },
- {
- "project": "86b0ee1e-a6a5-111b-rtrt-938b3c38dfc0",
- "viewId": "nxv:defaultElasticSearchIndex"
- },
- {
- "project": "a7d693345-8d1d-rtrt-111a-90b6b6ab94ee",
- "viewId": "nxv:defaultElasticSearchIndex"
- }
- ]
-}
-```
-
-@@@ note
-
-Ask a developer to add an ENV variable with the location of the 'AggregateElasticSearchView' as following:
-
-`STUDIO_VIEW=[yourOrgLabel]/[yourProjectLabel]/[viewId]`
-
-In our example, it would be:
-
-`STUDIO_VIEW=webapps/nexus-fusion/nxv:studioList`
-
-Every time when you create a new `Studio`, the `AggregateElasticSearchView` needs to be updated.
-@@@
-
 ## Studio Description
 
 Every Studio deserves a beautiful description to highlight its data. We've included a Description Viewer above the 

docs/src/main/paradox/docs/getting-started/notebooks/MOOC_Content_based_Recommender_System_using_Blue_Brain_Nexus.ipynb

@@ -113,9 +113,9 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io/web) can be used to get a token:\n",
+ "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io) can be used to get a token:\n",
  "\n",
- "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io/web), click on the login button in the top right corner and follow the instructions on screen.\n",
+ "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io), click on the login button in the top right corner and follow the instructions on screen.\n",
  "\n",
  "- Step 2: You will then see a `Copy token` button in the top right corner. Click on it to copy the token to the clipboard.\n",
  "\n",

docs/src/main/paradox/docs/getting-started/notebooks/building_a_kg.ipynb

@@ -95,7 +95,7 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "TOKEN = getpass.getpass() # Provide your Blue Brain Nexus token. It can be obtained after login into the sandbox: https://sandbox.bluebrainnexus.io/web/"
+ "TOKEN = getpass.getpass() # Provide your Blue Brain Nexus token. It can be obtained after login into the sandbox: https://sandbox.bluebrainnexus.io"
  ]
  },
  {

docs/src/main/paradox/docs/getting-started/notebooks/dataset_from_different_sources.ipynb

@@ -64,9 +64,9 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io/web) can be used to get a token:\n",
+ "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io) can be used to get a token:\n",
  "\n",
- "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io/web), click on the login button in the top right corner and follow the instructions on screen.\n",
+ "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io), click on the login button in the top right corner and follow the instructions on screen.\n",
  "\n",
  "- Step 2: You will then see a `Copy token` button in the top right corner. Click on it to copy the token to the clipboard.\n"
  ]

docs/src/main/paradox/docs/getting-started/notebooks/one_cell_minds.ipynb

@@ -64,9 +64,9 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io/web) can be used to get a token:\n",
+ "The [Nexus sandbox application](https://sandbox.bluebrainnexus.io) can be used to get a token:\n",
  "\n",
- "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io/web), click on the login button in the top right corner and follow the instructions on screen.\n",
+ "- Step 1: From the [web page](https://sandbox.bluebrainnexus.io), click on the login button in the top right corner and follow the instructions on screen.\n",
  "\n",
  "- Step 2: You will then see a `Copy token` button in the top right corner. Click on it to copy the token to the clipboard.\n"
  ]

docs/src/main/paradox/docs/getting-started/running-nexus/index.md

@@ -13,7 +13,7 @@ For a production deployment on your in-house or cloud infrastructure, please ref
 
 ## Using the public sandbox
 
-A public instance of Nexus is running at @link:[https://sandbox.bluebrainnexus.io/web](https://sandbox.bluebrainnexus.io/web){ open=new }. 
+A public instance of Nexus is running at @link:[https://sandbox.bluebrainnexus.io](https://sandbox.bluebrainnexus.io){ open=new }. 
 You can log in with a GitHub account. It's provided for evaluation purposes only, without any guarantees.
 
 The API root is @link:[https://sandbox.bluebrainnexus.io/v1](https://sandbox.bluebrainnexus.io/v1){ open=new }.

docs/src/main/paradox/docs/getting-started/try-nexus.md

@@ -114,7 +114,7 @@ We run the latest version of Nexus publicly for education. You can also use the
 
 ### 1.1. Using the Sandbox
 
-The @link:[Sandbox](https://sandbox.bluebrainnexus.io/web/){ open=new } is a deployment of Nexus for educational purposes.
+The @link:[Sandbox](https://sandbox.bluebrainnexus.io){ open=new } is a deployment of Nexus for educational purposes.
 
 Once on the Sandbox homepage, click on the top right corner on the login button.
 
@@ -279,7 +279,8 @@ You will now be presented with all the data that has been indexed across all pro
 ![Sandbox Home](../assets/tutorial-sandbox-search.png)
 @@@
 
-Each of the rows of this table represent Knowledge Graph entities that we have decided to expose, including some specific metadata describing them (the columns). You can now click on any rows in this table to open the corresponding dataset and look into its details:
+Each of the rows of this table represent Knowledge Graph entities that we have decided to expose, including some specific metadata describing them (the columns). You can now click on any row in this table to open the corresponding dataset and look into its details.
+
 @@@ div { .center }
 ![Sandbox Home](../assets/tutorial-sandbox-search-resource.png)
 @@@
@@ -563,7 +564,7 @@ You can learn more about SPARQL in the @link:[official documentation](https://ww
 
 As you saw in the example above, we can use SPARQL to query the cells in our Nexus project.
 
-Let's start by accessing your Nexus instance or the @link:[Sandbox](https://sandbox.bluebrainnexus.io/web/){ open=new }. Go to Admin page (from the left hand side menu), and navigate to your organization and project.
+Let's start by accessing your Nexus instance or the @link:[Sandbox](https://sandbox.bluebrainnexus.io){ open=new }. Go to Admin page (from the left hand side menu), and navigate to your organization and project.
 
 > In the Sandbox, the organization corresponds to the identity provider used, and the project to your username. For example, if you used GitHub, the organization will be `github-users` and your project will be your GitHub username.
 
@@ -585,7 +586,7 @@ Depending on the resource data type, you might see one or more "plugins". Plugin
 ![Morphology Plugin](../assets/tutorial-morphology-plugin.png)
 @@@
 
-More importantly, you will find the Admin plugin at the bottom of the view. Expand it and you will see the actual resource payload stored by Nexus, and navigate the graph through links, or visualize the surrounding graph in the graph tab.
+More importantly, you will find the Advanced view plugin at the bottom of the view. Expand it and you will see the actual resource payload stored by Nexus, and navigate the graph through links, or visualize the surrounding graph in the graph tab.
 
 @@@ div { .center }
 ![Admin Plugin](../assets/tutorial-admin-plugin.png)
@@ -753,29 +754,21 @@ You will land on:
 
 On this page you can create a new studio. A Studio is a dedicated web page in your project that you can organise into pages (workspaces, as horizontal tabs at the top) and sections (dashboards, as vertical tabs on the left side) and list your data in a logical way. The tables are powered by SPARQL queries and the data present in your project.
 
-@@@ div { .center }
-![Sandbox Home](../assets/tutorial-sandbox-studio-empty.png)
-@@@
-
-Start by creating a Workspace.
+Start by creating a Workspace. To create a workspace, click the Workspace button and in the menu that appears click Add Workspace. You will be presented with a dialog requesting the label of the workspace and optionally a description. Enter a label of your choosing and click Save.
 
 @@@ div { .center }
 ![Sandbox Home](../assets/tutorial-sandbox-studio-one-workspace-no-dashboard.png)
 @@@
 
-Then create a Dashboard, using the SPARQL query above.
+Next, create a Dashboard. Click the Dashboard button and choose Add from the pop-up menu. In the Dashboard creation dialog, specify the default Sparql Index view and specify the SPARQL query above. The 'Preview' button will list the columns to be returned by the query and support specifying options on the columns such as enabling searching or sorting.
 
 @@@ div { .center }
 ![Sandbox Home](../assets/tutorial-sandbox-studio-one-workspace-one-dashboard.png)
 @@@
 
 Because we are using the self, clicking on a row of the newly created table will open the resource view.
 
-It's your turn now to add a dashboard to list your Neuron Electrophysiology data. Create the dashboard and modify the SPARQL query above. The results should look like this:
-
-@@@ div { .center }
-![Studio Traces](../assets/tutorial-sandbox-studio-one-workspace-two-dashboards.png)
-@@@
+It's your turn now to add a dashboard to list your Neuron Electrophysiology data. Create the dashboard and modify the SPARQL query above.
 
 Congratulations! You've created your very first studio, which completes this tutorial step.