This repository is the microservice that implements the forms and Questionnaire functionality
You will need Control Tower up and running - either natively or with Docker. Refer to the project's README for information on how to set it up.
The GFW Forms API microservice is built using Node.js, and can be executed either natively or using Docker, each of which has its own set of requirements.
Native execution requires:
Execution using Docker requires:
Dependencies on other Microservices:
Start by cloning the repository from github to your execution environment
git clone https://github.com/gfw-api/gfw-forms-api.git && cd gfw-forms-api
After that, follow one of the instructions below:
1 - Set up your environment variables. See dev.env.sample for a list of variables you should set, which are described in detail in this section of the documentation. Native execution will NOT load the dev.env file content, so you need to use another way to define those values
2 - Install node dependencies using yarn:
yarn
3 - Start the application server:
yarn start
The endpoints provided by this microservice should now be available through Control Tower's URL.
1 - Create and complete your dev.env file with your configuration. The meaning of the variables is available in this section. You can find an example dev.env.sample file in the project root.
2 - Execute the following command to run Control tower:
./forms.sh develop
The endpoints provided by this microservice should now be available through Control Tower's URL.
There are two ways to run the included tests:
Follow the instruction above for setting up the runtime environment for native execution, then run:
yarn test
Follow the instruction above for setting up the runtime environment for Docker execution, then run:
./forms.sh test
It is necessary to define these environment variables:
- CT_URL => Control Tower URL
- NODE_ENV => Environment (prod, staging, dev)
{
"data": [
{
"type": "reports",
"id": "591f2513d3a6c4003f4960b4",
"attributes": {
"name": {
"en": "My first report",
"es": "Mi primer informe"
},
"languages": [
"en",
"es"
],
"defaultLanguage": "en",
"areaOfInterest": "aoi-id",
"user": "1a10d7c6e0a37126611fd7a7",
"questions": [
{
"type": "text",
"name": "name",
"defaultValue": {
"en": "Insert your name",
"es": "Spanish"
},
"_id": "591f2513d3a6c4003f4960b7",
"conditions": [],
"childQuestions": [],
"order": 1,
"required": false,
"label": {
"en": "Name",
"es": "Nombre"
}
},
{
"type": "checkbox",
"name": "age",
"defaultValue": 0,
"_id": "591f2513d3a6c4003f4960b5",
"conditions": [],
"childQuestions": [
{
"type": "text",
"name": "specific-age",
"defaultValue": {
"en": "Insert your name",
"es": "Spanish"
},
"conditionalValue": 0,
"_id": "591f2513d3a6c4003f4960b6",
"order": 0,
"required": true,
"label": {
"en": "Specific age",
"es": "Specific age"
}
}
],
"order": 2,
"required": false,
"values": {
"en": [
{
"value": 0,
"label": "19-32"
},
{
"value": 1,
"label": "12-43"
}
],
"es": [
{
"value": 0,
"label": "18-12"
},
{
"value": 1,
"label": "12-45"
}
]
},
"label": {
"en": "Range age",
"es": "Spanish"
}
}
],
"createdAt": "2017-05-19T17:02:11.415Z"
}
}
]
}
All endpoints are logged. Check if user is ADMIN or MANAGER in gfw application
GET: /reports -> Return all reports accessible to user logged
GET: /reports/:id -> Returns report with the same id. Check if user is ADMIN or MANAGER in gfw application
Example response:
{
"data": {
"type": "reports",
"id": "592402c4cfcfaf0070e78826",
"attributes": {
"name": {
"en": "My report template",
"es": "Mi report templato"
},
"languages": [
"en",
"es"
],
"defaultLanguage": "en",
"areaOfInterest": "aoi-id",
"user": "1a10d7c6e0a37126611fd7a7",
"public": false,
"questions": [
{
"type": "text",
"name": "name",
"defaultValue": {
"es": "Spanish",
"en": "Insert your name"
},
"_id": "592402c4cfcfaf0070e78829",
"conditions": [],
"childQuestions": [],
"order": 1,
"required": false,
"label": {
"es": "Nombre",
"en": "Name"
}
},
{
"type": "checkbox",
"name": "age",
"defaultValue": 0,
"_id": "592402c4cfcfaf0070e78827",
"conditions": [],
"childQuestions": [
{
"type": "text",
"name": "specific-age",
"defaultValue": {
"es": "Spanish",
"en": "Insert your name"
},
"conditionalValue": 0,
"_id": "592402c4cfcfaf0070e78828",
"order": 0,
"required": true,
"label": {
"es": "Specific age",
"en": "Specific age"
}
}
],
"order": 2,
"required": false,
"values": {
"es": [
{
"label": "18-12",
"value": 0
},
{
"label": "12-45",
"value": 1
}
],
"en": [
{
"label": "19-32",
"value": 0
},
{
"label": "12-43",
"value": 1
}
]
},
"label": {
"es": "Spanish",
"en": "Range age"
}
}
],
"createdAt": "2017-05-23T09:37:08.315Z"
}
}
}
POST: /reports -> Create an report and associate to the user. With body:
{
"areaOfInterest": "aoi-id",
"languages": ["en", "es"],
"defaultLanguage": "en",
"name": {
"en": "My report template",
"es": "Mi report templato"
},
"public": false,
"questions": [
{
"type": "text",
"label": {
"en": "Name",
"es": "Nombre"
},
"name": "name",
"conditions": [],
"childQuestions": [],
"order": 1,
"required": false,
"values": {},
"defaultValue": {
"en": "Insert your name",
"es": "Spanish"
}
},
{
"type": "checkbox",
"label": {
"en": "Range age",
"es": "Spanish"
},
"name": "age",
"conditions": [],
"order": 2,
"required": false,
"values": {
"en": [
{ "value": 0, "label": "19-32"},
{ "value": 1, "label": "12-43"}
],
"es": [
{ "value": 0, "label": "18-12"},
{ "value": 1, "label": "12-45"}
]
},
"defaultValue": 0,
"childQuestions": [
{
"type": "text",
"label": {
"en": "Specific age",
"es": "Specific age"
},
"name": "specific-age",
"defaultValue": {
"en": "Insert your name",
"es": "Spanish"
},
"conditionalValue": 0,
"order": 0,
"required": true,
"values": {}
}
]
}
]
}
Notes: public fields can only be passed as true by ADMINs. These templates appear to all users. Required fields:
- name
- languages
- defaultLanguage
- public
- questions
PATCH: /reports/:id -> Update the report with the same id.
DELETE: /reports/:id -> Delete the report with the same id.
GET: /report/:id/answers -> Return all answers of the report by id of the user logged
GET: /report/:id/answers/:id -> Return answer with the same id. Check if the answer is owned of the logged user
Example response:
{
"data": {
"type": "answers",
"id": "59240430cfcfaf0070e78866",
"attributes": {
"report": "592402c4cfcfaf0070e78826",
"username": "fwuser",
"organization": "gfw",
"areaOfInterest": "my-area-id",
"language": "es",
"createdAt": "12-04-2017T13:40:34:223Z",
"userPosition": [
"1",
"1"
],
"clickedPosition": [
"1",
"1"
],
"startDate": "2013-01-23 12:00:33",
"endDate": "2013-02-23 15:00:33",
"layer": "GLAD",
"user": "1a10d7c6e0a37126611fd7a7",
"responses": [
{
"name": "name",
"parent": "none",
"value": "Ed",
"_id": "59240430cfcfaf0070e7886f"
},
{
"name": "age",
"parent": "none",
"value": "1",
"_id": "59240430cfcfaf0070e7886f"
},
{
"name": "specific-age",
"parent": "age",
"value": "21",
"_id": "59240430cfcfaf0070e7886f"
}
]
}
}
}
POST: /reports/:id/answers -> Create an answer to the report with the id of the report and associate to the user. With body:
Without Content-type (it is possible send files as attachments). For example
<questionName>: <responseValue>
name: Pepe
age: 0-18
specific-age: 32
photo: upload_file
Notes: These templates appear to all users. Required fields:
- language
- userPosition (comma separated lat lng [1,1])
- clickedPosition (comma separated lat lng [1,1])
- createdAt
- Any questions for the template that have the value required as true
PATCH: /reports/:id/answer/:id -> Update the answer with the same id. Check if the answer is owned by the logged user
DELETE: /reports/:id/answer/:id -> Delete the answer with the same id. Check if the answer is owned by the logged user
GET: /reports/:id/download-answers -> downloads all answers to the report by :id.
WIP:
- All PATCH under development
- Accept query params to all GET requests
- Download individual answers for reports
- Add query params to fetch answers by language