Guides
Guides

Concepts

Learn about the different types of concepts and their nuances

Concepts define the different pieces of information that you collect as part of your service delivery.

For example, if you collect the blood pressure of a subject in a form, then "Blood Pressure" should be defined as a concept. You would notice that every question in a form requires a concept.

The datatype of a concept determines the kind of data can be stored against a concept, and therefor against the form question or form element. Using concepts with datatypes ensures incorrect answers are not captured in a form question, and is helpful for eventually data aggregation, validation and reporting.

Supported DataTypes in Concepts

The following datatypes are supported while defining concepts to be used in forms:

Concept DataTypeDescription
Numeric conceptsNumeric concepts are used to capture numbers. When creating a numeric concept, you can define normal ranges and absolute ranges. In the field application, if an observation for a concept collected goes beyond the normal range, then it is highlighted in red. Values above the absolute range are not allowed. For instance for concept: Blood Pressure (Systolic), you can choose a Numeric concept with ranges.
Coded concepts (and NA concepts)

Coded concepts are those that have a fixed set of answers. For instance for Blood Group you would choose a coded concept with values: A+, B+, AB+, etc.

These answers are also defined as concepts of NA datatype.

ID datatypeA concept of Id datatype is used to store autogenerated ids. See Creating identifiers for more information on creating autogenerated ids. For instance PatientIDs, TestIDs, etc.
Media concepts (Image, Video and Audio, File, ImageV2)

Images and videos can be captured using Image and Video concept datatypes. To capture Images with geotagging and other metadata associated, ImageV2 datatype can be used.

For audio recording, Audio datatype can be used.

For other generic file types, File datatype can be used.

Text (and Notes) conceptsThe Text data type helps capture one-line text while the Notes datatype is used to capture longer form text.
Date and time conceptsThere are different datatypes that can be used to capture date and time.
  • Date* - A simple date with no time
  • Time* - Just the time of day, with no date
  • DateTime* - To store both date and time in a single observation
  • Duration* - To capture durations such as 4 weeks, 2 days etc.
Location concepts
  • Location_ concepts can be used to capture locations based on the location types configured in your implementation.
Location concepts have 3 attributes:

  1. Within Catchment - Denotes whether the location to be captured would be within the catchment already assigned to your field workers. This attribute defaults to true and is mandatory.

  2. Lowest Level(s) - Denotes the lowest location type(s) you intend to capture via form elements using this concept. This attribute is mandatory.

  3. Highest Level - Denotes the highest location type that you would like to capture via form elements using this concept. This attribute is optional.

Subject concepts
  • Subject_ concepts can be used to link to other subjects.
Each Subject concept can map to a single subject type.

Any form element using this concept can capture one or multiple subjects of the specified subject type.

Phone Number conceptsFor capturing the phone number. It comes with a 10 digit validation. OTP verification can be enabled by turning on the "Switch on Verification" option. Avni uses msg91 for OTP messages, so msg91 Auth key and Template need to be step up using the admin app.
Group Affiliation conceptsWhenever automatic addition of a subject to a group is required Group Affiliation concept can be used. It provides the list of all the group subjects in the form and choosing any group will add that subject to that group when the form is saved.
Encounter
  • Encounter_ concepts can be used to link an encounter to any form.
Each Encounter concept can map to a single encounter type. It should also provide the scope to search that encounter. Also, name identifiers can be constructed by specifying the concepts used in the encounter form.

Any form element using this concept can capture one or multiple encounters of the specified encounter type.


Hidden concepts

Normally a value that is stored is shown, and a question hidden by a rule has its answer deleted. A hidden concept gives a third option: the value is stored, synced and reported like any other observation, but is never shown to anyone using the field app or the data entry app.

Hiding is a property of the concept, so it applies to every form that uses the concept, for every user in the organisation. It is not a permission: no role or user group can see a hidden value in either app. It takes effect for values already collected as well as new ones, because the decision is made when a screen is drawn.

The feature exists for cases where a value must be recorded without influencing the person recording it. The usual example is running an on-device AI model in shadow mode: the model's verdict is saved alongside the worker's own assessment so the two can be compared in reporting, without the worker ever seeing the verdict.

Marking a concept hidden

  1. In App Designer, open the concept on the Concepts screen.
  2. Tick Hidden and save.
The Concepts screen with Hidden ticked

The tick stores a hidden key-value on the concept. Configuration bundles carry it, so a concept exported from one organisation arrives in another still hidden. Unticking it and saving removes the marker, and values recorded earlier become visible again.

🚧

On the create screen, choose the datatype before ticking Hidden

Changing the datatype of a new concept clears every key-value on it, including the Hidden tick, without warning. Choose the datatype first and tick Hidden after. Editing an existing concept does not have this problem.

In the form designer, a question whose concept is hidden shows a read-only Hidden marker, and its Mandatory tickbox is disabled with the reason shown. The marker cannot be changed from the form; it belongs to the concept.

Where a hidden value never appears

In the field app:

  • the form page, including inside a repeatable question group
  • the summary at the end of the form, both the answers given and the decisions the app worked out
  • the subject's profile
  • past visits in the subject's history
  • program enrolments, and the answers recorded on program exit
  • approval screens
  • summary screens built by a rule
  • shared or printed copies of a form

In the data entry app:

  • a visit
  • the subject's profile
  • a program enrolment
  • the page shown after registering someone
  • summaries built by a rule
  • the list of completed visits
  • subject search results: a hidden concept configured as a custom search result field is left out of the result columns. The configuration itself is not changed, and the column comes back if the concept is unhidden.

A screen or table whose values are all hidden shows nothing at all, rather than an empty frame or a heading with no rows.

What hiding does to a question

  • It is never required. A hidden question is not validated, so it cannot block a worker from moving to the next page, whatever its Mandatory setting says. A Mandatory tick saved before the concept was hidden is kept and still shows in the form designer, but has no effect. This is the guarantee; the disabled tickbox in the designer only prevents the wrong expectation, because a concept can be hidden long after forms already use it.
  • A failed inference raises no error. If an on-device model cannot produce a value for a hidden question, the worker sees no error and is not blocked. For a question that is not hidden the error still appears and still blocks, exactly as before.

Hidden concepts and visibility rules are different things

Hiding a question with a form element rule that returns visibility: false removes the question from the form and deletes its answer. Marking the concept hidden keeps the answer and only stops it being drawn. The two sound alike and do opposite things to the value.

This also means a visibility rule that hides a hidden concept's question still deletes the value. Do not combine the two.

Designing a form with hidden questions

  • Put the hidden question on the same page as whatever produces its value. A value produced while a page is being filled, such as an on-device model's verdict, is written into a question on that page. If the hidden question sits on another page, the value is lost.
  • Keep at least one visible question on every page. A page whose questions are all hidden draws blank, heading included. Avni does not prevent this; it is a configuration mistake to avoid.

What hiding is not

  • Not a confidentiality control. The value is stored in the app's local database on the device, travels in sync, appears in every export, and is fully readable in the reporting database and in reports. Hiding only keeps it off the screens of the two apps.
  • Not protection from rules. A rule can read a hidden value and use it somewhere the worker can see: copy it into a visible question, or show a different prompt depending on what it was. The marker hides the value itself, not a conclusion drawn from it. Nothing in Avni prevents or detects this. Reviewing the organisation's rules is what catches it.
  • Not per user or per role. Hidden means hidden from everyone who uses the apps. Reporting is where a hidden value is read.

Showing counselling points in Forms

For showing counselling points in a form, always create a Form Element, using below coded Concept:

  • Concept UUID: b4e5a662-97bf-4846-b9b7-9baeab4d89c4
  • Concept Name: Placeholder for counselling form element
  • Answers: <None, no answers, to avoid showing them any options>

Specify counselling point as the Form Element Name, add numbering if needed.

Note: You can reuse the same "Placeholder for counselling form element" multiple times in a single form, without worrying about uniqueness constraint breach concerns.

Location Concept Configuration

General Location Concept Behavior

When "Within Catchment" is set to FALSE

When using a "Location" type concept with "Within Catchment" set to false:

  • You must ensure that you perform update of the form(s) using that concept
  • So that on form save, the organisation_config settings gets auto-modified to sync locations outside catchment to the user's device
  • This ensures all locations are accessible while filling the form

When "Within Catchment" is set to TRUE (default)

When this option is enabled:

Requirements:

  • Every user's catchment configuration must contain all required "Highest Level" type locations
  • Without this, the form will not display any locations for selection

Display Behavior:

  • Even if some users' catchments have locations higher than the Location concept's "Highest Level" type, those higher levels will not be shown
  • The listing will start from the "Highest Level" type
  • All locations across different lineages will be bunched together in a single list

CSJ Organization - Important Notes

Catchment Configuration Requirements

Note for CSJ org support: Please keep the following details for future reference:

  1. Catchment Level: For CSJ org, User Catchments must be configured at District Level and above. This is due to the HighestAddressLevelType configuration set for:

    • "Address of Applicant" in "Case" Registration
    • "Address of applicant - Claim" in "Claim" Registration

  2. Location Hierarchy: User Catchments should include both "Administrative State" and "State" hierarchy locations.

Known Limitation

Due to the form concept configuration restriction mentioned above:

  • State information will not be shown on the app while filling in the address fields
  • This applies irrespective of the catchment configuration for a user
  • For users with large catchments, all districts across different states will appear in a single listing
  • There is no ability to categorize districts by their respective states

Updated 7 days ago

What’s Next