In CLSPhila/LegalServerReader: LegalServer Report API Client

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

LegalServerReader provides a few simple functions for accessing the LegalServer Reports API and storing credentials for the api in a way that is at least somewhat more secure than storing the credentials in plain text files in your project directory.

LegalServerReader uses an encryption library called Sodium to encrypt and then decrypt credentials for your LegalServer API reports. It then can download the report and provide it to you as a dataframe. You can also use this library to map LegalServer's internal column names from things like "built_in_matter_colname_colname" to more helpful names like "Case ID Number".

Getting Started using LegalServerReader

Create Credendtials for a report.

Load the library, and then use it to save and encrypt credentials to a LegalServer report.

The library supports both types of Legal Server reports api credentials. Basic Auth credentials have a username and a password. Bearer Token credentials have a secret token.

To create credentials, call the function create.bearer.credentials or create.basic.auth.credentials. This function will ask you for the username and password of the api user account from LegalServer, or the secret authentication token.

Next, add reports to this set of credentials.

  creds <- add.report("First Report")
  creds <- add.report("Next Report")

add.report will prompt you to enter the url of the report. The url should include the api key that LegalServer generates for the report.

The name of the report you create here is just a friendly name for organizing credentials. It does not need to be related at all to what the LegalServer name of the report is.

Save Credentials to a file

This library uses sodium to symmetrically encrypt your credentials.

  creds <- create.credentials()

Finally, save the credentials to an encrypted file. save.credentials will ask you for a password for encryption.

  save.credentials(creds, path.for.secrets =  "path/to/secret.creds")

The path.for.secrets is the path to the encrypted credentials file.

Finally, another optional parameter is return.creds. By default this is FALSE, but if you set it to true, save.credentials will return a list object with your saved credentials. You will pass this list to the get.report function to download a report from LegalServer.

You can use pipes to create and save credentials as in:

creds <- create.credentials() %>%
         add.report("First Report") %>%
         add.report("Second Report") %>%
         save.credentials(path.for.secrets="~/secret.creds", 
                          return.creds = TRUE)

Load saved credentials

After you have saved credentials to a file, you can unencrypt them and load them into R as a list using get.credentials. You should identify the credentials.path.

creds <- get.credentials(credentials.path = "~/secret.creds")

Download a report.

To download a report using your credentials, use get.report. This function needs two parameters. First, credentials is a list of api credentials in the format created by save.credentials. report.name is the name you created in the credentials for your report.

rpt <- get.report(credentials = creds, report.name = "My Report from LegalServer")

Renaming Columns

If you'd like to rename the columns that get downloaded from LegalServer, LegalServerReader provides a mechanism for configuring a mapping from LegalServer's column names to friendlier column names.

First, you'll create an a configuration file in the .ini format. It will have a section that starts with your report name (the same name you used in credentials.gpg). And in that section will be a list of key=value pairs mapping LegalServer's column names to your preferred names. For example:

[My Report]
unhelpful_internal_colname_1=Case ID
other_long_internal_colname=Client Age

Next, you'll load this mapping and use it to rename the columns of your report.

mapper <- get.column.mapper(config.file="~/path/to/mapper.ini")
rpt.renamed <- remap.columns(rpt, mapper)

That's it!

CLSPhila/LegalServerReader documentation built on Dec. 3, 2023, 10:01 p.m.