The Mobenzi API allows you to programmatically add, update and delete project resources (such as media, CSV data, custom widgets) that can be utilised by forms within the project. You must authenticate with the credentials of a user who has "Design Form" permissions for the project that you wish to manage resources for.


CSV file validation


CSV files can be used for populating choice fields as well as pulling data into (pre-populating) a form. Additional validation rules are applied to both the header and data rows of a CSV file resource to ensure issues do not occur during data collection. 

  • Header values can only contain letters, numbers or underscores and must begin with a letter. No spaces or other special characters are allowed. The length of a header value cannot exceed 100 characters.
  • Data values can contain any characters except for double quotes " or backticks `.


Here's an example of a valid CSV file:


header_1header_2header_3
Some dataExample email@address.com$240
Valid data can include single quotes (')Dates allowed 1987-10-20$303

  

Adding a Resource

To add a Resource to a project, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/AddResource endpoint. The following POST parameters are available:

  • projectId [Required] - Integer identifier of project (study) in the account
  • name [Required] - Filename you wish to give to the Resource, including extension - no spaces or special characters are allowed
  • data [Required] - Raw file content - should be uploaded as multipart/form as a part of the body


If the Resource is added successfully, a success response is returned that confirms the filename that has been used to store the file - this may have been modified to remove any illegal characters and should be used to reference the Resource in future requests.


The following Node.js code sample demonstrates how you would add a Resource with name <RESOURCE_NAME> (including extension) to the project <PROJECT_ID> from a local file <FILE_PATH>.

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const fs = require("fs"); // fs is a default nodejs file streaming package
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/form-data

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/AddResource"; 
let formData = new FormData();
formData.append("projectId", "<PROJECT_ID>");
formData.append("name", "<RESOURCE_NAME>");
formData.append("data", fs.createReadStream("<FILE_PATH>")); //Create a filestream from a local file you wish to upload
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    var uploadedResourceName = result.data.d.AddResource;
    console.log(uploadedResourceName);
}).catch(error => {
    console.log(error);
});;


Updating a Resource

To update an existing Resource in a project, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/EditResource endpoint. The following POST parameters are available:

  • projectId [Required] - Integer identifier of project (study) in the account
  • name [Required] - Filename of the Resource you wish to update, including extension (there must be a Resource with this filename)
  • data [Required] - Raw file content - should be uploaded as multipart/form as a part of the body; this will overwrite the existing content stored


Updating a Resource via the API will trigger all devices linked to the project to download the updated version of the file automatically.


The following Node.js code sample demonstrates how you would edit a Resource with name <RESOURCE_NAME> (including extension) in the project <PROJECT_ID> with an updated local file <FILE_PATH>.

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const fs = require("fs"); // fs is a default nodejs file streaming package
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/form-data

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/EditResource"; 
let formData = new FormData();
formData.append("projectId", "<PROJECT_ID>");
formData.append("name", "<RESOURCE_NAME>");
formData.append("data", fs.createReadStream("<FILE_PATH>")); //Create a filestream from a local file you wish to upload
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    var uploadedResourceName = result.data.d.EditResource;
    console.log(uploadedResourceName);
}).catch(error => {
    console.log(error);
});;


Deleting a Resource

To permanently delete an existing Resource from a project, you would issue an HTTP POST request to the https://console.mobenzi.com/secure/api.svc/DeleteResource endpoint. The following POST parameters are available:

  • projectId [Required] - Integer identifier of project (study) in the account
  • name [Required] - Filename of the Resource you wish to delete, including extension (there must be a Resource with this filename)


A Resource can only be deleted if it is not being referenced by a form. Should you attempt to delete a Resource that is in use, an error will be returned.

The following Node.js code sample demonstrates how you would delete a Resource with name <RESOURCE_NAME> (including extension) in the project <PROJECT_ID>.

// Common node package includes
const axios = require("axios"); //axios is a common HTTP client for the browser and node.js
const FormData = require('form-data'); // formdata is available in the browser by default or from NPM at https://www.npmjs.com/package/form-data

// Specify the credentials of the user who will be making the API requests.
// Note: the user must have "Design Survey" permission to the relevant project.
var config = {
    auth : {
        username: 'api@yourdomain.com',
        password: 'apiuserpassword'
    }
};

// Prepare your request data
var url = "https://console.mobenzi.com/secure/api.svc/DeleteResource"; 
let formData = new FormData();
formData.append("projectId", "<PROJECT_ID>");
formData.append("name", "<RESOURCE_NAME>");
config.headers = formData.getHeaders();

// Use axios to issue the HTTP request (note: your code should add error checking on the response and handle appropriately.
axios.post(url, formData, config).then(result => {
    console.log(result.data);
}).catch(error => {
    console.log(error);
});;