4 Clicks or 1? Using jQuery to Start a SharePoint Workflow.
The IT Urgent Change process needs to be automated. It’s relatively simple and after gathering the requirements its clear that this can be accomplished using SharePoint and a SharePoint Designer workflow. The workflow is created and published to the list. The decision is made that the workflow will be started manually as opposed to automatically when the Change Request is created. Everyone in IT has contribute access to the list and there are no security requirements related to who can or can’t start a workflow.
This means a user must take the following steps to initiate the workflow:
1. Click the context menu and click the Workflows menu item
2. Select the Change Process Workflow.
That’s a few more clicks than should be required so I wanted to find a way to make starting a workflow a one-click affair. I knew this should be relatively simple with jQuery and the Dataview Web Part so I’d like to detail how I accomplished this so others can hopefully benefit from it.
The end result looks like this:
When the user clicks the Start Workflow link they see a nice Ajax loading image as seen below:
When the workflow has been initiated they are presented with a confirmation message telling them the process is underway:
On to the solution! First I need to give a shout out to Marc Anderson , the creator of the jQuery Library for SharePoint Web Services which can be found here: http://spservices.codeplex.com/. This is such a handy tool for interacting with the SharePoint web services from the client and this was my first opportunity to use it. I simply downloaded the JS files and put them in my SharePoint Scripting Resource Centre site collection as first conceived by Mark Miller at EndUserSharePoint.com. The original post can be found here: http://www.endusersharepoint.com/2010/01/05/build-a-sharepoint-scripting-resource-center/
Once that was done I need to do a few things. I created a Web Part Page and opened SharePoint Designer. I then added the Change Request list to one of the web part zones. In order to get the customizations that wanted needed to create a DataView out of it so I simply right clicked on the list and converted it to a XSLT Dataview. That’s all I really need to do here so I saved the page and opened it up in the browser. What you can do with a dataview is almost limitless. The best way to tackle customizations is to make all the changes you can using the SPD interface. Once you have reached the limits of what you can do there you can start customizing the XSL. Refer to the following series by Marc to learn everything you need to know about XSL and the DVWP. http://www.endusersharepoint.com/2010/01/19/unlocking-the-mysteries-of-data-view-web-part-xsl-tags-part-1-overview/
When you modify a dataview in the browser you have a different set of options then when you work with a regular list. The important thing we want to do here is modify the XSL in order to achieve the look and functionality we want.
In the interests of saving my sanity I copied the XSL and pasted it into SharePoint Designer (just a new XML document) so I could at least have the benefit of some colour in my life. I added the following snippet which I’ll explain as I go.
<xsl:if test=”not(normalize-space(@ChangePr) = ’5′ or normalize-space(@ChangePr) = ’2′)”>
<div>
<xsl:attribute name=”id”>
<xsl:text>WorkflowDiv</xsl:text>
<xsl:value-of select=”@ID” disable-output-escaping=”yes”/>
</xsl:attribute>
<a href=”#”>
<xsl:attribute name=”onclick”>
<xsl:text>javascript:StartWorkflow(‘</xsl:text>
<xsl:value-of select=”@EncodedAbsUrl” disable-output-escaping=”yes”/>
<xsl:text>’,'</xsl:text>
<xsl:value-of select=”@ID” disable-output-escaping=”yes”/>
<xsl:text>’);</xsl:text>
</xsl:attribute>
Start Workflow</a>
<img style=”visibility:hidden” src=”http://employeeportal/sites/sprc/PublishingImages/ajax-loader.gif”>
<xsl:attribute name=”id”>
<xsl:text>Loader</xsl:text>
<xsl:value-of select=”@ID” disable-output-escaping=”yes”/>
</xsl:attribute>
</img></div>
</xsl:if>
The result I want to achieve with this is another column in the dataview with the “Start Workflow” link that will call a Javascript function and passes in a few parameters and uses the jQuery Library for SP Web Services to kick off the workflow.
The following section says that we’re only going to render the link when the workflow is not complete or cancelled. When you covert a list view to a dataview your workflow column which normally reads “In Progress’, “Completed” etc. switches to the numerical value. Why? I haven’t a clue. But the easiest way is to use SPD to create some conditional formatting and then just copy the XSL that is generated.
<xsl:if test=”not(normalize-space(@ChangePr) = ’5′ or normalize-space(@ChangePr) = ’2′)”>
You can see that the 2 values we pass to our StartWorkflow function are the EncodedAbsUrl and the ID of the list item in question. The EncodedAbsUrl for a list item looks like this: http://servername/sites/its/Lists/Change%20Request/107_.000. We also output a hidden image with our nice loading image downloaded from http://www.ajaxload.info that will appear beside each item while the workflow is initiating.
Also note that our loading image and the div that wraps everything have an id property that concatenates on the list item id to it that we’ll use in our client side script.
On to the jQuery. We need to add a Content Editor Web Part to our page and place the following script inside:
Our jQuery and jQuery Web Services references
<script type=”text/javascript” src=”/sites//sprc/Resources%20%20jQuery/jquery-1.3.2.min.js”></script>
<script type=”text/javascript” src=” /sites/sprc/Resources%20%20jQuery/jQuery%20SP%20Services/jquery.SPServices-0.5.4.min.js”></script>
<script type=”text/javascript”>
function StartWorkflow(ItemURL, ItemID)
{
var loadingImage = ‘Loader’ + ItemID
var workflowDiv = ‘WorkflowDiv’ + ItemID
//Show our loading image
document.getElementById(loadingImage).style.visibility = ‘visible’;
$().SPServices({
operation: “StartWorkflow”,
item: ItemURL,
templateId: “{04ee1c93-f6b7-49b3-a79c-fa3142ecd688}”,
workflowParameters: “<root />”,
completefunc: function() {
document.getElementById(workflowDiv).innerHTML = ‘Workflow Started’;
}
});
}
</script>
As you can see there is very little scripting required here. We take the URL of the list item and the item id. We then show the loading image and make the web service call through Marc’s library:
There are 4 parameters.
- The operation is “Start Workflow”
- The URL is the value of the EncodedAbsUrl for the list item mentioned earlier.
The template id is the guid of the workflow template that we created in SharePoint Designer. You can find this out by following the first 2 steps at the very beginning of this article and then copying the URL from your browser. It will look something like this: http://servername/sites/its/Workflows/Change%20Process/Change%20Proce.aspx?List=d0fa2d98-6086-4c97-be85-4746c801e7f3&ID=89&TemplateID={04ee1c93-f6b7-49b3-a79c-fa3142ecd688}&Source=http%3A%2F%2Femployeeportal%2Fsites%2Fits%2FLists%2FChange%2520Request%2FAllItems%2Easpx. You can see that there is a TemplateID value in the query string and that’s what we want
- Our workflow doesn’t have an initiation screen so we simply pass it an XML node. You have to do this or the workflow will throw an exception. This took some digging to find out why the workflow wouldn’t start.
- completefunc – what we want to happen when we’re done. In this case we just want to get rid of the image and let the user know the workflow started. Remember that AJAX is asynchronous so if you try to take post-initiation actions with code inline it will actually run prior to the workflow having been started. If you want something to happen after the call to the SPServices library is done, put it in the completefunc.
There is no error handling in this solution yet but if you go to Marc’s Codeplex site you can see methods on how you can have error information returned and then trap them. It’s pretty straightforward.
That is how I used, jQuery, the jQuery Library for SharePoint Web Services and the DataView Web Part to allow a workflow to be started with one click.
Popularity: 61% [?]
It is incredibly easy to configure and it renders really slick looking charts. 
