Add and manipulate databases and forms using R

library(activityinfo)

Introduction

This tutorial will provide a quick introduction to how to work with forms to create and manipulate them using R. 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.

Note: in order to fully follow this tutorial you must have an ActivityInfo user account or a trial account with the permission to add a new database. Setup a free trial here: https://www.activityinfo.org/signUp

Adding a new database

To add a new database for this tutorial use addDatabase(label).

newDb <- addDatabase("A new ActivityInfo tutorial database!")

In order to get a list of the databases that you have access to, use getDatabases().

dbList <- getDatabases()

# get the first database
firstDb <- dbList[[1]]

# Make the list a data.frame
dbListDf <- do.call(rbind, lapply(dbList, data.frame))

# Get the record 
newDbRecord <- dbListDf[dbListDf$databaseId == newDb$databaseId,]

The getDatabaseTree(databaseId) call provides most important information about the database.

dbTree <- getDatabaseTree(databaseId = newDb$databaseId)
head(dbTree)

# One can pull out a list of the roles by their labels
roleLabels <- as.character(lapply(dbTree$roles, function(x) x$label))

# The defaults are "readonly" and "dataentry"
readOnlyRoleId <- (dbTree$roles[[which(roleLabels=="Read only")]])$id
dataEntryRoleId <- (dbTree$roles[[which(roleLabels=="Data Entry")]])$id

It is possible to add database users as well using addDatabaseUser(databaseId, name, email) and to retrieve the list of all database users using getDatabaseUsers(databaseId).

addDatabaseUser(
  databaseId = newDb$databaseId, 
  name = "Tutorial database user", 
  email = "activityinfo1@example.com", 
  locale = "en", 
  roleId = readOnlyRoleId
  )
addDatabaseUser(
  databaseId = newDb$databaseId, 
  name = "Tutorial database user",
  email = "activityinfo2@example.com", 
  locale = "en", 
  roleId = dataEntryRoleId
  )

# Retrieve a list of all the database users
dbUsers <- getDatabaseUsers(databaseId = newDb$databaseId)

dbUsers

Forms

Adding a new form is also possible in R in three steps:

1. Define a form schema with formSchema(databaseId, label, elements, folderId)
2. Add new fields using addFormField(formSchema/formId, schema, upload)
3. Upload the newly constructed schema to your database

To create the form field, there are a number of functions available that can be found in the documentation:

• attachmentFieldSchema
• barcodeFieldSchema
• calculatedFieldSchema
• dateFieldSchema
• formFieldSchema
• geopointFieldSchema
• monthFieldSchema
• multilineFieldSchema
• multipleSelectFieldSchema
• quantityFieldSchema
• referenceFieldSchema
• sectionFieldSchema
• serialNumberFieldSchema
• singleSelectFieldSchema
• subformFieldSchema
• textFieldSchema
• userFieldSchema
• weekFieldSchema

Some examples are presented below.

fmSchema <- formSchema(databaseId = newDb$databaseId, label = "ActivityInfo form generated from R")

consentField <- singleSelectFieldSchema(
  label = "Have you agreed and signed the consent statment", 
  code = "consent", 
  description = "Each respondant should be provided with the consent form.",
  options = toSelectOptions(c("Yes","No"))
)

dobField <- dateFieldSchema(label = "When were you born?", code = "dob")

# Note that it is possible to chain together

fmSchema <- fmSchema |>
  addFormField(consentField) |>
  addFormField(dobField) |>
  addFormField(textFieldSchema(label = "What is your name?", code = "respondant"))

It is also possible to remove a single question with deleteFormField(formSchema/formId, label/code/id).

fmSchema <- deleteFormField(fmSchema, label = "What is your name?")

After the form is completed, it can be uploaded with updateFormSchema(schema).

updateFormSchema(fmSchema)

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

getFormSchema(fmSchema$id)

List all forms and database resources

It is possible to access the list of all the database forms as a data.frame with the function getDatabaseResources(databaseTree).

# Update the database tree as new resources and users have been added.
dbTree <- getDatabaseTree(databaseId = newDb$databaseId)

# Retrieve a list of all the resources (forms, sub-forms)
dbResources <- getDatabaseResources(databaseTree = dbTree)

dbResources