cefriel / coney

CONEY: The CONversational survEY Toolkit

Coney - Community Edition

⚠️ The Community Edition of Coney is NO LONGER BEING DEVELOPED but we do our best to provide bug fixing/support when possible. You can find more information on the commercial version at coney.cefriel.com or below in this README.

Coney is a complete toolkit developed by Cefriel for CONversational survEYs offering components to design and administer surveys, and to analyse data.

Abstract

Coney is an innovative toolkit designed to enhance the user experience in surveys completion. Coney exploits a conversational approach: on the one hand, Coney allows modelling a conversational survey with an intuitive graphical editor; on the other hand, it allows publishing and administering surveys through a chat interface. Coney allows defining an arbitrary acyclic graph of interaction flows, in which the following question depends on the previous answer provided by the user. This offers a high degree of flexibility to survey designers that can simulate a human to human interaction, with a storytelling approach that enables different personalized paths. Coney’s interaction mechanism exploits the advantages of qualitative methods while performing quantitative research, by linking questions to the investigated variables and encoding answers. A preliminary evaluation of the approach shows that users prefer conversational surveys to traditional ones.

Coney's underlying data model is based on the survey ontology that we designed to represent, annotate, export and share both the questionnaire structure and the gathered responses. Furthermore, questions and answers can be semantically annotated at design time to easily elaborate and inter-link the collected data at analysis time.

You can know more about Coney and try it at coney.cefriel.com/!

Clone the repository

To clone the repository you can run the following command:

git clone https://github.com/cefriel/coney.git

The development is no longer handled using submodules.

Toolkit Usage

The repository contains a docker-compose file to build and deploy the entire project. Each Coney component contains its own Dockerfile to build the related Docker image.

A utility script is added to the repository to handle common commands. Check line endings before running it on Windows.

$ sh coney.sh help

Usage: <command> [image] [options]

Commands:
         build           Builds the selected image with the available 'environment.ts' file
         up              Starts the selected container (all if no image is specified)
         stop            Stops the selected container (all if no image is specified)

Images:
         api             Coney's Application Programming Interface
         create          Conversation editor
         chat            User's chat endpoint
         inspect         Realtime data visualization tool

Options:
         --env-cp        Rewrites the environment.ts file in the Angular service(s)

Deployment

The provided docker-compose file is configured to launch a local instance of Coney. We assume Docker is up and running on your machine. Then execute the following commands to launch Coney (depending on your operating system you may need to run the commands using sudo to reach the Docker Daemon):

sh coney.sh build
sh coney.sh up

To deploy Coney in a different environment the following actions are required to configure the deployment.

Basic deployment:

• Edit the nginx.conf file to configure the reverse-proxy. In particular update the server_name.
• Set the BASE_HREF for Angular using the related env variable when launching the build with docker-compose.

   export BASE_HREF=/coney
   docker-compose build --no-cache
  

• Change the file environment.ts to set the baseUrl that should used by Coney components to reach the back-end (coney-api).
• Change the file environment.ts to set the privacyUrl shown to users compiling surveys through the coney-chat component.
• Launch the build using the --env-cp option

   sh coney.sh build --env-cp
  

Notes:

• Unpublished surveys and coney-api logs are saved in the coney-data folder in the host filesystem. The content of the coney-data folder is added to the .gitignore file by default.
• The docker-compose deployment can be initialized with a set of surveys. Put coney-create files in coney-data and update the query.sh file to initialize the database accordingly. A default coney-demo survey is provided. TODO create a script to automatically build queries given the content of coney-data folder.
• Pay attention to line endings when modifying the query.sh, they should be UNIX style.
• Data of Neo4j are persisted in a neo4j/ folder in the host filesystem. The neo4j/ folder is added to the .gitignore file.

Components

Once running, the landing page is available at localhost/coney. All components are masked by a reverse-proxy.

Components are reachable at the following addresses:

• coney-create localhost/coney/create
• coney-inspect localhost/coney/inspect
• coney-chat localhost/chat (a valid payload is needed to correctly visualize the chat component)

The backend API can be reached at localhost/coney-api/<method_name>. If enabled at build time, the API documentation is available at localhost/coney-api/swagger-ui.html.

More information on the components and how to use them are available in the repository Wiki.

Coney Enterprise Edition

The Coney Enterprise Edition is mainly based on the open-source components, but offers additional features:

• Multi-user and multi-project features to support hierarchies and access levels for surveys
• Centralized console to access Coney components and browse projects and surveys
• Link personalization for survey delivery (users, metadata, limit to number completions)
• Chat interface personalization (colors, logo, etc.)

If you are interested, if you simply want to know more, and/or if you need help in the survey design process contact us at [email protected].

Coney In-Use

Published studies using Coney:

• Survey Study about Motivation for Participants in Citizen Science Projects [Data set]. Zenodo. https://doi.org/10.5281/zenodo.5753091
• Ride2Rail Choice Criteria Survey Dataset [Data set]. Zenodo. http://doi.org/10.5281/zenodo.4593471

To add something to the list please either submit a pull request or open an issue.

Publications

To know more in details the project you can access related pubblications:

• CHItaly 2019: Extended abstract and poster "CONEY: A CONversational survEY Toolkit" on Zenodo
• IJHCS 2020: Journal paper "Submitting surveys via a conversational interface: An evaluation of user acceptance and approach effectiveness" on Arxiv

Cite as

If you used Coney in your work, please cite the IJHCS article:

Irene Celino and Gloria Re Calegari: Submitting surveys via a conversational interface: an evaluation of user acceptance and approach effectiveness, International Journal of Human Computer Studies, Vol. 139, DOI: 10.1016/j.ijhcs.2020.102410, 2020.

BibTeX reference:

@article{celino2020submitting,
title = "Submitting surveys via a conversational interface: An evaluation of user acceptance and approach effectiveness",
journal = "International Journal of Human-Computer Studies",
volume = "139",
pages = "102410",
year = "2020",
issn = "1071-5819",
doi = "https://doi.org/10.1016/j.ijhcs.2020.102410",
author = "Irene Celino and Gloria {Re Calegari}"
}

License

Copyright 2020 Cefriel.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Acknowledgement

This project is partially supported by the ACTION project (grant agreement number 824603), co-funded by the European Commission under the Horizon 2020 Framework Programme.

coney's Issues

Creating a survey from triple file

Dear Cefriel Team,
is there a way to import a generated RDF file from the export again into Coney Create?
Thank you and best regards

Unable to Install Coney

Hello,

Description:

I am experiencing a build failure while attempting to install the Coney software on my system. Below are the details of the issue:

Environment:

Operating System: [Windows 10, Linux]

Issue Details:

The built gets keep on failing which has been tried out on both operating systems.

Screenshots

The buit gets failed on this step specified in the first screenshot

Apparenty it lacks the updation of the of the browser list , which i have updated rom old version to new as shown in the next screenshot :

But still the error is not getting solved.

Thank you for your attention to this matter. I appreciate the assistance in resolving the issue. If there's any additional information needed or further testing required on my end, please don't hesitate to ask. I look forward to a resolution

Fix build Angular components

As reported in #2 the build of the Angular components is not working because of a broken dependency caniuse-lite.

Refer to #2 for a temporary solution to the problem.

Unable to log in

I've followed your instructions to start the coney docker containers, however when I go to the landing page, I see some issues with loading images. If I then click on "Create", I'm asked for a username/password. However nothing I type is accepted. See attached screenshots.