-
Notifications
You must be signed in to change notification settings - Fork 10
Manual
In this manual, we describe how to use MobSOS Surveys both from the perspective of a regular end-user using the browser-based frontend and a developer using the RESTful API of the service.
In this short tutorial, we'll walk you through all options for interacting with MobSOS Surveys via its browser frontend. For now, we assume that MobSOS Surveys is available under the URL http://localhost:8080/mobsos-surveys and configured to use a given OpenID Connect provider for authentication.
Many resources in MobSOS Surveys are available even for anonymous users. However, some resources require authentication. These include creating, updating, and deleting surveys and questionnaires. MobSOS Surveys uses OpenID Connect for authentication, reflected by an OpenID Connect button in the top navigation bar. Besides plain authentication, you must also give consent that MobSOS Surveys may access your user information. It should be noted that - using OpenID Connect - MobSOS Surveys never gets access to your credentials! Instead, once you authenticated and gave your consent, MobSOS Surveys receives and manages an access token. As long as this token is not expired, you do not need to authenticate again. Token management is done automatically by MobSOS Surveys.
To authenticate, follow these steps:
- Click the Sign in with X button, where X is the OpenID Connect provider.
- (On the login page enter your credentials and press the Ok button.
- (On the following consent page, give your consent to MobSOS Surveys for accessing your user information and click the Ok button. After successful consent, you are redirected to MobSOS Surveys.
You are now authenticated and can use all features of MobSOS Surveys.
Let's start with a simple scenario. Consider you have created the mobile app "AchSo!" in the context of the Learning Layers project and registered the app as a client at the OpenID Connect provider. Now you want to evaluate your app. In particular, you decide to ask your end users about the usability of your app in an online survey. For this purpose, you plan to employ an established questionnaire instrument like the System Usability Scale (SUS). Since MobSOS Surveys already ships with a list of established questionnaire instruments, including SUS, we're ready to create a survey:
- Open your browser and go to http://localhost:8080/mobsos-surveys/surveys.
- Click the button + Create Survey. A form will open up.
- Enter your survey details:
- Select a language for your survey.
- Enter a name for your survey. This name must be unique among all other surveys in the system.
- Enter the name of the organization that conducts the survey.
- Enter the URL of the organization's logo.
- Enter a description for your survey.
- From the dropdown list of resources select AchSo!
- Set reasonable begin and end dates for your survey.
- From the dropdown list of available questionnaires select System Usability Scale (SUS)
- Click the Create button to create your new survey.
On successful survey creation you'll be directed to the dedicated page of your new survey (cf. screenshot below; TODO: add screenshot). You can now send the URL of this page to your end-users, such that they have the option to participate, ultimately submitting a response, and to check responses after having submitted a response. You as the organizer of the survey can bookmark this page to check responses or to edit the survey, e.g. prolong its lifetime. It should be noted that editing and deleting a survey is only allowed to its owner! Besides that, deleting or changing a survey can be dangerous. The deletion of survey metadata or a change to another questionnaire can lead to all response data collected so far becoming invalid or lost. However, changing metadata like name, description, or begin and end of a survey is not critical.
Let's assume you somehow get to the URL of an existing survey (e.g. http://localhost:8080/mobsos-surveys/surveys/1). This can happen as result of one of these events:
- someone (e.g. survey organizer, automated agent) sends you an invitation mail including the URL as a link.
- you reach the survey page by browsing the MobSOS Surveys frontend.
To participate in the survey, follow these steps:
- Open the survey page URL in your browser.
- Click the Participate button. A questionnaire form will open.
- In the questionnaire form, respond to items page-by-page. Notice that some items might be marked as required.
- On the final Submission page, press the 'Submit' button to submit your response.
After successful response, you are immediately directed to the survey response page, where you can check the current result status of the survey.
Given a survey URL, you can check responses by clicking the Responses button. You can also reach responses by simply appending /responses to the survey URL. Any survey response page features the following options:
- immediately check results from the included response count (N=...), boxplot visualization bundling responses to all numeric scale items and a list of freetext responses to open items.
- download the boxplot visualization as SVG file by clicking the Download Boxplot.
- download the surveys response dataset as CSV file by clicking the Download Dataset button. The downloaded file can be directly imported in statistics tools like Excel, SPSS, R for further analysis.
Consider the case that none of the questionnaires available in your MobSOS Surveys deployment matches your need for a survey you decide to conduct. In this case, you might consider authoring your own custom questionnaire form and creating a new questionnaire featuring this form. In the current version, questionnaire forms are authored as XML files, compliant with the MobSOS Surveys XML Schema. Authoring such documents is admittedly not very convenient, but still easy. Detailed instructions are available on the page Questionnaire Forms. A Web-frontend for editing questionnaires is planned as more simple solution.
Once you authored your questionnaire form XML file, follow these steps to register it as a new questionnaire in MobSOS Surveys:
- Open http://localhost:8080/mobsos-surveys/questionnaires in your browser.
- Click the + Create Questionnaire button. A form will open.
- Enter your survey details:
- Select a language for your questionnaire.
- Enter a name for your questionnaire. This name must be unique among all other questionnaires in the system.
- Enter the name of the organization contributing the questionnaire.
- Enter the URL of the organization's logo.
- Enter a description for your questionnaire.
- Choose the XML file containing your questionnaire form. MobSOS Surveys pre-validates the form file and displays a warning in case it's invalid.
- Click the Submit button to create your new survey.
After successful creation of your questionnaire, you are directed to the dedicated questionnaire page, showing the questionnaire data, including an overview of all items included in the questionnaire form. The questionnaire can now be used for any survey you plan to create (see tutorial above). It should be noted that editing and deleting a questionnaire is only allowed to its owner! Besides that, deleting a questionnaire is a dangerous operation, since with the deletion of a questionnaire or a change of the questionnaire form, all surveys depending on it would also change and might render response data collected so far as invalid. However, changing metadata like name, description, or organization of a questionnaire is not critical.
In this short tutorial we'll explain how to use the MobSOS Surveys RESTful API from other applications. Basically, every operation supported by the browser frontend is powered by the RESTful API. Thus, as a developer you can use MobSOS Surveys programatically within your own applications. Pretty neat, huh? In this section, we will only explain some typical use cases to illustrate the main principle of using the MobSOS Surveys RESTful API. Links to full API reference documentation and examples are provided at the end of this section.
Let's again consider a simple scenario. Assume you have developed an app called "AchSo!" and you want to have some very simple, yet effective feedback mechanism built into the app in the form of a 5-star rating and a free-text comment. Again, MobSOS Surveys ships with a simple feedback questionnaire form for this purpose. However, you do not want to direct your end-users to the survey page in an external browser, but instead collect the feedback directly within your app and then transmit it to MobSOS Surveys programatically using its RESTful API. To achieve this, follow these steps:
- Create a new survey (see tutorial above) and select the Simple Feedback Questionnaire from the list of available questionnaires.
- Collect 5-star rating and comment data in your app.
- Check the page of the used questionnaire for an overview of the identifiers of items that can/must be included in a response.
- Let your app send an HTTP request of the following form:
- Anonymous:
curl -v -X POST http://localhost:8080/mobsos-surveys/surveys/2/responses -H "Content-Type: application/json" -d " {\"SFQ.OS\":5,\"SFQ.C\":\"Love it!\"}" - Authenticated (including an OpenID Connect access token):
curl -v -X POST http://localhost:8080/mobsos-surveys/surveys/2/responses?access_token=<token> -H "Content-Type: application/json" -d "{\"SFQ.OS\":1,\"SFQ.C\":\"Crap!\"}"
You can now check the survey response page, if responses from your app were successfully submitted. Alternatively, you can also request survey responses with the API.
Consider the case you want to programatically process the results of a survey in an external application. Given the URL of the survey under consideration, the external application simply need to send an HTTP request of the following form to receive survey response data in CSV format:
curl -v -X GET http://localhost:8080/mobsos-surveys/surveys/2/responses?access_token=<token>&sepline=1&sep=; -H "Accept: text/csv"
The additional parameters sepline and sep allow to control the output of CSV data:
-
sepline=<N>: include a first line defining the separator (1) or not (0). Default is0. -
sep=<S>: configure separator. Default is,.
A sample output for the above sample request could be the following:
sep=;
uid;sid;cid;SFQ.OS;SFQ.C
uid1;2;achso;5;"Love it!"
anonymous1234;2;achso;1;"Crap!"
MobSOS Surveys is documented with Swagger. Swagger Resource Listing and API Declarations for all resources are available at http://localhost:8080/mobsos-surveys/api-docs/. Open this URL in any Swagger UI instance to check API docs and to interactively try the API. Alternatively, you can check Swagger API docs here (select MobSOS Surveys from dropdown): https://api.learning-layers.eu/doc/
A full list of example curl commandlines for all supported operations is available here. Please note that some of these commandlines are not stand-alone! The reason is that some operations require prior completion of other operations. For example, you must make sure that a specific survey exists and a questionnaire with a valid questionnaire form must be assigned to it, until you can submit a response to it.
In case you have any questions or suggestions, please send a pull request or contact me.