Actions

Central Participant Database: Difference between revisions

From LimeSurvey Manual

No edit summary
No edit summary
 
(136 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<languages /> <translate>


=Introduction=
<!--T:1-->
__TOC__


This new feature allows the administrator to store the participants to a central table that is independent of any token. The major advantages of allowing this is  :
=Introduction= <!--T:3-->
* The participants are backed up, so if a user wants to backup the participants without having to go through the trouble of exporting his participants to a CSV file and then importing them back into a new survey.
* The user need not have to import CSV to each specific survey , he/she just needs to add the survey to the central table and then can add to as many surveys as he wants.
* In case of multiple users , one user can choose to share his participants with others and also set if he wants it to be editable with the shared user or not.


Along with this, there is a advance attribute control and several other features.
<!--T:163-->
To access this feature: '''Configuration''' -> '''Central Participant Database''':


=The participants panel management tools=


<center>[[File:ParticipantPanel.png]]</center>
<!--T:190-->
<center>[[File:Central participants database.png]]</center>  
 
 
<!--T:4-->
This feature allows the administrator to store the participant information in a central table that is independent of any survey participants table. Its major advantages are:
* The central table acts as a backup. If a user creates a new survey, they will not have to export its participants to a CSV file and then import them back into a new survey.
* Users need only to add the participants to the central table. Then, the same participants can be added to as many surveys as the user wants.
* In case multiple users have access to a LimeSurvey installation, its owner(s) can choose to share their participants with other users and also set access rights for the shared users.
 
<!--T:5-->
You may also find in your LimeSurvey installation an advanced [[Central Participant Database#Attributes|attribute control]] and several other features.
 
=The participants panel management tools= <!--T:6-->
 
<!--T:164-->
The following options are available:


1) Home Screen


2) Information Screen( Summary of CPDB )
<!--T:7-->
<center>[[File:The participants panel management tools.png]]</center>


3) Display Participant&rsquo;s Grid


4) Import from CSV


5) Export All
<!--T:165-->
*[[Central Participant Database#Display CPDB participants|Display CPDB (Central Participant Database) participants]]
*[[Central Participant Database#Info|Info]]
*[[Central Participant Database#Import|Import]]
*[[Central Participant Database#Blacklist settings|Blacklist settings]]
*[[Central Participant Database#Attributes|Attributes]]
*[[Central Participant Database#Share panel|Share panel]]
*[[Central_Participant_Database#Export_participants|Export all participants]]


6) Blacklist Control
== Display CPDB participants == <!--T:28-->


7) Global Participant&rsquo;s Settings
<!--T:29-->
This is the main component of this panel. The majority of options can be accessed from here, such as adding, deleting, exporting, adding participants to surveys, etc.


8) Attribute Control
<!--T:32-->
Five options are available in the '''Action''' column for every participant listed in the table:


9) Share Panel


10) Panel Summary
<!--T:31-->
<center>[[File:displayParticipant.png]]</center>


==Home Screen==


Participant's Panel is a separate panel in the LimeSurvey administrator toolbar, so this icon takes back the user to the administrator panel
<!--T:166-->
*[[Central Participant Database#Edit participant|Edit this participant]]
*[[Central Participant Database#Delete participant|Delete this participant]]
*[[Central Participant Database#Share participant|Share this participant]]
*[[Central Participant Database#List active surveys|List active surveys]]
*[[Central Participant Database#Add participant to survey|Add participant to survey]]


==Information Screen==


This screen shows the summary of the Central Database by giving the statistics of Central Database. This gives the summary of
<!--T:167-->
{{Box|Before accessing the options mentioned above, you must have users listed in your database. To create them, click the '''[[Central Participant Database#Add participant|Add new participant]]''' button, located in the upper-right part of the window.}}


1) Total Participants in central table
===Add participant=== <!--T:45-->


2) Participants Owned by you
<!--T:46-->
Click the '''Add new participant''' button located in the upper-right part of the window: [[File:Add new participat CPDB.png]].


3) Participants Shared with you
<!--T:168-->
A dialog box with the following basic attributes will then appear:


4) Participants you have shared


5) Blacklisted Participants
<!--T:169-->
<center>[[File:addParticipant.png]]</center>


6) Total attributes in the central table


==Display Participant&rsquo;s Grid==
<!--T:170-->
*'''First name'''
*'''Last name'''
*'''E-mail'''
*'''Blacklist user'''
*'''Owner''': Any user of LimeSurvey defined in the [[Manage_users#User_management|user control management page]] can be an owner.


This is the main asset of the Participant's Panel. This is where you can perform majority of central Panel's operations, such as adding, deleting , exporting, adding to survey etc.
<!--T:171-->
{{Box|'''Custom attributes''' can be added. For further details, see the [[Central Participant Database#Attributes|attributes]] and [[Central Participant Database#Examples|examples]] sections.}}


Let me show you a screenshot of the same and explain each of the feature.
===Edit participant=== <!--T:172-->


<center>[[File:displayParticipant.png]]</center>
<!--T:173-->
To edit the basic and/or custom attributes of a participant, click the first button (from left to right) located in the '''Action''' column ([[File:Edit participant CPDB.png]]). A window with all the available attributes will be displayed.
 
===Delete participant=== <!--T:47-->


Explaination of the screenshot is given below
<!--T:49-->
You can easily delete one or multiple participants:
* If you want to delete one participant, go to the row where the respective participant is located and click the red bin button: [[File:Delete participant CPDB.png]].
* If you want to delete two or more participants, click the '''Selected participant(s)...''' button (under the last row, below the '''Action''' column) after you selected the corresponding entries: [[File:Select participants CPDB.png]]. Then, click the delete option.


1)  jqGrid header
<!--T:174-->
When you delete the participant(s), three options are available to you:


2)  Add Participant


3)  Delete Participant
<!--T:50-->
<center>[[File:deleteParticipant.png]]</center>


4)  Reload Grid


5)  Export to CSV ( Advanced )
<!--T:52-->
1) '''Delete only from the central panel''': The first option deletes the participant from the central participant database only. If the participant is in any survey participants table, they will not be removed.


6)  Advance Search
<!--T:53-->
2) '''Delete from the central panel and associated surveys''': The second option deletes the participant from central panel and from the surveys where they have been added to, but their responses are not deleted.


7)  Navigation Bar
<!--T:54-->
3) '''Delete from central panel, associated surveys and all associated responses''': The third option deletes all traces of that participant from the system, including their responses.


8)  Share Participant


9)  Add to Survey
<!--T:58-->
{{Alert|title=Attention|text=Please note that in all the three scenarios, the links created for the purpose of maintaining a participant's history are also deleted.}}


10) Total Count
===Share participant=== <!--T:59-->


11) Hide/show grid
<!--T:83-->
This is another important feature of the '''Central Participant Database'''. You can share your participants with other users. You just have to select the participant(s) you want to share and click either the green right-arrow icon ([[File:Share participate CPDB.png]]) or the '''Selected participant(s)...''' button located in the bottom left part of the participants table. A modal box will open which will allow you to select the user with whom you want to share the respective participant(s). You can also set whether the user who shares your participant can edit those participants. If you set it to ''No'', they will get an access denied error when trying to edit the entries of the shared participant.


11) Subgrid


Now I will explain each of the features
<!--T:84-->
<center>[[File:shareParticipant.png]]</center>


===Add Participant===
===List active surveys=== <!--T:60-->


You can easily add individual participant using the plus sign in the grid pager. For editing the added participant you can simply double click on the row on which you want to edit and after editing you can press enter and any changes you have done will be saved on the server.
<!--T:175-->
If you click the next icon ([[File:List active surveys CPDB.png]]), all the active surveys where the respective participant has been added to will be listed.


<center>[[File:addParticipant.png]]</center>
===Add participant to survey=== <!--T:61-->


===Delete Participant===
<!--T:86-->
Adding a participant to a survey can be done by clicking the last icon ([[File:Add participant to survey CPDB.png]]) from the '''Action''' column. If you wish to add more than one participant to a survey, mark them and select the '''Share''' option from the '''Selected participant(s)...''' dialog box (located in the bottom-left part of the central table).


You can easily mark a single participant to delete or you can choose all the participants in the grid to be deleted. There are three possible conditions when deleting a participant.


<center>[[File:deleteParticipant.png]]</center>
<!--T:91-->
<center>[[File:addtoSurvey.png]]</center>


The explanation of the three conditions is


1) Delete Participant(s) from central participants panel only
<!--T:191-->
<div class='simplebox'> [[File:help.png]] Please note that if you wish to add participants from the central database to a survey, the respective survey needs to contain a '''survey participants table'''! For further details, please continue reading the following [[Survey participants|wiki section]].</div>


2) Delete Participant(s) from central panel and token tables
<!--T:94-->
The title of the dialog box will show you the number of participants that are going to be added to the respective survey. Besides that, there is also a checkbox, that if checked, it will take you to the survey participants table of the survey to which you are adding the participants to.


3) Delete Participant(s) from central panel,token tables and all associated responses
<!--T:95-->
After clicking 'Next', you will be taken to the attribute map page.


The first option deletes the participant from the central panel only, if the participant is in the token table, he/she will not be removed.
<!--T:96-->
The attribute map page contains four tables and uses an advanced drag-and-drop functionality:


The second option deletes the participant from central as well as token table, but the responses are kept.


The third option deletes all traces of that participant from the system included responses.
<!--T:97-->
<center>[[File:attributemap.png]]</center>


In all the three options the links created for the purpose of maintaining history related to a particular participant are also deleted.


===Reload Grid===
<!--T:192-->
* The first table, ''Unmapped participant attributes'', shows all the attributes that are present in the central participant database. They are currently unmapped - not present in the survey participants table. These unmapped attributes can either be moved into the ''Token attributes to create'' table which creates new attributes in the survey participants table or they can be merged with the existing token attributes by dragging the unmapped attributes into the ''Existing token attributes'' table, besides the existing token attribute you wish to be merged with.


It simply reloads the grid from the server.
<!--T:193-->
* The second table, ''Token attributes to create'', helps you copy unmapped participant attributes into the survey participants table, creating new columns. Drag the attribute(s) you wish to add to the survey participants table and drop them into the second table. In this way, new columns/attributes will be added to the survey participants table.


===Export to CSV===
<!--T:194-->
* The third table, ''Existing token attributes'', displays the current attributes existing in the survey participants table. Drop the unmapped attributes here if you wish to copy the data from the unmapped attributes into the one of the existing token attributes (see screenshot below)


When exporting to CSV the user is presented with a dialog box asking him to mark the additional attributes which he wants to import. There is also a nice filter for filtering the attributes. It will display all the attributes (visible/non-visible).
<!--T:195-->
* The fourth table, the ''Standard token fields'', displays the standard token fields that can be merged with unmapped participant attributes. The only standard token field from a survey participants table that can be edited is the '''Token''' one. This is important when you wish, for example, to easily copy token codes across different LimeSurvey installations.


The export to CSV will work under two conditions :


1) Export filtered
<!--T:196-->
<center>[[File:Attributemaps test.png]]</center>


2) Export All


When you are done filtering it will export all the filtered results otherwise it will export all the participants visible to that user.
<!--T:197-->
<div class='simplebox'> [[File:help.png]] You can also overwrite the existing token attribute values from the survey participants table if a participant already exists. Use this option cautiously in order not to lose any important data on survey respondents.</div>


<center>[[File:exporttoCSV.png]]</center>


It will export with the file name as central_'the current time stamp'.
<!--T:98-->
After you have mapped all the attributes, you can click '''Continue'''. After processing the participants, a summary page will be displayed, telling you how many participants were successfully copied. If you have previously asked for redirection, you will be redirected to the survey participants table, otherwise you will be redirected to the CPDB main page.


===Advance Search===


This is another major feature of Central Panel. It has a powerful search which not only filters through the participant but through additional attributes as well (visible and non-visible). This feature is also integrated with the grid.
<!--T:99-->
<center>[[File:addtosurveysummary.png]]</center>


There are two level of searches that an administrator can do.
==Info== <!--T:20-->


1) Single Search
<!--T:21-->
Displays '''CPDB''' stats:


2) Combined Search


<center>[[File:advanceSearch.png]]</center>
<!--T:198-->
<center>[[File:ParticipantPanel.png]]</center>


You can add a complex condition using a plus sign next to the previous condition and remove the condition using a minus sign .


<center>[[File:advancesearchmultiple.png]]</center>
<!--T:22-->
1) ''Total participants in central table'' : The total number of participants located in the central participant database.


This search not only filters attributes in the grid but also from the database, so it is an extensive search.
<!--T:23-->
2) ''Participants owned by you'' : Shows the total number of participants that have you as a owner. By default, <u>the new participants</u> entered into the central participant database <u>have as owner the user that firstly added them to it</u>.  


===Navigation Bar===
<!--T:24-->
3) ''Participants shared with you'' : The number of participants that were shared with you by other users.


To decrease load time of the grid we have used pagination in the grid which allows the user to see the first X entries ( chosen by the user) and then load more if required by him. To control this we have a pagination control in the navigator bar
<!--T:25-->
4) ''Participants you have shared'' : The number of participants you shared with other users.


<center>[[File:navBar.png]]</center>
<!--T:26-->
5) ''Blacklisted participants'' : The number of blacklisted participants.


Using the drop down you can select the entries to be loaded and with navigation buttons you can navigate and also use the text box to go to a certain page. Please note that the number of pages will reduce as you increase the number of eateries visible per page. Also the search and sorting of grid are not dependent on the records visible in the grid at any particular time but are independent of them.
<!--T:27-->
6) ''Total attributes in the central table'' : The total number of attributes that can be found in the central table.


===Share Participant===
==Import== <!--T:81-->


This is another most important feature of CPDB. You can share the participants among other users in the LimeSurvey installation. You just have to select the participants you want to share and click on share. A modal box will open up which will allow you to select the user with who you want to share. You can also set as to whether the participant that you are sharing can be edited by the user with whom you are sharing. If you set it to no, user with whom you have shared will get a access denied error.
<!--T:176-->
If you wish to add participants via the import function, click the Import button that is located on the main toolbar of the '''Central participant database''' page: [[File:importCSV.png]]


<center>[[File:shareParticipant.png]]</center>
<!--T:177-->
The following options are available:


===Add to survey===


Add to survey can be done at three levels :
<!--T:178-->
[[File:Import CSV CPDB.png]]


1) all participants in current search


2) all participants
<!--T:82-->
Please note the text from the box on '''CSV input format''':
{{Box|The file should be a standard CSV (comma delimited) file with optional double quotes around values (default for OpenOffice and Excel). The first line must contain the field names. The fields can be in any order.
'''Mandatory field''': email
'''Optional fields''': firstname, lastname, blacklisted, language}}


3) only the participant's that I have selected
===Steps to import=== <!--T:110-->


As we know that the grid loads only the requested participants and rest of the participants are loaded when requested, thus ensuring minimum loading time for the user. So when you select a page on the grid (using multi-select or single select )that doesn't meant you have selected all the participants on the second and the third page as well.So when exporting you are presented with the above mentioned three options which will be visible/invisible to you as per the present scenario.
<!--T:111-->
1) Select a file to import and specify the settings associated with it.


<center>[[File:addtoSurvey.png]]</center>
<!--T:113-->
2) Map the attributes from the CSV file. Import the attribute data either into an existing attribute from the central participant database or into a new column by creating a new attribute. The newly created attribute will be of text box type - the format can be changed later.


For example if you have not selected any row and haven't done any search it will not show you any option and will offer you to add all the participants in the grid and so on...


<center>[[File:direct-all.png]]</center>
<!--T:114-->
<center>[[File:attributeMapCSV.png]]</center>


The title of the dialog box will show you the number of participants that you are going to export. Besides that there is also a check box that if checked will take you to the token table of the survey to which you are adding the participants.


After clicking next you will be taken to the attribute map page.
<!--T:115-->
In the screenshot from above, a new attribute called "New Age" will be created. The data from attribute "Sex" was mapped and copied into the existent "Sex" attribute from the central participant database.


The attribute map page has three columns and uses advance drag and drop functionality. The first column shows all the attributes that are present in the central table. The second column gives space to the user to create new attributes. The third column shows the attributes in the token table to which the user is adding participants to. The user is free to choose to either create a new attribute in the token table to copy new values to or map the values from the attribute in the central table to the token table.
<!--T:116-->
3) Click continue, and wait for the process to be done. At the end, a short summary will be displayed.


<center>[[File:attributemap.png]]</center>


After you have mapped all the attributes, you can click on continue and after processing the participants a summary page will show up that will tell you how many participants were successfully copied, after which if you have asked for redirection you will be redirected to the token table table or else you will be redirected to the central grid.
<!--T:117-->
<center>[[File:CSVsummary.png]]</center>


<center>[[File:addtosurveysummary.png]]</center>


===Total Count===
<!--T:118-->
Clicking ''OK'' will redirect you to the participants screen, showing you the newly imported participants.


The navigator in the right also displays the number of participants out of the total participants.
==Blacklist settings== <!--T:78-->


===Hide/Show grid===
<!--T:181-->
The '''Blacklist settings''' button is available on the main toolbar of the '''Central participant database''' page. Once you click it, the following page will be displayed.


Simply hide or show the grid.


===Subgrid===
<!--T:199-->
<center>[[File:CPDB Blacklist settings panel.png]]</center>


For editing of attributes in the system we have implemented subgrid in the main grid that shows all the attributes in the system and also edit them. The main grid shows only the visible attributes, the rest of the attributes are available here and only fetched when required. The subgrid as the main grid allows inline editing of attributes and also sorting. The subgrid also shows the links to the surveys to which the participant is added to. In case the participant is not added to any survey this subgrid hides itself. When you expand the subgrid all the attributes in the system show up, but that doesn't mean that you have saved all the attribute values for that participant in the database. Only when you add some value that attribute is saved for that particular attribute.


<center>[[File:subgrid.png]]</center>
<!--T:182-->
The following ''Yes/No'' options are available:
*'''Blacklist all current surveys for participant once the global field is set''': If set to ''Yes'', the blacklisted participant(s) cannot be added to any survey.
*'''Blacklist participant for any new added survey once the global field is set''': If new surveys are created, the respective participant(s) cannot be added to them (if ''Yes'' is picked up). However, they can still be added to those surveys created earlier.
*'''Allow blacklisted participants to be added to a survey''': Even if a participant is blacklisted, they can still be added to a survey.
*'''Hide blacklisted participants''': Useful function when you would like to hide participant for a specific amount of time and then make them available for the rest of users with whom those blacklisted participants have been shared with.
*'''Delete globally blacklisted participants from the database''': If ''Yes'', the blacklisted participants will be deleted from the database.
*'''Allow participant to un-blacklist himself/herself''': If ''Yes'', participants can un-blacklist themselves without the help of a LimeSurvey user.


<center>[[File:editattribute.png]]</center>
==Attributes== <!--T:126-->


==Import from CSV==
<!--T:183-->
To access the '''Attributes management''' panel, click the '''Attributes''' button located on the main toolbar of CPDB main page: [[File:Attributes management icon.png]]


This feature is similar to as we have in tokens.This supports files with only *.csv extension. The rest of the settings are similar with what we have for import CSV under tokens. As in add to survey we also have a drag and drop control over the attribute here. This feature all the headings in the CSV and show them . The user can map the attribute to already existing central attribute or choose to create new one.


Steps of Import
<!--T:132-->
<center>[[File:Add new attribute CPDB.png]]</center>


1) Select a file to import and associated settings.


<center>[[File:importCSV.png]]</center>
<!--T:127-->
The attribute management facilitates the addition of three types of attributes: ''text box, date, and drop-down list''. To add a new attribute, click t'''Add new attribute''' located in the upper-right part of the window:


2) Map the attributes in the CSV to the one in the central table or create new. New attributes will be created text box type which can changed later


<center>[[File:attributeMapCSV.png]]</center>
<!--T:135-->
<center>[[File:addingattribute.png]]</center>


In the example screenshot I have created a new attribute age and mapped sex with the attribute in the central table.


3) Wait for it process and show the summary.
<!--T:184-->
When adding a new attribute, the following options are available:
*'''Defaultname''': It will be used by LimeSurvey to name the attribute in case no other English name is provided.
*'''Attribute type''': You can choose either of the attribute types and the associated user interface will be presented to you while editing.
*'''Should this attribute be visible on the panel?''': It can be ''Yes'' or ''No''. This function determines whether the attribute is visible in the CPDB table or not. This can be later edited from the '''Visible''' column that is located in the main attributes table.
*'''Languages''': If you would like LimeSurvey not to use the defaultname as the name of the attribute, type here the desired name. Please note that the attribute management has multilingual support. Click on the plus sign after you have selected the language. A new field will appear below the English/default language.  


<center>[[File:CSVsummary.png]]</center>
<!--T:185-->
Once the changes are done, click '''Save'''.


Clicking ok will redirect you to the display participants screen showing the newly imported participants.
<!--T:200-->
<div class='simplebox'>[[File:help.png]] We recommend tha you write the name of the attribute in the corresponding language box even if you use only one language (the base language). The reason for this is that when you map attributes and you wish to add them to different survey participants table, the '''defaultname''' of the attribute is not displayed in the respective panel - only the name you give in the corresponding language box is shown.</div>


== Export All==
<!--T:186-->
In the attributes table, two actions are available (see the ''Action'' column):


This feature is for simplicity of the user. The user can click on it and can download all the participants that he has rights for.
<!--T:187-->
<center>[[File:Action table attribute management.png]]</center>


== Global Participant&rsquo;s Settings==
<!--T:188-->
If you click the first icon, a dialog box will be displayed. It includes the basic settings of the selected attribute that can be edited according to your needs.


For security purposes the editing of user id is restricted as it's the user id associated with the participant which decides the ownership of the participant. For which there is a setting the main CPDB panel which can be changed only by the super administrator. If the setting is set to yes, the user can edit the user field in the display grid.
<!--T:137-->
To delete an attribute from the table, click on the red trash button, located next to the edit button. Clicking the delete button will not only delete the attribute, but also the associated values from the CPDB.


<center>[[File:userideditable.png]]</center>
== Share panel== <!--T:146-->


When you double click on the row, you can see a drop down in the user id field where the list of all users in the system are listed and you choose which one to give participant rights to.
<!--T:147-->
The share panel shows all the information related to the shared participants. Please note that this panel shows only the shared participants owned by that particular user.


<center>[[File:displayparticipantedit.png]]</center>


== Attribute Control==
<!--T:148-->
<center>[[File:sharepanel.png]]</center>


This is yet another advance feature of the CPDB. The attribute control in the current system allows only to add the attribute of only text type, which this reduces complexity but when you have to add a large number of attribute values, it becomes very difficult to type in the exact same value, for example 'male' a large number of times. To overcome this problem we have introduced three different attribute types :


1) Drop Down
<!--T:149-->
This panel shows values like:


2) Text Box
<!--T:151-->
1) ''Last name''


3) Date Picker
<!--T:150-->
2) ''First name''


You can choose either of the attribute types and associated UI will be presented to you while editing attributes. For drop down you will need to add values. Also the attribute control has multilingual support.
<!--T:152-->
3) ''Email address''


<center>[[File:attributeControl.png]]</center>
<!--T:153-->
4) ''Shared by''


As you can see there are already two existing attributes in the system. You can set their visible right here by just checking the visible check box. the visibility will determine as to whether the attributes should be visible in the main grid or not.
<!--T:154-->
5) ''Owner''


For adding a new attribute you just have to click on the plus sign and another row will pop up allowing you to put in basic details and saving the attribute.
<!--T:155-->
6) ''Date added''


<center>[[File:addingattribute.png]]</center>
<!--T:156-->
7) ''Can edit?''


You can save the attribute by using the save button or by pressing enter after entering the attribute name.
<!--T:157-->
This information is for viewing/sorting purposes. Only the '''Can Edit''' field is editable for the user. The '''Can edit''' field allows you to determine whether to allow the respective participant to be editable by the user with whom that participant was shared with or not. Clicking on the check box will make an AJAX call and save the changes on the server.


For deleting an attribute in the system just click on the delete button next to the edit button. Clicking the delete button will not only delete the attribute but also the associated values.
==Export participants== <!--T:179-->


For advance editing such as adding of drop down values and adding multilingual languages you need to click on the edit button. On clicking the edit button you will see something like this.
<!--T:62-->
The export function is located on the main toolbar of the '''Central participant database''' page: [[File:Export CPDB.png]]


<center>[[File:attributeadvanceedit.png]]</center>
<!--T:180-->
When exporting to CSV, you are presented with a dialog box that asks you to mark the attributes you wish to export.


For adding a new language you can click on the plus sign and a new tab will pop up and you can add attribute name in that language there.
<!--T:63-->
You can export:


You can also add drop down values by selecting the drop down attribute type
<!--T:201-->
*'' '''None''' of the additional attributes''


<center>[[File:commonsettings2.png]]</center>
<!--T:202-->
*'' '''All''' the additional attributes''


You can edit the possible values of the drop down by clicking on the edit button or clicking on the value itself as it supports inline edit similar to what we have in the grid. Delete button is for deleting the possible value.
<!--T:203-->
*'' '''Certain''' additional attributes''


[[File:editcommonsetting.png]]


As you can see in the screenshots, the entire attribute properties can be edited here.
<!--T:67-->
<center>[[File:exporttoCSV.png]]</center>


== Share Panel==


The share panel shows all the information related to the shared participant . Please note that this panel shows only the shared participant by that particular user.
<!--T:68-->
The format of the exported file will be CSV.


This panel shows values like
===Export filtered participants=== <!--T:204-->


1) First Name
<!--T:205-->
To export filtered participants, use first the [[Central Participant Database#Search filters|search filters]]. Then. click the checkbox located on the left side of the '''Action''' column (to select all the filtered participants). Then, click the '''Selected participant(s)...''' button located at the bottom-right side of the table and select the export function. In this way, only the '''filtered participants''' will be exported.


2) Last Name
==Search filters== <!--T:69-->


3) E-Mail
<!--T:206-->
If you wish to filter the users from your database, use the search/dropdown boxes located below each column title:


4) Shared With


5) Owner
<!--T:207-->
<center>[[File:CPDB Filtered search.png]]</center>


6) Date Added


7) Can Edit
<!--T:208-->
Enter information in the search fields or select from the dropdown lists (when possible) the participants you want to be listed after the filtering process.


All this information is for viewing/sorting purposes only and only the can_edit field is editable for the user. The can edit field as explained earlier determines as to whether to allow the shared participant to be editable with the sharer or not. You don't need to double click or something, just clicking on the check box will make an AJAX call and save the changes on the server.
=Additional information= <!--T:160-->


== Panel Summary==
<!--T:161-->
Additional (technical) information is available in the [[Central participants database (User panel) Development]] wiki.


Panel summary is same as information, just that it is loaded when the CPDB panel is opened and it can be accessed again by using the information icon in the panel and it gives general information about the CPDB.
</translate>

Latest revision as of 12:58, 24 November 2022

Other languages:

Introduction

To access this feature: Configuration -> Central Participant Database:



This feature allows the administrator to store the participant information in a central table that is independent of any survey participants table. Its major advantages are:

  • The central table acts as a backup. If a user creates a new survey, they will not have to export its participants to a CSV file and then import them back into a new survey.
  • Users need only to add the participants to the central table. Then, the same participants can be added to as many surveys as the user wants.
  • In case multiple users have access to a LimeSurvey installation, its owner(s) can choose to share their participants with other users and also set access rights for the shared users.

You may also find in your LimeSurvey installation an advanced attribute control and several other features.

The participants panel management tools

The following options are available:



Display CPDB participants

This is the main component of this panel. The majority of options can be accessed from here, such as adding, deleting, exporting, adding participants to surveys, etc.

Five options are available in the Action column for every participant listed in the table:




Before accessing the options mentioned above, you must have users listed in your database. To create them, click the Add new participant button, located in the upper-right part of the window.


Add participant

Click the Add new participant button located in the upper-right part of the window: .

A dialog box with the following basic attributes will then appear:



Custom attributes can be added. For further details, see the attributes and examples sections.


Edit participant

To edit the basic and/or custom attributes of a participant, click the first button (from left to right) located in the Action column (). A window with all the available attributes will be displayed.

Delete participant

You can easily delete one or multiple participants:

  • If you want to delete one participant, go to the row where the respective participant is located and click the red bin button: .
  • If you want to delete two or more participants, click the Selected participant(s)... button (under the last row, below the Action column) after you selected the corresponding entries: . Then, click the delete option.

When you delete the participant(s), three options are available to you:



1) Delete only from the central panel: The first option deletes the participant from the central participant database only. If the participant is in any survey participants table, they will not be removed.

2) Delete from the central panel and associated surveys: The second option deletes the participant from central panel and from the surveys where they have been added to, but their responses are not deleted.

3) Delete from central panel, associated surveys and all associated responses: The third option deletes all traces of that participant from the system, including their responses.


  Attention : Please note that in all the three scenarios, the links created for the purpose of maintaining a participant's history are also deleted.


Share participant

This is another important feature of the Central Participant Database. You can share your participants with other users. You just have to select the participant(s) you want to share and click either the green right-arrow icon () or the Selected participant(s)... button located in the bottom left part of the participants table. A modal box will open which will allow you to select the user with whom you want to share the respective participant(s). You can also set whether the user who shares your participant can edit those participants. If you set it to No, they will get an access denied error when trying to edit the entries of the shared participant.


List active surveys

If you click the next icon (), all the active surveys where the respective participant has been added to will be listed.

Add participant to survey

Adding a participant to a survey can be done by clicking the last icon () from the Action column. If you wish to add more than one participant to a survey, mark them and select the Share option from the Selected participant(s)... dialog box (located in the bottom-left part of the central table).



Please note that if you wish to add participants from the central database to a survey, the respective survey needs to contain a survey participants table! For further details, please continue reading the following wiki section.

The title of the dialog box will show you the number of participants that are going to be added to the respective survey. Besides that, there is also a checkbox, that if checked, it will take you to the survey participants table of the survey to which you are adding the participants to.

After clicking 'Next', you will be taken to the attribute map page.

The attribute map page contains four tables and uses an advanced drag-and-drop functionality:



  • The first table, Unmapped participant attributes, shows all the attributes that are present in the central participant database. They are currently unmapped - not present in the survey participants table. These unmapped attributes can either be moved into the Token attributes to create table which creates new attributes in the survey participants table or they can be merged with the existing token attributes by dragging the unmapped attributes into the Existing token attributes table, besides the existing token attribute you wish to be merged with.
  • The second table, Token attributes to create, helps you copy unmapped participant attributes into the survey participants table, creating new columns. Drag the attribute(s) you wish to add to the survey participants table and drop them into the second table. In this way, new columns/attributes will be added to the survey participants table.
  • The third table, Existing token attributes, displays the current attributes existing in the survey participants table. Drop the unmapped attributes here if you wish to copy the data from the unmapped attributes into the one of the existing token attributes (see screenshot below)
  • The fourth table, the Standard token fields, displays the standard token fields that can be merged with unmapped participant attributes. The only standard token field from a survey participants table that can be edited is the Token one. This is important when you wish, for example, to easily copy token codes across different LimeSurvey installations.



You can also overwrite the existing token attribute values from the survey participants table if a participant already exists. Use this option cautiously in order not to lose any important data on survey respondents.


After you have mapped all the attributes, you can click Continue. After processing the participants, a summary page will be displayed, telling you how many participants were successfully copied. If you have previously asked for redirection, you will be redirected to the survey participants table, otherwise you will be redirected to the CPDB main page.


Info

Displays CPDB stats:



1) Total participants in central table : The total number of participants located in the central participant database.

2) Participants owned by you : Shows the total number of participants that have you as a owner. By default, the new participants entered into the central participant database have as owner the user that firstly added them to it.

3) Participants shared with you : The number of participants that were shared with you by other users.

4) Participants you have shared : The number of participants you shared with other users.

5) Blacklisted participants : The number of blacklisted participants.

6) Total attributes in the central table : The total number of attributes that can be found in the central table.

Import

If you wish to add participants via the import function, click the Import button that is located on the main toolbar of the Central participant database page:

The following options are available:



Please note the text from the box on CSV input format:

The file should be a standard CSV (comma delimited) file with optional double quotes around values (default for OpenOffice and Excel). The first line must contain the field names. The fields can be in any order.

Mandatory field: email

Optional fields: firstname, lastname, blacklisted, language


Steps to import

1) Select a file to import and specify the settings associated with it.

2) Map the attributes from the CSV file. Import the attribute data either into an existing attribute from the central participant database or into a new column by creating a new attribute. The newly created attribute will be of text box type - the format can be changed later.



In the screenshot from above, a new attribute called "New Age" will be created. The data from attribute "Sex" was mapped and copied into the existent "Sex" attribute from the central participant database.

3) Click continue, and wait for the process to be done. At the end, a short summary will be displayed.



Clicking OK will redirect you to the participants screen, showing you the newly imported participants.

Blacklist settings

The Blacklist settings button is available on the main toolbar of the Central participant database page. Once you click it, the following page will be displayed.



The following Yes/No options are available:

  • Blacklist all current surveys for participant once the global field is set: If set to Yes, the blacklisted participant(s) cannot be added to any survey.
  • Blacklist participant for any new added survey once the global field is set: If new surveys are created, the respective participant(s) cannot be added to them (if Yes is picked up). However, they can still be added to those surveys created earlier.
  • Allow blacklisted participants to be added to a survey: Even if a participant is blacklisted, they can still be added to a survey.
  • Hide blacklisted participants: Useful function when you would like to hide participant for a specific amount of time and then make them available for the rest of users with whom those blacklisted participants have been shared with.
  • Delete globally blacklisted participants from the database: If Yes, the blacklisted participants will be deleted from the database.
  • Allow participant to un-blacklist himself/herself: If Yes, participants can un-blacklist themselves without the help of a LimeSurvey user.

Attributes

To access the Attributes management panel, click the Attributes button located on the main toolbar of CPDB main page:



The attribute management facilitates the addition of three types of attributes: text box, date, and drop-down list. To add a new attribute, click tAdd new attribute located in the upper-right part of the window:



When adding a new attribute, the following options are available:

  • Defaultname: It will be used by LimeSurvey to name the attribute in case no other English name is provided.
  • Attribute type: You can choose either of the attribute types and the associated user interface will be presented to you while editing.
  • Should this attribute be visible on the panel?: It can be Yes or No. This function determines whether the attribute is visible in the CPDB table or not. This can be later edited from the Visible column that is located in the main attributes table.
  • Languages: If you would like LimeSurvey not to use the defaultname as the name of the attribute, type here the desired name. Please note that the attribute management has multilingual support. Click on the plus sign after you have selected the language. A new field will appear below the English/default language.

Once the changes are done, click Save.

We recommend tha you write the name of the attribute in the corresponding language box even if you use only one language (the base language). The reason for this is that when you map attributes and you wish to add them to different survey participants table, the defaultname of the attribute is not displayed in the respective panel - only the name you give in the corresponding language box is shown.

In the attributes table, two actions are available (see the Action column):

If you click the first icon, a dialog box will be displayed. It includes the basic settings of the selected attribute that can be edited according to your needs.

To delete an attribute from the table, click on the red trash button, located next to the edit button. Clicking the delete button will not only delete the attribute, but also the associated values from the CPDB.

Share panel

The share panel shows all the information related to the shared participants. Please note that this panel shows only the shared participants owned by that particular user.



This panel shows values like:

1) Last name

2) First name

3) Email address

4) Shared by

5) Owner

6) Date added

7) Can edit?

This information is for viewing/sorting purposes. Only the Can Edit field is editable for the user. The Can edit field allows you to determine whether to allow the respective participant to be editable by the user with whom that participant was shared with or not. Clicking on the check box will make an AJAX call and save the changes on the server.

Export participants

The export function is located on the main toolbar of the Central participant database page:

When exporting to CSV, you are presented with a dialog box that asks you to mark the attributes you wish to export.

You can export:

  • None of the additional attributes
  • All the additional attributes
  • Certain additional attributes



The format of the exported file will be CSV.

Export filtered participants

To export filtered participants, use first the search filters. Then. click the checkbox located on the left side of the Action column (to select all the filtered participants). Then, click the Selected participant(s)... button located at the bottom-right side of the table and select the export function. In this way, only the filtered participants will be exported.

Search filters

If you wish to filter the users from your database, use the search/dropdown boxes located below each column title:



Enter information in the search fields or select from the dropdown lists (when possible) the participants you want to be listed after the filtering process.

Additional information

Additional (technical) information is available in the Central participants database (User panel) Development wiki.

Retrieved from "http://manual.limesurvey.org/index.php?title=Central_Participant_Database&oldid=174996"