Modifying a Posting in a Knowledge Base

Adding a new posting to a knowledge base only requires the code example id to identify the knowledge base posting. All other parameters are optional, and represent new values for the code example posting. If an optional parameter is omitted then the corresponding field in the knowledge base entry will not be altered. Most fields can be edited by the original poster, knowledge base moderators, knowledge base editor, publisher supervisor and sysadmin. These fields are marked with an asterisk. Other users cannot edit the code example. Other fields, such as creation date, cannot be modified. The following table contains a complete list of the mandatory and optional parameters. Some fields have additional restrictions on who may modify them. Fields that contain CDATA are so marked.

Parameter name	User permission	Description
`applet`	*	CDATA: This field is only used to contain applet Java code at present. Default value is the empty string.
`class`	*	Class/section name for the code example
`closed`	*	Boolean indication if this is an open issue (help request) or a closed (resolved) issue. Default value is false.
`cmd`	*	CDATA: Sample code to be compiled and executed (or interpreted).
`created`	no-one may edit	Milliseconds since the dawn of Unix
`description`	*	CDATA: Discussion of the posting.
`example`	moderator and above	Boolean indication if this is a quality tested code example
`id`	no-one may edit	Code example id (used to select the example posting)
`imports`	*	CDATA: This field either contains command line parameters (for sandboxes that support complete programs/classes, or `include`/`import` statements that reference libraries that are necessary to compile and run the code example. Default value is the empty string.
`kb`	* (user must have permission to modify both the old and the new knowledge bases)	Knowledge base/book name for the code example
`method`	*	Method/subsection name for the code example
`package`	*	Package/chapter name for the code example
`pre`	*	If set to `true` or `1`, the result returned by the Zamples server will be enclosed in `<pre></pre>` tags. Default value is false.
`priority`	*	If this code fragment is a support request (`closed=false`, `example=true`) this value is used to indicate the urgency of the need. The range of values is from 1 (least urgent) to 5 (most urgent). Default value is 3. Once posted, the person who created the posting can not increase the priority, only decrease it. At least moderator privilege is required in order to be able to increase the priority.
`purpose`	*	CDATA: Reason for the posting.
`ranges`	*	Specifies lines of code to display to the user. Default is to display all lines.
`sandbox`	*	Contains the sandbox code for the code example. This tells the Zamples server how to handle the code example. Default value is `HTML/JSP`. Available sandboxes may be discovered through the discovery REST call.
`stylesheet`	*	Set to `1`, `0`, `true` or `false` depending if the stylesheet is to be applied to the code example's output. Not necessary if your client does not use HTML to display results. Default value is the empty string.
`subject`	*	CDATA: All code examples must have a non-zero length subject
`topic`	*	Fully qualified topic path. For example: `topic:subtopic:subsubtopic`.
`user`	supervisor and above	User handle of user who created the code example

As always, you can specify the parameters in an HTTP POST, and HTTP GET or a combination of POST and URL parameters.

If successful, a 200 status is returned along with the information specified in the request, otherwise the appropriate error status and one or more error messages are returned.

Only the author of the code fragment, the moderator, the author of the document, the publisher supervisor or the Zamples installation administrator can modify postings.

Specifying Return Values

The types of return values can be specified in the request through the use of the optional retval parameter, which is case sensitive. retval can be specified more than once in a request, and successive specifications are cumulative. By default, only warnings, errors and changed elements are returned.

Value	Default	Return type
`none`	no	Errors only.
`errors`	yes	Errors are always returned, so this value need not be supplied
`warnings`	yes
`old`	no	The complete old record.
`changed`	yes	A summary of changed fields.
`unchanged`	no	A summary of fields that had new values specified that were equal to the old values.
`new`	no	The complete new record.
`all`	no	All available information is returned (good for debugging, not suitable for production use)

The order in which you specify multiple values of retval is important. They are evaluated from left to right, however the output sections that are requested are always listed in the same order, regardless of the order in which they were requested, as follows:

errors
warnings
the complete old record
changed fields
unchanged fields
the complete new record

Here are a few examples that use URL parameters to clarify retval usage. Remember that you can also pass multiple hidden input fields:

/JspExplorer/zamples/modify: Errors, warnings and a change summary are returned.
/JspExplorer/zamples/modify?retval=none /JspExplorer/zamples/modify?retval=none&retval=errors: The two URLs are equivalent. Only errors are returned.
/JspExplorer/zamples/modify?retval=none&retval=warnings: Only errors and warnings are returned.
/JspExplorer/zamples/modify?retval=all /JspExplorer/zamples/modify?retval=changed&retval=unchanged&retval=old&retval=new: These two equivalent combinations return all returned values: errors, warnings, the complete old record, changed fields, unchanged fields and the complete new record.
/JspExplorer/zamples/modify?retval=none&retval=changed&retval=unchanged&retval=old&retval=new: The only difference between this example and the previous example is that the first instance of the retval parameter (none) resets the returned information to errors only, before the remaining retval instances are accumulated. The result is that the warning section is suppressed. The returned sections are therefore errors, complete old record, change summary and complete new record.

Return Value Organization

All return values are returned within an XML document. As previously mentioned, the order of each section is fixed, although some sections might not be present.

<?xml version="1.0"?>
<edit>
   <errors>
      <error field='example' msg='User xxxx does not have moderator privilege for knowledge base yyyy'/>
      <error field='kb' msg='User xxxx does not have write privilege for knowledge base yyyy'/>
      <error field='subject' msg='Zero-length subjects are not allowed'/>
      <error field='user' msg='User xxxx does not exist'/>
   </errors>
   <warnings>
      <warning field='user' msg='User xxxx does not have read privilege for knowledge base yyyy'/>
      <warning field='user' msg='User xxxx is disabled'/>
   </warnings>
   <old id="12254" created="1107931589000" notify="true" pre="true" priority="3" sandbox="jdk14" 
      user="makarand" topic="23" closed="false" example="true" stylesheet="false" 
      kbName="Amazon Web Services" packageName="tutorial" 
      className="default" methodName="1">
      <applet><![CDATA[]]></applet>
      <cmd><![CDATA[// program goes here]]></cmd>
      <description><![CDATA[defies logic]]></comment>
      <imports><![CDATA[import com.amazon.soap.axis.*;]]></imports>
      <purpose><![CDATA[Show 'em how it's done]]></imports>
      <ranges><![CDATA[]]></ranges>
      <subject><![CDATA[Simple Search using Java]]></subject>
      <topic><![CDATA[]]></topic>
   </old>
   <new id="12254" created="1107931589000" notify="true" pre="true" priority="3" sandbox="jdk14" 
      user="makarand" topic="23" closed="false" example="true" stylesheet="false" 
      kbName="Amazon Web Services" packageName="tutorial" 
      className="default" methodName="1">
      <applet><![CDATA[]]></applet>
      <cmd><![CDATA[// program goes here]]></cmd>
      <description><![CDATA[defies logic]]></comment>
      <imports><![CDATA[import com.amazon.soap.axis.*;]]></imports>
      <purpose><![CDATA[Show 'em how it's done]]></comment>
      <ranges><![CDATA[]]></ranges>
      <subject><![CDATA[]]></subject>
      <topic><![CDATA[]]></topic>
   </new>
   <changed>
      <field name="example" oldValue="false" newValue="true"/>
   </changed>
   <unchanged>
      <field name="pre" value="true"/>
   </unchanged>
</edit>

The DTD for the returned document is (out of date):

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT applet EMPTY>
<!ELEMENT changed (field)>
<!ELEMENT cmd (#PCDATA)>
<!ELEMENT comment (#PCDATA)>
<!ELEMENT edit (errors?,warnings?,old?,changed?,unchanged?,new?)>
<!ELEMENT error EMPTY>
<!ATTLIST error field NMTOKEN #REQUIRED msg CDATA #REQUIRED>
<!ELEMENT errors (error*)>
<!ELEMENT field EMPTY>
<!ATTLIST field name NMTOKEN #REQUIRED newValue NMTOKEN #IMPLIED oldValue NMTOKEN #IMPLIED value NMTOKEN #IMPLIED>
<!ELEMENT imports (#PCDATA)>
<!ELEMENT new (applet?,cmd?,comment?,imports?,subject?)>
<!ATTLIST new
	className NMTOKEN #IMPLIED
	closed NMTOKEN #IMPLIED
	created NMTOKEN #IMPLIED
	example NMTOKEN #IMPLIED
	id NMTOKEN #IMPLIED
	kbName CDATA #IMPLIED
	methodName NMTOKEN #IMPLIED
	notify NMTOKEN #IMPLIED
	packageName NMTOKEN #IMPLIED
	pre NMTOKEN #IMPLIED
	priority NMTOKEN #IMPLIED
	sandbox NMTOKEN #IMPLIED
	stylesheet NMTOKEN #IMPLIED
	topic NMTOKEN #IMPLIED
	user NMTOKEN #IMPLIED
>
<!ELEMENT old (applet?,cmd?,comment?,imports?,subject?)>
<!ATTLIST old
	className NMTOKEN #IMPLIED
	closed NMTOKEN #IMPLIED
	created NMTOKEN #IMPLIED
	example NMTOKEN #IMPLIED
	id NMTOKEN #IMPLIED
	kbName CDATA #IMPLIED
	methodName NMTOKEN #IMPLIED
	notify NMTOKEN #IMPLIED
	packageName NMTOKEN #IMPLIED
	pre NMTOKEN #IMPLIED
	priority NMTOKEN #IMPLIED
	sandbox NMTOKEN #IMPLIED
	stylesheet NMTOKEN #IMPLIED
	topic NMTOKEN #IMPLIED
	user NMTOKEN #IMPLIED
>
<!ELEMENT subject (#PCDATA)>
<!ELEMENT unchanged (field)>
<!ELEMENT warning EMPTY>
<!ATTLIST warning field NMTOKEN #REQUIRED msg CDATA #REQUIRED>
<!ELEMENT warnings (warning*)>

Simple Code Posting Modification

<form action='/JspExplorer/zamples/modify' method=post>
  <input type=hidden name=clientUser value='myUid'>
  <input type=hidden name=clientPassword value='myPwd'>
  <input type=hidden name=id value='1258'>
  <input type=hidden name=comment value='myComment'>
  <input type=submit value='Save' class=formInput>
</form>

Possible error codes

In addition to the common error statuses, this Zamples REST call can generate the following error statuses and messages:

`400 Bad Request - code posting id missing[, found XXXX instead].`	The code example id was not specified.
`400 Bad Request - invalid code posting id (XXXX).`	The requested code posting id must be a positive integer.
`400 Bad Request - Moderator privilege or better is required to change a posting's priority.`	Once posted, the original poster cannot raise the privilege of the posting.
`400 Bad Request - The posting creation date may not be modified with the Zamples REST interface.`	No revisionist history allowed.
`404 Not Found - code posting id XXXX not found in the knowledge base`	The requested code posting id does not exist.
`500 Unspecified failure`	An unknown error occured when saving the code posting

Saving a New Posting to a Knowledge Base

Zamples Client REST Interface Specification

Deleting a Posting From a Knowledge Base