XOG is the XML based webservice offered by CA Clarity which provides you functionality to send XML to retrieve or update data in Clarity. You will get the result as another XML. XMLSpear is my full featured XML editor that is on the market now for more than 5 years. I thougt it would be more convenient to edit and xog files in XMLSpear all together. That's why I built the Clarity XOG plugin. The XOG plugin for XMLSpear offers you an integrated environment where you can develop, validate and test your XOG files and manage your XOG connections to different environments.

You will need java 1.5+ to run XMLSpear with XOG plugin. So you can pick up your favorite platform : Linux, Mac OS X or Windows.

Configure your XOG connections

To use this plugin you first have to install it. This is described in the install.txt file in the download package. One of the steps described there, is to create a configuration file for each target environment. Several example configuartions are incuded in the package.
For people familiar to the clarity command-line xog client: these files are the equivalent to the propertyfile, but the fomat is XML. It maybe convenient to load a file tree (File --> Add File Tree) with the configurations directory as the root of the tree: now you can easily view and edit the files by clicking them in the tree. You can check your changes by validating the xml against the schema. Press the green "check icon" in the toolbar to turn on real-time validation. Load the changes in the tool by reloading the configuration (Clarity --> Reload config).

Important note: If you are using the default port then leave the port element empty.

Create or edit XOG file

Again it maybe convenient to load a file tree with your xml and xsd directories. If you have installed the CA Clarity XOG client, then you may use that install directory as a file root. Now open a XOG input file. You can edit the file in the XML handler.
To see which attributes or elements can be inserted, right-click the xsd schema file in the file tree and choose "show schema in tree" from the popup menu (choose NikuDatabus in the subsequent popup which prompt you for the root element).
To create a XOG file from scratch, the you can also right-click the xsd schema file in the file tree and choose "generate XML" from the popup menu (choose NikuDatabus in the subsequent popup which prompt you for the root element).

Example of Object xml:

<NikuDataBus>
	<Header version="12.0.0.5028" action="read" objectType="user" externalSource="NIKU"/>
	<Query>
		<Filter name="userName" criteria="EQUALS">XXXXX</Filter>
	</Query>
</NikuDataBus>

<Query xmlns="http://www.niku.com/xog/Query">
	<Code>P027_NSQL</Code>
</Query>

<FlushAllCaches xmlns="http://www.niku.com/xog/InvokeAction">
</FlushAllCaches>

Check your file

To check the XOG file for errors, click the green validation button on the toolbar. This will turn on real-time validation. If there are errors, they will be displayed in the "Problems" window. You can click on the errors to jump to the location of the error in the source.

note:
The XOG xsd schemas all have a syntax error which will be displayed the first time you turn on validation: [5:43]: cos-nonambig: column and column (or elements from their substitution group) violate "Unique Particle Attribution". During validation against this schema, ambiguity would be created for those two particles.
This error can be ignored.

Execute the XOG

To make the actual xog request, choose Clarity -->doXOG from the menu. You have several input and output options and you can choose the target environment from a list. You can configure a proxy server for XOG webservices that are behind a proxy.

notes :
The first time you XOG to a new SSL Server, you may be kept asking to accept the certificate. You have to restart XMLSpear to get the certificate properly loaded. You can also edit the plugin.properties file in the configuration directory. It contains a property to trust all certificates.
There is also another property to keep characters entities (unicode notations) in the XOG response.

Check result

Check the result. Sometimes, if the result contains html messages in the content, it is most convenient to view the results in the XML table view. The console tab will show the logging of the process, which may be important in case of unexpected errors.

Initially the XOG plugin was created to xog instance data of an Object. In version 2.3 support was added for the Query and InvokeAction api. The plugin is not dependant of a specific clarity version. Only a few xog operations are tested. Please report bug or issues.
Any sugestions are welcome!

XMLSpear with Clarity XOG plugin 2.30 installed (release date 2011-09-19).

Documentation how to use the CSV to XOG plugin (release date 2011-07-14).

The plugin is also available as separate download. You will find instructions how to install the plugin into XMLSpear.

• This release is a further enhancement of fix 2.22. But now support is added for Query and InvokeAction requests. For these requests you do not code a NikuDatabus element

• Some xog results do not contain a XOGOutput element. An example is the contentpack read xog. The program will no longer throw an exception in this cases. Thanks to Steve for reporting this issue.

• added function to convert CSV to XOG
• Feature to XOG multiple input files
• XOG timeout setting changed to unlimited

• Proxy support enabled
• Added a schema file for the configuration XML so you can validate your configuration while editing them in XMLSpear
• Use the given userid and password for subsequent XOG calls
• a property can be configured to show non ascii characters as unicode numbers in the XOG response message ==> showUnicodeCharacters=true
• a property can be configured to trust all certificates ==> trustAllCertificates=true
• Improved handling of new certificates

(your e-mail program will be started)