PowerShell for Sitecore Item Web API

My colleague Adam Simmonds did a demo of the Sitecore Item Web API at work based on the code provided by Kern Herskind from a recent Sitecore User Group.  It was great to see a small, simple, yet powerful API available to mobile solutions and third-party services that could operate in a RESTful way.

The ability to drop into a solution with very minor configuration changes makes the API incredibly simple to apply to existing solutions (if the Sitecore version is supported of course).  It also follows Sitecore's principle design of pipelines and security; making it really easy to extend with custom functionality or handlers while also restricting requests at a user level using the security domain set for the website.  This means full control of security restrictions can be applied using the standard Sitecore security model and interface.

In short, it’s pretty damn awesome.

Now with added PowerShell

On Tuesday evening I knocked up a quick module to send requests to a site running the API.  Yesterday I cleaned it up, improved documentation, and packaged with a proper manifest.

I’m not entirely happy with the state of the code but it is now much more usable and in a better state to extend and (hopefully) be useful to others.  I'm still learning PowerShell and need to work out a coding style and development process that works for me.

Usage

The module implements a small handful of commands:

• Add-SitecoreItem – Creates a new Sitecore item, optionally setting fields
• Get-SitecoreItem – Gets one or more Sitecore items which match the context of the given parameters
• Remove-SitecoreItem – Deletes one or more Sitecore items based on the context
• Set-SitecoreItem – Updates the fields of one or more Sitecore items

There is an additional Invoke-SitecoreRequest method which is a special “bare bones” function  to allow extended control of the parameters passed to Sitecore.  All other functions act as wrappers to this function, providing validation and parameter restrictions where possible.

Aside from making it simple to perform CRUD actions with Sitecore  (think bulk uploads, change properties, quick reports etc) I hope to use this to perform some level of integration testing.

I'm currently spending a lot of time investigating (and improving!) build processes.  With the aim of making the transition of code from Dev -> Stage -> Live as seamless and robust as possible.  Increasing the robustness involves validating that packages and items have been deployed properly.  This looks like it may be a useful tool to perform validation of fields that have been updated.

Download and Install

All the information you need is available at the Github repo.

If you don't have the Sitecore Item Web API installed already you can download the API and documentation from Sitecore (You'll need an SDN login).

Examples

For demo purposes the account used here is an admin.  To restrict access, use Sitecore roles and the configuration options in the Sitecore Item Web API config include.

Getting an item

Adding an item

Setting an item

Removing an item

Further Work

1. Tests - seriously, if I want to use this for testing and building I’m going to need a decent test suite to know things are working as expected.  This will also give me a chance to get to grips with Pester.
2. Additional functions – RSA encryption and the ability to upload media are next on the list
3. Pipelining – PowerShell functions are even more useful when you chain them together.  It would be great to run something like: Import-Csv input.csv | Add-SitecoreItem mydomain –user username –pass password | select –expand Items | select DisplayName,ID,Path,Version | Export-Csv output.csv (which would read a csv, create new items based on each row then output the new item details to another csv
4. Code structure – I don’t like everything being one big file.  I’d like to break things into smaller chunks and related modules. 
5. Session based access – It’s a bit tedious adding the domain, username and password to every request.  While requests are stateless a PowerShell session needn't be.  Something like: Start-SitecoreSession domain username password -encrypt –params @{ path = “/sitecore/content/home” } could set session level variables that can be used by methods.  This is extended to cater for parameters which could apply to every call (while overriding at a function level) and also be a good place to perform encryption duties.
6. Aliases - For parameters as well as functions.  The breadth of parameters available to the functions make it tedious to type long form when you just want to type in the command line.
7. Response formatting - I've done a small amount of work to normalise the formatting of the different responses the API provides.  However the response format of the Fields property is a little awkward.  It would be better if this was an array of fields rather then a hash with guid based keys.

Hopefully this little module will be of use to others.  If you've taken a look and have any suggestions or improvements (or bugs!) let me know ;-)