README.Rmd

---
output: github_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  eval = megamation:::has_creds()
)
```

```{r eval = !megamation:::has_creds(), echo = FALSE, comment = NA}
message("Missing credentials. Code chunks will not be evaluated.")
```

```{r, include = FALSE}
library(httptest2)
start_vignette("README")
```

# megamation <a href="https://asadow.github.io/megamation/"><img src="man/figures/logo.png" alt="megamation website" align="right" height="139"/></a>

**Authors:** 
[Adam Sadowski](https://adams.quarto.pub/w/)<br/>
**License:** 
[GPL (>= 3)](https://www.gnu.org/licenses/licenses.html)

<!-- badges: start -->
[![R-CMD-check](https://github.com/asadow/megamation/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/asadow/megamation/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/asadow/megamation/branch/master/graph/badge.svg)](https://app.codecov.io/gh/asadow/megamation?branch=master) [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

## Overview

megamation provides an R interface to [Megamation DirectLine](https://megamation.com/) via the [API](https://apidocs.megamation.com/). 

## Installation

You can install the released version of megamation from [CRAN](https://cran.r-project.org/) with:

```{r, eval = FALSE}
install.packages("megamation")
```

And the development version from [GitHub](https://github.com/) with:

```{r, eval = FALSE}
# install.packages("pak")
pak::pak("asadow/megamation")
```

## Attach megamation

```{r}
library(megamation)
```

## Authorization

You have two options.

Either use `mm_authorize()`:

```{r, eval = FALSE}
mm_authorize(
  key = "<YOUR-MEGAMATION_KEY>",
  url = "<YOUR-MEGAMATION_URL>"
)
```

Or run `usethis::edit_r_environ()` to install your API credentials in your `.Renviron`.

``` {r, eval = FALSE}
MEGAMATION_KEY = '<YOUR-MEGAMATION_KEY>'
MEGAMATION_URL = '<YOUR-MEGAMATION_URL>'
```

Now `megamation` functions will automatically use your credentials, so you don't
have to expose them in your code.

## Grabbing Data

`mm_data()` downloads data from your tables into R.

```{r}
mm_data("status")
```

It provides informative R errors (alongside HTTP errors).

```{r, error = TRUE}
mm_data("statuses")
```

### Filtering

`mm_data()` allows you to easily filter by fields (columns).

#### Available Filters

`mm_names()` allows you to see the columns that can act as filters.

```{r}
mm_names("workorder")
```

#### Modifiers

You can use Megamation's [modifiers](https://apidocs.megamation.com/) on filter values.

- `[]` for containing

- `!!` for not equal

- `>>` for greater than

- `<<` for less than

- `<>` for between.

For example, supply `<field> = "[]<value>"` to get rows where `<field>` contains `<value>`. Here's how you would request all work orders containing trades `ADMIN` and `IT`.

```{r, eval = FALSE}
admin_and_it <- c("[]ADMIN", "[]IT")

mm_data("workorder", trade = admin_and_it)
#> # Data Not Shown for Privacy
```

#### Dates

Avoid `<>` for dates. Instead, use a sequence of R `Date`'s. Here's how you would request all work orders from January, 2023.

```{r, eval = FALSE}
jan_2023 <- seq.Date(
  as.Date("2023-01-01"),
  as.Date("2023-01-31"),
  by = "day"
)

mm_data("workorder", date = jan_2023)
#> # Data Not Shown for Privacy
```

## For More

Please see the package website: <https://asadow.github.io/megamation/>.

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

## Code of Conduct

Please note that the megamation project is released with a [Contributor Code of Conduct](https://asadow.github.io/megamation/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. Feedback, bug reports (and fixes!), and feature requests are welcome; file issues or seek support [here](https://github.com/asadow/megamation/issues).