Browse
 
Tools
Rss Categories

API Overview

Reference Number: AA-00431 Last Updated: 2014-09-11 17:54

At the highest level the Mobenzi Researcher API enables 4 core functions:

  1. Survey overrides - enable modification of the survey's design prior to its distribution to a fieldworker
  2. Submission triggers - enable custom processing when a submission event occurs
  3. Queries - enable custom filters and searches for working with Mobenzi Researcher entities programmatically
  4. Data manipulation - enable modification of captured data programmatically

The different areas can be used in isolation or in combination to perform some powerful actions. Overrides and Triggers are configured at a Survey level within a Study and are executed in real-time. The Restful ADO.NET Data Services can be incorporated into an external system to access existing data entities from your account.

Survey Overrides

Overrides can be used to modify certain aspects of a survey's design at the time it is sent to a handset. An override URL can be configured per survey that will be called by Mobenzi Researcher system (along with a number of GET parameters) when a fieldworker checks for updates on their handset. Mobenzi Researcher will expect the URL endpoint to respond with XML according to a predefined format. 

By controlling the XML output, it is possible to modify or override any of the following survey design parameters:

  • Generate one or more "instances" of the survey - each of which can have a unique title when displayed on the handset
  • The folder in which the survey (or instance) should be placed in on the handset
  • The question text displayed (you only need to override the questions you wish to change)
  • The options available for a specified question
  • Default values and variables
  • Constraints

A simple example of a useful override would be where a contextual option list should be displayed, depending on which fieldworker was conducting the survey (e.g. the list of areas assigned to each fieldworker). Overrides also allow the possibility of sending down multiple instances of a survey template to a device, pre-populated with instance specific default values and/or custom question text.

The parameters included in the request which are sent to your override URL endpoint are:

Name Type Description
 survey_id  integer  Identifies which survey is being overridden
 device_id  uniqueidentifier  Identifies from which device (handset) the update request has been made (and to which the survey will be sent)
 fieldworker_id  uniqueidentifier  Identifies from which fieldworker the update request has been made
 survey_external_id  string  User-defined reference for developer's internal use
 languages  string  Comma separated list of languages the fieldworker is associated with
 survey_xml  string  XML representing the unmodified survey (can also be downloaded manually)

The override feature enables third-party systems to provide context to surveys that are sent to mobile devices. The features that the survey override mechanism supplies:

Feature Description
 Instance count  Default instance count is 1. If the instance count is reduced to 0, the relevant survey will not be sent to the fieldworker even they are assigned to the survey. If the instance count is increased, different override parameters can be provided for each instance.
 Survey title  The title of the survey (as it appears on the handset) may be overridden.
 Question text  The question text of any field (including instruction fields) may be overridden. 
 Option label  The list of options (labels and values) for select questions may be overridden.  
 Default value  The default values of any field may be overridden. This is also the mechanism used to set the value of variable question types.
 Required field flag  Override whether the question should be required or optional. 
 Survey removal  Specify whether the instance should be removed upon completion.

Override configuration

To facilitate development of the third party process handler, it's possible to download sample XML for the survey you wish to override. Once a survey is selected, click the Design tab and from the ribbon select API. From the API screen, enter the Dynamic Override URL. 

As per the screenshot below, there is a link to download sample API XML to facilitate development of the override handler.


Submission Triggers

Submission triggers are used for notifying external systems about events related to a submission. There are 3 different event triggers that can be configured at a survey level, namely:

  • Submission received - triggered when a new submission is uploaded
  • Submission updated - triggered when a user modifies a submission
  • Submission deleted - triggered when a user deletes a submission

It is possible to configure a URL endpoint for each of these events that will be called in real-time as the event occurs within Mobenzi Research. A number of parameters will be posted to the given URL at the time of the event occurring. These parameters include:

Name Type Description
  submissionid   uniqueidentifier   Identifies the submission uniquely
  surveyid   integer   Identifies which survey the submission was for
  externalid   string   User-defined reference to the survey
  customid    string   User-defined instance id (usually set by the override handler)
  createdon    datetime   Date/time at which the submission was received by Mobenzi Researcher. Only present for a "Submission Received" trigger
  createdby    string   Name of the fieldworker who uploaded the submission. Only present for a "Submission Received" trigger
  modifiedon    datetime   Date/time at which the submission was modified. Not present for a "Submission Received" type
  modifiedby    string   Name of the user who modified the submission. Not present for a "Submission Received" type
  submissionjson    string   If "Post All Data" is checked on the trigger configuration this POST parameter will contain a JSON object representing the submission

Submission trigger configuration 

Triggers are configured at a survey level. Once a survey is selected, click the Design tab and from the ribbon select API. From the API screen, complete the trigger section as highlighted in the screenshot below.


Only enter a URL for the triggers you wish to handle. To remove an existing trigger simply clear the trigger URL field and click Save.

Once one or more trigger URL’s have been configured, the triggers are activated immediately for all future events.

RESTful ADO.NET Data Services

In order to simplify the process of mapping the XML or JSON responses back into usable objects, several common wrapper classes have been created in different languages to assist third-party developers. An example of a program using this C# wrapper DLL has been attached to this article (see attachments).

Making use of the C# Wrapper

Once you have added a reference to the DLL (MobenziResearcher.API.dll) and included the Mobenzi Researcher API wrapper namespace (MobenziResearcher.API), you should be able to view the available functionality exposed by examining the IAPIService interface. An example of fetching all submissions for the last day for a specified survey is as simple as:

Example usage of Mobenzi Researcher C# API

    String user = "USERNAME_GOES_HERE";
    String pass = "PASSWORD_GOES_HERE";
    DateTime fromDate = DateTime.Now.AddDays(-1);
    DateTime toDate = DateTime.Now;int surveyId = 123;
    IAPIService service = new APIService(user, pass);
    var submissions = service.GetSubmissions(surveyId, fromDate, toDate);

    foreach (var submission in submissions)
    {
        Console.WriteLine("Submission ID: " + submission.Id + " Upload Date: " + submission.UploadDate);
    }
    Console.ReadLine();

Mobenzi API Entities

To manually review entities accessible via the Mobenzi Researcher API you first need to log into your research console and then access the API URL (https://www.researchconsole.com/secure/api.svc/). 

If you wish to review data returned for any particular entity, you would access the entity as follows: https://www.researchconsole.com/secure/api.svc/{Entity} – please note that {Entity} should be replaced with any particular entity you are interested in reviewing, also note that the API is case-sensitive. For example, if you wished to review all Question entities for your console, you would navigate to https://www.researchconsole.com/secure/api.svc/Questions

Use filters to limit entities returned

Please be aware that when accessing records for a particular entity in the fashion described above a query to retrieve all data (i.e. no filtering is applied) will be produced. If you access the Response or Submission entities in this manner, all Responses/Submissions will be returned. This may cause your browser to freeze or crash as there are usually a large number of these entities accessible through your console.

Searching and Filtering

Appropriately, ADO .NET Data Services provides a rich query protocol which allows you to search and filter the data you may be interested in.

For example, to review the first 10 Submissions for 2010, you could so as follows:

  • https://www.researchconsole.com/secure/api.svc/Submissions?$top=10&$filter=year(uploaddate) eq 2010&$orderby=uploaddate

If you wished to include the actual responses for each of the first 10 Submissions for 2010, you could so as follows:

  • https://www.researchconsole.com/secure/api.svc/Submissions?$top=10&$filter=year(uploaddate) eq 2010&$orderby=uploaddate&$expand=Responses

Query String Options

Option Description Example
 expand The ‘expand’ option allows you to embed one or more sets of related entities in the results. For example, if you want to display a Submission and its Responses, you could execute two requests, one for /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’) and one for /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)/Responses.

The ‘expand’ option on the other hand allows you to return the related entities in-line with the response of the parent in a single HTTP request. You may specify multiple navigation properties to expand by separating them with commas, and you may traverse more than one relationship by using a dot to jump to the next navigation property.
A Submission with related Responses: /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses.

A Submission with related Responses and Response Options related to each Response: /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses/ResponseOptions.

A Submission with related Responses and Survey: Orders with related /Submissions(guid’42d4de6e-38b9-4b88-bcb1-df70227aff0a’)?$expand=Responses,Survey
 orderby Sort the results by the criteria given in this value. Multiple properties can be indicated by separating them with a comma. The sort order can be controlled by using the “asc” (default) and “desc” modifiers. /Submissions?$orderby=uploaddate /Submissions?$orderby=uploaddate desc
/Submissions?$orderby=uploaddate,survey_id desc
 skip Skip a given number of rows when returning results. This is useful in combination with “top” to implement paging (e.g. if using 10-entity pages, saying $skip=30&top=$10 would return the fourth page). NOTE: Skip only makes sense on sorted sets; if an orderby option is included, ‘skip’ will skip entities in the order given by that option. If no orderby option is given, ‘skip’ will sort the entities by their primary key and then perform the skip operation. Return all Submissions except the first 10:
/Submissions?$skip=10

Return the 4th page where each page shows only 10
Submissions: /Submissions?$skip=30&$top=10
 top Restrict the maximum number of entities to be returned. This option is useful both by itself and in combination with skip, where it can be used to implement paging as discussed in the description of ‘skip’. Top 10 Submissions: /Submissions?$top=10
Get the last 10 Submissions: /Submissions?$orderby=uploaddate desc&$top=10
 filter Restrict the entities returned from a query by applying the expression specified in this operator to the entity set identified by the last segment of the URL path. Get all Submissions for Survey with Id 101 :
/Submissions?$filter=survey_id eq 101
Get all Questions where the question name contains “health”: /Questions?$filter=substringof(‘health’, name)

Logical Operators

Operator Description Example
  eq   Equal  /Questions?filter=name eq ‘Health district’
  ne   Not equal   /Questions?filter=name ne ‘Health district’
  gt   Greater than  /Submissions?$filter=year(uploaddate) gt 2009
  ge   Greater than or equal  /Submissions?$filter=year(uploaddate) ge 2010
  lt   Less than  /Submissions?$filter=year(uploaddate) lt 2009
  le   Less than or equal  /Submissions?$filter=year(uploaddate) le 2010
  and   Logical and  /Submissions?$filter=year(uploaddate) le 2010 and survey_id = 101
  or   Logical or  /Submissions?$filter=year(uploaddate) eq 2008 or year(uploaddate) eq 2010
  not   Logical negation  /Questions?$filter=not endswith(name,‘test.’)

Arithmetic Operators

Operator Description Example
 add  Addition  /Submissions?$filter=hour(uploaddate) add 5 gt 10
 sub  Subtraction  /Submissions?$filter=hour(uploaddate) sub 5 gt 3
 mul  Multiplication  /Submissions?$filter=minute(uploaddate) mul 0.5 lt 3
 div  Division  /Submissions?$filter=minute(uploaddate) div 2 lt 3
 mod  Modulo  /Submissions?$filter=minute(uploaddate) mod 2 eq 3

Grouping Operators

Operator Description Example
 ()  Precedence grouping  /Responses?filter=(year(Submission/uploaddate) sub 5) lt 2005

Other Functions

String Functions Date Functions Math Functions
 bool substringof(string p0, string p1)  int day(DateTime p0)  double round(double p0)
 bool endswith(string p0, string p1)  int hour(DateTime p0)  decimal round(decimal p0)
 bool startswith(string p0, string p1)  int minute(DateTime p0)  double floor(double p0)
 int length(string p0)  int month(DateTime p0)  decimal floor(decimal p0)
 int indexof(string arg)  int second(DateTime p0)  double ceiling(double p0)
 string insert(string p0, int pos, string p1)  int year(DateTime p0)  decimal ceiling(decimal p0)
 string remove(string p0, int pos)    
 string remove(string p0, int pos, int length)    
 string replace(string p0, string find, string replace)    
 string substring(string p0, int pos)    
 string substring(string p0, int pos, int length)    
 string tolower(string p0)    
 string toupper(string p0)    
 string trim(string p0)    
 string concat(string p0, string p1)    

Authentication

The API should always be accessed via the SSL/HTTPS endpoint. This ensures that any data accessed through the API is encrypted while being transferred. The API supports basic HTTPAuthentication.  To access the API programmatically, you will need to set the “Authorization” HTTP header when executing the web request to the relevant API endpoint. Please note that the credentials used should be that of a valid user setup in your console. To access the Submission and Response data, the user should be setup with the View Responses permission.  

Please note that if the user account used to access the API is linked to more than one console, a custom HTTP header is required to be set. The custom HTTP header is “AccountID”. The value of this header should be set to the unique identifier for the account/console you are targeting. If you are unsure what your unique console/account ID is, please contact support.

Updating and Deleting API Entities

Currently, it is only possible to update and delete Response entities via the API. In future, the API will be upgraded to support modification and deletes of other entities such as Submissions. Please review the section on request authentication above to ensure that all requests to update/delete entities via the API carry the correct authentication tokens.

To delete a response, the response ID is required. The following HTTP DELETE action will delete a response with the ID ‘E271F157-4356-4E16-B63B-AD681AED7BEE’:

  • URL: https://www.researchconsole.com/secure/api.svc/Responses(guid'E971F157-4356-4E06-B63B-AD681AED7BEE')
  • Please note that the HTTP method must be set to DELETE. Also, the user account being used to authenticate should have the Modify Responses permission in the relevant study.

To update a response, the response ID is required. The HTTP MERGE method action and payload will update a response with ID ‘E271F157-4356-4E16-B63B-AD681AED7BEE’:

  • URL: https://www.researchconsole.com/secure/api.svc/Responses(guid'E971F157-4356-4E06-B63B-AD681AED7BEE')

Attachments
MobenziAPIDemo.zip 70.2 Kb Download File
Rss Comments
  • There are no comments for this article.