How to configure Pilario for Data Collection

Discover how Pilario's user-friendly interface, trusted relationships, and data anonymity features through forms and dashboards make it a valuable tool for data collection

Some users, being part of a federation or consortium, might want to use Pilario as a data collection tool due to the simplicity of the platform, the already established trust relationships and/or to avoid dealing wIn this article we cover the ith third parties to ensure data anonymity. Pilario addresses these needs via the data collection forms and dashboards.

In this help article we will be using the following terms to simplify, Collector(s) will refer to the federation, consortium, company, etc which want to collect and analyse data. Submitter(s) will be those who will fill the forms defined previously.

The basic workflow to achieve data collection is the following:

1. The Collector prepares a form with all the fields to collect. These fields can be of different types, mandatory or optional, displayed under certain conditions, etc
2. The Collector defines a dashboard to analyse the data provided. The data can be directly displayed in Pilario or exported for analysis in other tools.
3. The Collector asks/provides the Submitters for/with their pairing pair: tenant id and pairing key. This ensures a trust between both parties which can be revoked at any time by any of them.
4.  The Collector creates user groups, which includes one or many Submitters previously paired, and shares the form with them.
5. Submitters fill the forms.
6. Collector analyses the data directly in Pilario via the defined dashboard. Or exports the data for analysis.

Setting the system for Data Collection

Pilario needs to be configured before being used for data collection. The settings have been placed in two different places to make it easier to access. The basic ones can be quickly accessed via the direct menu, for the more advanced ones, the user needs to go to the system settings tab.

In order to open the basic data collection settings, click on the left menu item Data Collection. This will display the following items:

• Forms
• Submissions
• Dashboards

In the following subsections, we describe in depth each of the settings available.

Dashboards

Dashboards are used to get a visual representation of the data collected. Every form that is created will be displayed in the dropdown menu but, the data displayed or available to export, will be determined by the report formula setting (see the next section).

Here we present an example of a Dashboard generated.  Note the following actions:

• A user can perform dynamic filtering of the graphs by using the dropdown filters at the upper part of the page
• The export button is available before all results. Clicking on it will download a CSV file containing all the data currently represented (filtering applies).
• Moving the mouse over the different graphs will display the value of the data.

Forms

Forms define the data that wants to be collected. A user must define a set of mandatory parameters, defined in the General section and then as many Fields as wanted.

Most of the attributes listed in the General section are self-explanatory, nevertheless, we list them here with a short description.

• Name: represents the name of the form. This field will be displayed in the Submitters' data collection section.
• Description: represents a description of the form. This field will be displayed in the heading of the form and can help submitters understanding the nature of the form, for example, by providing a long description of what the usage of the data will be.
• Help link: a valid URL which will provie more information about the form. Used to complement description when needed if the Collector wants to add addtional references or images about the nature of the form. 
• Status: defines the status of the form. Forms are by default created with a Draft status. In this state, they will not be available to the Submitters. A form needs to be Published to be available for the Submitters. If after being published this state is changed to draft, the form will disappear from the Submitters data collection page, but when published again they will be able to access their previous submissions.
• Start date and End date: determine the timeframe during which the form is open for submissions. If the form is published outside this timeframe, it will still be visible, but submitters will not be able to submit any data.
• Allow multiple submissions: determines if a form can be submitted several times. If set to False after the first submission, the form will not display the option for new submissions. However, if this is changed after previous submissions, all the forms will still be accessible to the Submitters.
• Anonymous submissions: determines whether form submissions will be anonymised and cannot be traced back to the submitter. While the system enforces this feature by default, it is visually presented in the interface to help users understand how their data remains anonymous.

• Minimum submitters: specifies the number of submitters needed before a report can be generated or data can be exported in the Dashboards. If the required number of submitters is not met, the system will prompt a message accordingly instead of displaying data. This feature helps Collectors determine if they need to remind Submitters to submit their data.
• Share groups: determines the group or groups the form will be shared with. Have a look into the subsection below to see how to create share groups.
• Report formula: determines the report formula that will be used to generate the reports. It should always return an object of the type dashboard. The following example, that can be used as a template, is used to count the number of True and False in a form that contains that as the single field.

/**
 * Available field names are: 
 * - a_boolean_field
 */

const { form, submissions, records, aggregate } = context

// Manually counting True and False values
let trueCount = 0;
let falseCount = 0;

for (const record of records) {
  if (record.a_boolean_field === true) {
    trueCount++;
  } else if (record.a_boolean_field === false) {
    falseCount++;
  }
}

// Sample dashboard
const dashboard = [
  {     
    title: 'True or False',
    legend: { x: 'True or False', y: 'Count' },
    data: [
      { x: 'True', y: trueCount },
      { x: 'False', y: falseCount }
    ]
  }
];


return dashboard

The Fields section, allows the user to define the data that wants to be collected. A form can contain one or more fields. For each field, there are several attributes that can be defined.

• Label: describes the field label and can also be understood as the field name. It is a good practice to keep this simple and short. 
• Description: can be used to provide more information to Submitters about the field that is being collected. It is presented in the form under the label.
• Data type: defines the type of data that is being collected. Three types are available: Text, Number, Boolean.  Some other attributes are available based on the type.
• Unit: it is only available for the data type Number and Boolean. It can be used to help Submitters understand the units in which the data is being collected. Will be presented inside the data box as a helper text.
• Filter: enables this fields as filters in the report generation.
• Display as: it is only available for the data type Number and Boolean and can be Input or Select. The Input option makes the field a free entry value, while Select allows the Collector to define a list of values to select and which will be presented in a dropdown list.
• Multiple: it is only available for fields with a Display as > Select. Used to allow the selection of several items from the dropdown list.
• Possible values: it is only available for fields with a Display as > Select. Used to provide a list of values that will be available in the dropdown list. For example, this can be useful to define a list of countries.
• Minimum value and Maximum value: it is only available for fields with Data type > Number and with a Display as > Input. Used to define the maximum values permitted, the form will not let the Submitter saving the form if the value is out of that range.
• Required: permits defining rules and group of rules to enforce the field being filled before submitting. The rules can be defined based on absolute terms i.e. Always required or based on other fields. For example, a user might have enabled a boolean field like Do you have any other remarks?, based on that, it could enforce filling a free text value named Other remarks.
• Visibility: permits defining rules and group of rules to enforce the field being visible or hidden in the form. The rules can be defined based on absolute terms i.e. Always hidden or based on other fields.

In order to open the more advanced data collection settings:

1. Click on the Settings item on the left menu bar
2. See the DATA COLLECTION on the left menu which contains the following elements
   1. Share groups
   2. Pairings

Share groups

Share groups are groups of organisations with whom the forms will be shared. A share group has a Name and a Description that can help the Collector organising different organisations. A previously paired organisation (see section below) can be part of none, one or many share groups.

Pairings

Before organisations can share data, they need to establish a trust relationship. This is achieved via the Pairings.

In order to establish the relationship, any party needs to share with the other a pair of ids called Organisation Id and Pairing key. The trust relationship is a two-way relationship and can be established and revoked from any side.

Once the pairing has been established, the Collector chan define groups to include the organisations and share forms.

Submitting data

Users can now submit data, in the Data Collections item in the left menu bar where a list of all the forms that have been shared with the current organisation will be visible. For more detailed explanation of this process follow the article How to use Pilario for Data Collection (submissions).