Introduction to ActivityInfo and R

Introduction

This tutorial is about the ActivityInfo R Package that is a client used to access to the ActivityInfo API. While this is an API client, names of functions and arguments are modelled more closely to web user interface to facilitate its use.

With this client, you can programmatically obtain and modify your data. You can also manage users, create new databases and forms, or define reports. Any thing else that is possible through ActivityInfo's user interface can be automated using the API and this R package.

Install the R client

First, you should install ActivityInfo API R client in your system.

# install.packages("devtools")
devtools::install_github("bedatadriven/activityinfo-R")

Then, put the library call at the top of your script file.

library(activityinfo)

If you are using the ActivityInfo Self-Managed Server, you must provide the URL of your server using activityInfoRootUrl

Authentication

In order to access to the ActivityInfo API, an authentication process has first to be done. One must generate a personal access token from the Profile Settings page in ActivityInfo. Logging in by email and password through the API is now deprecated and insecure.

activityInfoToken(token)

After the authentication process has been successfully completed, a prompt will ask if the token file named .activityinfo.credentials should be written to your home directory. Only write the file to your home directory if this is secure. Don't share or publish this token file and preserve securely as it contains your personal access token.

Before start working on the API calls, do not forget to restart your R session to have changes applied.

Databases

In order to get the database schemas that you have access to, usegetDatabaseSchema(databaseId) call, which actually retrieves "/resources/database/{databaseId}" from the API.

db_schema <- getDatabaseSchema("ck35o0kja3")
head(db_schema)

Forms

In order to get the form or sub-form schemas that you have access to, use getFormSchema(databaseId) call, which actually retrieves "resources/form/{id}/schema" from the API.

form_schema <- getFormSchema("ck35pixlz9")
head(form_schema, 4)

Querying

You can query an ActivityInfo form as a data.frame. With the columns argument, it's possible to specify the query parameters for which columns to fetch and that can also be used to rename the column names.

qt <- queryTable("ck2ll1o1ec", columns = c(
  id = "_id",
  sum = "Parent.sum",
  sqm = "[Square Meters]"
))
head(qt)

The notation used in the columns text values are based on the ActivityInfo Query Language and more information can be read in the Formulas Manual.