[rt-users] AT REST interface implementation

[Philip Kime]

Skipped content of type multipart/alternative-------------- next part --------------
Design notes
------------
Custom fields in the CLI use prefix "CF_". This makes them obvious and avoids possible conflicts if people have Custom Fields named things like "Type" and "Status". This doesn't apply to the usual TicketSQL search on Custom Fields which are the usual "CF.{name}" format.

The ticket code for updates on Select* fields isn't great so I've augmented it for assets with a check for a valid value before changes are made. Otherwise, nasty things happen like - the update happens anyway and when the user next edits the CFs in the GUI, the bad values are validated and deleted automatically - nasty suprise.

The history display code for tickets allows a meaningless thing like this

rt show ticket/<tid>/history/id/<transid>

where Transaction <transid> has nothing to do with Ticket <tid>. You can effectively look at any transaction via any ticket, which makes no sense and is a potential security hole. You can't do this with assets - there is a check to make sure that the transaction(s) requested are from the asset specified

Usage
-----
Usage is pretty much what one would expect from the rt command. I've added asset stuff to the rt command help function so "rt help asset" works and several of the exampled include example for assets. Here's a summary and some more extensive examples.

Assets can be specified as

asset/<id>

just like tickets,users etc. and attributes like links and history as:

asset/<id>/history
asset/<id>/history/links
asset/<id>/history/watchers
asset/<id>/history/customfield
asset/<id>/history/id/<transaction id>
asset/<id>/links

the "-t" flag to the rt command takes "asset" as a type too.

Some examples:

# open the forms editing interface for a new asset. No custom fields will be available since the Type of the Asset isn't know at this time
rt new -t asset

# New asset non-interactively with the required fields on command line
rt new -t asset set Name=somename Type=Servers Status=production

# edit an asset interactively
rt edit asset/<id>

# edit an asset non-interactively, changing a CF
rt edit asset/<id> set CF_name="some value"

# edit an asset non-interactively, adding a CF value to a multi-valued CF
rt edit asset/<id> add CF_name="some value"

# edit an asset non-interactively, deletin a CF value 
rt edit asset/<id> del CF_name="some value"

# show an asset in full or in part
rt show asset/<id>
rt show asset/<id>/watchers
rt show asset/<id>/customfields
rt show asset/<id>/history

# show only certain fields
rt show asset/<id> -f Name,Type,CF_CFname

# show details of a specific transaction
rt show asset/<id>/history/id/<transaction id>

# show an asset's links
rt show asset/<id>/links

# add/remove links to/from an asset (all asset link types supported including custom types)
rt link -t asset <id1> ComponentOf <id2>
rt link -t asset <id1> DependsOn <id2> 
rt link -d -t asset <id1> DependsOn <id2> 

# search for assets with TicketSQL
rt list -t asset 'CF.{CFname} LIKE "%"' (returns just IDs)
rt list -t asset -l 'CF.{CFname} LIKE "%"' (returns all fields)