2.6 Forms Tool Help

Forms: Overview

In Sakai, forms are online structures that allow you to collect and store data. They are the electronic counterparts of paper forms, such as those you fill out to submit applications, complete surveys, and so forth. 

Each form consists of a name, instructions to the user, and a set of input fields or boxes with field names. Both the instructions and the field names guide site participants in completing the form appropriately.  The form itself, in the Forms tool, is a structure comprising places for data.  When an instructor or other user in the role of CIG Coordinator creates and publishes a new form, the form is ready for data entry.  When the form is filled out, the completed form data is stored in Resources. If the form was filled out in the process of completing a matrix cell or wizard page, the data will be stored in the Portfolio Interactions folder in My Workspace > Resources. If the form was completed via the Resources tool, it will most often be stored in the participant's My Workspace Resources folder.

In Sakai, forms allow you to collect, store, and display information in wizards, matrices, and portfolios. These forms can serve a variety of purposes. For example, you may use forms to collect routine information, such as contact information and educational or work history. You may also use forms to prompt users to document their learning or provide metadata for work they have completed. Other forms may be designed to guide users in documenting the details of a teaching experience, restating a particular learning outcome in their own words, or describing an internship experience. Some forms are specifically dedicated to guide users to reflect upon their learning, skills, course work, or other experiences. Still other forms can be used to collect feedback or evaluation from instructors or peers on the user's work.

In wizards and matrices, different forms can be presented to users in different roles:

• Site participants may be asked to fill out forms to provide background information, document work on projects, describe courses, reflect on co-curricular experiences, or organize thoughts about learning outcomes. These users fill out and save one or more completed forms as they work in each wizard page and matrix cell.
• Site participants may also be asked to reflect upon the items they have included in the matrix cell or wizard page by commenting on the origin of the items, the process of creating them, their strengths and weaknesses, what was learned, and what might be some next steps for improving them.
• Reviewers and evaluators may use forms to provide feedback on a site participant's work in matrix cell or wizard page. These forms collect formative feedback (from reviewers) and summative feedback (from evaluators) on the work demonstrated in individual wizard pages and matrix cells or on the work in the matrix or wizard as a whole. Forms for summative feedback can include an evaluation scale or an elementary or a full-fledged clickable rubric with descriptors for the levels of each criterion.

For Participants

You will not normally use (or even see) the Forms tool in your portfolio sites.  That work has been done before you start.  You will follow the workflow given by your instructors, during which you will fill out and save one or more forms, and use the completed forms (sometimes called form instances) as elements in the portfolio that you build.

For CIG Coordinators:  Completed Forms and Data Types 

Within a particular wizard, matrix, or portfolio, you may specify that some forms are required, some forms can be completed only once, and some forms need not be completed at all if they are not appropriate.

Other forms can and should be used repeatedly to collect multiple versions of the same type of data in several completed instances of the same form. So, a student may complete and save a contact information form many times to capture information about his or her home, work, school, summer residence, parents, study abroad and/or research locations. When working with portfolios, the student can include any or all of these different completed form instances in one or more portfolios and/or one or more versions of a specific portfolio.

The instructions, fields, and field names in forms vary, depending on the information the form is designed to collect. Fields may also be as small or large as the creator of the form deems necessary.

Forms can contain many fields and types of data. The supported data types are shown in this table.

Each field in the form uses a specific data type.  Fields can be configured to validate the user's input (for example, to ensure that the numeric value for a date falls within a plausible range).  Also, the form creator can specify whether a field is optional or required and whether the field may be repeated (filled out more than once).

Available field types include text, rich text, date, selection (radio buttons for less than five options, drop-down menu for five or more), group, file (for attachments), and Boolean (check boxes).

Forms may be published globally (that is, for use in all sites in the Sakai instance) or locally (for use in the current site only). Most forms are created for specific sites. However, if you create a form that has general applicability, you may recommend that it be published globally. Only a system administrator can publish a form globally (in response to your recommendation).

A portfolio template may display all fields from a form included in the template or only selected fields. The same form (and some or all of its fields) may be used in multiple portfolio templates, wizards, and matrices.

For CIG Coordinators:  The Forms Tool and the Resources Tool

CIG Coordinators can create and publish forms for use in the site. Each form is based on an XML schema definition (.xsd file). The XSD file is usually created offline and later added to Resources from which it can be "added" to the Forms tool.

Important: We strongly recommend that you store all XSD files in your My Workspace Resources folder rather than in the portfolio site's Resources area. Site participants do not need to work with or see these files. By storing XSD files in your personal Resources area (preferably in a folder named Form XSDs or something similar), you prevent site participants from possibly being confused by them. This practice leaves the site Resources area free to be used as the place for files that are appropriate for all site participants. It also allows you to use a single copy of an XSD file in your My Workspace Resources to create forms in all of your sites. Alternatively, you may "hide" the XSD files in a portfolio site's Resources as single files or in a hidden folder (using Edit Details in the Actions drop-down menu).

The Forms tool is used to "add" XSD files from Resources, give them meaningful names, provide instructions for using them, and publish them for use by site participants. You may also use the Forms tool to export forms in one site and import them into another.

The Forms tool does not provide direct access to the forms you create. Instead, site participants access forms that they need to complete via the Matrices, Wizards, and Portfolios tools. In addition, they may create, view, and edit form instances in Resources.

For CIG Coordinators:  Accessing a List of Forms

To open the Forms tool, click Forms in the Sakai menubar. Sakai displays the Manage Forms page.

The Manage Forms page contains a list of forms that have been created locally for your site. The forms are ordered alphabetically. For each form, you can see the name of form owner, when it was last changed, and its site and global states (published, unpublished, or waiting for approval).

If the list of forms is longer than one page, use the buttons near the top of the page (First, Previous, Next, or Last) to display other pages in the list.

For CIG Coordinators:  Adding and Managing Forms

Preliminary Steps

Before adding a form, follow these steps:

1. Create, or find, the XSD file that defines the data structure that you want. Review existing global forms on your Sakai instance. You may find a form that suits your purposes, in which case you do not need to create a new one. You cannot create an XSD file in the Forms tool; to create an XSD file, use an offline XML editor or the Form Builder (Contrib) tool.

2. When creating or editing an XSD file, plan the content carefully. Keep the following points in mind:

• Field names are displayed to the left of the text fields to which they apply.
• Field names wrap somewhat unpredictably.
• Long field names are difficult for participants to read.

3. Consider adding the new form to the Forms tool in a test site in order to view and change it as needed before including it in your production site.

Adding a Form

To add a form, open the Forms tool and follow these steps:

1. If you have not already done so, upload the XSD file (as well as any alternate renders for the XSD) to Resources.
2. In the site where you wish to add the form, open the Forms tool.
3. If you are not already on the Manage Forms screen, click the Reset icon.
4. Click Add in the menu at the top of the page. Sakai displays the Add Form screen.
5. In the Name box, enter a meaningful name for the form.  Choose the name carefully; be sure to choose a name that indicates the specific use of this form. After the form has been added to the site or published globally, its name will be visible in Resources to all site participants (or if published globally, to all participants of all sites in this Sakai instance). Therefore, if the form is tailored to a particular matrix cell or wizard page, a generic name such as Reflection is misleading and makes the form seem appropriate for general use when, in fact, it is not. Use a generic name for a form only if the fields, field names, and instructions in it make the form suitable for use in a wide variety of situations.
6. Click Select Schema File. Sakai displays the Select Item screen.
7. Navigate the site and folder hierarchy to locate the XSD file you uploaded in step 1. Click Select next to the name of the file.  The schema file will appear in the list at the top.
8. Click Continue to return to the Add Form screen. The name of the file you selected is shown in the Schema File (XSD) box. 
9. In the Instruction box, enter instructions to help the participant complete the form.  Use the icons and drop-down menus to format the text as appropriate.
10. If you developed an alternate form creation renderer (controling the data entry view) and/or form view renderer (controling the read-only view) for the XSD, use the Select XSL File links to upload and select the XSL renderers.
11. To check the form, click Preview.   Enter test data into the preview of the form and click Validate to ensure the form works properly.  Then click Return to go back to the Add Form screen.
12. To complete the process, click Add Form.  (Or, to return to the Manage Forms page without adding this form, click Cancel.)  Sakai creates the form and returns to the Manage Forms page. The new form is added to the list in an unpublished state.

Previewing a Form

Before adding a form to a matrix cell, wizard page, or portfolio template, you can preview the form to make sure it's appropriate for your intended purpose:

• Method One: This method works for forms listed in the Forms tool, including "hidden" forms. However, it cannot be used to preview "global" forms, i.e., forms that the Sakai administrator has made available to all users.

1. Go to the worksite containing the form you wish to preview. From the menubar, click Forms to open the Forms tool.
2. On the Manage Forms page, locate the form you wish to preview, and click Edit.
3. On the Edit Form page, click Preview. An empty version of the form will appear.
4. To test the form, enter sample data in each field and click Validate. To return to the Edit Form page, click Return.
5. Click Save Changes or Cancel to return to the Manage Forms page.

• Method Two: This method works for site-specific and "global" forms, but cannot be used to preview "hidden" forms.

1. Go to My Workspace.
2. In the menubar, click Resources to open the Resources tool.
3. Open the Add menu next to any folder, and choose New Form Item.
4. All of the forms to which you have access (except hidden forms) will be listed on the Select a Form page. Forms are organized into groups by site (the site in which the form resides) and then alphabetically by form name. Select the form you wish to preview, and click Continue. An empty version of the form will appear.
5. To test the form, enter sample data in each field and click Continue. The Edit Details screen for the form will be displayed. Otherwise, click Back to return to the list and preview another form, or click Cancel to return to Resources in My Workspace.
6. Give the completed form an appropriate name, complete the Edit Details screen, and click Finish. The Resources folder for My Workspace will be displayed.
7. Click the name of the completed form to review its content. (Remove the completed form if it is no longer needed.)

Changing a Form

Using the Forms tool, you may change the name of a form and the instructions for using it. However, you cannot use the tool to change the structure (fields and data types) of the form itself.

To change the name or instructions for a form, access the Forms tool and follow these steps:

1. If you do not see the Manage Forms screen, click the Reset button.
2. Find the form you want to change, and click Edit. Sakai displays the Edit Form screen.
3. Change the content in the Name and Instruction boxes as needed. Use the icons and drop-down menus to format the instructions text as desired. To preview the form while editing, click Preview.
4. When you are finished, click Save Changes to save and return to the Manage Forms page.  Or, to return to the Manage Forms page without saving, click Cancel.

Publishing a Form

In order to make a form available to site participants, you must first publish it.

To publish a form, access the Forms tool and follow these steps:

1. If the Manage Forms page is not displayed, click the Reset button.
2. On the Manage Forms page, find the form you want to publish.
3. Optional: Click Edit to ensure that the information for the form is complete and correct. From the Edit Form page, click Preview to verify that the form structure and layout is correct.  Make changes as needed, and save the changes before proceeding.
4. Return to the Manage Forms page and click Publish for the form you want to publish. Sakai displays the Publish Form confirmation screen.
5. To proceed with publishing the form, click Yes. Sakai displays the Manage Forms page. The Site State for this form is changed to "published."  Or, to return to the Manage Forms page without publishing the form, click No.

Requesting Global Publication of a Form

If you have created a form that has general applicability, you may want to make it available for use in all sites. However, only Sakai system administrator(s) can publish a form globally (that is, across all sites in Sakai), so you must send the administrator a request.

To request that a form be published globally, access the Forms tool and follow these steps:

1. If the Manage Forms page is not displayed, click the Reset button.
2. On the Manage Forms page, find the form you want to submit to the system administrator for global publication.
3. Click Publish Global for the form. Sakai displays the Publish Form confirmation screen.
4. To proceed with the request, click Yes. Sakai displays the Manage Forms page. The Global State for this form is changed to "waiting for approval."  Or, to return to the Manage Forms page without submitting the request, click No.

Publishing a Form Globally

If you are a system administrator, you may publish a form globally (that is, for all sites in a Sakai instance). To do so, log in and follow these steps:
1. Go to the Portfolio Admin site.
3. Access the Forms tool. Sakai displays the Manage Forms  page.
4. Find the form you want to publish globally and click Approve Global Publish link beneath its name. Sakai displays the Publish Form confirmation screen.
5. To proceed with the request, click Yes. Sakai displays the Manage Forms page. Or, to return to the Manage Forms page without submitting the request, click No.
6. The form is now available for use in all sites.

Exporting and Importing a Form

If you own more than one site, you may want to use a particular form in two or more sites. To do so, you may either recreate the form on the second site from the XSD file in Resources or export the form to your desktop as a compressed file and then import it to the other site(s) where you plan to use it. The compressed ".zip" file contains the XML file defining the editable data fields, Name and Instructions, and the XSD file comprising the schema.  You may also wish to acquire exported zip files for forms from other users for import to your site(s).

Exporting a Form

To export a zipped file for a form, access the Forms tool and follow these steps:

1. If the Manage Forms page is not displayed, click the Reset button.
2. Find the form you want to export.
3. Click Export below the name of the form.
4. Your browser will prompt you to open or save the file. Save the file to a local storage device. The exported form will have a .zip extension.

Importing a Form

To import a form, access the site to which you want to import it and follow these steps:

1. Upload the compressed ".zip" file to Resources (in the site you where you are maintaining this site's forms). 
2. Access the Forms tool. If the Manage Forms page is not displayed, click the Reset button.
3. Click Import at the top of the page. Sakai displays the Import Form screen.
4. Click Select File. Sakai displays the Add Attachment screen.
5. Navigate the site and folder hierarchy to locate the XSD file you uploaded in step 1. Click Select next to the name of the file.  The .zip file will appear under Items to attach at the top of the page.
6. Scroll to the bottom of the page and click Continue. Sakai displays the zip file Import Form screen again.  The name of the file you chose is displayed in the Import File box.
7. Click  Import. Sakai imports the file from the Resources area and returns to the Manage Forms page.  The imported form is listed under its original name with a site state of "unpublished". Or, to return to the Manage Forms page without importing the file into the Forms tool, click Cancel. 

Deleting a Form

Forms definitions can be deleted from the Forms tool only if they have never been used. Once the definition has been used to create and save a completed form, the form cannot be removed unless all associated form instances are deleted first. To delete a form:

1. In the menubar of the portfolio site with the form you want to delete, click Forms.
2. On the Manage Forms page, locate the form you wish to delete and click Delete.
3. You will be asked to confirm the deletion. Click Yes to confirm or No to cancel.

After you confirm the deletion, the system will check whether the form has been used to create and save form instances. If the form is in use, you'll be notified that the form could not be deleted. If not, the form will be deleted and you'll be returned to the Manage Forms page.

Changing Forms Tool Permissions

All site participants can complete forms without permissions to use the Forms tool. However, permissions to create, change, delete, export, and publish forms by using the Forms tool can be restricted by role. To assign or change permissions, access the Forms tool and follow these steps:

1. If the Manage Forms page bar is not displayed, click the Reset button.
2. Click Permissions at the top of the Manage Forms page. Sakai displays the Permissions screen.
3. Referring to the table below, check boxes to select the appropriate permissions for users in each role.

4. To save the permissions settings, click Save. Sakai saves the settings and displays the Manage Forms page. Or, to return to that screen without saving your changes, click Cancel.