README.Rmd

---
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/README-",
  out.width = "100%"
)
```

# sharepointr

<!-- badges: start -->

[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- badges: end -->

The goal of SharePointR is to make it easier to read, write, and work with files stored in SharePoint by extending the `{Microsoft365R}` package.

## Installation

You can install the development version of SharePointR like so:

``` r
# pak::pkg_install("elipousson/sharepointr")
```

## Requirements

To use this package (or `{Microsoft365}`) you must:

-   Have a work or school account with access to [Microsoft SharePoint](https://www.microsoft.com/en-us/microsoft-365/sharepoint/collaboration)
-   Have enabled permissions for the default `{Microsoft365}` app ID

See the `{Microsoft365}` [documentation on app registration for more information](https://github.com/Azure/Microsoft365R/blob/master/inst/app_registration.md).

## Usage

`{Microsoft365}` uses S6 methods for nearly everything which may be difficult for users (me included) who are less familiar with this interface.

The `{sharepointr}` package seeks to ease this challenge by wrapping the `{Microsoft365}` methods and adding support for the specification of SharePoint sites, drives, and items using SharePoint URLs instead of item or drive ID values.

```{r}
library(sharepointr)
```

### Reading and writing objects to and from SharePoint

The most useful functions for most users may be `read_sharepoint()` and `write_sharepoint()`.

`read_sharepoint()` downloads a SharePoint file to a temporary folder and then, based on the file extension, reads it into your environment using an appropriate function and package (e.g. using `officer::read_docx()` for Microsoft Word files or `sf::read_sf()` for common spatial data files):

```{r}
docx_shared_url <- "https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/General/Baltimore%20Data%20Academy/Baltimore%20Data%20Academy%20Announcement%20Content.docx?d=w0a50d3cd74ce4a8da6d82596037f0148&csf=1&web=1&e=cBURo2"

read_sharepoint(docx_shared_url)
```

`write_sharepoint()` saves an R object to local files and then uses `upload_sp_item()` to uploads the file to SharePoint.

I plan on adding features to allow the custom mapping of file extensions and object classes to specific functions or packages and adding more thorough documentation. Feel free to submit an issue or make a pull request if you have ideas of how to do this.

### Working with SharePoint items, lists, and plans

This package currently support three main categories of SharePoint objects:

-   **Items** (including **directories** and **files**) and **item properties**

-   **Lists and list items**

-   **Plans and tasks**

Typically these functions return a `ms_object` object, a list of `ms_object` objects, or a data frame. In some cases, the data frame is based on the object properties and includes a list column where the `ms_object` is stored.

For example, `get_sp_item()` returns a `ms_drive_item` object and supports parsing for shared file and folder URLs:

```{r}
get_sp_item(docx_shared_url)
```

Set `as_data_frame = TRUE` to return a data frame instead of a `ms_drive_item` object:

```{r}
get_sp_item(docx_shared_url, as_data_frame = TRUE)
```

These basic functions to "get" objects are extended by functions like `download_sp_item()` that adds support for downloading copies of your SharePoint files (this is the function that powers `read_sharepoint()`):

```{r}
withr::with_tempdir({
  docx_dest <- download_sp_item(docx_shared_url)

  file.exists(docx_dest)
})
```

Some of the original `{Microsoft365R}` S6 object methods already return a data frame by default such as `sp_dir_info()`:

```{r}
sp_dir_info("https://bmore.sharepoint.com/:w:/r/sites/MayorsOffice-DataGovernance/Shared%20Documents/General/Baltimore%20Data%20Academy")
```

Others use the `as_data_frame` parameter to convert a list into a data frame as a convenient alternative.

### Helpers for SharePoint sites and drives

Most functions in the package rely on a pair of helper functions: `get_sp_site()`, `get_sp_drive()`, and `get_sp_item()`, that can parse a URL to determine the SharePoint site URL, drive name, and file path based on the URL.

`get_sp_site()` is a minimal wrapper for `Microsoft365R::get_sharepoint_site()`:

```{r}
site_url <- "https://bmore.sharepoint.com/sites/MayorsOffice-DataGovernance"

get_sp_site(site_url = site_url)
```

`get_sp_drive()` returns a `ms_drive` object but required a SharePoint URL that includes the name of the drive (otherwise it returns the drive named in the "sharepointr.default_drive_name" option):

```{r}
get_sp_drive(docx_shared_url)
```

## Related packages

There are a few similar packages available:

-   [sharrpoint](https://gitlab.com/tolmay/sharrpoint): An R package to interact with Sharepoint API (files & lists).
-   [sharepointr](https://github.com/LukasK13/sharepointr): A R package for reading from and writing to SharePoint lists.
-   [msgraphr](https://github.com/davidski/msgraphr): A minimal R wrapper of the SharePoint Online (Office 365) APIs (last updated 3 years ago).

I know this package name conflicts with the existing sharepointr package. Unfortunately, I didn't notice find it until after I set up the repository. However, given that it appears that the sharepointr package may be no longer under development, I plan stick with the current name for the time being.