The Participants API |
Related: Invite, Invite Lists and Authentication.
The Participants API allows other systems to tell ViewsFlash that an event has occurred, and that as a result, a participant has become eligible to participate in a questionnaire and an email may be sent to that effect. For example, after a Help Desk customer interaction is completed, a service is delivered, or an online transaction is placed, those systems can use this API to tell ViewsFlash about it. ViewsFlash can then send an email to the person involved inviting them to fill out a questionnaire about their experience. The e-mail can include a unique URL, which the questionnaire can use to look up the transaction and automatically import certain elements into the questionnaire, thus avoiding asking the customer again. For example, after ordering telephone service, the questionnaire could already know the type of service ordered, the employee ID of the person taking the order, and the duration of the call. This information could be used in the questionnaire to ask specific questions based on the type of service ordered, and the information gathered could be used to analyze employee performance.
For this purpose, a web service API is provided for applications to use. The API can be used from a JSP page with an include, or can be used as a REST API over HTTP, as described in Web Services API.. The application signals ViewsFlash that an event has occurred by sending a command to ViewsFlash/servlet/viewsflash with the following query string parameters:
&cmd=participants
&action= insert or delete
&pollid= Place!questionnaire
&userid=userid
&username=username
&email=email
&password=password
cmd=participants is required, and indicates that this query activates the Participants API
action=insert indicates that this participant should be added; action=delete indicates the participant should be removed
pollid= gives the name of the questionnaire's Place and its name. For example, questionnaire Service in place Examples is referred to as pollid=Examples!Service. This notation is also used in all URLs that refer to a questionnaire, including its URL
userid= gives the unique ID of the questionnaire, which is discussed in more detail below
username= gives the participant's name, e.g.,, John Smith
email= gives the participant's email address, e.g.,, john.smith@yahoo.com
password= gives the participant's password for his unique ID, when type of authentication is being used
The Participants API is meant to be used with a questionnaire that uses an Invite List. These lists work together with the authentication method used in the questionnaire. A list specifies whether to use userid, password, e-mail address and username, in any combination. The Participants API should use exactly the same parameters that are specified in the Invite List. The Security options used should be compatible with the Invite list. Before using the API, set up the questionnaire, configure its Security, set up an Invite list, and test the entire thing manually. The Invite List can be created using a few entries in CSV format. When using this API, there is no need to store the invite list on a database or an LDAP server.
For example, a questionnaire that uses question authentication and designates the email address field as the user ID would require a list with email addresses and user ID's, and the web service calls would include the email address twice, once in userid= and once in email= ; if username were used, it could be used in question piping to compose a personalized e-mail.
Another example: a questionnaire that used Basic ( J2EE ) authentication would require a userid in the invite list. e-mail and username would be optional. This setup is most useful when ViewsFlash runs in a portal, where the "Show all eligible" questionnaires presents portal visitors with a set of links to the questionnaires they are eligible to participate in. The Participants API, when it receives the query, will result in the new questionnaire being shown to the participant identified by the user ID.
Another example: a questionnaire uses question authentication and a Case Number to identify each questionnaire. This setup would be useful in the examples envisioned at the beginning of this section. The userid is the case number (transaction ID, purchase ID, etc). The email address belongs to the customer.
How this works
This Web Service writes records to the internal VWFTRACKING table. ViewsFlash, using a background thread, sends email to new entries on the list that have an email address. The ViewsFlash survey portlet, if used in a portal, also uses this table to populate the list of available questionnaires. Whether an email is sent or not is indicated in the Invite page of the questionnaire setup; the email address field in the Invite List must also be enabled. If a user ID is used in the invite list, respondents IDs must be on the invite list or they are rejected.
Extensibility
It may be desirable to include additional information about the questionnaire in the email invitation. For example, a building safety assessment could use a building ID code as the User ID, and it would be desirable to include the building name in the email. The VWFTRACKING table contains a CUSTOM column that can be used for this purpose. Additional columns can be added to VWFTRACKING as well; the columns can use any legitimate name that doesn't use special characters.
To populate the CUSTOM column and the additional columns, use their names as additional parameters in the API query described above, prefixed with "extra." For example:
cmd=participants&...other parameters...&extra.custom=Harris+Building&extra.region=West
In this example, the CUSTOM column is being used to hold the building name, and a REGION column, created specifically for this purpose by ALTERing the VWFTRACKING table, contains the region name.
To use the CUSTOM and other columns in the body, subject, to, from, or reply to fields in an email, use piping syntax in the Invite page: [/custom] and [/region]. Use lower case only. For example:
Please take the survey at this URL ... The survey concernts building [/custom], located in region [/region].
See: Invite, Invite Lists and Authentication.