Web Services API Reference

     


You can also use ViewsFlash as a component in a web application by using its API commands. This section provides a reference to each command and what it does.

How to issue commands
ViewsFlash receives commands through its service() method as a URL. Any method that results in this protocol is compatible with ViewsFlash. These include any way to issue an http get command from another application. For example, you can use Java's HttpURLConnection class in JSP pages, or the Microsoft.XMLHTTP class in Windows ASP pages.

You can also, from a Java environment that provides appropriate support, invoke the service() method of ViewsFlash directly, provided the appropriate conventions are followed. See How to use the Web Services API.

In all cases, you send ViewsFlash a query string, just like you would enter into your web browser, such as:
cmd=getpoll&spotname=Default

Responses and errors
When ViewsFlash receives a request, it returns a text/html string with the requested information. If the request is in error, ViewsFlash will return a string of the form:
<viewsflash [/NG] ... > with additional error information inside. You should parse for "<viewsflash" and log the message and take whatever action is appropriate for a failed request. Because the error message is enclosed in <>, if you let it pass through to a browser, it will be invisible but can be examined with a View Source. You must test for this string and take appropriate action.

Command Reference

Command,
parameters
Operation
cmd=getpoll
&spotname=SSS (required)
Fetches the voting form HTML of the currently scheduled poll in place SSS.
&pollid=pollingplace!poll If present, fetch poll pollingplace!poll rather than the currently scheduled poll. Useful for previewing.
&style=TTT If present, use this Poll Style template instead of the default.
&stylesfx=SSS If present, append this to the name of the style template to use.
&pollidsfx=PPP If present, present the voting form using the question and answer text from a poll named 'pollid'+'pollidsfx', but refer to the underlying 'pollid'.

Command,
parameters
Operation
cmd=getresults
&spotname=SSS (required)
Fetches the current (live) results for the currently scheduled poll in place SSS.
&style=TTT If present, use this Response Style template instead of the default.
&results=r.html If present, use this page, relative to the web root directory, to compose results.
&latest=1 If present, compose results of the current poll or, if closed, the most recent poll.
&pollid=pollingplace!poll If present, compose results for this specific poll. You must also specify spotname.
&stylesfx=SSS If present, append this to the name of the style template to use.
&pollidsfx=PPP If present, present vote results using question and answer text from a poll named 'pollid'+'pollidsfx', but get the results from underlying poll 'pollid'.

Command,
parameters
Operation
cmd=geteither
&spotname=SSS (required)
If the visitor has not voted yet in the current poll, fetches the voting form HTML of the currently scheduled poll in place SSS.
If there is no current poll, returns the default value specified in the place settings page.
If the visitor has already voted in the current poll, fetches the current (live) results for it.

Command,
parameters
Operation
cmd=ifvoted
&spotname=SSS (required)

If the visitor has not voted yet in the current poll, returns "0".
If the visitor has already voted, returns "1".
If there is no current poll, returns "2".
If the visitor is not authorized to vote, returns "3".

&verbose=1 Besides the single digit described above, returns a single '|' character followed by the appropriate error text from the "Display the following response page" fields in the Security page, which are usually set to begin with an equal sign when using this option, to indicate a literal.

Command,
parameters
Operation
cmd=getpollnames
&spotname=SSS
Fetches a list of poll IDs in place SSS, separated by a | character. Returns "-1" if there is nothing to return.

&status=archived or current or scheduled or possible or latent or all
(optional, choose one; default is current)

current lists the single poll that is active, if any

archived lists questionnaires in the Archived Polls page

scheduled lists questionnaires with explicit start and end dates

possible lists everything on the place page (i.e., everything not archived)

latent lists questionnaires that are open now or are scheduled to be open in the future

&match=mask If present, this mask is the same as a file system wildcard, e.g., P?21?,* where a ? matches one character and * matches one or more characters. Only polls that match the mask will be listed.
&sort=alpha Without this argument, polls are listed in the same order as the Place page; when this argument is present, polls are sorted alphabetically, with case sensitivity.
&title=1 If this argument is present, each poll name returned is followed by 'title= and the Title of the poll
&smp=1 If this argument is present, each poll name returned is followed by 'smp=s or 'smp=m depending on whether the survey is a single page or multiple pages, respectively.
&isscheduled=1 If this argument is present, and the place schedules only one poll at a time, a * precedes either the pollname of the currently open poll, eg., *Go!now, or *-1 if there is no currently open poll.

Command,
parameters
Operation
cmd=checkpoll
&pollname=PPPPPP
&spotname=SSSSS

Checks place SSSSS to check the status of poll PPPPPP. Returns the following:
0 - Poll doesn't exist. You must create it before using it!
1 - Poll open for voting
2 - Poll defined, scheduled to open in the future
3 - Poll closed and archived, voting no longer allowed
4 - Poll defined, but not scheduled
Illegal opening/closing times will return the standard error return <viewsflash [/NG] ... >

This code can be used in cmd=getresults by using the [/pollstatus,code,message] tag.


Command,
parameters
Operation
cmd=getpubdate
&spotname=SSS
Fetches the publication date of polls in place SSS, if available, or an invisible error message otherwise. If no spotname is used, returns the current time.

&pollid=pollingplace!poll

If not specified, looks up the currently scheduled poll. If specified, looks up pollingplace!poll .

&date=start or end (optional; default is end) Looks up the start or end date
&format=a or b (optional; default is b) If a, returns in format "8/9/00 11:00 AM". If b, returns a long integer representing Unix time in milliseconds since 1/1/1970, such as 965844000000.

Command,
parameters
Operation
cmd=gettime
Returns the number of 10-second ticks since approximately 6/30/99, with leading zeroes. This is the same time convention used for the cookies thrown when you use the History parameter.

Command,
parameters
Operation
cmd=getspotnames Fetches a comma-delimited list of place names.

Command,
parameters
Operation
cmd=multisample Retrieves a javascript fragment for opening a window and conducting a survey in it. The survey shown is picked from the list of surveys identified by id= parameters. Each of the surveys must be set up for Random Sampling and must be currently active to be included; if not, it will be ignored.
id=pollid The id of a survey, e.g., pollingplacename!pollname
id=pollid repeat one pair of these for every survey
history=cookiename The name of a cookie that will track the sampling history for all these surveys. Do not use the history parameter when using this command.
multiple=yes If yes, the visitor may be presented with more than one of the surveys on the list. If no, the visitor will be presented with at most one survey.

Command,
parameters
Operation
cmd=provision
Creates a Place and assigns a user access rights to that place. The operation returns "OK" if successful or an error message otherwise.
addname=SSSS The name of the place to be created
users=UUUU The user IDs of the users who will be granted all rights to the Place
email=xxxx@xxx.xxx (Optional) The email address where a message will be sent including the URL of the newly created Place.

Command,
parameters
Operation
cmd=provision2
Gets or sets access rights in a Place.The operation returns "OK" if successful or an error message otherwise.
spotname=SSSS The name of the place
op=getrights Use op=getrights to receive the rights in a place. The operation returns a list of the users and their rights, like this:
createusers=*,tom|analysisusers=peter|viewdatausers=|stagingusers=@publishers|
op=setrights Use op=setrights to set the rights in a place. Add the following parameters. If a parameter is omitted, that right will not be granted to anyone.
createusers=*,tom&analysisusers=peter&viewdatausers=&stagingusers=@publishers
email=xxxx@xxx.xxx (Optional) The email address to send a message alerting that Place rights have been set.

Command,
parameters
Operation
cmd=provision3
Creates a questionnaire by copying from another
newpollid=SSSS!PPPP SSSS is the name of the place, PPPP is the name of the questionnaire to be created. It must not exist. Required.
pollid=SSSS!PPPP SSSS is the name of the place, PPPP is the name of the questionnaire to be copied. It must exist already. Required.
publish=1 If this parameter is used, the questionnaire will be published immediately, with a starting date of Now and no ending date.

Next: Embedding questionnaires in JSP pages