SHAREPOINT ONLINE/OFFICE 365: HOW TO DEVELOP APPROVAL WORKFLOWS ON LIST ITEM UPDATE EVENT USING MICROSOFT FLOWS

In this article we will see how to deal with SharePoint Online List Item update event.

For the demo in this article I will consider a business scenario where on update of any Product in the Product list, an approval process will execute and an email is send to approver for the selection of Price Range for the Product just updated.

To start with a demo I have a Product List in SharePoint Online Site as shown below-

2

Go to “Flow” Menu and Click on “Create a Flow”

3

Here we have two choices either we can use any available workflow template that suites our requirements or we can create a new one from scratch

4

For this demo we will create a Flow using blank template

Go to Flow Site by clicking “See you flow” links

5

Click on “Create from blank” this will launch Workflow Designer

6

On the Workflow Designer, Select the Trigger

We can select trigger from the any of the available services as shown highlighted below-

7

Select SharePoint Online as target service & select for the Trigger “SharePoint-When an existing item is modified”

8

Provide the Title to the Workflow “Product Details Modification Approval Request”

9

Create SharePoint context by providing Site URL and List Name as shown-

10

You can optionally rename the Step by selecting “Rename” option as shown below-

11

Here I have changed the name of Step to “Get SharePoint Context”

12

Add another action to the workflow by clicking “Add an action” option

13

Send email by selecting “Office 365 Outlook” Service and “Office 365 Outlook-Send approval email” action

14

Rename the name of Step to “Request Approval”

15

Choose or approver’s email in “To”, here I am just selecting the email of the person who has originally created the Product in list by choosing “Created By Email” field

Specify Subject as applicable

Specify User Options that allows approver to select the approval options from within the mail

Specify the Body content as required. This content can consist of dynamic tokens provided by Workflow runtime as shown below-

16

Update List Item by selecting “SharePoint Online” Service and “SharePoint-Update item” action

17

Rename the step to “Update item”

Specify Site URL & List Name

In Id field select “ID” token provided by workflow runtime. This token represents the List item Id of the item that triggered this workflow to execute.

It is important to note that values to all mandatory fields in the list must be provided. If you don’t want to change the values you can choose same values again.

18

For Title field we have selected “Title” token that represent current value present in list for the Title field of this item

19

In “Product Price Range” field choose “SelectedOption” token that will hold the value selected by the approver from within the mail

20

Once all the Steps are configure as required we can save the workflow by clicking “Save flow”

21

Click “Done” to return back to the workflow dashboard

22

On the workflow dashboard we can see the details of services used with in this workflow

23

Now modify and the Product in Product List and notice the “Product Price Range” field which is currently set to “Low”

24

Once the Product details has been changed, this will trigger the workflow that we have developed

25

On execution the workflow we can see a new email hitting the inbox of the approver

26

Let’s consider the approver submitted “High” as approval option

27

This action will update the “Product Price Range” field for the list item to “High” as shown below-

28

Hope you find it helpful.

SharePoint Online/Office 365: How To Develop Approval Workflows On List Item Add Event Using Microsoft Flows

Microsoft introduces Flows that enables development of Workflows for SharePoint Online and other more than 50 services over the cloud.

In this article we will see the demonstration of Microsoft Flow around SharePoint Online and will deal with List Item Add Event.

For this demo let’s consider we have a Product Catalog List which required Approval to happen with each new item added.

We have a Product List as shown below-

2

Go to “Flow” Menu and Click on “Create a Flow”

3

Here we have two choices either we can use any available workflow template that suites our requirements or we can create a new one from scratch

4

For this demo we will create a Flow using blank template

Go to Flow Site by clicking “See you flow” links

5

Click on “Create from blank” this will launch Workflow Designer

6

On the Workflow Designer, Select the Trigger

We can select trigger from the any of the available services as shown highlighted below-

7

Provide the title of the Workflow

Select SharePoint Trigger “SharePoint-When a new item is created” that will fire when a new item is added to SharePoint Online List

8

Provide Site Url and List name to setup SharePoint context

Add an action to the Workflow by clicking “Add an action”

9

Select approval action by selecting “Outlook.com – Send approval email”

10

Select “Approver Email” in “To”, since this “Approver” is a People Field on SharePoint,

Workflow designer is intelligent enough to represent each property as a separate field

11

Add a condition to the workflow by clicking “Add a condition”

12

In the condition we are check if Approver Approved the Production or not.

If Approved then send approval email to requestor else delete the Product and send Email to requestor

13

Choose “Created By Email” field in “To” as it will hold the Email Id of the Requestor (Person added the Product)

Choose “Approver Email” field in “CC” to send a copy of the mail to Approver also

14

If not approved, delete the Product by choosing action “SharePoint – Delete item”

15

 

In the “Delete item” action specify SharePoint Site Url and List Name

Select “ID” token for the field “Id”. This token will hold the ID of the List Item that trigged the Workflow

16

After deleting the item we, send email to Requestor by choosing “Created By Email” in “To” field
Specify the body of email as desired
Choose “Approver Email” field in “CC” to send a copy of the mail to Approver also

17

Once all the actions are configured as required save the workflow by clicking “Save flow”

18

With this we are all done and now it is time to test the workflow

To test the Workflow, add a new item in the Product List. Specify Title and Approver and Save the Product.

Save action will trigger the Workflow that we just created

19

As a result of Workflow execution Approve will get the Email with “Approve” and “Reject” options

20

Beauty of this implementation is that Email contains clickable options for approver to submit the approver’s choices from within the email

Here Approver rejects the Product

21

As a result of this Rejection, the workflow will delete the Product from the List and send an Email Notification to Requestor and Approver informing same.

22

Product has been deleted from the list

23

Now again add a new Product to the list that will again trigger the event to execute the workflow

24

Product has been added

25

As a result of Workflow execution Approve will get the Email with “Approve” and “Reject” options

26

This time Approver approved the Product

27

As a result of this Approval, the workflow sends an Email Notification to Requestor and Approver informing same.

28

Hope you find it helpful.

SharePoint Online/2016/2013: How To Upload Large Files Using PowerShell Automation

Uploading large files to SharePoint On-Premise or Online is an obvious problem during data migration from any external systems like Lotus Notes.

Here is one of such errors which we might encounter while trying to upload a file of size greater than 250 MB-

1

In this article I will explain a data upload strategy where we can split a large file into multiple chunks of smaller size.

Solution Architecture Diagram

For better understanding we can refer to the following solution architecture diagram-

2

Based on this diagram we can conclude the following facts-
1. This solution can be hosted on multiple servers to launch parallel uploads
2. This solution can consume data from Network File Shares
3. Once data file is retrieved (say of size 300 MB), this solution will split the file (100 MB) automatically based on the pre-configured chunk size (which should not exceed the size limit of 250 MB)
4. Each chunk then appended to the file uploaded in multiple iterations

In order to start with this demo we would need a SharePoint Document Library in SharePoint Online (or On-Premise) Site as shown below-

3

Another prerequisite to demo is to have files of various sizes that we can use to upload to the document library.

I made use of following command line utility to generate files of various sizes. This utility takes destination folder path and size of the file in KBs as input.

Here is the usage example of the command line utility-

fsutil file createnew "C:\Prashant\Self Paced Training\Sample Files\2GB.txt" 2147483648

Similarly I have generated other files too as shown below-

4

Now let’s dive down into the code to understand the actual implementation.

Step 1: Declare a variables to hold the document library name & folder path. For production use I recommend to have these values in an external configuration file.

Step 2: Reading files from the folder specified in path variable in Step 1

Step 3: Loop through all the files and pass each file to the “UploadLargeFiles” function along with the document library name

5

Step 4: Generate unique upload id & get file name of the file to be uploaded

Step 5: Get handle on document library object and load the root folder (or any target folder) with in the document library

Step 6: Calculate the block size to be uploaded and total file size (as shown in the architecture diagram)

Step 7: Read the bytes from the source file and set the read buffer based on the block size

6

Step 8: Read the bytes based on the buffer limit that we set in earlier steps

7

Step 9: Check if this is the first chunk that is being uploaded, if yes then add a new file to SharePoint Document Library, get the file content based on the buffer size for the chunk and call “StartUpload” function that is defined under “Microsoft.SharePoint.Client.File” class. This will add the file to the document library but with small bunch of content only.

Step 10: Check if this is not the first chunk that is being uploaded, if yes then find the file in document library and get the handle on it

Step 11: If this is another chunk of data which is not the last chunk, this chunk will be appended to the same file by using “ContinueUpload” function that is defined under “Microsoft.SharePoint.Client.File” class. This will append the content to the file identified by Upload Id that we have initialized in earlier steps.

Step 12: If this is last chunk of data, this chunk will be appended to the same file by using “FinishUpload” function that is defined under “Microsoft.SharePoint.Client.File” class. This will append the content to the file identified by Upload Id that we have initialized in earlier steps and commits the changes to the file. Once this function completes successfully the changes will be made persistent to the file.

8

Step 13: Perform exception handling and call the “UploadLargeFileToLibrary”

9

I recommend to read the documentation on Microsoft.SharePoint.Client.File class and understand functions carefully before using it.

Once we execute this script we can see the following information-

  1. File Name to be uploaded
  2. Chunk size
  3. Total Time taken to upload the files

It is important to note that total time taken to upload the files may vary depending on the hosting environment.

File Size to be uploaded: 10 MB

10

File Size to be uploaded: 50 MB

11

File Size to be uploaded: 500 MB

12

File Size to be uploaded: 2 GB

13

Once the script executed successfully we can see the respective files uploaded to the SharePoint Online Site as shown below-

14

That is all for this demo.

This article is equally applicable for both SharePoint Online & On-Premise Versions.

Hope you find it helpful.

SharePoint 2016/2013/Online: How to Optimize SharePoint Custom Pages Using HTML5 IndexedDB API

In this article we will discuss another obvious performance issues with SharePoint Solutions involving large volume of data transactions surfacing SharePoint Custom Pages.

This could become more prominent if we have strict governance in place and we are not allowed to make use of advanced server side options (Custom Web Service End Point, MTA Enabled Modules etc.).

In one of the recent assignment I came across a similar scenario where I need to crawl data from an external Web Service end Point and surface data on SharePoint Pages. Since the anticipated data volume was huge and traditional caching approaches like Cookies wont’ work due to size limitations.

In pursuit of the solution I have gone through the “HTML5 Web Storage APIs” that allows you to setup an In-Browser Transactional Database System called “IndexedDB”.

Here is a quick introduction of IndexedDB for details I must recommend you to visit IndexedDB

“IndexedDB is a transactional database system, like an SQL-based RDBMS. However, unlike SQL-based RDBMSes, which use fixed-column tables, IndexedDB is a JavaScript-based object-oriented database. IndexedDB lets you store and retrieve objects that are indexed with a key; any objects supported by the structured clone algorithm can be stored. Operations performed using IndexedDB are done asynchronously, so as not to block applications.”

I also want to thanks to “Raymond Camden” for his detailed research on Storage Limits for IndexedDB and believe you must refer this link to understand the limits carefully before getting into concrete implementations.

Now let’s try to understand the implementation details by using following diagram:

Solution Architecture Diagram & Explanation

1

In this solution the SharePoint Page will try to look for the required data in Local Indexed DB created to support this page. If data is not found in local database, page will issue the request for data from SharePoint List.

Since we are dealing with “100,000” Items present in SharePoint List, I made use of “REST API + OData Continuation” data access strategy to overcome SharePoint List Threshold Limits. This mechanism will access only 100 List Items at a time and it is safe to extend this limit up to 2000 items per fetch.

Each fetch will a JSON Object that will be persisted into Indexed DB as individual record. I opt this strategy to reduce the page load time. If the number of items are not much you can add each item as separate record.

Every subsequent data call will be automatically diverted to the local database as primary source.

Additionally we can add “Auto Refresh Modules” to keep the local database fresh with SharePoint List Changes and sync the changes with Indexed DB “Asynchronously”.

Ideally speaking for a complete solution “Auto Refresh Modules” are must to have.

So this all about execution summary for this solution.

Now let’s have look at implementation details as follows-

I have created a SharePoint List with two columns and “100,000” Items added to it as shown below.

Demo

This list will be acting as data source for the page. In actual scenarios this source could be a Web Service End Point which can provide voluminous data on demand.

2

3

Before getting into code let’s see how this Page will behave on execution. Demonstrating the page in action will be helpful later when we get a deep dive in code.

If we run the page we will see this page took about “3 minutes” to get execution completed.

The first execution cycle will include the following actions:

  1. Initialize IndexedDB Database
  2. Query SharePoint List
  3. Add REST API Response to IndexedDB
  4. Load page with data from IndexedDB

Since we are adding data to the store asynchronously, overall application will remain functional even it is taking 3 minutes to complete.

4

Following screen shot showing data adding to IndexedDB asynchronously

5

We can also review the Indexed DB initialized as the part of this request using “Developer Tools or F12 Key” with in the browser as shown below-

6

We can explore each item in the each of the JSON Object as shown below-

7

Now refresh the page to see the execution again and we can see roughly “1 second” to complete the page request.

The subsequent execution cycle will include the following actions:

  1. Query IndexedDB for data
  2. Load page with data from IndexedDB

So we can see how we can trim the execution path by using a well-defined strategy.

8

Code Analysis

Let’s do the code analysis to understand the concrete implementation.

In Step 1 we are enclosing some of the literals as variables and will refer theses variables later in the code

9

In Step 2 we are checking if respective Indexed Database is initialized already or not and if not Initialize the Database. In this demos let’s call this database as “Products”

10

In Step 3 “onsuccess” event handler will get executed and database object will get stored in a global variable “SharePointOptimization.sharePointStore”. This variable will be acting as start point for all the operations on the database in future.

In Step 4 default error handling module is assigned as callback function to “onerror”, “onblocked”, “onabort” event handler

11

In Step 5 we are querying SharePoint List using REST API

12

In Step 6 we are making use of OData Continuation Techniques to overcome SharePoint List Threshold restrictions.

In this step we also call “AddDataToStore” function that will add SharePoint List Items coming as JSON Object to the Local Indexed Database.  It is important to recall that in this demo I am storing 1 JSON Object as 1 record in database and each object contains information for 100 List Items.

13

In Step 7 we are adding JSON Objects to IndexedDB. In order to do that we need to perform following operations-

  • Initialize Transaction with Read Write Operation Permissions
  • Get Handle on “Products” Database inside IndexedDB Data Stores
  • Call asynchronous “add” method to add JSON Object to “Products” Store

In Step 8 we are calling “QuerySharePoint” function to query data from SharePoint List in case data is not available in Local Database.

14

Steps 9, 10, 11 explains about “ReadSPStore” function where we will read the data from Local Data Store (IndexedDB)

In Step 9 following operations are performed-

  • Initialize Transaction with Read Operation Permissions
  • Get Handle on “Products” Database inside IndexedDB Data Stores
  • Call asynchronous “count” method to get total number of JSON Object available in “Products” Store

In Step 10 following operations are performed-

  • Check for get count request status
  • If success Initialize Indexed DB Cursor by calling asynchronous “openCursor” function

In Step 11 following operations are performed-

  • Check for get cursor request status
  • If success read the record from IndexedDB and add to the local array variable
  • Call “continue” function as long as there are items left in local store
  • Once all data is read and save to the local array pass this array to “RenderUI” function to render this data on the interface as required

15

In Step 12 we can plug any UI engine to produce more intuitive UI as applicable, for the sake of this demo I am writing out the Count of Store records * 100 (since each record contains 100 Items) to show the total number of items stored in the local store.

16

Steps 13, 14, 15 show you a helper function to check if local store contains required data or not. It helps to decide if we need to read data from Local Store or SharePoint List

“GetProductCount” function is quite similar to the “ReadSPStore” function except it perform a lesser number of operations

17

In Step 16 we will initialize Local SharePoint Store by calling “InitializeSharePointStore” function

18

In Step 17 we can see some of the UI elements to build a basic UI for this demo

19

Point of caution

Before implementing this mechanism make sure you have identified all the compatibility issues around this corner.

I would recommend you to refer the following site every now and then to make sure you are using features supported by the targeted browsers.

http://caniuse.com/#search=IndexedDb

20

Since I have made use of artifacts which are compatible with SharePoint Online Development Guidelines so we can use this approach with pages hosted in SharePoint Online as well.

That is all for this demo.

Hope you find it helpful.

 

SharePoint 2016/2013/Online- How to Apply Password Encryption for Component as Service using PowerShell

Recently I have developed a couple of PowerShell based components that will serve as data crawlers for federated data sources like External Web Services, SQL Server Databases, and Excel Workbooks & SharePoint Lists.

In order to authenticate the Service Accounts against all of these sources I had no choice but to embed the User Name and Passwords with in the PowerShell Code in plain text. It gets even worst when few of the Web Services could support only “Basic Authentication”.

Saving passwords in plain text to code files could lead us to the Compliance Issues and could get the solutions rejected eventually.

In order to fix this issue I have implemented a couple of mechanism to deal with each type of Authentication requirements.

In this article I will discuss the mechanism to authenticate the requests to SharePoint Lists.

In order to simplify this demo let’s consider a simple scenario where I am having a list “MyLocations” as shown below and I need to export its metadata using a PowerShell based component.

1

To keep the content crisp I will walk you through the specific section from code and skipping all the CSOM specific code which you can refer in my earlier articles if you like.

I have intentionally divided this implementation into two separate code files in order to keep the passwords safe from the developers. Intent is to get the Encryption File generated by the SharePoint Admins and provided these files to developers for so that they can use it in code directly as shown below.

In the following code snippet you can see the commands to encrypt password “12345678” and export it to a text file “BANSALP.txt”

2

This file would look like as shown below:

34

This way you can store passwords for all required service accounts in different text files without violating Security Compliance.

Now in order to pass this encrypted password to SharePoint for authentication we can make use of “System.Management.Automation.PSCredential” Class as shown below.

Here “Get-Content” Command let is used to read the content from “BANSALP.txt” file and “ConvertTo-SecureString” Command let to get the encrypted password as secure string

5

Once credential Object has been created we can assign this credential object to SharePoint Client Context “Credentials” Property

6

With this Client Context SharePoint Authenticates the incoming request based on the ACL of the requestor

Following is the outcome of the call that we have send to SharePoint:

7

I have exported the metadata to a “csv” file as well that would look like this.

8

Hope you find it helpful.

SharePoint 2013/Online: JavaScript Injection using Embed JavaScript Pattern

Based on the latest recommendations from Microsoft, User Interface SharePoint 2013 & SharePoint Online should be customized using Client Side Frameworks and not using Traditional Master Page Customization based on Branding Solutions.

Moving on the same recommendations we will discuss JavaScript Injection or Embed JavaScript Pattern which is one of the newly recommended techniques from Microsoft that enables the developers to write applications to push the client scripts into the page from outside SharePoint Environment.

This sounds similar to the implementation of the Delegate Controls in an on premise SharePoint Installation but in this case we push the scripts from outside of the SharePoint Environment.

Using Client Side Frameworks such as JQuery along with this technique we can perform DOM Manipulation (adding, removing, modifying HTML Elements) as and when needed in whichever ways.

We must make use of Custom Actions with SharePoint App Model in order to implement Embed JavaScript Pattern by utilizing location identifier ScriptLink that can be accessed through UserCustomActions collection of SPWeb Object.

In this in this article we will see how to implement Embed JavaScript Pattern in real time business applications as below-

Lets’ start with a SharePoint App Project by selecting App for SharePoint Project Template

1

Specify the Site URL

Choose Provider-Hosted as hosting model in order to develop High Trust Apps

2

Choose ASP.Net Web Forms Application to create Web Application Project for the Provider Hosted App

3

Provide Certificate details for the High Trust Apps

4

Now once the project is ready we can start with the coding part of Solution as follows-

Steps 1 – In the default.aspx add HTML code to provide UI for the solution

5

In the App.js file add the following code-

Steps 2 – Refer the JQuery File from the CDN

Steps 3 – Calling InjectJavaScript Function

6

Steps 4 – Inside InjectJavaScript Function, check if MDS is enabled and if it is Register Custom JavaScript code using RegisterModuleInit function.

The first parameter to the RegisterModuleInit function is the path to the JavaScript file relative to the _layouts folder.  Since this solution deploys the JavaScript file into a folder under the _layouts virtual directory, you have provided that relative path.  The second parameter is the entry point function which is LoadJSInsideHostWeb.

This approach will ensure that this JavaScript will work both with MDS enabled & disabled sites.

7

Steps 5 – Inside LoadJSInsideHostWeb function, we are calling LoadJQuery function to include JQuery file from the CDN and once loaded successfully it is calling ModifyHostWeb which will do the actual job of Injecting JavaScript Code to the Host Web

8

Steps 6 – Inside ModifyHostWeb function

  • We are manipulating the Site Title of the Host Web by using JQuery Element Identifier
  • We are replacing the Site Icon of the Host Web by using JQuery Element Identifier

9

Steps 7 – Inside LoadJQuery function we are loading JQuery File from the CDN

10

Steps 8 – Here we are hooking up the button click event for InjectJs & RemoveJS HTML buttons

Inside each event handler we are calling InjectJavaScript & RemoveJavaScript functions by passing Client Context to the Host Web & Web Object referring the Host Web and setting the notification message on the SharePoint App Page (default.aspx) to show the status of the operation

11

Steps 9 – Inside InjectJavaScript function we are making use of Custom Actions Framework for SharePoint to inject JavaScript based customization inside the Host Web in the following steps-

12.1

Preparing path of the Script file that we are going to inject into the Host Web and embedding it by creating the dynamic script block with src attribute set to the script file path.

Then we are retrieving the UserCustomActions collection in context of the Host Web and adding the new User Custom Action with Location as Script Link and Script Block as dynamic script block created earlier

 

13

Steps 10 – Inside RemoveJavaScript Function we are removing the User Custom Action from the UserCustomActions collection in context of the Host Web based on the Description & Location property of the User Custom Action.

14

With this we are done with the code.

Now lets’ run the App and see it in action by pressing F5 in Visual Studio

Once the App launched we can see the UI with a Result Panel & two HTML Buttons

  • Inject JavaScript to Host Web – This button will Inject JavaScript to the Host Web using User Custom Action
  • Remove JavaScript to Host Web – This button will Remove JavaScript from the Host Web by removing User Custom Action

15

If we look the Host Web before embedding the script to it, it would look like as follows. Notice we have default Site Icon and Title which was provided at the time of site creation

16

Now on App Page click on Inject JavaScript to Host Web button to push custom JavaScript into the Host Web

On clicking the button we can see the success message in the Result Panel confirming that the JavaScript has been applied to the Host Web

17

If we revisit the Host Web we can see the Site Icon and Title has been changed as per the code we had added to the custom JavaScript File that we have injected into Host Web

And since this change takes place at the Master Page Level, we can see the effect of the change all across the site on every screen as shown below:

18

19

20

 

Now in order to unplug the JavaScript based customizations out of the Host Web we can click on Remove JavaScript to Host Web

Once the Remove operation has been completed successfully we can see the result panel confirming the success of the operation.

21

And we can go back to Host Web to ensure that the Site Icon and Original Title are restored back as usual.

22

So we can clearly see the “Embed JavaScript Pattern” is very effective as it gives you handle on customizing Host Web Elements from outside the SharePoint itself.

Point of Caution

It is the responsibility of the App Developer to handler the smooth removal of the injected code as soon as the App gets uninstalled. There are a couple of issues that I would like to point out around this fact as follows:

If code is injected using SharePoint Hosted App, then it is not possible to get it removed the injected code automatically by any mean. In this case it is required to provide a User Interface or any other mean to execute the code for removal of injected Javascript followed by User Training for the Administrators to run the code first before uninstalling the App.

If code is injected using Provider Hosted App, then it is possible to get it removed automatically by handling App Uninstalling Event using Remote Event Receivers. You can refer to following of my earlier blogs on Remote Event Receivers to get better understanding on usage

That’s all for this demo.

Hope you find it helpful.

SharePoint 2013/Online: Send Email Using REST API

Sending Email is one of the most common functionalities that need to be developed in almost every project irrespective of the nature of the project.

Based on the new development paradigms introduced by Microsoft, recommended development approach prefers to make use of Client Side Object Model and REST API for developing functionalities for SharePoint 2013.

In this article by moving on the same lines we will discuss how to develop a Mail Client for SharePoint Online/2013 using REST API End Point exposed by SharePoint 2013.

In this demo I will make use of OOB Content Editor WebPart for executing the Javascript Code and a virtual mail Utility “smtp4dev” which is available on CodePlex for free download. “smtp4dev” allow you to test mail functionality by intercepting incoming mails using a thin mail client by configuring a local SMTP Server in your development VM.

I have mentioned quite a number of such useful tools in one of my earlier blog post SharePoint Developer Tools – Get Your Gears, and recommend you to visit it for details on the tools that can be very helpful in enhancing developer productivity while working in SharePoint Environment.

Let’s start by writing JavaScript code and since we are making use of Content Editor WebPart we need to perform some additional tasks:

  • Open SharePoint Designer
  • Visit Site Assets Library
  • Add a new Text file and give it a proper name of your choice

1

In the text file add the code as shown in the following steps

Step 1: CSS of your choice to build the UI as desired. In my case I put some CSS classes for the UI of mail client

2

Step 2: Add some HTML elements that design the UI for the Mail Client and apply CSS classes appropriately

3

Step 3: Add reference to “jquery.js”, “sp.runtime.js” and “sp.js” files

4

Step 4: Add “document.ready” function to bind the click even of the button with the appropriate event handler

5

Inside Event Handler function “SendMail ()” we will proceed with the code as follows:

Step 5: Reading values from UI control to prepare the Email Contents to be sent

Step 6: Preparing the Request Header object to be sent along with REST API call to SharePoint, this object is necessary to provide execution details to be authenticated by SharePoint

Step 7: Preparing REST API URL to pass into the subsequent call by making use of page context variable

Step 8: Preparing API Call by configuring metadata object of type “SP.Utilities.EmailProperties”. It is worth to spend time to review this object for a while to notice what all properties are exposed by this object. We can specify From Email, To Email, CC Email, Subject & Body of the mail with in this object

Step 9: In the success call back we can perform the desired action, in this demo we are just writing down a success message to the Result Panel

6

With this we are all done with coding and now it is time to create a new page and add Content Editor WebPart to the page

  • Go to Site Page Library
  • Add a new WebPart Page
  • On the WebPart Page, Click Add WebPart Link

7

  • From the WebPart Picker choose “Content Editor” WebPart that falls under “Media and Content” category
  • Click Add to add the WebPart to the Page

8

Next thing is to add the reference to the JavaScript Code file that we have created in the steps above.

  • To refer the Code file Edit the WebPart
  • Specify the relative URL of the Code file in the Content Link placeholder in WebPart Properties as shown below

9

10

  • Once done with the changes choose “Stop Editing” from the Ribbon to save the changes to the WebPart

11

If the code executes successfully we will see the UI for Mail Client rendered as shown below

12

Before we execute the code to send the mail we need to first have a look to the “smtp4dev” tool. This tool will receives the mail messages and get them displayed to “Messages” Tab

13

Now enter the Name, Email Address and Message on the UI and click “Send Email” button

14

Once the Email functionality gets executed successfully, we will see the Success message print in the Result Panel and also an Email Received Notification from “smtp4dev” tool.

15

We can analyze the received further by looking it into the “smtp4dev” tool “Message” Tab.

In the “Message” Tab select received mail and click on the “Inspect” button

16

On the “Message Details” screen under the “Body” Tab we can see the body of the mail received

17

Since this the REST call we can analyze the corresponding Request-Response cycle using any Web Proxy tool, here I am using Fiddler to inspect it.

We will get a null response Object in case of successful execution of the Email functionality.

18

Known Limitations

Issue with Attachments

Adding attachments with in the Email is not supported using this approach and this limitation is due to limited exposure of the properties by “SP.Utilities.EmailProperties” Object.

Only following properties has been exposed by this object to be used with in REST Call

19

Here we can see that there is no property exposed for adding attachments along with the mail.

Issue with External Mails

External Mail are not supported using this approach which means we can only send mails to valid Site Users only if you try to send the mail to any external User or Email ID you will probably get the following error:

20.png

That is all for the demo.

Hope you find it helpful.