SimPrints Integration with ODK Collect

Introduction to Simprints

SimPrints is hardware and software used to collect fingerprint biometric data which integrates with mobile data collection tools like ODK Collect. SimPrints will collect fingerprints and associate it with a Globally Unique Identifier (GUID). It can be used for enrolment, verification, and identification.

• In enrolment, a person’s fingerprint collected and associated with a GUID. Once enrolled, a person can be verified or identified by their GUID.
• In verification, a known person uses their fingerprints to confirm their identity.
• In identification, a person is identified based on a match of their fingerprints in a search against all collected fingerprints.

Recommended Devices

SimPrints works best on mobile devices with Android versions of 4.0.1 (API 14) or up and a dual-core minimum.

Installing SimPrints

The SimPrints app integrates with ODK Collect. Therefore, you must first download, install, and configure ODK Collect. For more information on downloading, installing, and configuring ODK Collect, please see our documentation.

Once you have installed ODK Collect, you will need to install the SimPrints app:

1. On your Android device, navigate to the Google Play Store and search for Simprints.
2. Click Install, and Accept.

XLSForm syntax to enroll, verify and identify beneficiaries

When authoring your XLSForm, you will have to include additional items as listed below for the Simprints integration to work:

• The API key is provided by Simprints and is used to authenticate access to the Simprints app. To obtain this, you will need to contact Simprints.
• The Module ID lets the Simprints app know in which module for your project you would like to add, update, or search for a beneficiary.
• The Result Format is how the data should look when the data is returned from Simprints.
• The User ID is used to identify which user is making a request to the Simprints app and is important for searching and syncing.

Setting the User ID

The User ID should be included at the beginning of the survey before any data collection questions:

• In the type column, type “username”
• In the name column, type “username”

The User ID is automatically taken from ODK Collect. To set this value, go to

ODK Collect’s General Settings, and select User and device identity. In User and device identity, select Form Metadata. Under User-defined, select Username and enter your desired username. This username can be any username that you will use for all requests to the Simprints app.

Setting the API key

The API key should also be defined at the beginning of the form, prior to collecting any data:

• In the type column, type “calculate” as the question type.
• In the name column, type “api_key”.
• If you have not already created a calculation column, in the first empty cell in the first row, type “calculation”.
• In the same row as the api_key field name under the calculation column, type “concat(‘API Key Provided by Simprints’)” where the value between the single quotes is the API Key provided by Simprints.

Setting the Module ID

The Module ID should be defined at the beginning of the form, prior to collecting any data:

• In the type column, type “calculate” as the question type.
• In the name column, type “module_id”.
• In the same row as the module_id field name under the calculation column, type “concat(‘Module ID determined by user’)” where the value between the single quotes is the name of the module ID created by the user used to add, update, or search for a beneficiary.

Note:

• You may want to use different module ids for different projects or areas of data collection to differentiate the pools of GUIDs.

Setting the Result Format

The Result Format should be defined at the beginning of the form, prior to collecting any data, but after defining the Module ID:

• In the type column, type “calculate” as the question type.
• In the name column, type “result_format”.
• In the same row as the result_format field name under the calculation column, type “concat(‘ODKv01’)” where the value between the single quotes is format the results from the Simprints app will be returned as. Essentially, the results will be returned from the Simprints app in a format that is readable by ODK.

Enrolling beneficiaries

In your registration form, after including your username, API key, module ID, and result format, you should include questions to collect any other identifying information you would like to use later in the identification or verification processes. These questions may include their full name, their gender, their age, etc. In the example form, only the name, gender, and age are included. These questions will be added to XLSForm as normal. Please see xlsform.org for more information on XLSForm syntax.

After all the questions used to identify the beneficiary have been included, combine the data information:

• In the type column, type “calculate” as the question type.
• In the name column, type the desired field name for the combined identification field. In the example form, “name_gender_age” was used.
• In the same row as the combined identification field name under the calculation column, type “concat(${fieldname1}, ‘ ‘, ${fieldname2}, ‘ ‘, …..)” where the value between the dollar sign ($) and curly brackets ({ }) is the field name of the individual questions used for identification (i.e. name, gender, age, etc) separated with a comma (,) and space between single quotes (‘ ‘). You should include all the individual field names of questions that were used as the identifying information. In the example form, the function is “concat(${name}, ‘ ‘, ${gender}, ‘ ‘, ${age})”.

You can collect the beneficiary’s fingerprint at any point after including the username, API key, module ID, and result format. To indicate where the beneficiary’s fingerprint is collected:

• In the type column, type “begin group”.
• In the name column, type “registration”.
• In the label column, type “Register Person”.
• In the first empty cell in the first row, type “intent”.
• In the same row as the registration field name under the intent column, type “com.simprints.id.REGISTER(apiKey=${api_key}, userId=${username}, moduleId=${module_id}, resultFormat=${result_format})”.
• If you have not already created the appearance column, in the first empty cell in the first row, type “appearance”.
• In the same row as the “registration” field name under the appearance column, type “field-list”.
  • NOTE: If this is not included, the form will not work.

In the next row after the “registration” group field name:

• In the type column, type “text” as the question type.
• In the name column, type “guid”.
• In the label column, type “Registered person’s GUID”.

In the next row after the “guid” field name:

• In the type column, type “end group”

Failed Registration

There is a possibility that the registration may fail. If no value is displayed below the text “Registered person’s GUID”, the registration failed. To inform the user of an error:

• In the type column, type “note” as the question type.
• In the name column, type a field name for the failed registration note.
• In the label column, type “The registration failed. Beneficiary could not be registered.”
• If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
• In the same row as the field name under the relevant column, type “${guid} =’ ‘ “. This will help this note to only show when the guid is empty.
• If you have not already created a required column, in the first empty cell in the first row, type “required”.
• In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from finalizing the form.

Please see our example form for additional assistance in developing your own form.

Verifying beneficiaries

The verification form will also use a linked dataset to pull identifying information that was collected while enrolling beneficiaries. When you upload your verification form to Ona, you will have to link the registration dataset, which you will name the linked dataset. In the example form, this linked dataset is named “Registration”.

In your verification form, after including your username, API key, module ID, and result format, you will create a multiple-choice question to allow a user to select the beneficiary to verify:

In the survey worksheet:

• In the type column, type “select_one” as the question type, add a space, and enter the listname associated with the choice options for this question. In the example form, the listname is called “name_gender_age”.
• In the name column, type the desired name of the field. In the example form, the field name given is “beneficiary_selected”.
• In the label column, type the question text, such as “Select the beneficiary:”.
• If you have not already created the appearance column, in the first empty cell in the first row, type “appearance”.
• In the same row as the created field name under the appearance column, you will use the search function to create a dynamically populated list of choice options. Type “search(‘Name of linked dataset’) where the value between the single quotes is the name of the linked dataset given. For example, in the example form, the function used is “search(‘Registration’)” where Registration is the name of the linked dataset given.

In the choices worksheet:

• In the list_name column, type the given listname or copy/paste it from the select_one question.
• In the name column, type the name of the CSV column in the linked dataset you would like to use to uniquely identify the selected choices. If the value is located in a group special notation must be used. Please see our documentation on referencing field names from a linked dataset in the linked form.
• In the label column, type the name of the combined identification field from the registration form. If the value is located in a group special notation must be used. Please see our documentation on referencing field names from a linked dataset in the linked form.

After creating the multiple choice question to select the beneficiary to verify, you will collect the beneficiary’s fingerprint:

• In the type column, type “begin group”.

• In the name column, type “verification”.
• In the label column, type “Verify Person”.
• In the first empty cell in the first row, type “intent”.
• In the same row as the “verification” group field name under the intent column, type “com.simprints.id.VERIFY(apiKey=${api_key}, userId=${username}, moduleId=${module_id}, verifyGuid=${field name of multiple choice question to select beneficiary to verify}, resultFormat=${result_format})” where the value after “verifyGuid =” between the dollar sign ($) and curly brackets ({ }) is the field name from the multiple choice question use to select the beneficiary to verify. In the example form, this field name was “beneficiary_selected”
• If you have not already created the appearance column, in the first empty cell in the first row, type “appearance”.
• In the same row as the verification field name under the appearance column, type “field-list”.
  • NOTE: If this is not included, the form will not work.

In the next row after the “verification” group field name:

• In the type column, type “text” as the question type.
• In the name column, type “guid”.
• In the label column, type “Verified person’s GUID”.

In the next row after the “guid” field name:

• In the type column, type “text” as the question type.
• In the name column, type “confidence”.
• In the label column, type “Verified person’s confidence”.

In the next row after the “confidence” field name:

• In the type column, type “text” as the question type.
• In the name column, type “tier”.
• In the label column, type “Verified person’s tier”.

In the next row after the “tier” field name:

• In the type column, type “end group”

After collecting the beneficiary’s fingerprints, the beneficiary GUID will be used to confirm the identity with the data collected in the registration form. For each question used as the identification information in the registration form, in the section after collecting the beneficiary’s fingerprint, add a field to pull data based on the field “guid” or the beneficiary’s GUID:

• In the type column, type “calculate” as the question type.
• In the name column, type a field name for the value being pulled (i.e. “name_pulled” for the row where the name is being pulled.
• If you have not already created a calculation column, in the first empty cell in the first row, type “calculation”.
• In the same row as the field name under the calculation column, type “pulldata(‘Name of Linked Dataset’, ‘field name of the value to be pulled from the Linked dataset’, ‘guid field name in the linked dataset’, ${guid}) If the value referenced from the linked dataset is located in a group, a special notation must be used. Please see our documentation on referencing field names from a linked dataset in the linked form.

Once you have repeated the process of pulling all the data used as identification information, you can display all the information in a note:

• In the type column, type “note” as the question type.
• In the name column, type a field name for the verification note.
• In the label column, type “Verified Person: ${field name of pulled value 1, ${field name of pulled value 2}, …” where the value between the curly brackets ({ }) is the field name of each pulled value. In the example form, this would look like “Verified Person: ${verfied_name}, ${verfied_gender}, ${verified_age}” where only the name, gender, and age were collected in the registration form.

Failed Verification

There is a possibility that the verification may fail. Two possible types of a failed verification are:

1. If no value is displayed below the text “Verified person’s GUID:”, the verification failed. To inform the user of an error:
   • In the type column, type “note” as the question type.
   • In the name column, type a field name for the failed verification note.
   • In the label column, type “The verification failed. Beneficiary could not be verified.”
   • If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
   • In the same row as the field name under the relevant column, type “${guid} =’ ‘ “. This will help this note to only show when the guid is empty.
   • If you have not already created a required column, in the first empty cell in the first row, type “required”.
   • In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from finalizing the form.
2. If the value below the text “Verified person’s tier” is TIER_4 or TIER_5, the verification failed as the confidence that the person selected is the same person being verified is too low.
   • In the type column, type “note” as the question type.
   • In the name column, type a field name for the failed verification note.
   • In the label column, type “The verification failed. The confidence of the identification was too low.”
   • If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
   • In the same row as the field name under the relevant column, type “${tier} = ‘TIER_4′ or ${tier}=’TIER_5’ “. This note will appear when the confidence that the selected person is the same as the person being verified is too low.
   • If you have not already created a required column, in the first empty cell in the first row, type “required”.
   • In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from finalizing the form.

Please see our example form for additional assistance in developing your own form.

Identify a Beneficiary

The identification form will also use a linked dataset to pull identifying information that was collected while enrolling beneficiaries. When you upload your identification form to Ona, you will have to link the registration dataset, which you will name the linked dataset. In the example form, this linked dataset is named “Registration”.

In your identification form, after including your username, API key, module ID, and result format, you can collect the beneficiary’s fingerprint:

• In the type column, type “begin group”.

• In the name column, type “identification”.
• In the label column, type “Identify Person”.
• In the first empty cell in the first row, type “intent”.
• In the same row as the “identification” group field name under the intent column, type “com.simprints.id.IDENTIFY(apiKey=${api_key}, userId=${username}, moduleId=${module_id}, resultFormat=${result_format})”
• If you have not already created the appearance column, in the first empty cell in the first row, type “appearance”.
• In the same row as the “identification” field name under the appearance column, type “field-list”.
  • NOTE: If this is not included, the form will not work.

In the next row after the “identification” group field name:

• In the type column, type “text” as the question type.
• In the name column, type “guid”.
• In the label column, type “Ordered list of identified GUIDs”.
• If you have not already created the odk:length column, in the first empty cell in the first row, type “odk:length”.
• In the same row as the “guid” field name under the odk:length column, type “1000”.

In the next row after the “guid” field name:

• In the type column, type “text” as the question type.
• In the name column, type “confidence”.
• In the label column, type “Corresponding confidences for identified GUIDs”.
• In the same row as the “confidence” field name under the b column, type “1000”.

In the next row after the “confidence” field name:

• In the type column, type “text” as the question type.
• In the name column, type “tier”.
• In the label column, type “Corresponding tiers for identified GUIDs”.
• In the same row as the “tier” field name under the odk:length column, type “1000”.

In the next row after the “tier” field name:

• In the type column, type “end group”

After collecting the beneficiary’s fingerprints, the beneficiary’s GUID will be used to create a list of possible beneficiaries that match the data collected in the registration form:

• In the type column, type “begin group”.
• In the name column, type “select_identification”.
• In the label column, type “Identification”.

After the “select_identification” group:

• In the type column, type “calculate” as the question type.
• In the name column, type “count”.
• If you have not already created a calculation column, in the first empty cell in the first row, type “calculation”.
• In the same row as the count field name under the calculation column, type “count-selected(${guid})”. This function will provide a count of the number of possible matches returned by the Simprints app.

After the “count” field name, you will have to pull the combined identification field for all the possible associated GUIDs. The number of GUIDs could vary depending on the number of people you registered, but at maximum, it will pull 20 possible GUIDs. You will need to create 20 fields to pull the data for all possible GUIDs. Repeat the process below for each possible GUID:

• In the type column, type “calculate” as the question type.

• In the name column, type a field name for the value being pulled (i.e. “combined_pulled1” for the row where the combined identifying information is being pulled).
• In the same row as the field name under the calculation column, type “pulldata(‘Name of Linked Dataset’, ‘field name of the value to be pulled from the Linked dataset’, ‘guid field name in the linked dataset’, selected-at(${guid}, 0))”. If the value referenced from the linked dataset is located in a group, a special notation must be used. Please see our documentation on referencing field names from a linked dataset in the linked form.
  • The last value in the pulldata function (i.e. selected-at(${guid}, 0)) will pull the value of the guid. The number is always 1 less than the value you are pulling (i.e. if you are pulling the first value, the number should be 0). Therefore, for proceeding pulldata function, the 0 will become 1 for the second pulled data, e.t.c.

After pulling the identifying information for each possibly associated GUID, you will need to select the one identity it might be:

In the survey worksheet:

• In the type column, type “select_one” as the question type, add a space, and enter the listname associated with the choice options for this question. In the example form, the listname is called “name_gender_age”.
• In the name column, type the desired name of the field. In the example form, the field name given is “identity”.
• In the label column, type the question text, such as “Select the correct beneficiary:”.
• If you have not already created the choice_filter column, in the first empty cell in the first row, type “choice_filter”.
• In the same row as the created field name under the choice_filter column, you will use 20 choice filters connected using the “or” conditional statement. Type “cf1=${count} or cf2=${count} or cf3=${count} or cf4=${count} or cf5=${count} or cf6=${count} or cf7=${count} or cf8=${count} or cf9=${count} or cf10=${count} or cf11=${count} or cf12=${count} or cf13=${count} or cf14=${count} or cf15=${count} or cf16=${count} or cf17=${count} or cf18=${count} or cf19=${count} or c20=${count}”. This function will use the count field name to determine how many options will show, with a possible maximum number of 20 choice options.

In the choices worksheet:

• In the list_name column, type the given listname or copy/paste it from the select_one question.
• In the name column, type “1” for the first value
• In the label column, type “${field name pulled in previously}” where the value between the dollar sign ($) and curly brackets ({ }) is the field name of the first pulled data of the combined identifying information.
• Repeat for all 20 GUID pulled data fields
• Add an option that none of the above beneficiaries are correct:
  • In the list_name column, type the given listname or copy/paste it from the select_one question.
  • In the name column, type “21” for the first value
  • In the label column, type “None of the above”.
• In the first empty cell in the first row, type “cf1” for the first choice filter.
• Repeat for all 20 choice filters (i.e. cf2, cf3, etc.).
• In the row with the first choice option for the given listname in the cf1 column, type “1” and for all following rows for the choice options up to 20, type “0”. For the row with the choice name 21, type “1”.
• In the row with the first and second choice options for the given listname in the cf2 column, type “2” and for all following rows for the choice options up to 20, type “0”. For the row with the choice name 21, type “2”.
• Repeat following the above pattern. Please see the example form for the choice_filter scheme for all 20 choice options.

After identifying the correct person in a multiple-choice question, you will want to pull the label from the selected beneficiary instead of the choice name (e.g. a number between 1 and 20):

• In the type column, type “calculate” as the question type.
• In the name column, type a field name for the value.
• In the same row as the field name under the calculation column, type “jr:choice-name(${field name for beneficiary selected in identification process},’${field name for beneficiary selected in identification process}’)” where the value between the dollar sign ($) and the curly brackets ({ }) is the field name of the multiple choice option where the identified beneficiary was selected

Then, you will want to identify the selected beneficiary by their GUID:

• In the type column, type “calculate” as the question type.
• In the name column, type a field name for the value.
• In the same row as the field name under the calculation column, type “selected-at(${guid}, ${field name for beneficiary selected in identification process}-1)” where the second value between the dollar sign ($) and the curly brackets ({ }) is the field name of the multiple choice option where the identified beneficiary was selected.

Lastly, you will want to identify the selected beneficiary who has a passing confidence level:

• In the type column, type “calculate” as the question type.
• In the name column, type a field name for the value.
• In the same row as the field name under the calculation column, type “selected-at(${tier}, ${field name for beneficiary selected in identification process}-1)” where the second value between the dollar sign ($) and the curly brackets ({ }) is the field name of the multiple choice option where the identified beneficiary was selected.

Once you have identified the identifying information, GUID, and confidence of the identified beneficiary, you will want a note to show the value:

• In the type column, type “note” as the question type.
• In the name column, type a field name for the identification note.
• In the label column, type “The selected individual is: ${field name determining the label of the selected beneficiary} with a unique id of: ${field name to identify the selected beneficiary by their guid}” where the first value between the curly brackets ({ }) is the field name determining the label of the selected beneficiary and the second value is the field name to identify the selected beneficiary by their guid.

After the note to confirm the identified beneficiary:

• In the type column, type “end group”

Note:

• It is possible to pull GUID that is not associated with any beneficiary collected in the registration form. This will result in blank options when selecting the beneficiary.

Failed Identification

There is a possibility that the identification may fail. Three possible types of failed identification are:

1. If no value is displayed below the text “Ordered list of identified GUIDs”, the identification failed. To inform the user of an error:
   • In the type column, type “note” as the question type.
   • In the name column, type a field name for the failed identification note.
   • In the label column, type “The identification failed. Beneficiary could not be identified.”
   • If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
   • In the same row as the field name under the relevant column, type “${guid} =’ ‘ “. This will help this note to only show when the guid is empty.
   • If you have not already created a required column, in the first empty cell in the first row, type “required”.
   • In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from moving forward in the form.
2. If the value for the selected identified beneficiary is TIER_4 or TIER_5, the identification failed as the confidence that the identified person is the correct person is too low. In the row after the selected beneficiary’s guid is identified:
   • In the type column, type “note” as the question type.
   • In the name column, type a field name for the failed identification note.
   • In the label column, type “The identification failed. The confidence of the identification was too low.”
   • If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
   • In the same row as the field name under the relevant column, type “${tier} = ‘TIER_4′ or ${tier}=’TIER_5’ “. This note will appear when the confidence that the selected person is the correct person is too low.
   • If you have not already created a required column, in the first empty cell in the first row, type “required”.
   • In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from finalizing the form.
3. If the data collector selects “None of the above” when identifying the beneficiary because their information did not come up, the identification process failed. In the row after the beneficiary’s identity is selected:
   • In the type column, type “note” as the question type.
   • In the name column, type a field name for the failed identification note.
   • In the label column, type “You selected “None of the above”. Your beneficiary cannot be identified. Please try again.”
   • If you have not already created a relevant column, in the first empty cell in the first row, type “relevant”.
   • In the same row as the field name under the relevant column, type “selected(${identity}, ’21’)“. This note will appear when the selected beneficiary is “None of the above”.
   • If you have not already created a required column, in the first empty cell in the first row, type “required”.
   • In the same row as the field name under the required column, type “yes“. This will prohibit the data collector from finalizing the form.

Please see our example form for additional assistance in developing your own form.

Failed Registration, Verification, or Identification

There are several reasons that any of these processes could fail. Possibilities could include the wrong API key or the person was never registered and can not be verified or identified. If you encounter a lot of failed processes, please contact the support team for additional assistance.