GRASP Designer User Manual Draft Version - English Edition GRASP Designer version 0.0.32 July, 2015 By Information and Knowledge Management Unit, UN WFP Palestine Country Office July, 2015 1
GRASP Designer - User Guide Contents GRASP Designer tool 3 1. 3 Easy Steps to deploying a form... 3 2. Accessing the GRASP Designer Tool... 3 3 Home: 7 Menus... 7 Tabs... 7 a. Forms Tab... 7 The Form editor... 10 b. Contacts Tab... 16 Import contacts from a csv file:... 18 c. Sending methods... 18 d. SMS Connection:... 19 i. Installation and configuration of SMS Gateway... 19 ii. Configuration... 19 iii. Message: (SMS) Status:... 20 e. Internet Connection:... 20 i. Network Connection... 20 ii. Setup the Internet/WLAN Connection... 21 2
1 GRASP Designer tool The GRASP Designer tool is built on FrontlineSMS, an application to manage sending and receiving of SMS messages and design of forms for data collection. 1. 3 Easy Steps to deploying a form 1. Create a group of users and in it create all the user contacts inside the group. See section 3.4 2. Create a form using the Form Editor. See section 3.3 3. Publish the form and (optionally) send by SMS to the users 2. Accessing the GRASP Designer Tool Double clicking on the shortcut Design tool on the desktop, or select the GRASPDesigner icon from the Start menu. As shown on the screenshots below a command prompt will open and after few seconds the Logon screen will appear on the screen 3
Insert the following credentials: Name: supervisor1 Password: grasp1 At the first access of GRASP you have to select the language Click Done and the first-time wizard window will open By clicking Sta land to the foll next page) 4
GRASP Designer Tool: Home Page. 1. Main menu, 2. Tabs, 3.Switch Language, 4. Send Bulk SMS, 5.Log of latest events 5
6
3 Home: Menus File: allows you to import export contacts, messages, keywords, and import forms Settings: you can select the language and open the Preferences dialog box that allows you to customize certain Grasp settings. View: permits displaying or hiding the tabs on the top of the screen. Help: Tabs Forms: you can create new forms and manage those already done. Contacts: you can manage your address book, your contacts and groups Keywords: you can create SMS Autoreplies, be able to configure SMS to email settings and set up advanced features. Messages: is where you view all your incoming and outgoing SMS messages by Contact Group or Keywords. Emails: you can configure automatic email sending linked to SMS reception SMS Connection: is where you can set up your GSM modem connection. a. Forms Tab Click on the tab Forms to access the Form Manager Once the page is opened, you will note that is made up of a main window where all the forms created will appear, and of 9 buttons that will allow you to perform different actions 7
Note: at the first access the main window will be empty and the only button enable will be New. New: allows creating a new form. Copy: let s copying an existent form, renaming it and editing sending it again. Edit: you can edit a form already saved but not sent yet. Delete: you can delete a form already saved but not sent yet. Send & publish: permits sending the form using SMS transmission. Export prototype: allows you to export the form (xml file). Where you can copy this file to another PC, and import it. Group: is for selecting a group to send the form. Only publish online: you will transmit the form using internet connection. Launch Form Test: allows to test the form on the management tool, so that you can check it before distributing it. Note: currently, it is not working, we are planning to work on it soon. If you want to Import an xml form on the form manager(1): a) Right click on File, b) Mouse over Import, c) Select Form Prototype, browse for the xml file(2), select it and click on Import (3). 2 1 3 You can also export forms into an xml file to exchange with other GRASP installations. To do that: (1) a) Select the form you want to export, 8
b) Click on the button Click on Browse and select a folder where to save the form prototype and click Ok (2), Then click on Export (3). 2 1 3 If you want to make the designer faster, you can use the function Hide. Once that you hide a form you can still receive data, but you won t see it listed on the form manager. To do that(1): a) Select the form you want to hide from the form manager, b) Right click on it, c) Select Hide A message will be shown on your screen, Click on yes (2). 1 2 9
The Form editor The form editor consists of 3 sub sections 1. The right panel Palette where you can select the fields to be added to the form, there are 16 different types. 2. The central area Preview is the working space where you drag the fields you want to add to the form. 3. The left panel Properties is where you can see and define the properties of the fields. 10
Form Editor Palette Preview (Design Area) Properties 11
Fighting Hunger Worldwide 1. Palette: Field types The field types available are: Single-line text, Multi-line text: this field does not return any data; it is used, if necessary, just to give additional information to the user. They are automatically named by the system. Text Area, Text Field: accepts any kind of text (and numbers). Number: allows the user to insert integer and decimal numbers, it can be a calculated field. Drop-down list: allows the user to choose a single value from a list. You must associate a list to this field. Check box: Radio Button: You must associate a list to this field. Currency: This field asks user to insert decimal values and associate that to a currency. Date: is a date field DD/MM/YYYY Table: Tables are used for asking a set of questions for a list of items. Typical examples are a list of commodities, products or locations. Data collected in tables will be exported in a relational table. Rosters: Rosters are used for asking a set of questions repeatedly for a variable number of times. A typical example is a household member roster. Data collected in tables will be exported as a relational table. Geographic location (GPS): This field will register three data: latitude, longitude and accuracy (m) as decimal numbers, using the GPS integrated in the device. E-mail Address: will collect an email address Phone Number: can register only phone numbers preceded by the country code Separator: is a particular item that allows you to divide the form in sections (screens for the mobile application). They are automatically named by the system. Multi-format Barcode: this field will capture barcodes, qr codes from the camera of the device Image: this field will capture photos from the camera of the device 2. Field properties (left panel) Select a field by clicking on it and you will see on the right panel all the properties available for it e.g. reference list property is enabled only for drop-down, radio and tables fields. At the bottom of this section you can find the Save button Type: Represents the field type. Label: The Label of the Field defined here is the text (question) that will be displayed on the Mobile questionnaire. It can be empty and has no character limitation in UTF-8 character set, so you can write letters with accent and special characters. WFP Palestine Country Office Al-Munther Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227
page 13 Name: The name is used to identify the field and it is used in the creation and visualization of data on Management Tool. Is the variable name. Single-line text, Multi-line text and separators name is automatically given by the system. Required: A required field is a field that cannot be left empty by the user (during the form filling on the mobile device). It can be set up using the dropdown under the proprieties table. Is calculated: and Formula: A number based field can be calculated. It means that the field is read only and its content is auto-generated using the formula associated with it. To make a field calculated check Is calculated checkbox and click on the Formula dialog box to open it. The formula can be written by dragging other numerical fields into the calculation box and using the arithmetic operators provided. Notes: o Calculated fields can be used for validity and visibility checks to create validation that concern more than one field, and to provide error messages to users o To make the calculated field visible to the mobile user, the last 3 letters of the field name must be VIS. Note that when a red label (validation error) will always be visible. o You can calculate the total of a field s values in a table or roster simply by using the field outside of the table or roster. Reference list: shows the list associated with the field. Only dropdown, radio button and tables have this property. To associate a list to a field you must select it from the reference list dropdown. If the list is not present you can click Edit list and create it. (see below). Fixed repetition: is a Roster property that allows you to determine and limit the number of its repetition. Validity conditions: You can add validity conditions to a field to prevent inconsistent data. For numerical fields these consist of larger than or smaller than conditions. For text fields they consist of conditions on the length of the text value. Conditions may be combined by either All or Any combinations. To add validity conditions click on Add and select the operator and the complete the condition by entering a value for each operator added. Visibility conditions: allows you to make the field visible or not, depending on inserted conditions or on the value of previously defined field or fields. To add a visibility condition, select the field that is to depend on other fields. Drag these fields into the visibility area and define for each the visibility condition by selecting an operator and a value. The List Editor The List Editor window manages the lists in all the forms in GRASP. Lists are used for options in dropdown lists, radio button lists and are used also to manage the records in a table. To create a list enter a name for the list in the lower left box and click on Add above it. Lists can be deleted by selecting the and clicking Remove underneath. Then enter the items in the list, each on one line, in the right box. Click on Add above it. They will be added to the list in the pane above. They can be selected and removed with the Remove button. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 13 of 21
page 14 It is also possible to copy a list from another form. Select the list to copy and click on Copy, and provide a new name for the list. Lists can be renamed after selecting them in the left pane and using the Rename button. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 14 of 21
page 15 Best Practices in Questionnaire Design Data Quality The quality of the data that will be collected will depend on a good questionnaire design and otherwise on the preparation of the enumerator. In other words designing a questionnaire well ensures that the quality of the data does not depend on the skill and good will of every single enumerator. Numerical Fields 1. Always prefer radio buttons or drop-down selections to text or number fields. 2. Always use validation ranges for numbers, even if you have to keep them broad. Avoid having numbers without any validation. Validation 1. Avoid restricting validation when extreme cases may exist, for example having AGE between 18 and 100. An enumerator may find a 17 year old or a 101 year old Head of Household for example and they would be blocked. It is possible to add a warning text or even a checkbox with Age is an extreme value. Please verify question that is visible only if age<18 or age>100 which would force the enumerator to check. 2. Make use of calculated fields to check that entered data makes sense. For example Field1 + Field2 <= Field3. You can add a Please verify checkbox or a Please select reason dropdown list to ask the enumerator to validate why the responses do not tally. Special Codes Avoid entering special codes. For example a question that asks a number will sometimes say Enter 0 for not applicable. It is better to have a yes/no question and then a numeric field that is visible only if it is relevant. Optional vs Required In general try to avoid non-required questions (optional questions) and avoid default responses for questions. In the current version of GRASP there is no provision for default responses. Test the Questionnaire Always test your questionnaire fully for the validation and visibility using the Data Entry tool, every time you create a complex set of fields or every section, and finally using an Android device. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 15 of 21
page 16 3. Save button Once you have finished designing your form you can save it by clicking Save, or discard it clicking on Cancel In order to save successfully the form: 1. All fields must be named following the rules explained in the Name section, 2. All fields that require a list must have associated one, 3. All tables and roaster must have at least a field inside and the formula editor must be closed before saving the form. If any of these conditions is not respected an appropriate message will inform you. b. Contacts Tab It is necessary to populate your contact book and create a group of contacts to distribute each form to. A group can contain several contacts. You can create and manage your contacts and groups by clicking the Contacts tab. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 16 of 21
page 17 To create a group click on New Group, write its name and then click Ok. Once your Group is created, you can add new members into the Group by Clicking on New Contact Insert all the information required and select the group previously created. Note: The mobile number has to be preceded by country code.e.g. +3900000000 WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 17 of 21
page 18 If SMS is not being used, any unique ID can be given for each user. It must be preceded by a + sign. We advise to use your country telephone code, followed by a number e.g. +390001, +390002, etc. otherwise to identify users by team. Eg.+3901001, +3901002, +3902001, +3902002 Once you have created the groups and contacts you can also edit or delete them by selecting the group or contacts and clicking Delete or Edit buttons. Import contacts from a csv file: To populate you address book you can also import the contact from a.csv file. To do that: (1) d) Right click on File e) Mouse over Import f) Select Contacts Automatically the Importing contacts and groups window will open, browse for the.csv file and then select it. You can also select the contact details to import (2), once that you have chosen those you want to include click on import (3). c. Sending methods To distribute a form you have to associate it to a group. To do that follow the below steps: 1. Go on the Form tab. 2. Select the form to distribute. 3. Right click on it and select Group. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 18 of 21
page 19 4. Once that you have selected the group you can send the form using SMS or internet. GRASP data collection and transmission can occur in any or all of several ways: 2G/3G mobile network from the field. SMS text messaging from the field. WLAN once back in the office (or any WLAN hotspot e.g. internet caffe). Data collected on paper and entered on the web by data entry clerks. Data entered online directly from the field using a mobile web page (for example from Ipads) d. SMS Connection: The SMS connection page is where you manage the modems and devices to be used for the SMS sending. Even if mobile internet is used there may be cases in which SMS may be used: to send batch communication to all users, for example that a new form is available and that they should download it, or if network connectivity is not available and the mobile device user has data that needs to be sent. 1 or more GSM Modems are required to send/receive SMS. i. Installation and configuration of SMS Gateway Install the gateway using the installer. The installer proceeds with the following steps: Accept the license terms. Set the database connection. Insert address, port, username and password for the connection. When the installation is complete start the gateway software to see it is working properly. First time you have to select the language. The gateway is active in the system. Configure it to see the modem to be used for sending messages. ii. Configuratio n Connect the modem to the server and do the following steps: 1. Run the Gateway software if it is not already active. 2. Select "Tab connections" and WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 19 of 21
page 20 click on the button "Auto Detect Phones". The mobile device will appear in the "Inactive connections". 3. You must wait while the software connects to the modem, disappearing from the "inactive connections" and appearing in "active connections". The modem is connected but not yet set to be used by the software. 4. Double click on the line of the modem. A dialog box will appear. 5. Select the check box to "use for sending use for receiving", "delete messages from phone after receiving". 6. Clear the check box to "use delivery reports". 7. Leave blank SMSC reports and SIM Pin. Press Save. Note: the SIM Card cannot have a pin code! 8. The modem is ready for use. When the server on which you installed the SMS Gateway software is turned off or rebooted you need to run it again to allow the modem to receive requests for sending text messages properly. iii. Message: (SMS) Status: To check the status of the SMS sent click on the tab Messages, go to the left panel and click on All messages. Outbox: this means that the SIM card you plugged into the modem is not connected, and the modem is not working. So the message has been stored in the outbox. As soon as the modem connectivity will be restored the form will be sent. Pending: the form sending is ongoing. Failed: the sending failed, check the modem connection and if there is enough credit on the SIM card. Sent: the form has been sent to the mobile device successfully. Received: the server received the form from the mobile. e. Internet Connection: i. Network Connection The server has to be accessible on internet using a static IP address only if either of the following 2 conditions are required: The data is to be sent from mobile devices from remote locations (using mobile internet or from an WLAN internet connection) and not exclusively using SMS or WLAN from the office. The data and the analysis are to be consulted not only from the server s console but also from others via the web. In this case an internet provider must provide a static IP address and guarantee continuity of service as appropriate for the use case. This is a service that can be purchased if not already available. A domain name may be purchased to point to that IP address so that the server responds to a specific name, for example http://data.mydomain.org WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 20 of 21
page 21 If mobile internet (GPRS, EDGE, 3G, HSDPA etc) is expected to be used to transmit the data, then an appropriate contract must be researched with the mobile phone service providers. It is important to look at coverage and cost. ii. Setup the Internet/WLAN Connection Note: internet/wlan transmission of data occurs via the GRASP Reporting tool. WFP State of Palestine Country Office Al-Noman Street, Beit Hanina, East Jerusalem Telephone: +972 (0)2 5401340/1/2 Fax: +972 (0)2 5401227 Page 21 of 21