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/).
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.
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.
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.
board_name: it’s the casual name (title) you give to a Boardboard_id: That’s the unique ID you see in the browser-link when watching your Board (i.e: https://<TEAM_DOMAIN>.upwave.io/board/board_id/view/...)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.
The upwaver package gives three basic functionalities to directly access UpWave information.
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("ims-fhs", "cb52b691defef3e689b47e4caa9fa24e0db6858b")
my_board_list$count## [1] 21## Length Class Mode
## count 1 -none- numeric
## next 0 -none- NULL
## previous 0 -none- NULL
## results 21 -none- list## Length Class Mode
## id 1 -none- numeric
## title 1 -none- character
## team 3 -none- list
## created_dt 1 -none- character
## created_by_user 5 -none- listUse board_details() to get detailed background Information about a specific board.
my_board_details <- upwaver::board_details("ims-fhs", 14310, "cb52b691defef3e689b47e4caa9fa24e0db6858b")
summary(my_board_details)## Length Class Mode
## id 1 -none- numeric
## title 1 -none- character
## 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- listUse 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("ims-fhs", 14310, "cb52b691defef3e689b47e4caa9fa24e0db6858b")
my_card_list$count## [1] 20## Length Class Mode
## count 1 -none- numeric
## next 0 -none- NULL
## previous 0 -none- NULL
## results 20 -none- list## Length Class Mode
## id 1 -none- numeric
## board 2 -none- list
## title 1 -none- character
## 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 5 -none- list
## 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- listAn 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("ims-fhs", 14310, "cb52b691defef3e689b47e4caa9fa24e0db6858b")
my_storypoints$storypoints_status## title status storypoints
## 1 US22 - Bestehende Touren modifizieren 0 0
## 2 US21 - Touren planen (5) 0 0
## 3 US20 - Zielfunktion definieren 0 0
## 4 US19 - Touren planen (4) 0 0
## 5 US18 - Entwicklung einer Zeit-/Distanzmatrix 0 10
## 6 US17 - Milestone Workshop zur Diskussion 0 10
## 7 US16 - Touren planen (3) 2 0
## 8 US15 - Optimierungs-Job entgegennehmen 3 Completed
## 9 US14 - Stammdaten entgegennehmen 3 Completed
## 10 US13 - Daten des Optimierungs-Jobs bereitstellen 3 Completed
## 11 US12 - Stammdaten bereitstellen 0 10
## 12 US10 - Touren planen (2) 2 0
## 13 US9 - Zulässigkeit des Tourenplans prüfen 2 0
## 14 US8 - Verfügbare Ressourcen bestimmen 2 10
## 15 US7 - Bereitstellung der Testdaten Camion 3 Completed
## 16 US6 - Touren planen (1) 3 Completed
## 17 US4 - einfache, syntethische Testfälle erstellen 3 Completed
## 18 US3 - Definition der Rückgabeobjekte 3 Completed
## 19 US2 - IMS-Datenmodell validieren 2 0
## 20 US1 - IMS-Datenmodell erstellen 3 Completed## [1] 40For 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:
US-ID: The Number you want to give to your Card (Userstory)name: The name (title) of your Userstorydescription: The description of your Userstory# 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