Published: 13th March 2017
You might have built your first Add-in by the time you are reading, or maybe you are brand new to SharePoint Online Development. Whatever maybe your situation, I wanted to introduce this with a real world application.
Most of the sample applications below require workflow. So in this post, we will be developing an approval workflow within the Add-in using Visual Studio 2017.
You could use any one of the below applications if you wanted to try.
Just take one of the example systems above and build your first Add-in, so that you can learn more rather firing Visual Studio and creating an example Add-in.
In this post, I would like to take Travel Request system as an example. It is one of the typical application most of the organization uses for maintaining the travel requests.
The concepts you will learn by the end of this post:
Below are the fields and type of the fields we will have in this system.
This travel system is where users can fill the request, and the respective manager will approve the request.
This application requires a form for users to fill the details and workflow for the approval process.
Before building these within your Add-in, it's important to understand "Why Add-ins."
It was always a question when Microsoft released this for the first time a few years back; then, there was a lot of reasons due to previous versions of SharePoint drawbacks.
One of them is mainly migration issues and challenges.
The second one is FARM solutions, which creates a lot of problems when you don't do it properly, or I would say don't build it correctly.
"Apps" is the old name. "Add-ins" is the new name, which separates the functionality you wanted to create it. So in the future, if you wanted to upgrade your SharePoint to a newer version of SharePoint it doesn't create any issues.
Coming to Add-ins, there are two major types of Add-ins available.
SharePoint Hosted Add-in
Provider Hosted Add-in
In this type of Add-ins, you can use whatever the code that you would like to use. What I mean by that is, you can write your add-ins in C#, JAVA, PHP, etc. in different languages that you and your team capable of. But you need to have a separate provider to host the Add-in.
This provider can be IIS or Azure. If you are working on Office 365 most of the time, you might use Azure which will be your provider. If you are on on-premises, you might use the local server or different IIS site within your server.
I just wanted to give a little bit of context here, before we move on to developing your first Add-in.
In this Demo, your first Add-in will be SharePoint Hosted Add-in. In future blog posts, you will also learn how to develop provider hosted Add-ins.
There are a couple of ways you could create fields in your add-in.
# One, create the columns in Host web and use those columns.
Using this option, you will still have a dependency on the host web because your Add-in uses the columns from host web. So in this approach, you are not able to get the isolation that you are looking for.
# Two, provision those within Add-in itself.
Using this approach, your Add-in will be completely isolated from your host web so you can achieve the main purpose of Add-ins.
I will be showing both options.
For that, I will be creating all the required columns in Host web.
Once you create all the columns, you will have them in host web. Please refer to the image below.
If you do not know how to create columns and what are the types columns you can create, please refer to the below videos.
Below video explains what are site columns and how you can create those.
Do you want to learn more about SharePoint Fundamentals? Click the image below and enroll in the FREE course.
Let us create a project to build Travel Request Application.
File => New => Project
Select Add-ins under Office/SharePoint from which you can select project type as SharePoint Add-in.
Enter your project name. Here, the project name is TravelRequest.
Click OK. It will open the wizard to create the project.
Select the site where you want to deploy the Add-in, "https://spjourney.sharepoint.com/sites/appsdev/SitePages/DevHome.aspx" which is a developer site collection.
Select hosting option as SharePoint-hosted.
Enter the credentials.
Based on the site you are accessing, it will show if it SharePoint Online or SharePoint 2013 or SharePoint 2016. In this case, I am using Office 365, so the default is SharePoint Online.
Once you click Finish, it will create a SharePoint hosted Add-in which has the structure like shown below.
It's time to add the required site columns to the Travel Request Add-in project.
Create a folder called "Site Columns," and add columns to it. To do that right, click on the "Site Columns" folder and Click on Add -> New Item. The screen, like being shown below, will come up from that. Select Site column, enter column name and click on Add button.
The one below is the default elements.xml file for the site columns created from the above step.
Let us add the other columns we created to elements.xml file. Here, I would use the SharePoint Client Browser Tool.
Check the Tools for SharePoint Online Development on how to use the SharePoint Client Browser tool.
Once I connected to the tool, I can get the schema.xml details of each column I've created. In the next step, I will copy those details and update the elements.xml file of site columns.
If I select one of the columns in the list, it shows all the properties of the column. We are interested in schema.xml of that particular column.
Below file is the final elements.xml file for all the site columns we need for TravelRequest Add-in.
Create a folder with the name "Content Types."
To create a content type, right click on the "Content Types" holder that has been created in the above step. Click on Add -> New Item, a screen will come up from that. Then, select Content Type, enter the name of your content type and click Add.
Inherit the content type from item content type.
Add all the columns that were created under site columns.
Below is the code of Travel Request Content Type.
Create a folder with the name "Lists."
Create a list by adding a new item to the folder "Lists."
Enter the name of SharePoint list that you want to create, and click on Add. It will open the wizard to choose the list settings.
Use the default (Blank) template to create the list, and click Finish.
As a standard practice, we will create the columns by selecting the content type. So, click on content types button from columns tab.
Choose the content type from the drop down menu. It will populate all the content types available in the SharePoint site and content types that we have added to the project. You need to add the content type which you created before.
Download the source code of Travel Request Add-in.
In this Add-in, you will have a basic approval workflow where the employee will submit the travel request and the manager will approve. Once it is approved, an email will be sent to the travel desk team to process further travel arrangements.
In this workflow, like what I've discussed, will have three roles.
Before building the workflow, we might need to create the respective SharePoint groups in the SharePoint site for the approval process.
Let us create a new folder, Workflow, in the same Add-in solution.
Add new workflow by right-clicking on the folder, and select the workflow template.
Name this workflow as "ApprovalWorkflow."
Next step is, you need to select the type of the workflow. Here below, it is List Workflow.
Select the list to which you want to run the workflow. Being shown below, it is Travel Request and creating new "WorkflowHistory" and "WorkflowTaskList" for storing workflow history and task info.
The WorkflowHistory list will be used to store all the logging information so we can debug the workflow.
WorkflowTaskList is used to store all the tasks created.
Click Next, and choose the starting options accordingly. In this, I am setting to start the workflow automatically when an item is added.
Once you click Finish, the ApprovalWorkflow will be created and along with that are the "WorkflowHistory" List and WorkflowTasksLists.
To create the tasks in this example, we used SingleTask workflow activity which will create the tasks for an assigned user or group. In our example, we will use a group (Approvers=Managers) and assign the tasks for the request raised by the employee.
You can drag and drop the activity to add to the workflow. Once that SingleTask activity is added to the workflow, you need to configure it. Click on Configure button on the SingleTask Activity.
Below are the different properties of SingleTask activity, but the necessary ones are Assigned To and Task Title. I have added both of them. For the simplicity, I have taken the group ID of my site, added to a variable and assigned to the activity here. But in the actual implementation, you might need to get the group ID based on the group name because these values will change depends on the environment you work with even the names of the groups are same.
You check this blog post on Check if the SharePoint Group exists, then if it was available, you could get the group ID.
Once you configured the required option, below image shows the completed workflow. It doesn't have too many actions so you can get started with simple approval workflow. Based on the requirements, you can add the additional activities.
After deploying the workflow, you can add an item and test if the workflow is running as expected or not. In the below image, you can see that the task is assigned to Approvers group where your managers will be available. Instead of the group, you might have the list which stores your manager info. Or, you can get the details directly from user profile manager field or in another scenario, the department where you belong. The manager details are stored in that list. Irrespective of the location where your manager details are stored, you need to get the user or group ID to work with SingleTask activity.
I have created a bonus video, which explains how to create a approval workflow for travel request application.
In this post, you have learned:
I hope you found this blog post helpful.
Download the source code of Travel Request Add-in
In the next post, you will see how to deploy this Add-in as an enterprise solution. To know if there are any new changes to the requirement on how the upgrade process works, stay tuned.
Do you want to me add anything to this post? Or, do you have a question for me? Leave a comment below, and I will try to answer your questions as soon as I can.
What type of Add-ins did you develop on your projects and what was the reason for selecting the specific type? Leave a comment below.
Devendra Velegandla is a four-time recipient of Microsoft's Most Valuable Professional (MVP) award (2014-2017) for Office Servers and Services MVP and SharePoint Server. He received the MCC award for his contributions in Microsoft MSDN/TechNet forums. He loves sharing articles, videos, and tutorial on SharePoint and Office 365.