SharePoint Workflow Best Practices

Note that I will add some screenshots in the near future.  Comment if there is something that I should expand on.

Automation is key to streamlining business processes to really leverage SharePoint and get a good return on investment in configuring SharePoint.  Most of the workflows you may have already seen were simple and only created an email notification, but out of the box SharePoint Designer workflows can do so much more.

There are two other ways to get a workflow.  You can use an out of the box workflow from SharePoint like Collect Signatures or the three-step workflow, but I’d advocate against them.  Like most things Microsoft did with these workflows or the Fab 40 templates if you can remember when Microsoft released those for SharePoint 2007, they are to be seen as examples of what you can do more than released into production.  You can also create workflows with Visual Studio.  I’d suggest that if you can do it with SPD, use SPD.  If you cannot use SPD or you don’t want to run the risk of having a site collection admin breaking something, use Visual Studio, but hire someone really smart to use Visual Studio and ensure that you work in an environment where it is allowed through governance before you start.  Using Visual Studio expands simple tasks such as inserting logic steps and breaks it down into actual code, making it difficult to debug if something goes wrong.  Save yourself the headache and just use SPD whenever possible.

Here are some of my best practices you should remember when designing a workflow.

1.      Draw out your business work process on paper before you begin.

Most people need this visual aid to show the start, goes to Mr. X, gets reviewed by Ms. Y, and published by Dr. Z.  Draw the stick figures and identify what the triggers are that take you from one to another and the next.  Identify what needs to happen at each stage.  If you know that the reality of the work is to tell Dr. Z that a package is on the way when Mr. X gets it, automate it.  Workflows can take multiple paths and can create, read, update, or delete items in other lists if necessary.  Want to make it pretty and don’t have Visio?—I use Gliffy.com.  Use PowerPoint if you really have no other alternative.  The first time you draw it out, however, should be all of the stakeholders in the room with a big white board.  Challenge everything about that workflow.  Be clear with them to identify the differences between their business processes and the workflow.  The way you need to build it in SharePoint probably won’t look exactly like the swimlane diagram someone hands you.

2.      Write out your workflow in plain words on paper to say what needs to happen at every step in the business work process to accomplish this.

Write out very simply something like this:

start workflow set workflow variable check flag for notification if flag not set, send notification, set flag, create item in package tracker list if status is publish, update tracker list, copy document to published library, and create announcement etc.

All of that will help you find the gaps in where you might need to create that column for each flag (hidden choice columns usually) so that when your workflow runs a second, third, or fourth time it does not create another email notification, another item in a tracker, or another announcement.  You need to identify where you do not want the workflow to run over and over and where you would need it to run over and over.

3.      Get your stakeholders to sign their name to the business process.

Time and time again I have seen pipe dreams sold to me as what the actual process is when it rarely if ever follows the documented process.  If there are more exceptions to the rule or the office cannot agree to what a process is, walk away until that office’s leadership can.  Note that you might be building this for one office who needs input from other offices, so ensure you really know who all of the stakeholders are.

4.      Use an index card to walk your item through the workflow on your desk.

Sometimes I use Post-It Notes ® or Sticky Notes on the computer to show the routing on my desktop if I’m using one of my better resolution screens.  This is just to get good visualizations to explain your user story back to the customer or just help you get your head wrapped around what your customer’s users are doing.  The index card is good so you have room to write down key column names so you can identify where things update.

5.      Name your workflow correctly.

On all of the list workflows, I make precede the workflow name with the name of the list.  It just makes it easier to find in case I have many other lists with their own worklfows.  If the workflow is to change the permissions on a personnel roster, it would look something like this: Personnel Roster – change permissions on change.  If you are using a content type workflow, precede it with the content type name.  If you are using a site workflow, precede it with the site name or Site WF.

6.      Fill in the description.

A good name doesn’t absolve you from adding content to your description.  I don’t know how many times I’ve seen similarly named workflows on the same list that I’ve had to read all of the steps to know which workflow does what.  Include in the description your name, maybe a link to the documentation you have on it, and a revision date.

These little things will not just help you when you are asked to make a change six months after you created the workflow, but it will keep people from badmouthing you if someone is looking at one of your workflows after you left an organization.  Imagine you were asked to change some complex workflow.  You open up SharePoint Designer to open it up and you see all of the documentation linked.  You would want the person who made that workflow on your team again.  Your reputation for how you do this will get around, especially if you speak at SharePoint user groups and remind them that this is what you do. 😉

7.      Rename your stages and steps.

This should be obvious, but I still do it often.  Especially if you have a longer workflow, rename the steps and stages so you can quickly find where things should happen.

8.      Name all of your variables up front and initialize their values.

It is like traditional programming where you declare your variable.  It is just a good thing to do this up front to ensure that a null value doesn’t creep in somewhere.  Null values can suspend your workflows.  After you are done declaring all of these variables, use one logging statement to show all of their values in the history list.  Use good names for all of your variables, and ensure they stand out from the names of your columns.  I usually add var to the front of all of the names of my variables just to be certain not to confuse them with any columns.  I also CamelCase variable names to aid in knowing that these are never displayed.

9.      Comment your workflow before you go to add the actual conditions and actions.

All of the plain English you wrote up in step 2 should be in comments throughout.  If it is a rather simple workflow, you can just add this to the names of your steps, but it is a good practice to support your buddies when you are working with a team of people.

10. Create a load of logging statements.

Every time you set a column or variable’s value, you should log the old value and new value to see it took properly.  Data type mismatches happen a lot, especially if you are using some columns with similar names.  We all make mistakes while making things.  Using the logging statements will help you find your errors when a workflow suspends mysteriously.

11. Log things to a separate audit log list.

I will always use version control with my document libraries where I might need to see the previous version of things, but if I want to see the changes in a single column or a status change, I usually create a previous value column for it.  Assume you have a column, Status.  I would also have prvStatus and make it a hidden column.  When the item is created, I’d set prvStatus equal to Status.  On the workflows based on a change to the item, add the condition:

If Status is not equal to prvStatus Create Item   Title = [Modified by] changed the status from [prvStatus] to [Status] on [Modified].  ItemID = ID (This is the ID of the item you were working with so it can show the relationship.)
You can then add a web part to this audit log to the dispform.aspx page of the list and filter its values to show the history of an item.

12. Use a new workflow history list.

I’m guilty of often using the same history list, and it won’t kill you if you do use the same history lists, but it isn’t wise.  Say you have a lot of testing for a long workflow.  Say you have 20 log statements in the workflow.  You test.  You made a few mistakes, and you get requests to make a few changes.  How many tests do you think you can do?—Only 250.  By default, no history list has its columns indexed, so it will hit that 5,000 item limit threshold like any other list.  If you are using the same history list for a few workflows, you won’t be able to see the results of any of your tests in short time.  Use a new history list.  Index its columns.

In addition, you can create an easy way to turn on and off your logging.  This takes us to the 400-level training, but have another list with Title and a choice column for on and off.  Add an item and call it Workflow XYZ Logging and select on.  When you are initializing your variables, have one for varWFLogging.  Set it to Yes or No based on the value Workflow XYZ Logging in that other list.  In SPD 2013, you can copy and paste, so when you were going to set all of those logging statements, create If varWFLogging equals Yes.  Then put your logging statement inside of it.  Then you can flip it on and off as you test things.  Keep some logging outside of the condition.  It can be overkill for a simple workflow, but if you have a lot of steps, I’d suggest setting this up.

13.  When it is possible, cut up large workflows into small workflow.

Sometimes, just having your workflow cut into stages and steps is sufficient, but sometimes it is best to call a workflow from the first workflow to run only when the conditions are necessary and the steps are repeatable.  For instance, you can have a 2013 workflow that you use for everything when there is a change; but, if the logic calls for it, that workflow could call a 2010 workflow with its impersonation step to change the permissions on the item you are using.

14. Use only one workflow to execute on creation or change.

It can be the same workflow, but do not have two or three workflows that kick off at the same time when an item is created or changed.  It can cause collisions that make things ugly.

15. Add a workflow as an option in the context menu.

If you have a manual workflow to do something to an item, use SPD to create a link to it right in the context menu.  It adds to the UI/UX of the application for a little more spit and polish.

16.  Do not use a pause for more than five minutes.

I bring this up because I often see people try to put a pause of like a week or months even inside of a workflow to archive the item after a long period or to send out a reminder email.  Well, that doesn’t work very well.  When you reboot the services on the box, the workflows get lost.  They break.  You won’t know without checking through all of your content where these orphaned workflows are.  Use an information management policy to kick off a manual workflow to do these things instead.

So when should you use a pause?—At the beginning of a workflow that would start immediately after an item is created sometimes.  What I have found is that copy jobs from one list to another aren’t always complete by the time another workflow might start in the destination list, so it would be good to have a one-minute pause here to ensure all of the metadata is set properly before your workflow starts to run with it.

Other Pro Tips for SharePoint Designer

Use it to help manage your permission groups.  You could have hundreds of permission groups in your site collection.  Managing them all through the GUI could be painful.  Through SPD, you can click on Site Groups and see all of them in one view.  It’ll help you find misspelled and redundant groups.  It will help you update the descriptions of those groups if they are missing.

Use SPD to create your HTML, JS, and CSS files right in the libraries where you’ll keep them.  If you have clicked on All Files in the navigation on the left side of the screen, you can get into any library and look directly at files.  You can create or edit all of your client-side code with a nice UI.  It beats using Notepad most of the time.

Permissions 101

The basics of SharePoint permissions haven’t changed too much over the versions, but there are things Microsoft has done with SharePoint 2013 with sharing I do not appreciate. Worse is the newer permission level of edit. Maybe my users are worse than your users, and you’ve been able to train people to not add columns without planning to lists and libraries. I’ve not met users who don’t eventually do something undesirable with edit permissions. Contribute used to be the default permission level for regular users/members of a site. I’d suggest changing it back to contribute for all of your future sites.

 
 

The worst thing that Microsoft did with its permissions has everything to do with semantics. At least with my clients in my market, they like to be in control of their empire, regardless of how small it is in a 50,000-person organization. When Microsoft automatically creates for you ABC Visitors, ABC Members, and ABC Owners when you create a new site, the management of the office often insists it is in the Owners group. This means that the people who often have the least technical skills in the office have the power to create apps and will see more things to click on than they should. Data owners are not the same as site owners; trying to explain that in such a large organization is difficult but possible. You just need to fight lots of little battles and ruffle a lot of feathers. The easy way around this is to create a new group called ABC Leadership and put them in there while you rename the default owners group to ABC Site Administrators. You could use ABC Management instead, but calling them leadership makes them feel better. Words have meanings, and you should pay attention to the emotions they can elicit.

 
 

If you take away nothing else from this writing, please use that advice on renaming the groups.

 
 

You should have created your groups before you created your site, assuming it is not the root site of the site collection. Do not let SharePoint create them for you. You should already know the different audiences of your organization and most of the different roles you will encounter. You will want a single group to represent everyone in your organization. I’d suggest that this is your ABC Visitors group or an equivalent. Add everyone to that group. Never again should you create another visitors group with the same population inside of it. It is one of the most common things I see. I’ve looked at many site collections where there are multiple owners groups and visitors groups with the same handful of people in many owners groups and the entire organization in all of the visitors groups. Imagine cutting down the number of groups to manage by up to 66% by just not creating all of those redundant groups.

 
 

SharePoint permissions pass down from the site to the subsites and lists and even the items inside until you break inheritance. A site’s overall permissions are by default the permissions of the Pages and Site Pages libraries you might have on your site and, therefore, the home page of your site. Ask yourself if everyone who has contribute rights on your site should have the ability to modify the home page of the site? Maybe, but probably not. Often times, I see the site administrators lock down the Site Pages library to prevent people from making edits, but they often make it so that the organization cannot even view the homepage. Be careful how you do that. I’d suggest that you break inheritance on the library, not just on the page. Like with all places where you break inheritance, it isn’t obvious that the permissions on one object might have different permissions than another or its parent. For this reason you should be careful to break inheritance only when you need to. It would be a wise move to not only document a matrix (permission map) of all of the permissions each group has compared to each list or library on the site but to also add in the descriptions of each that it has unique permissions and what that means for the people looking at the list or library.

 
 

I’d also suggest that you do not break inheritance at the folder or item level within a list or library unless it is highly documented or—even better—controlled by a workflow so that you remove the human element from being able to accidentally grant or deny people you should not. Everything is truly business requirement specific when you make these decisions, but a good example of this would be to an human resources library where you have a folder for everyone in the organization. You would likely allow HR to have contribute to all of those folders, the individual to have read or contribute no delete (you should probably create this permission level), and each individual’s supervisor to have some level as well. The beauty of this is that HR will see all of the folders, supervisors would only see their own and those of the people they manage, and individuals would only see their own.

 
 

This is because security trimming in SharePoint does not allow a user to see that an object even exists if that individual cannot access it. Alternatively, you can use audiencing to selectively show web parts and links. Audiencing is not a method of security. It just allows you to better advertise directly to the right consumers. This is very important because most apps you build will need to have at least two very distinct audiences: those who add the content and those who consume the content. Sometimes they are the same groups of people, but usually it is a smaller group to create the content than to consume it. So the links in your current navigation could go to a number of extra views that matter only to the creators of content if without cluttering up the list of options for external visitors of your site. Everyone might have access to the same list, but you don’t need to advertise all of the views the creators might want. Could you imagine going to a restaurant and seeing all of the dishes that have an ingredient you don’t want automatically removed from the menu? That is exactly what you are doing when you use audiencing. Use it wisely, and document it.

 
 

When creating all of the groups to your site, you may be tempted to use the ABC Members group and groups like it in ways that are not desirable in the long run because of the management burden. If you had an HR directorate in your organization with branches A, B, C, and D, you would likely create HR A Members, HR B Members, HR C Members, and HR D Members. That would be totally reasonable. So if you had an HR site and a subsite for each of the branches, you might have already created an HR Members group. This is why you should plan all of these groups on paper long before you build. Because you know you’ll already need to create sub-population groups, it is against your best interest to have a group where you have put them together as well. This is because the parent HR site should have the following groups with these default permissions:

HR Site Administrators

Full Control

HR Leadership (don’t forget this tip)

Contribute

HR A Members

Contribute

HR B Members

Contribute

HR C Members

Contribute

HR D Members

Contribute

Org Visitors (everyone)

Read

By creating an HR Members group as well, you’d have yet another group to update as people joined and left HR. By mapping out all of the groups you’ll need at the smallest manageable group, it becomes much easier to get granular without the management overhead you’ll have with SharePoint creating all of these groups for you.

 
 

At the same time, I’ve sometimes seen site administrators add users from other organizations to the default members group of the site. Assume that a few in Legal often work with the folks in HR B. If you add them to the HR B Members group, you’ll inadvertently give them access to things that you might not want them to access. This isn’t about you not trusting them, but they might not like it either. You could have a workflow that sends out email notifications when anyone in the company updates a service feedback survey for when HR helps people. If that workflow uses HR B Members as the distribution of that notification, you’ll start spamming the Legal people. Use role-based access control (RBAC) when planning your groups. If you add Legal Members as another group that can contribute to the library where they collaborate with HR B, you fix all of these issues. You also save yourself some pain when Legal hires a new person. By just adding that person to the Legal Members roles, the new person gets all of the accesses of all of the other Legal people where he or she should have that level of access. You should not ever need to hit 20 sites to add the person to a different group because that is where the other Legal people have access.

 
 

To document all of these permissions well, you need to create a permission map for each of your sites. You can just create a little table in Excel or on a wiki page. It doesn’t matter what your preference is as long as you do it for all of your sites and preferably the same way. It’ll eventually look something like this:

 
 

  

Description

HR Site Administrators

HR B

Agency Members (everyone)

Legal Members

Customer Feedback Survey

Survey that goes out periodically to those who HR B supports after fulfilling a request.

Full Control

Contribute

Contribute

  

Disciplinary Documents

Collaborative library where HR works with Legal to process disciplinary actions.

Full Control

Contribute

  

Contribute

HR eFile

Folders exist for every employee in the agency. Each employee can see his or her own file.

Full Control

Contribute

Dynamic – Workflow

  

HR FAQs

Frequently asked questions regarding HR functions.

Full Control

Contribute

Read

  

Leave Calendar

Internal calendar for the office to track who is in the office.

Full Control

Contribute

  

  

Office Calendar

Calendar for everyone in the agency to see when HR is hosting seminars about benefits as in and out briefings among other things.

Full Control

Contribute

Read

  

Shared Documents

Not used because of changes to the library made by the publishing feature.

Full Control

  

  

  

Site Assets

Keeps pictures for the pages along with some custom CSS files for the site.

Full Control

  

Read

  

Site Pages

All of the pages that add the context for the content in the lists and libraries.

Full Control

  

Read

  

Team Tasks

Used internally to assign taskers to different members within HR B.

Full Control

Contribute

Read

  

 
 

After you have mapped out what the permissions should be, you can use this as a checklist to ensure that they stay that way. Inevitably, you’ll add someone to your site administrators group who will mess it up, so periodically review the lists to ensure that you have the permissions set according to your plan. Of course this is just an example. You’ll likely have many more lists and libraries as well as groups to map out. Like all settings for a list or library, you should make a very conscious decision about what the permissions should be for each of them and add it to the map you’ve made.

 
 

Sometimes you will want to create some special permission levels. For HR, you might have a few libraries where you want everyone to be able to submit a form but not be able to modify it or even read it afterward or maybe read only your own. Create the additional groups with caution as some features might need a particular setting to work correctly. A general rule in SharePoint is to never mess with the out of the box configurations but to copy and modify to create new. So don’t open the contribute permission level and remove the ability for people to delete. Instead, create a new permission level Contribute No Delete. You can do a lot of unique things. I’ll repeat this ad nauseum: document what you do. When you get a promotion or go on vacation for two weeks, someone else will need to step into your role in case a change needs to happen, and that person will need to understand what you have made, how you made it, and why you chose one way vice another.

 
 

What you should not do is give a group multiple permission levels. I have seen many times over the years where a site administrator—or more often a person who got permission because of rank in the office without the technical training to support the duties—has given a group View, Read, and Contribute. That is so very redundant. I’ve even seen a group get Contribute and Contribute No Delete on the same library, and the person who did that cannot understand why the group can still delete things. SharePoint grants most privilege when there are competing permission levels. Grant each group the least amount of privilege it needs to do its job on the corresponding lists, libraries, and sites.

 
 

Sometimes, you might need to have a list that has thousands and thousands of items where HR A, HR B, HR C, and HR D have different levels of access as the item goes through its workflow. You have the option of copying the item to a new list with the different permission settings for that item to inherit the permissions from its new parent, or you can elect to keep the items in the list and have the workflow adjust the permissions. If you have only a handful of ways you would like to adjust these permissions, you can create folders in a list and assign different permission levels to these folders. Then your workflow can change the path of the item so that it inherits the permissions of that folder and then the next and so on. You would build your views to not see folders, but the folders would affect the permission levels. This is so that you only need to worry about a handful of permission scopes rather than thousands if you were to have the workflow change the permissions on each item. While a list can support up to 50,000 unique permission scopes, it is a pain in the butt to manage that way. Additionally, the extra folders can help you get over the 5,000 items in a view threshold even if they are never visible to most of the users of the app. This is also best for data integrity. If you were to move things from list to list to work through the permission changes, you would probably end up with new Created dates that don’t align to the items properly, so you’d need to add additional columns just to track the original created date. Version control would be almost useless.

 
 

Pet Peeve

When I look at permission groups while doing a site audit to find what all is broken, I often find these common issues:

  • No text is in the description.
  • The group is owned by the individual who created it.
  • The group’s membership is visible only to those who are members.

 
 

Why is this bad?—

Everywhere you see a place to add a description, I’d beg you to add it except in your lists’ columns. A description for a permission group should probably include why it was necessary and no other existing group would work along with the date you created the group. Annotate in the description when you might have had to rename it. How often have you seen an office change its name? Don’t create a new group and delete the original. DON’T. It can create all kinds of issues later. If Human Relations changes to Human Capital, just change all of the HR references to HC. It’ll save you a lot of pain.

 
 

Groups should never have a single point of failure to update the membership, and you are that failure if you list only yourself as its owner. Make either the site’s administrators group the owner, or create new groups just for managing the membership. Assume your office is structured like CFO 1, CFO 2, CFO 3, CFO 4, CFO Leadership, CFO Front Office, and CFO Site Administrators. As the site administrator, your function is to build apps, and all of that stuff. You should not need to be involved in the office administration of bringing on new staff or removing them when they leave for a better position. If you make the CFO Front Office staff the owner of the CFO 1, CFO 2, CFO 3, CFO 4, and CFO Leadership groups but give them adequate training to understand why they shouldn’t allow someone from CFO 4 into the leadership group, there is little reason they cannot fulfill this duty better than you can. This is because you shouldn’t have all new users run through you. When I see this, it is usually because even the SharePoint site administrators now what their own little empire that so many others had been guilty of creating.

 
 

Lastly, unless you are a SharePoint site collection administrator for the Masons, everyone should be able to see the membership. Microsoft defaults this way in the rare event that your SharePoint environment is facing the open internet, and you don’t want someone to punch in the URL for each group to figure out who to phish. Obviously, if your SharePoint environment does have the open internet accessing it, lock that stuff down as much as you can and preferably with AD security groups so bad actors with nefarious motives cannot use the URLs to scan through all of the users of the environment. I usually find this kind of problem not during a site audit but when someone says their workflow won’t work. If your workflow wants to email everyone in the Leadership group but your average user doesn’t have access to see who is in that group, the workflow cannot create the email. And what does it say about your or the organization if you don’t trust your coworkers enough for them to know the membership of such groups? Should someone be walked out of your building because you believe they are a security risk?

 
 

To wrap this up, plan your permissions before you implement them, never grant permissions directly to individual users, and document everything you do. I hope that you have gotten something out of this.

 
 

 
 

SharePoint Saturday Pittsburgh

For the second annual SharePoint Saturday Pittsburgh, I got to speak again. Great venue at Carlow University, but I’ve not got the best AT&T coverage. I don’t know if it is the building or the location of the nearest tower. I stayed at the Hampton Inn in Irwin because it was very nice and less expensive than the Hampton Inn right next door. Plus, I didn’t want to worry about rush hour traffic leaving Pittsburgh when I was arriving on Friday night.

 

The schedule for this was great. I love that I know most of these speakers already. Some really great folks signed on for this. I decided to sit in on the following sessions:

 

John Ramminger’s Leveraging External Data in SharePoint Online and On Premises

Learned a lot here. Helping me to finally try to use Business Connectivity Services.

Tim Beamer’s Document Security in SharePoint, permissions aren’t enough

I think I can comfortably set up Data Loss Prevention in SharePoint for one of the guys I’m working for. I don’t know if I read about this or saw another session on it a year or more ago, but I could swear that I’d seen a lot of this content before.

My own session, SPS Analyst Series: The Build Process (I’ve given the same session over and over for a couple years now, but I do make tweaks.)

Wish I could have seen Joe McShea’s session, Spice Up Your forms and Views with Client Side Rendering (CSR), or Nikkia Carter’s session, BI: From the Basics. She is really good, but I see and talk to her often enough that I might be able to pick her brain another time.

 

Mohamed Derhalli’s Styling SharePoint Pages without Writing Code never happened.

He didn’t make it, so a bunch of us stayed in the room and just talked about crazy stuff we were running into. That is the best. A conversation is better than a lecture any day.

 

CA Callahan was the main reason I stuck around until the end of the day when I knew I’d have a five-hour drive going home. She had Now where did they put that? Overlooked web parts, features, and templates of SharePoint.

I always learn something new when I listen to her. The main thing this time was Word Automation Services. I had never even heard of that. One can create aspx files from Word documents with this. I really need to see it in action. To convert the content in a Word document from someone’s user guides or standard operating procedures, I had been publishing the Word document to a wiki then copying the html out of the body into the page where I wanted it. The best part of this was being able to have pictures come through properly formatted, and it is great for creating knowledge base articles. You can even make properly formatted Word templates for each kind of KB article you have so that the fonts, colors, and formats are all locked in place from a document library that has the template in its content type. This is definitely something I need to investigate further.

 

Sponsors of SPS Pittsburg included the following:

 

SharePoint Permission Pain

<rant>

I just need to go off for a minute.  I just got off the phone with a “SharePoint guy” for the leadership for some potential work that I am not going to do.  These individuals do not know or understand SharePoint from the fundamental understanding of how they’d like to use it for the enterprise to the understanding of where to click to do simple things.  They wanted control so much, they would not give me full control to their site.  They told me they’d give me design but then take it back each day when I had no more need for it.  The “SharePoint guy” doesn’t know SharePoint or else they’d have him build these libraries.  We aren’t even talking hard stuff.

The leadership—these mid-level managers—would have full control.  These are the same people who don’t know how to use SharePoint and could really use a class.  They have full control and the guy (me) who had designed the permission architecture they agreed to kind of sort of use a few months ago—it took this long for them to agree to implement what they believed was a good design—gets design.  I will not have the ability to alter the master so that I could put a disclaimer banner of sorts on each page of the site that regulations mandate they do.  The people running their farm haven’t bothered to implement these banners in the last six or so years they had the environment up and running.

</rant>

It really blows my mind.  I feel like Beatrice from the Essurance ads.  “That isn’t how any of this works!”

So how does this happen?  I won’t say it is Microsoft’s fault.  That would be an easy cop out that a lot of folks use far too easily.  Understanding how to use an expensive platform like SharePoint should fall on the shoulders of the people who decided to purchase it, whether they learn it themselves or trust in the people they decide to hire to manage it.  The problem is that few people bothered to question whether or not Team Site Owners, Team Site Members, and Team Site Visitors are the appropriate permission groups a site should have.

Leadership, those with rank and privilege in the organization, own their content.  No one should ever question that, but when someone creates a new site and sees an owners group, they automatically assume that the data owners are the Team Site Owners.  Now, these individuals who are too busy to take a SharePoint 101 class and probably don’t even have the time to open all of the email in their inboxes are the ones who will get the access requests because they didn’t bother to adequately plan for all of the people who will need to access the site.  They will give all of the underlings, including the younger more technically savvy members of the team, only contribute permissions, often by individually granting them permission rather than putting them in the Team Site Members group.  Often, I’ll see that they will add everyone outside of the team to the Team Site Members group because Microsoft defaulted the description of the group to say something like, “Use this group to grant people contribute permissions to the SharePoint site: XYX.”  Eeekk!!!  “Hey, let’s go create another 100 sub sites with new permission groups for each of them and manage them this way so that Bob Smith needs to be added to 100 XYZ Members groups!”  Some of these people think this is not just acceptable but encouraged because the site creates these groups with that description automatically.

The data owners—leadership of the organization—should get their own group.  That group should be given contribute or read permissions to all of the content they might want, which may or may not be everything on the site.  They might not want to see 50 libraries on the site.  Maybe they only want to see the links to lists and libraries they give a damn about because they only care about the 30,000-foot view of the data and don’t care about how you make the sausage.  That is assuming they are good leaders/executives.

Think about the user experience for yourself as someone who has SCA rights or full control to a site.  You get to see every single list and library as links in the quick launch or global navigation or custom menu thing you’ve built.  That can be a little overwhelming for most of the users.  It is like sitting down in front of the menu at the Cheesecake Factory.  They make a wonderful Cuban sandwich if you haven’t tried  it yet, but do you know how much other stuff I ate before I found the sandwich I hold so dear?  The more things you give them to click on, the longer they will take to make the decision as to what they’d like to click on.  We’ve already discussed that the leadership doesn’t have that much free time.  Why would you agree to make their lives harder because they want to micromanage what you are building for the workers in the team to enable them to be more efficient in what they do?  Push back.  They didn’t get where they are because they are stupid, but they are ignorant or ill-informed because of a lack of training and bad SharePoint people.  You do them a disservice by not educating them when they demand full control.

That is enough for now.  I’m happy to get it off of my chest.

Lessons: Developing a SharePoint app for a high trust environment

I just went through the harrowing experience of developing a SharePoint app for a high trust environment. Some of it was due to office politics, while most was due to plain miscommunication and incompetence.

There are some important lessons to be garnered which I think apply to any instance in which you are contemplating developing an app for your environment.

  1. High trust apps cannot be “ported” to cloud solutions, such as SharePoint Online or Office 365. If you code your app correctly, you can reuse the code and the overall framework of your app. For instance, I coded my app using the Client Side Object Model (CSOM), which is one of the recommended languages that Microsoft wants you to use when building an app; therefore I can reuse my code should my client want to move to the cloud in the future.
  2. If you are going to be developing a high trust application, you need to make absolutely certain that your infrastructure is appropriately configured. This is way too much of a topic to cover as it is expansive, and I don’t say that lightly. It doesn’t help that Microsoft’s own documentation is lacking and in some cases just wrong (I’m looking at you, MSDN Powershell code). If your environment is not configured properly, you will be fighting an uphill battle with an almost infinite number of possible moving factors which might cause your app to fail.
  3. Consider the return on investment (ROI). If you can accomplish the same end goal building a traditional, farm based solution, I would advise you go with the latter and not the former just because it’s newer and shinier. Chances are if you are building an app in a high trust environment, like I was with my client, there is no chance you are going to the cloud anytime in the near future, irrespective of what the Microsoft talking heads are telling you. Plan and build accordingly. Be smart about the choices you make when contemplating the SharePoint app model versus a traditional solution.
  4. LISTEN TO YOUR INFRASTRUCTURE PEOPLE. Just because other developers on the ground happen to be Microsoft, this doesn’t mean they are the best equipped to be giving you input on the solution you are building. Your app will only be as successful as the actual configuration of the environment you are deploying on. Make sure you get all the appropriate certificate serial numbers, issuer IDs, and token information necessary for your app from the infrastructure folks.

With SharePoint 2013, there are some quirks which just cannot be overcome with a standard, traditional farm solution, irrespective of the code you write. In this case, you will have no choice but to write your app using the app model. I had this misfortune particularly with the site collection provisioning process, which at a certain step could not be overridden no matter what using a traditional farm solution, but that is a topic for another time.

What is high trust? High trust is basically the same concept as with a traditional farm solution, in which your app will have “superpowers” to the farm, and therefore can have the same ramifications as a traditional solution if something were to go wrong. Where it deviates is the fact that you can build your app so that it is hosted completely outside of SharePoint, therefore isolating and preventing it from screwing with your SharePoint instance. Therefore, your app can go “down”, and will not take SharePoint with it.

This topic can go on and on, but that is it for now. I’ll have much more to share in the near future.

SharePoint Testing

I just realized I’d left this unpublished from a few weeks ago. This should have been published before my trip to SharePoint Saturday Atlanta.
—-BREAK—-
So I’m working with a new client again, and I’m seeing what I’ve often seen with other previous clients: test sites and test lists and even testtesttest2 lists. This drives me nuts for a few reasons:

  • They are usually old. If you don’t know your job as a SharePoint person and need to create a test list for you to figure things out, admit you don’t know how SharePoint works.
  • They lack any kind of context. It might have just the title column, no records, and modified last 5 months ago. How do I know if it holds any value to anyone whatsoever?
  • Whoever made them didn’t change the permissions or correct the navigation for it. This is what drives me nuts the most. Not only do you obviously not know the platform, you are advertising it to everyone who can see the site that you don’t know what you are doing and are cluttering up their UI.

If SharePoint were your house, we’d already have had an intervention for your hoarding.

Just stop it already.

In another client’s O365 environment, they were looking to create another web application (paying a lot more money by the way) to have a testing area, but they weren’t doing some kind of crazy code affecting O365. It wasn’t necessary at all. I’m glad I stopped them.

So here is my freebie to everyone out there.

O365/SharePoint Online Users

If you are an O365 customer, you might want one site collection as a test environment.

Why?

Because you do need a place to train other people and a place to make new masterpages without deploying the new look and feel right into production. I’ve seen too often someone create a new masterpage and roll it out without being approved properly. Bad idea. Create the new site collection and then a NEW copy of the masterpage. NEVER edit the defaults. Just don’t. Work with it there and fill the site with a bunch of lorem ipsum junk text. You’ll get a better feeling for how things will look. Also, don’t forget to add a few dozen links to your quick launch and global navigation to see how well they look under the new master.

You do not need to put new lists in this environment to test them and then build the exact same thing in your production sites. That is just silly. That is beyond silly. This is not traditional application development with rounds and rounds of software development design meetings and half a dozen folks creating their own pieces of code that others will piece together to make this one beautiful application in six months. SharePoint is a middle platform to create applications in minutes. If you don’t like it, delete it. If you create it properly, use the same content type over and over to make the application for multiple groups of users.  It could also be that place where you and only you have your test lists because you don’t know how to make a feature work properly, but that still wouldn’t be the best place for the test list.

SharePoint 2013 On-Premises Users

You have the world as your oyster with your own environment, but you still load it up with test sites and lists.  Shame on you.  Other options are available and here is what you need.

Scenario 1:  We will write custom C# applications that will need binaries injected in the hive.

Solution:  Build another farm.  Scale it to have the same number of web front ends (WFEs) running the exact same version as production.  You will only need one SQL box on the back end.  All we are trying to do is replicate the environment as much as possible with far fewer resources like memory and storage.  You will need to change files on the WFEs in this scenario.  While highly customizable, this is really only advantageous to very few customers out there doing some really amazing things.

Scenario 2:  We will write some custom JS, CSS, and HTML and use the client-side object model (CSOM) to make things pretty and more functional.

Solution 2:  Still build out a second farm.  BUT why?  If you are an IT systems administrator who has been in this business for more than a year, you will know and will probably have experience of getting a patch that has broken a server or two, especially after you have hardened the servers (STIG’d in my market) to make them more secure.  How do you know which patches from Microsoft or any of the other third party applications that you have running on all of your boxes will not screw up your environment?  You test.  You will only need one WFE.  The SQL instance will be a new instance on a cluster that you are using for ALL of the other SQL things going on in your environment.  Again, we are trying to replicate your environment with as few resources as possible.

But what about SharePoint testing?—Aside from testing a cumulative update before adding it to all of the WFEs in production, you don’t need to use this test environment for anything else.  If you aren’t running any monitoring software that you need to patch on your production WFEs, you might not even need this.  Microsoft has an OK record of not destroying SharePoint farms with patches, but it is by no means spotless.  I do recall a few years ago a 2010 update that screwed up a lot of folks.  Those patches are the only things you are testing.  You aren’t testing lists, web parts, sites, or anything else.  Don’t even give anyone else the URL if you are the systems admin or farm admin for SharePoint in your IT department.

So where do you test things?

In production.  Let me explain it as simply as I can.  When you write up a document in word and it is in draft form, do you keep it on a different computer?  When it is ready to print, do you copy it out of the draft version and paste it into a clean document?  Of course you don’t.

Build the entire application right where you need it.  The key is to change the permissions on the list/library/site/etc. to the pieces of it so only those involved in building it can see it.  When it is ready for go-live, change the permissions.  That is it.  You can even update your navigation, unless you are creating a lot of hard links, because security trimming in SharePoint won’t show those links to people until they have the permission to see them.  If, however, you are using a lot of hard links in the navigation, set the audience on those links to just those involved in building.  When the application is ready for go-live, take the audiencing off.

If you are a client, looking for good SharePoint folks and you see a bunch of test crap in your environment after you hire them, recompete that contract ASAP.

Add a Link to Manual Workflow

I’m building out a little thing for the company’s recruiters for when we add a friend to the list. An email goes to the boss of all of the recruiters saying one dropped. I have a link to the resume and the item, but I also had all of the pertinent information in the email. So even though the boss would be able to click on the link, go to the list item and click on my custom button to assign a recruiter, I thought I could cut out a step. I just created a link to the workflow I use to assign the recruiter.

ManualWorkflowPostPic0

The URL for that looks like this:

https://xxxxxxxxxxxxxxx.sharepoint.com/wfsvc/6f981489c973485293741943682bda4a/WFInitForm.aspx?List={1519fb4a-ef7b-468f-ad4f-7b0b2fea8f6a}&ID=8&ItemGuid={83D33457-7C55-41F9-938D-69143006E3AC}&TemplateID={B7CB07B2-F62C-49D2-9848-11858888F65F}&WF4=1&Source=https%3A%2F%2Fxxxxxxxxxxxx%2Esharepoint%2Ecom%2FLists%2FReferAFriend%2FAllItems%2Easpx

I know that looks like a crazy URL to build, and it is.

First, you can strip off the source. That is so SharePoint knows were to drop you after you submit. It is coming from an email, so we only really need to build this:

https://xxxxxxxxxxxxxxx.sharepoint.com/wfsvc/6f981489c973485293741943682bda4a/WFInitForm.aspx?List={1519fb4a-ef7b-468f-ad4f-7b0b2fea8f6a}&ID=8&ItemGuid={83D33457-7C55-41F9-938D-69143006E3AC}&TemplateID={B7CB07B2-F62C-49D2-9848-11858888F65F}&WF4=1

It comes in a few parts. You know what list this is, so we have the front of the URL, the list GUID, the ID, the ItemGUID, and the template ID. Separating much of these are braces {} so that the URL is constructed correctly. I thought I could use this string:
ManualWorkflowPostPic1

Well, guess what. There is no way to add those braces to a string. Microsoft will send you back this error:

ManualWorkflowPostPic2

That is unless you put those into their own variables. So I made all of these variables for the GUID, ID, open bracket, and close bracket:

ManualWorkflowPostPic3

Then, I changed my string to this:

ManualWorkflowPostPic4

Now I am able to insert it into my email to the management.

ManualWorkflowPostPic5

The management doesn’t like going outside of Outlook for anything, so this is the best middle ground I could do until I build an Office Add-in. I might do that in three years.

A Screw Loose

I often complain about neck pain. I usually share this with people soon enough because people ask me why I hurt, so I’ll just save my breath a little and tell everyone. It still hurts, but it isn’t like it used to be. On January 17, 2011, Martin Luther King Jr. Day, a guy pulled out of a parking garage and attempted to make a left on a four-lane road, K Street in DC. There was a bus blocking his view of me coming down the road, so he hit my passenger side. I didn’t notice the pain at first. In fact, it was several weeks later when I was driving on the highway and sneezed. Half a minute later, I felt this electrical pain going down my left arm. Considering my family history, I thought I was having my first heart attack. I pulled over and started to cry. I thought it was over, my life was done, no one could save me now. After two minutes of some excruciating pain, everything was normal again. No pain. Laughing hysterically, I knew I dodged a bullet but needed to see my doctor.

Long story short, my neurosurgeon figured out it was because of the accident. He eventually gave me a cervical fusion of C5, C6, and C7 by going through the front of my neck and pushing my throat to the side. I was off work for six weeks. My daughter was just six months old at the time of my surgery, eight months after the accident. The doctor forbid me from picking her up for months. Some of the drugs made me feel just stupid. I’d stop in the middle of my sentences forgetting what was going on. I went back in periodically to get a check up. Each time I got new X-rays. A little more than a year after the surgery, I was starting to feel a lot more pain without any more activity. My X-ray showed something scarey. One of the bottom screws in C7 had come out a little bit. I literally have a screw loose.

The bottom screw there pokes out 3.5mm.
The bottom screw there pokes out 3.5mm.

The doc decideded I needed another surgery to put to metal rods in my neck from the back instead of the front. Because the penticles (pieces of the vertabra that extend horizontally) at C7 were too thin, he needed to jump down to T1 and T2. C7 essentially floats now like a busted kitchen cabinet hinge. I can feel it sometimes when I turn my head moving when it isn’t supposed to. I feel better, but I still hurt. Most of the day I have a dull pain that gets progressively worse until I can lay down. If I look down too much from reading or cooking, it gets bad quickly. Before the surgeries, I wouldn’t feel much pain at all most of the day, but I’d fall down on the ground and cry like a baby if I sneezed. Successive sneezes were awful.

The scar on the back of my neck is pretty awesome. I want a tatoo of a couple battery symbols or “Warranty void if opened by unlicensed technician” next to it. Any ideas?

It still itches often.
It still itches often.

So you know how the doctor asks you to rank your pain on a scale of 1 to 10? I have a new reference point for what a 10 is. Makes you think about what is important in this world.