---
title: "Getting started with dhis2r"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with dhis2r}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(httptest2)
start_vignette("dhis2r")
```

```{r setup}
library(dhis2r)
```


Connect to the DHIS2 instance using `Dhis2r$new()`

In this vignette I used a Personal Access Token (PAT) as a more secure alternative to HTTP Basic Authentication, and should be your preferred choice when creating a new app/script etc. 

```{r}
dhis2_play_connection <- Dhis2r$new(base_url = "https://play.im.dhis2.org/stable-2-40-5",
                                    username = "admin",
                                    password = "district")
```



``` r
dhis2_play_connection <- Dhis2r$new(base_url = "https://play.im.dhis2.org/stable-2-40-5",
                                    api_token = "d2pat_2EkxmqdxtwAGDGe1hXzpWEixYdvHGRw71587176066")
```



### Get user information

```{r}
# [Ways of keeping your user credentials safe](https://solutions.posit.co/connections/db/best-practices/managing-credentials/)
dhis2_play_connection$get_user_info()
```

 Get information about the account 

```{r}
dhis2_play_connection$account_info
```

 Get access rights information about the account 
```{r}
dhis2_play_connection$access_rights
```


### Get metadata

 Get all resources on which you can get metadata on.

```{r}
 dhis2_play_connection$get_metadata()

```
 Get metadata on Data Elements using the plural name `dataElements`.

```{r}
dhis2_play_connection$get_metadata(endpoint = "dataElements")

```
The code above only returns it's name and code/ID used on DHIS2, we shall use the code to get analytics.

#### Get all possible fields of a metadata of a resource

You can get more fields beyond ID and name 

*NOTE* All resources have different fields 

```{r}
 dhis2_play_connection$get_metadata_fields(endpoint = "dataElements")

```


```{r}
 dhis2_play_connection$get_metadata_fields(endpoint = "organisationUnits")

```


```{r}
 dhis2_play_connection$get_metadata_fields(endpoint = "indicators")
```

### Getting metadata fields beyond ID and Name

dataElements

```{r}
 dhis2_play_connection$get_metadata(endpoint = "dataElements", fields = c("name","id","aggregationType"))

```

organisationUnits

```{r}
dhis2_play_connection$get_metadata(endpoint = "organisationUnits",
                                                        fields =  c("name","id", "level"))

```

You can use `":all"` in the fields to get all fields of metadata associated with a resources

periodTypes

```{r}
dhis2_play_connection$get_metadata(endpoint = "periodTypes", fields = ":all")
```

### indicators

```{r}
dhis2_play_connection$get_metadata(endpoint = "indicators")
```

### Get analtyics

```{r}
dhis2_play_connection$get_analytics(analytic = "s46m5MS0hxu",
                                    org_unit = c("O6uvpzGd5pu", "fdc6uOvgoji"),
                                    period = "202101",
                                    output_scheme = "NAME")

```

```{r}
dhis2_play_connection$get_analytics(analytic = "FTRrcoaog83", #Accute Flaccid Paralysis (Deaths < 5 yrs)
                                    org_unit =   c("ImspTQPwCqd"), #Sierra Leone (National level)
                                    period = "LAST_12_MONTHS",
                                    output_scheme = "NAME")

```

```{r, include = FALSE}
end_vignette()
```