SharePoint 2013: Batch Exception Handling

Batch exception handling in JSOM is a new concept in SharePoint 2013, that enables us to execute Try Catch and Finally code blocks in the same way as we do in Server side code; i.e., executing within the same Server call.

For instance, while working with Server side code, if we need to create a new list, then we need to first check its existence and if the list does not exist, only then will code create it.

A point to remember here is this whole logic will be executed in the same Server call.

On the other hand, if we try to perform the same action while working with JavaScript Client Object Model (JSOM), we need to issue two separate calls to the Server -- one is to check for the existence and other is to load or create the list.

Using new batch exception handling, construct “startScope, startTry, startCatch, and startFinally,” and we can achieve this in a single JSOM call to the Server.

In this article, we will see the implementation details for the batch exception handling, using SharePoint Hosted App.

  • Create a new project using “App for SharePoint 2013” Project Template,


  • Specify the Host Web URL.
  • Specify “SharePoint Hosted” as Hosting Model.

    SharePoint Hosted

  • Wait while Visual Studio configures the project for you, as shown below:


  • Prepare UI, using HTML elements decorated with the desired CSS usingDefault.aspx (App Start Page)

Step 1: Specify the page title.

Step 2: Add HTML to present the UI elements for “Result Panel” and decorate the element with the required CSS of your choice.

Step 3: Adding a container to hold the button to execute the batch exception handling process.

Step 4: Add an HTML button, specify its Label and decorate it with the required CSS,

 HTML Button

  • Write code to implement the logic for the batch exception handling by modifyingApp.js JavaScript File.

Step 5: Bind the event handler with the button, using dynamic binding in the “document. Ready” function,


Inside the event handler is the function “batchExceptionHandling.”

Step 6: Instantiate SharePoint context and get the instance of the current Web (all old-school things).

Step 7: Instantiate the exception Handling Scope.

Step 8: Start a Scope block by calling startScope() method.

Step 9: Start a Try block by calling startTry() method.

Step 10: Inside the Try Block, try to load the instance of the list in our case list is “My-Custom-List”.

Step 11: Dispose the Try Block by calling dispose() method.

Step 12: Start the Catch Block by calling startCatch() method.


This catch block will be executed only when the action in Try block fails, like in this case, if we try to load “My-Custom-List” and it is not available in the SharePoint Site the operation will fail and catch block will get executed.

Step 13: Since we get an exception while loading the list that means list is not available, so add the new list with the same name

Step 14: Dispose the Catch Block by calling dispose() method.

Step 15: Start the Finally Block by calling startFinally() method.

Step 16: Load the list now, since by this time we will have list available anyway (Created if it doesn't exist or loaded if it exists).

Step 17: Dispose the Finally Block by calling dispose() method.

Step 18: Dispose Scope Block by calling dispose() method,


Step 19: In the success callback function, check for the exception that  occurred during the function call by calling “get_hasException()” method. If the method returns True, that means we had created the list, otherwise we already had a list that we loaded.


With this step, we are all done with the coding part and now the next step is to launch the app and see some action.

  • Build and deploy the solution


  • Enter the credentials, when asked for authentication,


After successfully authenticating the user, we can see the Start Page for the app.

Start Page

Open the SharePoint Manager and browse the App Web -> Lists and see, if we got the list “My-Custom-List” created or not, in our case we do not have any such list created.


Now click the button, “Batch Exception Handling” and see the result panel.

The first time when we click the button, JSOM code executes within the Exception Handling Scope, and see if the list is already available in the site or not, if not it will be added by the code present in catch block as shown below:

catch block

We can confirm the same in SharePoint Manager as well.


When we click the button afterwards the code in Try Block gets executed and successfully loads the list due to which the Success Callback function “get_hasException()” function returns False and we get an alternative message in the Result Block as shown below:

Result Block

I found this technique really effective,when we have a scenario for implementing Fall Back mechanisms without involving multiple Server calls for the same request.

I hope this simple implementation helped you to understand the concept of batch exception handling.