-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
96 lines (65 loc) · 3.69 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/",
out.width = "100%"
)
highbond_openapi <- Sys.getenv('highbond_openapi')
highbond_org <- Sys.getenv('highbond_org')
highbond_datacenter <- Sys.getenv('highbond_datacenter')
highbond_table <- Sys.getenv('results_table_readme')
```
# galvanizer
<!-- badges: start -->
<!-- badges: end -->
galvanizer is a package designed to interact to Highbond's API (https://docs-apis.highbond.com). By using R with galvanizer, you can download data from Highbond's Results and Project modules. For Highbond Results, you can also process data locally and upload data into Highbond Result tables.
## Installation
You can install the currently available version of galvanizer from [CRAN](https://cran.r-project.org/package=galvanizer):
``` {r eval=FALSE}
# Release:
install.packages('galvanizer')
# Development version:
# devtools::install_github("jonlinca/galvanizer")
```
## Getting started
Before using the API, you will need some core information to access your Highbond instance. They are:
* Highbond API token
* Organization number
* Data Center location
To generate a Highbond API token from your Highbond instance by referencing the [help files](https://help.highbond.com/helpdocs/highbond/en-us/Content/launchpad/getting_started/managing_access_tokens.html). This can be found on your profile page.
![generate API token](man/figures/generate_token.png)
To identify your organization number and data center, best found from your Launchpad, under Options / Organization. The organization number will be under the format of `https://accounts.highbond.com/orgs/<ORGANIZATION_ID>/details`
To use any functions, you will need to create and pass a Highbond Authentication object. You can make it by passing the API token, organization / instance number and data center location to `setup_highbond()`:
```{r}
library(galvanizer)
highbond_auth <- setup_highbond(highbond_openapi, highbond_org, highbond_datacenter)
```
## Highbond Results data
Once you have those, then you need to identify the table you want to upload and download data from. The easiest way to do this is to navigate to the Results Data Analytic table you want to upload and grab the `TABLE_ID` from the URL. It will look like:
`https://<company_name>.results.highbond.com/projects/<COLLECTION_ID>/controls/<ANALYSIS_ID>/control_tests/<TABLE_ID>`
You can choose to upload a set of test data into a new Data Analytic to try this out:
```{r, message=FALSE}
upload <- data.frame(name = c('Cowbell', 'Rufus'),
age = c(21, 32),
active = c(TRUE, FALSE),
date_started = c(as.Date('2019-01-01'), as.Date('2020-01-01')),
date_ended = c(as.POSIXct(Sys.time()), as.POSIXct(Sys.time())))
# Substitute your API key, org number, data, center, table, and the dataframe to be uploaded
post_results_records(highbond_auth, highbond_table, upload = upload, purge = TRUE)
```
Once that has successfully uploaded into Highbond Results, you can view the results online and also download the new data too:
![successful results upload](man/figures/highbond_results_upload.png)
```{r}
download <- get_results_records(highbond_auth, highbond_table)
head(download$content$data)
```
## Highbond Projects data
Highbond Projects data (also known as 'Audits') is also retrievable, depending on which screen of information you would like to retrieve from. There are options to download all or just one set of information, depending on the pane chosen.
```{r, eval=FALSE}
projects <- get_projects(highbond_auth)
```