Home > Blog > How to Create a Custom Workflow Initiation Form

In this DIY Post, learn how to display dynamic information on a SharePoint workflow initiation form with SharePoint Lists, rather than InfoPath.

Environments: SharePoint 2013 and SharePoint O365

Scenario: You need to display dynamic information on a SharePoint workflow initiation form.

Solution: Utilize an OOTB SharePoint list to be used as your workflow initiation form instead of using the InfoPath option to customize the OOTB designer workflow form.

Description: I’ve ran into situations where the requirements dictated that dynamic information be displayed in SharePoint (not via email) when a workflow is being initiated. This post will describe how to use a “supporting” custom SharePoint list to display the initiation form information and trigger the workflow against the “target” list. This solution only uses client-side technologies: jQuery and SharePoint’s CSOM.

Step 1 – Create your SharePoint List That Requires a Workflow

Create a new SharePoint list that will ultimately have the workflow ran against. Here is the example list that I am using for this post:

List name = “RandomApproval”

I created a single item in this list:

Step 2 – Create your SharePoint Initiation Form List

Create a new SharePoint list to be used as your workflow initiation form. For this example I’m going to add a couple of additional columns to the list:

List name = “StartWFInitiationForm”

·Approvers (multiple people column) *required

·Due Date (Date only) *required

·Comments

·TargetItemID (number, 0 decimals) – this will store the List Item ID we will be targeting

A benefit to using a SharePoint list as our initiation form is that SharePoint does all the work for you when it comes to the OOTB functionality such as required fields, people picker, etc… It also provides an easy way to track additional/custom information pertaining to the initiation should you want to include that level of auditing.

Step 3 – Modify the Default New Form on the StartWFInitiationForm List

Go to the List tab on the new list and edit the “Default New Form” and then edit the page.

This will bring you to your traditional web part page view of the default new form. Now you add a script editor web part to the top of the form.

n the script editor you can load jQuery, if not already being loaded on your site, and then all the work will happen in the next 2 lines.

  1. CustomInitiation.js – a custom JavaScript file that will load all the information we want to display on the form; we’ll create this file in the next step
  2. HTML div “CustomDisplayDiv” will be the placeholder to insert the custom information we want to display

Step 4 – Code the CustomInitiation.js file

Here is where the “heavy lifting” starts. In this example I am just pulling back information from the target list item to be displayed on the custom initiation form. This script:

1) Retrieves the target item ID we want to start the workflow on from the URL QueryString

2) Uses CSOM to populate the initiation form with custom information

//Create your JavaScript Namespace

var INCWORX = INCWORX || {}

INCWORX.SP = INCWORX.SP || {}

INCWORX.SP.WFInitiation = {

itemID: null,

targetItem: null,

init: function() {

// Hide columns that the user does not need to see

$ (“[id^=’Title’]”).closest(‘tr’).hide();

$ (“[id^=’TargetItemID’]”).closest(‘tr’).hide();

 

// Change the “Save” button to say “Start Workflow”

$ (“[id$=’SaveItem’]”).prop(‘value’, ‘Start Workflow’);

 

// Retrieve the List Item ID from the query string that this workflow will be targeting

INCWORX.SP.WFInitiation.itemID = $.getUrlVar(‘itemid’);

 

if(!INCWORX.SP.WFInitiation.itemID)

{

// Add some custom message incase the target item ID was not found in the QueryString

$ (“#CustomDisplayDiv”).html(“ERROR: The item ID was not located.”);

$ (“[id$=’SaveItem’]”).hide(); // Hide the Save button so the form cannot be submitted}

 

// Set the target item ID in the custom column we created so we have access to it after the form is saved

$ (“[id^=’TargetItemID’]”).val(INCWORX.SP.WFInitiation.itemID);

$ (“[id^=’Title’]”).val(“Custom Initation for ” + INCWORX.SP.WFInitiation.itemID);


// Build your client context

var clientContext = new SP.ClientContext();

var web = clientContext.get_web();

 

// Retrieve the list of the target item

var list = web.get_lists().getByTitle(“RandomApproval”);

// Retrieve the target item with the columns we will display on the initiation form

INCWORX.SP.WFInitiation.targetItem = list.getItemById(INCWORX.SP.WFInitiation.itemID, “Include(Title,ApprovalType,DateRequested,Reason,Author)”);

 

clientContext.load(INCWORX.SP.WFInitiation.targetItem);

clientContext.executeQueryAsync(Function.createDelegate(this, INCWORX.SP.WFInitiation.onQuerySucceeded), Function.createDelegate(this, INCWORX.SP.WFInitiation.onQueryFailed));

},

onQuerySucceeded: function() {

 

var displayDiv = $ (“#CustomDisplayDiv”);

 

// Retrieve the columns to be displayed on the initiation form

var itemTitle = INCWORX.SP.WFInitiation.targetItem.get_item(“Title”);

var itemApprovalType = INCWORX.SP.WFInitiation.targetItem.get_item(“ApprovalType”);

var itemDate = new Date(INCWORX.SP.WFInitiation.targetItem.get_item(“DateRequested”));

var itemReason = INCWORX.SP.WFInitiation.targetItem.get_item(“Reason”);

var itemAuthor = INCWORX.SP.WFInitiation.targetItem.get_item(“Author”).get_lookupValue();

 

displayDiv.append(“<h2>” + itemTitle + “</h2>”);

displayDiv.append(“<strong>Requestor: </strong>” + itemAuthor);

displayDiv.append(“<br >”);

displayDiv.append(“<strong>Approval Type: </strong>” + itemApprovalType);

displayDiv.append(“<br >”);

// Format the date, remember that getMonth is 0 based

displayDiv.append(“<strong>Date Requested: </strong>” + (itemDate.getMonth()+1) + “/” + itemDate.getDate() + “/” + itemDate.getFullYear());

displayDiv.append(“<br >”);

displayDiv.append(“<strong>Reason: </strong>” + itemReason);

 

},

onQueryFailed: function(sender, args) {

$ (“#CustomDisplayDiv”).html(“ERROR: ” + args.get_message());

}

}


jQuery (document).ready(function ()

{

// Function to retrieve QueryString parameters from the URL

$.extend({

getUrlVars: function(){

var vars = [], hash;

var hashes = window.location.href.slice(window.location.href.indexOf(‘?’) + 1).split(‘&’);

for(var i = 0; i < hashes.length; i++)

{

hash = hashes[i].split(‘=’);

vars.push(hash[0]);

vars[hash[0]] = hash[1];

}

return vars;

},

getUrlVar: function(name){

return $.getUrlVars()[name];

}

});

 

// Make sure the custom JavaScript is loaded after the SharePoint client object model is loaded

SP.SOD.executeFunc(‘sp.js’,’SP.ClientContext’,INCWORX.SP.WFInitiation.init);

 });

The resulting display of the New Item form on the custom Initiation list should look like the following.:

Step 5 – Initiation Form 2013 Designer Workflow

Create a SharePoint 2013 Designer workflow on your initiation list. We need to use a 2013 workflow so we can trigger a 2010 workflow on the target list. In this workflow you can access the information the user entered on the Initiation form to start the workflow on the target list (the “RandomApproval” list). You can pass in the values from the initiation form as parameters to the 2010 workflow.

Step 6 – Add a Custom View Ribbon Action

Using SharePoint Designer, add a custom view ribbon action to the target list (RandomApproval) so users can launch the initiation form from the SharePoint list.

The Navigate to URL field contains: /sites/<your site>/Lists/StartWFInitationForm/NewForm.aspx? itemid={SelectedItemId} . Pass the “itemid” QueryString parameter as the SelectedItemId property to the NewForm.aspx page. That way it can be retrieved from our custom initiation form on load.

Conclusion

While not every workflow initiation form needs to be this complicated, it is a great tool to have in your pocket knowing you can create a custom workflow initiation form without the need for InfoPath, SharePoint App or deployed code. It will come in handy when users want to display dynamic information on the form. So at the end of this blog post, this is what we have accomplished:

1)Created a list that we want to run a workflow against

2)Created a “supporting” list that we use for our workflow initiation form

3)Added custom JavaScript to the initiation form NewForm.aspx to populate custom information we want to display to the user starting the workflow

4)Added a SharePoint Designer 2013 workflow on the initiation form list that runs when an item is created which then triggers the actual workflow that resides in the target list

5)Added a custom View Ribbon action to the target list so users can easily go to the custom workflow initiation form

There are also countless other value-add features that can be accomplished with our custom workflow initiation form just using client side scripting, some examples:

·Dynamic required fields –research the “PreSaveAction” function for SharePoint forms

·Pre-populate fields on form load

·Populate fields based on what the user selects on the form

·Validate that the workflow can be started

– Verify a document is not checked out

– Verify that the item is at the appropriate “state” to be started (the previous workflow was completed/approved)

0 Comments

[wpforms id="1422"]
<div class="wpforms-container wpforms-container-full" id="wpforms-1422"><form id="wpforms-form-1422" class="wpforms-validate wpforms-form" data-formid="1422" method="post" enctype="multipart/form-data" action="/blog/sharepoint-diy-create-a-custom-workflow-initiation-form" data-token="5004881076b4dd02782711e0acad13b3"><noscript class="wpforms-error-noscript">Please enable JavaScript in your browser to complete this form.</noscript><div class="wpforms-field-container"><div id="wpforms-1422-field_0-container" class="wpforms-field wpforms-field-name" data-field-id="0"><label class="wpforms-field-label" for="wpforms-1422-field_0">Name <span class="wpforms-required-label">*</span></label><input type="text" id="wpforms-1422-field_0" class="wpforms-field-large wpforms-field-required" name="wpforms[fields][0]" required></div><div id="wpforms-1422-field_1-container" class="wpforms-field wpforms-field-email" data-field-id="1"><label class="wpforms-field-label" for="wpforms-1422-field_1">Email <span class="wpforms-required-label">*</span></label><input type="email" id="wpforms-1422-field_1" class="wpforms-field-large wpforms-field-required" name="wpforms[fields][1]" required></div><div id="wpforms-1422-field_3-container" class="wpforms-field wpforms-field-phone" data-field-id="3"><label class="wpforms-field-label" for="wpforms-1422-field_3">Phone <span class="wpforms-required-label">*</span></label><input type="tel" id="wpforms-1422-field_3" class="wpforms-field-large wpforms-field-required wpforms-masked-input" data-inputmask="&#039;mask&#039;: &#039;(999) 999-9999&#039;" data-rule-us-phone-field="true" name="wpforms[fields][3]" required></div><div id="wpforms-1422-field_2-container" class="wpforms-field wpforms-field-textarea" data-field-id="2"><label class="wpforms-field-label" for="wpforms-1422-field_2">How can we help you? <span class="wpforms-required-label">*</span></label><textarea id="wpforms-1422-field_2" class="wpforms-field-small wpforms-field-required" name="wpforms[fields][2]" required></textarea></div><div id="wpforms-1422-field_15-container" class="wpforms-field wpforms-field-html" data-field-id="15"><div id="wpforms-1422-field_15"><p style="padding-top: 10px; padding-bottom: 10px; font-family: 'Open Sans', sans-serif; font-size: 10px; color: #333333;">By clicking the button below, you are agreeing to our <span style="text-decoration: underline;"><span style="color: #000000;"><a style="color: #000000; text-decoration: underline;" href="https://www.incworx.com/privacy-policy">Privacy Policy</a></span></span>.</p></div></div><div id="wpforms-1422-field_7-container" class="wpforms-field wpforms-field-hidden" data-field-id="7"><input type="hidden" id="wpforms-1422-field_7" name="wpforms[fields][7]" value="How to Create a Custom Workflow Initiation Form"></div><div id="wpforms-1422-field_9-container" class="wpforms-field wpforms-field-hidden" data-field-id="9"><input type="hidden" id="wpforms-1422-field_9" name="wpforms[fields][9]" value="75.101.220.230"></div><div id="wpforms-1422-field_10-container" class="wpforms-field wpforms-field-hidden" data-field-id="10"><input type="hidden" id="wpforms-1422-field_10" name="wpforms[fields][10]"></div></div><div class="wpforms-field wpforms-field-hp"><label for="wpforms-1422-field-hp" class="wpforms-field-label">Phone</label><input type="text" name="wpforms[hp]" id="wpforms-1422-field-hp" class="wpforms-field-medium"></div><div class="wpforms-submit-container" ><input type="hidden" name="wpforms[id]" value="1422"><input type="hidden" name="wpforms[author]" value="2"><input type="hidden" name="wpforms[post_id]" value="583"><button type="submit" name="wpforms[submit]" class="wpforms-submit " id="wpforms-submit-1422" value="wpforms-submit" aria-live="assertive" data-alt-text="Sending..." data-submit-text="Submit">Submit</button></div></form></div> <!-- .wpforms-container -->