Home
CKAN is a dynamic platform that allows you to integrate extensions based on a default structure, depending on the requirements imposed. A repository of open-source extensions (https://extensions.ckan.org/) is publicly available and provides several documented extensions to facilitate its integration, saving work and time. Since there was the need to gather information through questionnaires and there wasn't any existing extension with it, the CitiesQuest was created. It works like a new layer over the CKAN structure where the extension's components are directly integrated into the interface.
CitiesQuest is an objective, efficient, and usable CKAN extension to allow users to create and fill questionnaires and manage the gathered data. Since CKAN provides the necessary tools and functionalities for the easy and correct management of data (open or not), implementing this extension will provide a new way of gathering information. It can be used for any scenario, although the main focus was the people's feedback. Nowadays, people search even more for cities to start their life. The opportunities and resources that a city provides are rising, giving a better lifestyle and stability. But, in the end, it is up to people to make good use of and manage what it's provided. That means that the people's opinion, lifestyle, security, and mindset are crucial pieces for a city's wellbeing and growth. Having that in mind, this extension meets the imposed requirements by helping to gather information through the filling of questionnaires, which are used to get people's feedback, event reports, or data that can improve the general management of a city.
First, to be able to use the extension, install it into the CKAN instance. For that, please go to Installation Page.
Having the extension installed on CKAN, it's possible to check that the main screen has a different structure already. A new component to list all the available questionnaires is rendered, depending on the user and privacy (check the following image).
Considering that there is no organization at the beginning of the CKAN instantiation and the questionnaires need one, the list on the main screen will be empty. So, the first thing to do is to [create an organization](Create an organization).
With an available organization, it is possible to add datasets. Briefly, a dataset is a unit where the data is published. Each dataset can have one or more resources with different types of data (e.g. a dataset about air quality observations in a city can have two spreadsheets as distinct resources for two separated years). With an available organization, it is possible to add datasets. Briefly, a dataset is a unit where the data is published. Each dataset can have one or more resources with different types of data (e.g. a dataset about air quality observations in a city can have two spreadsheets as distinct resources for two separated years). To differentiate each dataset, CKAN provides a specific dataset field named ‘extras’, structured as a set of key/value ‘Custom Fields’ where the admin can define whatever he wants. In this case, we have two types of keys (it is possible to integrate more):
- is_data_store
Datasets with this extra field will store data gathered from filling the provided questionnaires. Each questionnaire response is associated with a record and can be visualized by going into the resource and searching by id, username, questions, or answers. All the resources can be automatically created, depending on the name of the questionnaire that it is associated with.
- is_templating
For CKAN to build and list questionnaires, create a new dataset with this extra field. Consequently, the resources within this type of dataset are ready to be rendered, enabling its filling.
To see how to create and manage datasets, click here
At this point, there are organizations and datasets ready to store data. The CKAN component that enables data storing is understood as a resource. Each resource, always associated with a dataset, defines the data's type and provides the tools to visualize the data (having permission for that) and export it.
For instance, if a user wants to add a new questionnaire, it is mandatory to create a new resource in a 'templating' dataset. Depending on the questionnaire's type, the resource can be added to an existing dataset, or a new dataset is created before. Only then, a JSON file with the questionnaire's structure is uploaded to that resource (to be processed by the extension).
For the case of the questionnaires, they have to be uploaded into a specific platform's dataset, as explained further. Their data came from JSON files generated on an external website that handles standard survey generation for the web (https://surveyjs.io/Examples/Survey-Creator). This extension is responsible for getting the data and rendering structured and organized questionnaires.
SurveyJS is an online visual survey creator and form builder that offers what is needed.
This website is a critical part of the process. The website's default questionnaires structure is what the extension will try to understand to manage to render it in an efficient and organized way. Since the extension doesn't include all the tools and features provided in the website and to avoid malformed questionnaires, some rules and requirements were defined where the pages order and corresponding properties are required to follow.
The following steps show the correct workflow to create questionnaires:
-
Go to https://surveyjs.io/Examples/Survey-Creator#content-result. Then, using the survey design, start creating the questionnaire.
-
Change the page properties to create an introduction page (title, name, description).
-
Create the right components on the introduction page (Component objects).
-
Add new pages to fill them with questions.
-
All the questions must be inside a Panel object. After inserting one or several Panels, there are four types of inputs that our extension accepts:
-
radio group: To add it to the questionnaire, choose the ‘RadioGroup’ tool and click or drag it into the panel. It is possible to change the order of the questions by dragging them up and down. Having the object in the survey design and inside a panel, click on it and go to the ‘Properties’ link. There, the questions default fields (ignore the ‘Description’ field) are defined, and then it can be defined if it is required or not. By activating the ‘Is required’ field, the extension will assume the obligation, and the user will have to answer it. Then, it is needed to configure the possible answers. For that, go to the ‘Choices’ option (a dropdown button in the ‘Properties’ area). It contains the default key/values generated by the website, and those are the fields that must be changed. It is possible to erase, add options and change their values. Follow the next steps for a correct definition of each option:
-
change the ‘Text’ input to the value that will appear in the question as possible options;
-
change the ‘Value’ input with a snake case style (p.e not_at_all ). It is the same as the ‘Text’ input but converted into a snake case.
-
-
single input: It is the classic type of question where the user needs to write his answer. To add it, choose the tool ‘Single input’ (it is also possible to order it). The rules to apply are the same as used in the radio group questions except that there are no choices, and it is possible to write a placeholder.
-
Geolocation: This input type renders a map where the user can search for a specific address and choose it to identify places. The options available for each search are the available ones with the key used in the geocoding software allocated (it can be nominatim or mapbox);
-
Annexes (images): This type of entry offers the possibility of uploading images. It can be narrow to one or unlimited. The images are only uploaded in the end, which gives the option to delete the chosen ones and add different ones.
-
-
Finishing the questionnaire pages with the introduction page as well, the questionnaire is complete. Now, the raw data needs to be accessed and then exported. For that, SurveyJS provides a JSON Editor. It is a tab that enables the visualization of the questionnaire's raw data and provides the information in JSON format. To be able to export this data, this tab has several buttons with different actions. By clicking on the ‘Copy’ button, the data is copied.
-
Once all the necessary data has been copied from the JSON Editor, the next step is to save it in a local file. To do it, use a text editor. Then create a new file, paste all the data and save it with JSON extension (e.g trash_bins.json).
-
Create a new resource in a templating dataset and upload the JSON file to CKAN.
-
In CKAN, a JSON file is provided, as an example that contains SurveyJS generated data and can be imported into the website and then changed to the creators’ requirements.
Having the questionnaires created, the questionnaire's list on the main page will list them to the users that have permission to fill them.
The following examples are two questionnaires that were already tested and collect crucial data regarding public initiatives and the incident's report.
In this example, it's provided a form only with two questions regarding the user's opinion about the initiative, briefly explained on the initial page and at the beginning of the form, and an open text for the user to write what he desires. Important to mention that the first one is mandatory and the second isn't.
After some responses, its visualization in CKAN is the following:
To collect crucial data from this report, all the available question's types are used:
- Choose the exact place where the incident occurs using a dynamic map;
- Description, year, and open comments through single input questions;
- Annexes using file input;
It contains both mandatory questions and not, and input verification.
After some responses, its visualization in CKAN is the following:
Note: All the responses can be exported in several formats (JSON, CSV, TSV, and XML)