Introduction to ActivityInfo and R

Introduction

This tutorial is about the ActivityInfo R Package that is a client used to access to the ActivityInfo REST API. While this is an API client, names of functions and arguments are modeled 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)
library(dplyr)

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, you must authenticate to the server with a personal API token. You can 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("2d6016c9cb3be78954eb396f806a20e9")

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

You can list the databases that you own or have been shared with you using [activityinfo::getDatabases]. Use the asDf argument to get the list as a data.frame:

dblist <- getDatabases()
head(dblist)

In order to get details about a specific database, you can use [activityinfo::getDatabaseTree], or [activityinfo::getDatabaseResources] to return a data.frame with the list of resources in the database. "Resources" include forms, subforms, folders, and reports.

resources <- getDatabaseResources("cfcdyr0kq6ik2wmf")
head(resources)
#> # A tibble: 6 × 5
#>   id                label           type     parentId         visibility
#>   <chr>             <chr>           <chr>    <chr>            <chr>     
#> 1 reference         Reference Data  FOLDER   cfcdyr0kq6ik2wmf REFERENCE 
#> 2 csqojmfkq6jsm9n3x Sub-sector      FORM     reference        REFERENCE 
#> 3 c7b2moekq6ikasi2  Partner         FORM     reference        REFERENCE 
#> 4 cc605xmlbgj5pee9  Monthly reports SUB_FORM ceam1x8kq6ikcujg PRIVATE   
#> 5 cnjjpvl444fhj13   3W Dashboard    REPORT   cfcdyr0kq6ik2wmf PRIVATE   
#> 6 cjgeoufkq6jqblf3b Sector          FORM     reference        REFERENCE

Forms

In order to get the form or sub-form schemas that you have access to, use getFormSchema(formId) call, which retrieves the the form's schema, including a list of fields in the form:

schema <- getFormSchema("ceam1x8kq6ikcujg")
head(schema, 4)
#> $id
#> [1] "ceam1x8kq6ikcujg"
#> 
#> $schemaVersion
#> [1] 25
#> 
#> $databaseId
#> [1] "cfcdyr0kq6ik2wmf"
#> 
#> $label
#> [1] "Projects"

You can find a form's ID from your browser's address bar when you have the form page open:

Getting records

You can get the records from an ActivityInfo form as a dplyr-compatible table. Let's retrieve the list of projects from the Simple 3W template

records <- getRecords("ceam1x8kq6ikcujg") |> collect()
head(records)
#> # ActivityInfo tibble: Remote form: Projects (ceam1x8kq6ikcujg)
#> # A tibble:            6 × 20
#>   `_id`            `_lastEditTime` Organization `Organization Name` `Sub-Sector`
#>   <chr>                      <dbl> <chr>        <chr>               <chr>       
#> 1 cphnje3kq6pbwb8…      1624284965 c9pinkskq6n… The Fred Hollows F… cu6zg2hkq6j…
#> 2 cilhx8pkq6pbwb9…      1624284965 cwhjya2kq6n… United Nations Chi… czhoavkkq6j…
#> 3 cb1xxe2kq6pbwb9…      1624284965 cndrfpgkq6n… American Refugee C… c92dsnnkq6j…
#> 4 cfpwparkq6pbwb9…      1624284965 cqw5pxtkq6n… Pact Global Microf… cgrx56xkq6j…
#> 5 cwt9ttukq6pbwb9…      1654689264 cqw5pxtkq6n… Pact Global Microf… cgrx56xkq6j…
#> 6 cqs04chkq6pbwb9…      1624284965 cctqkddkq6n… Karuna Mission Soc… czhoavkkq6j…
#> # ℹ 15 more variables: `Sub-sector Sector` <chr>, `Sector Name` <chr>,
#> #   `Sub-sector Name` <chr>, Location <chr>, `Admin 2 State/Region` <chr>,
#> #   `Admin 1 Name` <chr>, `Admin 2 Name` <chr>, `COVID-Related` <chr>,
#> #   `Project title` <chr>, `Project start month` <chr>,
#> #   `Project end month` <lgl>, `Project status` <chr>,
#> #   `Suspension reason` <lgl>, Remarks <chr>, `Monthly reports` <dbl>

Note that we pipe the records to [dplyr::collect], which actually retrieves all the records from the server.

For forms with tens of thousands of records, you may want to apply filtering to narrow down the results before downloading all the records from the server. You can use the [dplyr::filter] function to apply a filter:

unicef <- getRecords("ceam1x8kq6ikcujg", prettyColumnStyle())  |> 
  filter(`Organization Name` == "United Nations Childrens Fund") |>
  collect()
#> Adding filter: (cd3hjlwkq6ikojan.name == "United Nations Childrens Fund")

This will send the filter to the server, and only download matching records.

Updating records

You can also use the R package to add, update, and import records. For single records you can use the [activityinfo::addRecord] and [activityinfo::updateRecord] functions:

addRecord(formId = "cxy123", fieldValues = list(
    text_field = "Alice Jones",
    multi_line_text = "Line 1\nLine 2",
    date_of_birth = "1980-01-01",
    week_project_start = "2022W1",
    month = "2023-06",
    quantity_field = 42.0, 
    location = list(latitude = 52.0705, longitude = 4.3)))

updateRecord(formId = "cxy123", recordId = "" fieldValues = list(
    text_field = "Alice Smith"))

For adding or updating many records at once, you can use the [activityinfo::importRecords] function.

Adding and modifying forms

You can also add new forms and modify existing form schemas. You can add or remove fields from a form, or add an entirely new form.

The example below will add a new database, and then add a new form for a survey to the database.

surveyDb <- addDatabase("Surveys")
surveySchema <- formSchema(
  databaseId = surveyDb$databaseId,
  label = "My new survey",
  elements = list(
    textFieldSchema(
      label = "What is your name?",
      code = "NAME",
      description = "Please provide your full name",
      required = TRUE
    ),
    singleSelectFieldSchema(
      label = "What is your sex?",
      code = "SEX",
      options = c("Female", "Male", "Prefer not to answer"),
      required = TRUE
    ),
    singleSelectFieldSchema(
      label = "Are you pregnant",
      relevanceRule = "SEX != 'Male'",
      options = c("Yes", "No"),
      required = TRUE
    )
  )
)
surveyForm <- addForm(survey)

Managing users

The R package can also be used to automate user management for a database.

For example, you could read a list of users from Active Directory or other external source and automatically add them to an ActivityInfo database using [activityinfo::addDatabaseUser]:

addDatabaseUser(
  databaseId = databaseId,
  email = "alex@example.com",
  name = "Alex",
  locale = "en",
  roleId = "admin")