upwaver

Adrian Stämpfli and Michael Schmid, IMS-FHS

2019-04-15

‘upwaver’ is a wrapper around the ‘Upwave’ API that allows users to access the ‘Upwave’ API from within R.

While using ‘Upwave’ (https://www.upwave.io/) you might come to a point where you want to extract detailed information of ongoing projects or you might want to upload Cards to certain Boards directly out of a Excel sheet. ‘upwaver’ is a small tool to solve such problems without copy-pasting a lot of content.

The package was designed based on the given ‘Upwave’ API (https://upwavehq.github.io/api/).

Basics about ‘Upwave’ and ‘upwaver’

Your Domain

Each organisation (company, team) with an ‘Upwave’ account has its own <TEAM_DOMAIN>. You can see this on the frontpage of your ‘Upwave’ account: (https://<TEAM_DOMAIN>.upwave.io). The ‘upwaver’ package refers to this <TEAM_DOMAIN> as organisation.

Authentication

To access information of your account (domain), you need an access token. It can be obtained by visiting your account settings. Click your profile image, select “Settings” and find your API-Key in the “Account” tab. The ‘upwaver’ package refers to the API-Key as token.

Boards

An ‘Upwave’ account consits of different Boards (projects) on which an organisation works simultaneously. The ‘upwaver’ package identifies a Board with the board_id and board_name.

Cards

Each Board consits of different Cards which can be seen as lots of “work packages”. The contain Information about the actual tasts to do inside the project. They are the objects to talk to when using ‘upwaver’

Getting Board- & Card- information from ‘Upwave’

The ‘upwaver’ package gives three basic functionalities to directly access ‘Upwave’ information.

List of Boards

Use list_boards() to get a list of all boards of your organisation. Archived boards will not be shown in this list.

my_board_list <- upwaver::list_boards("4597", "807a0c3451c04602b4dbfdc0338a65f7")
my_board_list$count
## [1] 2
summary(my_board_list)
##          Length Class  Mode   
## count    1      -none- numeric
## next     0      -none- NULL   
## previous 0      -none- NULL   
## results  2      -none- list
summary(my_board_list$results[[1]])
##                      Length Class  Mode     
## id                   1      -none- numeric  
## title                1      -none- character
## access               3      -none- list     
## team                 4      -none- list     
## background_image_url 1      -none- character
## created_dt           1      -none- character
## created_by_user      5      -none- list

Board details

Use board_details() to get detailed background Information about a specific board.

my_board_details <- upwaver::board_details("4597", 14351, "807a0c3451c04602b4dbfdc0338a65f7")
summary(my_board_details)
##                            Length Class  Mode     
## id                         1      -none- numeric  
## title                      1      -none- character
## access                     3      -none- list     
## purpose                    1      -none- character
## background_image_url       1      -none- character
## background_image_thumb_url 0      -none- NULL     
## created_dt                 1      -none- character
## created_by_user            5      -none- list     
## columns                    3      -none- list     
## rows                       1      -none- list     
## colors                     3      -none- list     
## rows_enabled               1      -none- logical  
## plugin_type                1      -none- character

List of Cards

Use list_cards() to get detailed Information about all Cards of a specific board. This includes cards that are marked as completed.

my_card_list <- upwaver::list_cards("4597", 14351, "807a0c3451c04602b4dbfdc0338a65f7")
my_card_list$count
## [1] 19
summary(my_card_list)
##          Length Class  Mode   
## count     1     -none- numeric
## next      0     -none- NULL   
## previous  0     -none- NULL   
## results  19     -none- list
summary(my_card_list$results[[1]])
##                  Length Class  Mode     
## id               1      -none- numeric  
## title            1      -none- character
## access           3      -none- list     
## board            2      -none- list     
## description      1      -none- character
## cover_image_url  1      -none- character
## color            3      -none- list     
## state            1      -none- numeric  
## due_dt           0      -none- NULL     
## created_dt       1      -none- character
## created_by_user  0      -none- NULL     
## archived_dt      0      -none- NULL     
## finished_dt      0      -none- NULL     
## finished_by_user 0      -none- NULL     
## assigned         0      -none- list     
## watched          1      -none- logical  
## num_comments     1      -none- numeric  
## num_attachments  1      -none- numeric  
## progress         2      -none- list

Getting Storypoints-Information from ‘Upwave’

An additional feature of upwaver is the storypoints_and_status() function. It’s was designed by our institue for internal reasons. Nevertheless it might be useful for your organisation as well.

If working with agile methods (i.e. SCRUM, agile testing, ASD, …) you might want to work with storypoints in order to estimate time resources. Our institute works with storypoints in the following way. Each ‘Upwave’ Card has a short text at the bottom the Card description that says:
“Aufwand: X SP” or “Aufwand: X AT” as an indicator for the estimated storypoints. The value X, title and status of every Card is be caught by storypoints_and_status() and given as a list.

my_storypoints <- upwaver::storypoints_and_status("4597", 14351, "807a0c3451c04602b4dbfdc0338a65f7")
my_storypoints$storypoints_status
##                                               title status storypoints
## 1                   US12 - Stammdaten bereitstellen      1           8
## 2          US17 - Milestone Workshop zur Diskussion      1           5
## 3      US18 - Entwicklung einer Zeit-/Distanzmatrix      1           1
## 4              US19 - Touren planen (4)"Feasable 2"      1           2
## 5                    US20 - Zielfunktion definieren      1           3
## 6                    US21 - Touren planen (5)"Good"      1           1
## 7             US22 - Bestehende Touren modifizieren      1           5
## 8                  US2 - IMS-Datenmodell validieren      2           8
## 9             US8 - Verfügbare Ressourcen bestimmen      2           8
## 10        US9 - Zulässigkeit des Tourenplans prüfen      2           2
## 11               US10 - Touren planen (2)"Feasable"      2           3
## 12                  US1 - IMS-Datenmodell erstellen      3   Completed
## 13             US3 - Definition der Rückgabeobjekte      3   Completed
## 14 US4 - einfache, syntethische Testfälle erstellen      3   Completed
## 15                          US6 - Touren planen (1)      3   Completed
## 16        US7 - Bereitstellung der Testdaten Camion      3   Completed
## 17 US13 - Daten des Optimierungs-Jobs bereitstellen      3   Completed
## 18                 US14 - Stammdaten entgegennehmen      3   Completed
## 19           US15 - Optimierungs-Job entgegennehmen      3   Completed
my_storypoints$sum_storypoints
## [1] 46

Create a Userstory (Card) on ‘Upwave’

For own puposes we created a function that directly uploads Userstorys to the leftmost column of a desired Board from a local excel file. This might me helfpul when a list of basic tasks has been defined in an exel-sheet during a meeting or similar and you don’t want to copy paste it all into ‘Upwave’

The function needs several input parameters to coordinate the source (excel file) with the desired ‘Upwave’ Board. Keep in mind that the excel file needs the following three columns:

# create_card_from_excel(
#   excel_file = "path_to_your_excel_file", 
#   sheet = "name_of_the_excel_sheet" or number_of_the_excel_sheet, 
#   line_number = line_nr_you_want_to_upload, 
#   organisation = "your_organisation", 
#   board_id = your_board_id, 
#   board_name = "your_board_name", 
#   token = "your_token")

To upload several Cards, we recomment a simple for-loop

# for (i in 1:30) {
#   create_card_from_excel(..., line_number = i, ...)
# }