Add census conexion configuration documentation

docs/SUMMARY.md

@@ -41,6 +41,7 @@
   * [OAuth](en/features/oauth.md)
   * [GraphQL](en/features/graphql.md)
   * [Recommendations](en/features/recommendations.md)
+  * [Configure Census Conexion](en/features/census_configuration.md)
 
 * [Open Source project](en/open_source/open_source.md)
   * [Code of conduct](en/open_source/code_of_conduct.md)
@@ -75,7 +76,7 @@
     * [Servidor local de correo](es/installation/dev_mailserver.md)
   * [Configuración básica](es/installation/basic_configuration.md)
   * [Documentación y guías sobre CONSUL](es/installation/documentation_and_guides.md)
-    
+
 * [Personalización](es/customization/customization.md)
   * [Introducción](es/customization/introduction.md)
   * [Textos & Traducciones](es/customization/translations.md)
@@ -90,6 +91,7 @@
   * [OAuth](es/features/oauth.md)
   * [GraphQL](es/features/graphql.md)
   * [Recomendaciones](es/features/recommendations.md)
+  * [Configurar conexión con el Censo](es/features/census_configuration.md)
 
 * [Proyecto Open Source](es/open_source/open_source.md)
   * [Código de conducta](es/open_source/code_of_conduct.md)

docs/en/features/census_configuration.md

@@ -0,0 +1,167 @@
+##Configure connection to the Census:
+
+The objective of this service is to be able to configure the connection with the Town Hall Census through the Administration panel without having to modify the application code.
+
+It should be noted that to properly configure this connection will require a technical profile that knows the WebService of your City Council.
+
+Currently the application was designed to send only the **document number** and **document type**. With this new feature is enabled the possibility of sending if necessary the fields **date of birth** and **postal code**.
+
+
+#### Activate feature
+In the section **Configuration > Global Configuration** a new tab **Remote Census Configuration** has been added.
+
+If we have the feature deactivated we will see an informative text that will indicate us how to activate it:
+![Feature disabled](../../img/remote_census/feature-disabled-en.png)
+
+To activate the feature you must perform 2 steps:
+1. Execute the following command `bin/rake settings:create_remote_census_setting RAILS_ENV=production`
+1. Access through the administration panel of your application to the section **Settings > Features** and activate the module **Configure connection to the remote census (SOAP)** as shown below:
+![Feature enabled](../../img/remote_census/feature-enabled-en.png)
+
+#### Configuration
+Once the feature is activated, we can access the section **Settings > Global Settings** and click on the tab **Remote Census Configuration**.
+In this screen you will be able to fill in all the necessary information to be able to configure the connection with the Census of each Town Hall.
+
+The information to be filled in is divided into three sections:
+
+1. **General Information**
+  - **Endpoint**: Host name where the census service is available (wsdl).
+
+    ![General information - Endpoint](../../img/remote_census/general-information-endpoint-en.png)
+
+1. **Request Data**
+
+  In this section we will fill in all the necessary fields to be able to make a request to verify a user through the Census of the City council.
+
+  ![Request Data](../../img/remote_census/request-data-en.png)
+
+  To help you understand how to fill in each of the fields, we will rely on a supposed WebService that receives a method called  `:get_habita_datos` with the following structure:
+  ```
+  {
+    request: {
+      codigo_institucion: 12,        # Static Value
+      codigo_portal:      5,         # Static Value
+      codigo_usuario:     10,        # Static Value
+      documento:          12345678Z, # Dynamic value related to Document Number
+      tipo_documento:     1,         # Dynamic value related to Document Type
+      nivel:              3          # Static Value
+    }
+  }
+  ```
+
+  Required fields for the request:
+
+  - **Request method name**: Request method name accepted by the City Census WebService.
+
+    Example:
+    ![Request Data - Method name](../../img/remote_census/request-data-method-name-en.png)
+
+  - **Request Structure**: Structure of the request received by the WebService of the Census of the City Council. The "static" values of this request should be reported. The "dynamic" values related to Document Type, Document Number, Date of Birth and Postal Code should be filled with blank value.
+
+    Example:
+    ![Request Data - Structure](../../img/remote_census/request-data-structure-en.png)
+    ![Request Data - Structure](../../img/remote_census/request-data-structure-info-en.png)
+
+  - **Path for document type**: Path in the request structure that sends the Document Type.
+
+    *NOTE: DO NOT FILL IN if the WebService does not require the Document Type to verify a user.*
+
+    Example:
+    ![Request Data - Path document type](../../img/remote_census/request-data-path-document-type-en.png)
+
+  - **Path for document number**: Path in the request structure that sends the Document Number.
+
+    *NOTE: DO NOT FILL IN if the WebService does not require the Document Number to verify a user.*
+
+    Example:
+    ![Request Data - Path document number](../../img/remote_census/request-data-path-document-number-en.png)
+
+  - **Path for date of birth**: Path in the request structure that sends the Date of Birth.
+
+    *NOTE: DO NOT FILL IN if the WebService does not require the Date of Birth to verify a user.*
+
+    In the case of *Example* we will fill it in blank, since it is not necessary to send the date of birth to verify a user.
+
+    Example:
+    ![Request Data - Path date of birth](../../img/remote_census/request-data-path-date-of-birth-en.png)
+
+  - **Path for Postal Code**: Path in the request structure that sends the Postal Code.
+
+    *NOTE: DO NOT FILL IN if the WebService does not require the Postal Code to verify a user.*
+
+    En el caso del *Example* lo dejaríamos en blanco, ya que no se necesita enviar el código postal para verificar a un usuario.
+
+    Example:
+    ![Request Data - Path postal code](../../img/remote_census/request-data-path-postal-code-en.png)
+
+1. **Response data**
+
+  In this section we will configure all the necessary fields to be able to receive the answer of the WebService and to verify a user in the application.
+
+  ![Response Data](../../img/remote_census/response-data-en.png)
+
+  As in the previous section we will define an example answer, to help you understand how to fill in each of the fields in this section.
+
+  ```
+      {
+        get_habita_datos_response: {
+          get_habita_datos_return: {
+            datos_habitante: {
+              item: {
+                fecha_nacimiento_string: "31-12-1980",
+                identificador_documento: "12345678Z",
+                descripcion_sexo: "Varón",
+                nombre: "José",
+                apellido1: "García"
+              }
+            },
+            datos_vivienda: {
+              item: {
+                codigo_postal: "28013",
+                codigo_distrito: "01"
+              }
+            }
+          }
+        }
+      }
+  ```
+
+  Required fields to parse the response:
+
+  - **Path for Date of Birth**: In what path of the response is the user's Date of Birth?.
+
+    Example:
+    ![Response Data - Path date of birth](../../img/remote_census/response-data-path-date-of-birth-en.png)
+
+  - **Path for Postal Code**: In what path of the response is the user's Postal Code?.
+
+    Example:
+    ![Response Data - Path postal code](../../img/remote_census/response-data-path-postal-code-en.png)
+
+  - **Path for District**: In what path of the response is the user's District?.
+
+    Example:
+    ![Response Data - Path district](../../img/remote_census/response-data-path-district-en.png)
+
+  - **Path for Gender**: In what path of response is the user's Gender?.
+
+    Example:
+    ![Response Data - Path Gender](../../img/remote_census/response-data-path-gender-en.png)
+
+  - **Path for Name**: In what path of the response is the user's Name?.
+
+    Example:
+    ![Response Data - Path Name](../../img/remote_census/response-data-path-name-en.png)
+
+  - **Path for the Last Name**: In what path of the response is the user's Last Name?.
+
+    Example:
+    ![Response Data - Path Last Name](../../img/remote_census/response-data-path-last-name-en.png)
+
+  - **Condition for detecting a valid response**: What response path has to come informed to be considered a valid response and user verified.
+
+    Example:
+    ![Response Data - Path valid response](../../img/remote_census/response-data-path-valid-response-en.png)
+
+
+  Once the general data, the necessary fields of the request and "all" fields to validate the response have been filled in correctly, the application will be able to verify any user through the defined WebService.

docs/en/features/features.md

@@ -3,3 +3,4 @@
 * [OAuth](oauth.md)
 * [GraphQL](graphql.md)
 * [Recommendations](recommendations.md)
+* [Configure Census Conexion](census_configuration.md)

docs/es/features/census_configuration.md

@@ -0,0 +1,168 @@
+##Configurar conexión con el Censo:
+
+Este servicio tiene como objetivo poder configurar la conexión con el Censo de Ayuntamiento a través del panel de Administración sin necesidad de modificar el código de la aplicación.
+
+Cabe destacar que para configurar correctamente esta conexión se requerirá de un perfil técnico que conozca el WebService de su Ayuntamiento.
+
+Actualmente la aplicación estaba pensada para enviar solo el **numero de documento** y el **tipo de documento**. Con esta nueva funcionalidad se habilita la posibilidad de enviar en caso de ser necesario los campos **fecha de nacimiento** y **código postal**
+
+
+#### Activar la funcionalidad
+En la sección **Configuración > Configuración Global** se ha añadido una nueva pestaña **Configuración del Censo Remoto**.
+
+Si tenemos la funcionalidad desactivada veremos un texto informativo que nos indicará como activarla:
+![Feature disabled](../../img/remote_census/feature-disabled-es.png)
+
+Para activar la funcionalidad deberá realizar 2 pasos:
+1. Ejecutar el siguiente comando `bin/rake settings:create_remote_census_setting RAILS_ENV=production`
+1. Acceder a través del panel de administración de su aplicación a la sección **Configuración > Funcionalidades** y activar el módulo de **Configurar conexión al censo remoto (SOAP)** como se puede ver a continuación:
+![Feature enabled](../../img/remote_census/feature-enabled-es.png)
+
+#### Configuración
+Una vez activada la funcionalidad, podremos acceder a la sección **Configuración > Configuración Global** y clicar en la pestaña **Configuración del Censo Remoto**.
+En esta pantalla se podrá rellenar toda la información necesaria para poder configurar la conexión con el Censo de cada Ayuntamiento.
+
+La información a rellenar esta dividida en tres apartados:
+
+1. **Información General**
+  - **Endpoint**: Nombre del host donde se encuentra el servicio del Censo con el que queremos conectarnos (wsdl).
+
+    ![General information - Endpoint](../../img/remote_census/general-information-endpoint-es.png)
+
+1. **Información para realizar la Petición**
+
+  En esta sección rellenaremos todos los campos necesarios para poder realizar una petición para verificar un usuario contra el Censo del Ayuntamiento.
+
+  ![Request Data](../../img/remote_census/request-data-es.png)
+
+  Para ayudar a entender como rellenar cada uno de los campos, nos basaremos en un supuesto WebService que recibe un método llamado `:get_habita_datos` con la siguiente estructura:
+  ```
+  {
+    request: {
+      codigo_institucion: 12,        #Valor estático
+      codigo_portal:      5,         #Valor estático
+      codigo_usuario:     10,        #Valor estático
+      documento:          12345678Z, #Valor dinámico relacionado con Número de Documento
+      tipo_documento:     1,         #Valor dinámico relacionado con Tipo de Documento
+      codigo_idioma:      102,       #Valor estático
+      nivel:              3          #Valor estático
+    }
+  }
+  ```
+
+  Campos necesarios para la petición:
+
+  - **Nombre del método de la petición**: Nombre del método que acepta el WebService del Censo del Ayuntamiento.
+
+    Ejemplo:
+    ![Request Data - Method name](../../img/remote_census/request-data-method-name-es.png)
+
+  - **Estructura de la petición**: Estructura de la petición que recibe el WebService del Censo del Ayuntamiento. Los valores "fijos" de esta petición deberán informarse. Los valores "dinámicos" relacionados con Tipo de Documento, Número de Documento, Fecha de Nacimiento y Código Postal deberán dejarse en blanco.
+
+    Ejemplo:
+    ![Request Data - Structure](../../img/remote_census/request-data-structure-es.png)
+    ![Request Data - Structure](../../img/remote_census/request-data-structure-info-es.png)
+
+  - **Ruta para Tipo de Documento**: Ruta donde se encuentra el campo en la estructura de la petición que envía el Tipo de Documento.
+
+    *NOTA: NO RELLENAR en caso de que el WebService no requiera el Tipo de Documento para verificar un usuario.*
+
+    Ejemplo:
+    ![Request Data - Path document type](../../img/remote_census/request-data-path-document-type-es.png)
+
+  - **Ruta para Número de Documento**: Ruta donde se encuentra campo en la estructura de la petición que envía el Número de Documento.
+
+    *NOTA: NO RELLENAR en caso de que el WebService no requiera el Número de Documento para verificar un usuario.*
+
+    Ejemplo:
+    ![Request Data - Path document number](../../img/remote_census/request-data-path-document-number-es.png)
+
+  - **Ruta para Fecha de Nacimiento**: Ruta donde se encuentra campo en la estructura de la petición que envía la Fecha de Nacimiento.
+
+    *NOTA: NO RELLENAR en caso de que el WebService no requiera la Fecha de Nacimiento para verificar un usuario.*
+
+    En el caso del *Ejemplo* lo dejaríamos en blanco, ya que no se necesita enviar la fecha de nacimiento para verificar a un usuario.
+
+    Ejemplo:
+    ![Request Data - Path date of birth](../../img/remote_census/request-data-path-date-of-birth-es.png)
+
+  - **Ruta para Código Postal**: Ruta donde se encuentra campo en la estructura de la petición que envía el Código Postal.
+
+    *NOTA: NO RELLENAR en caso de que el WebService no requiera el Código Postal para verificar un usuario.*
+
+    En el caso del *Ejemplo* lo dejaríamos en blanco, ya que no se necesita enviar el código postal para verificar a un usuario.
+
+    Ejemplo:
+    ![Request Data - Path postal code](../../img/remote_census/request-data-path-postal-code-es.png)
+
+1. **Información para parsear la respuesta**
+
+  En esta sección configuraremos todos los campos necesarios para poder recibir la respuesta del WebService y verificar a un usuario en la aplicación.
+
+  ![Response Data](../../img/remote_census/response-data-es.png)
+
+  Al igual que en el apartado anterior definiremos un ejemplo de respuesta, para ayudar a entender como rellenar cada uno de los campos de esta sección.
+
+  ```
+      {
+        get_habita_datos_response: {
+          get_habita_datos_return: {
+            datos_habitante: {
+              item: {
+                fecha_nacimiento_string: "31-12-1980",
+                identificador_documento: "12345678Z",
+                descripcion_sexo: "Varón",
+                nombre: "José",
+                apellido1: "García"
+              }
+            },
+            datos_vivienda: {
+              item: {
+                codigo_postal: "28013",
+                codigo_distrito: "01"
+              }
+            }
+          }
+        }
+      }
+  ```
+
+  Campos necesarios para parsear la respuesta:
+
+  - **Ruta para la Fecha de Nacimiento**: En que ruta de la respuesta se encuentra la Fecha de Nacimiento.
+
+    Ejemplo:
+    ![Response Data - Path date of birth](../../img/remote_census/response-data-path-date-of-birth-es.png)
+
+  - **Ruta para el Código Postal**: En que ruta de la respuesta se encuentra el Código Postal.
+
+    Ejemplo:
+    ![Response Data - Path postal code](../../img/remote_census/response-data-path-postal-code-es.png)
+
+  - **Ruta para el Distrito**: En que ruta de la respuesta se encuentra el Distrito.
+
+    Ejemplo:
+    ![Response Data - Path district](../../img/remote_census/response-data-path-district-es.png)
+
+  - **Ruta para el Género**: En que ruta de la respuesta se encuentra el Género.
+
+    Ejemplo:
+    ![Response Data - Path Gender](../../img/remote_census/response-data-path-gender-es.png)
+
+  - **Ruta para el Nombre**: En que ruta de la respuesta se encuentra Nombre.
+
+    Ejemplo:
+    ![Response Data - Path Name](../../img/remote_census/response-data-path-name-es.png)
+
+  - **Ruta para el Apellido**: En que ruta de la respuesta se encuentra el Apellido
+
+    Ejemplo:
+    ![Response Data - Path Last Name](../../img/remote_census/response-data-path-last-name-es.png)
+
+  - **Condición para detectar una respuesta válida**: Que ruta de la respuesta tiene que venir informado para considerarse una respuesta válida.
+
+    Ejemplo:
+    ![Response Data - Path valid response](../../img/remote_census/response-data-path-valid-response-es.png)
+
+
+  Una vez rellenados correctamente los datos generales, los campos necesarios de la petición y "todos" los campos para validar la respuesta, la aplicación podrá verificar cualquier usuario contra el WebService definido.

docs/es/features/features.md

@@ -1,5 +1,6 @@
-# Technical Features
+# Funcionalidades Técnicas
 
 * [OAuth](oauth.md)
 * [GraphQL](graphql.md)
 * [Recomendaciones](recommendations.md)
+* [Configurar conexión con el Censo](census_configuration.md)