README.md

In ices-tools-prod/icesSharePoint: Helper functions to interact with the ICES sharepoint

icesSharePoint

icesSharePoint provides helper functions to access the SharePoint site used by ICES.

Before you can access the SharePoint via R, you must have a valid user name and password given to you by the ICES Secretariate. icesSharePoint requires your ICES username and password to be saved in environment variables, see for example, Appendix: Storing API Authentication Keys/Tokens in the httr package vignette. The first time you use the API, the package will create an appropriate file (‘\~/.Renviron_SP’) to contain your username and password. It is important that this file is in a private location in your computer, such as your home drive ‘\~’. Your password is never sent to the API, but is used to authenticate via ntlm.

Installation

icesSharePoint can be installed from GitHub using the install_github command from the devtools package:

library(devtools)
install_github("ices-tools-prod/icesSharePoint")

Usage

For a summary of the package:

library(icesSharePoint)
?icesSharePoint

Basic example

First of all you need to set your ices username for the session, this is done like so:

# set ices username
options(icesSharePoint.username = <your ices login name>)
# check it has worked
options("icesSharePoint.username")

A first call to anything will ask you for a password, for example:

spdir()

there after it will be stored in a secrets store that only you have access to. However be carefull because if someone gains access to your computer your password will be accessible via:

keyring::key_get("icesSharePoint", "colin") # beware!! this will print your password to the screen

You need to be logged into your machine as you to read this, but if someone somehow wrote a dodgy script, they could programatically access your password…. so beware!

You can clear the password at the end of the session with this:

icesSharePoint:::SP_clearpassword() # which just calls

The next step is set the site you are accessing to save supplying it in all the function calls, this exmaple uses WGMIXFISH-ADVICE sharepoint site. Only ices users who have been granted access can access this folder.

options(icesSharePoint.site = "/ExpertGroups/WGMIXFISH-ADVICE")

Now find the directory you want to access

# this prints the directory contents, and is useful to navigate to find the
# directory or file you are interested in
spdir()
spdir("2020 Meeting Documents")
# etc
spdir("2020 Meeting Documents/06. Data/FIDES")

Now that you know the directory you want to acces, you can loop over all the files and download them one by one. Single files can also be accessed in a similar way

fnames <- spfiles("2020 Meeting Documents/06. Data/FIDES", full = TRUE)
for (fname in fnames) {
  spgetfile(fname, destdir = ".")
}

You can also download the file in one line and specify the site you want to access from the spgetfile function. Another useful point of note is the destdir argument. by default files are downloaded in the same folder structure as they are on the sharepoint, but destdir overrides this.

spgetfile(
  "2021 Meeting Documents/06. Data/Iberian Waters/ANK2020.xlsx",
  site = "/ExpertGroups/WGMIXFISH-ADVICE",
  destdir = "."
)

References

ICES Community SharePoint site:

https://community.ices.dk/SitePages/Home.aspx

Microsoft SharePoint 2013 REST interface reference

https://msdn.microsoft.com/en-us/library/office/jj860569.aspx

Development

icesSharePoint is developed openly on GitHub.

Feel free to open an issue there if you encounter problems or have suggestions for future versions.

ices-tools-prod/icesSharePoint documentation built on June 27, 2021, 5:16 p.m.