gin-scripts/tonic-PLAN.Rmd

---
title: "Adding tonic to gin: the plan"
author: "colomb_julien"
date: "8/6/2020"
output: 
  bookdown::html_document2:
    keep_md: yes
    toc: true
  
---

```{r, echo=FALSE}
botname = "tonic-bot"
RAT = "read-access-team"
WAT = "write-access-team"
```

# Overview

TONIC: Templates for organizing nifty information containers


GIN users will use their GIN credential to login to the tonic application. In this application, they will be able to perform some function that are either complex (requiring many steps) and/or functions they do not have the access rights to perform. In the backend, the application will login to GIN using the `r botname`. 

`r botname` will create organisation, teams and repositories on behalf of the loged-in user. In order to use the application on existing repositories or organisations, one needs to add `r botname`  as a collaborator on a repository, or as an owner of an organisation (this step is automatized when `r botname` is creating them).

Instead of creating simple repositories, `r botname` creates research repositories (RR): these repositories are created from a template and include submodules (themselves created from templates). Submodules allow for a differentiation of access rights and easy publication of part of a repository.

# Information available from login

After login, the application will know the user's credential, and can therefore access the metadata associated and find:

- organisations where he is a member, and `r botname` is an owner.
- organisation that are lab-organisation (i.e have the 2 default teams)
- repositories were he and `r botname` has write access to

# Administration functions

## Create new lab-organisation ()

The principle is to create an organisation, where `r botname` and the logged-user will become owners. The organisation also get two teams per default: the `r RAT` and the `r WAT`, with read and write access rights respectively.

- Problem: the bot would need admin access, or the API must change to create the organisation.
- createteam seems not to work here.
- putative problem: what if there is already an organisation with that name ?



Create the organisation:
(code not working: no admin access)

```{bash, results='hide'}
. setgin.sh
## create an organisation, with bot

botname="jcolomb"
loginuser="bruce-wayne"

#Inputs

thisorga="testorga"

createorga(){
  organame=$1
    data="{\"username\":\"${organame}\",\"Description\":\"${organame}\"}"
    echo post ${data} ${ginhost}/api/v1/admin/users/${botname}/orgs
}

createorga ${thisorga}
#POST /admin/users/:username/orgs
# username	string	Required Organization user name
# full_name	string	Full name of organization
# description	string	Description to the organization
# website	string	Official website
# location	string	Organization location
```

Add login user as organisation owner:
(code not working, probably because put does not work ?)

```{bash}
. setgin.sh

botname="jcolomb"
loginuser="bruce-wayne"
thisorga="testorga"

addusertoorga(){
  organame=$1
  user=$2
    data="{\"role\":admin}"
    echo put ${data} ${ginhost}/api/v1/orgs/${organame}/memberships/${user}
}

addusertoorga ${thisorga} ${loginuser}
```

Create the teams:

```{bash}
. setgin.sh

botname="jcolomb"
loginuser="jcolomb"
thisorga="testorga"


createteam() {
    teamname=$1
    organisation=$2
    permission=$3
    
    data="{\"name\":\"${teamname}\",\"description\":\"default team\",\"permission\":\"${permission}\"}"
    #post ${data} ${ginhost}/api/v1/orgs/${organisation}/teams
    echo post ${data} ${ginhost}/api/v1/orgs/${organisation}/teams
}

createteam readaccess ${thisorga} read
createteam writeaccess ${thisorga} admin


```


## Add members to a lab-organisation ()

Here, we will add the member to an organisation, with member permission and add him to the default teams.

- choose an organisation from the list
- add username of user to add (could use the same search GIN has)

```{bash}
## add someone to organisation + teams
. setgin.sh
botname="jcolomb"
loginuser="bruce-wayne"

#Inputs:
thisorga="testorga"
newuser="bruce-wayne"

# PUT /orgs/:orgname/memberships/:username
# role="member"


addusertoorga_m(){
  organame=$1
  user=$2
    data="{\"role\":member}"
    echo put ${data} ${ginhost}/api/v1/orgs/${organame}/memberships/${user}
}

addusertoorga_m ${thisorga} ${newuser}

## for each team:
#PUT /admin/teams/:teamid/members/:username

addusertoteam(){
  organame=$1
  teamname=$2
  user=$3
    teamlist="GET /orgs/${organame}/teams"
    teamid="id from teamlist with name==teamname"
    
    data="{\"role\":member}"
    echo put ${data} ${ginhost}/api/v1//admin/teams/${teamid}/members/${user}
    
}

addusertoteam ${thisorga} readaccess ${newuser}
addusertoteam ${thisorga} writeaccess ${newuser}

# PS there is no way to get all members of an organisation ?
```


# Repository functions

## Overview of research repositories

We call the research repository, a GIN repository created from a template folder structure developed for (neuro-)research, and that hosts submodules. The user may be able to select submodules and templates, during or after the creation of the research repository.

Because users must get access to all repository at once, each research repository comes with its team, which get admin access to the parent repository and all submodules.


## Create research repository ()

### user inputs

- RR name
- main template for parent repository (may include some submodules)
- (optional) existing team to add the new RR

message: additional submodules (for data for instance) may be added later

### create repository

- check that name is available
- if no exisiting team has been indicated: create a new team (add _1 if name unavailable)
- create repository
- add repository to team (indicated or newly created)
- downlaod repository on /temp
- clone template into it
- sync to gin (change remote URL to project repo, git annex init)
- add default submodules (see below)
- set git annex 
- sync to gin (change remote URL to project repo, git annex init)

## Add existing (lab) submodule to a research repository ()

input: 

- submodule address
- folder name in parent repository

logic:

- if needed: download repository on /temp
- add submodule with git submodule add
- sync to gin

## Add specific submodule to a research repository ()

- input: submodule template + folder name in parent repository +  parent repository
- automatic extra: teamid of team with write access to parent repository

logic:

- create submodule repository
- disable issue-tracker
- add repository to team (indicated or newly created)
- downlaod repository on /temp
- clone template into it (including git-annex behavior)
- sync to gin (change remote URL to project repo, git annex init)
- add submodule to parent repository (see above)

## Clone research repositories ()

- clone parent repository
- update submodules