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