Are you having issues implementing the app?

Introduction

From time to time, customers contact us after having some difficulties establishing the HPRM Governance and Compliance App in their environment.  The difficulties are almost always caused by exactly the same things.  In this article, I want to cover what the most common challenges are and how to go about addressing them.

General points

It is important to remember that this product integrates two highly configurable enterprise applications: SharePoint and HP Records Manager.  If either of these applications is not functioning correctly, then any attempt to integrate them will fail.  That may seem like an obvious statement to make, but the number of times that this is forgotten warrants this reiteration.

In SharePoint 2013, the “app model” is provided as the way to integrate with SharePoint.  Provider-hosted apps are the model to be used when integrating with external systems such as HPRM.  Whilst this is a capable model, SharePoint is not configured out of the box to use the provider-hosted model.  There are a number of steps that need to be performed to enable this model in SharePoint.

A significant percentage of our installation document is simply about ensuring SharePoint is ready.  In fact, there is more content in the installation guide about preparing SharePoint than there is about installing the HPRM Governance and Compliance app.

Unfortunately, this has been misconstrued by some as requiring a lot of effort to install our product.  This is simply not the case.  If you have correctly configured SharePoint, then a large amount of the installation process is not applicable.

Once again, the bulk of preparation is all about making sure SharePoint is configured to support high-trust provider-hosted apps. If you are already using a provider-hosted app, you are ready to go. This is a one-time deal, and is not unique to our app.

There are reams of TechNet & MSDN articles on this subject, rather than just pointing you off to articles, we have tried to condense everything down into the installation guide. However, if you are not familiar with the app model, I would recommend researching it much more thoroughly. Here is a recommended starting point, this article has lots of relevant, related articles that I would also suggest reading:

How to: Create high-trust apps for SharePoint 2013 - https://msdn.microsoft.com/library/fp179901(v=office.15).aspx

Make sure SharePoint is working correctly

On more than one occasion, it has been found that the customer’s implementation of SharePoint was not working correctly or they had created a standalone instance of SharePoint rather than a farm.

If you are having strange behaviour showing up in SharePoint, then chances are, there is something wrong with it.  This could just be that you haven’t configured it correctly, you have used accounts that are not suitable or something has just been corrupted somehow. 

SharePoint is fussy about service accounts and permission levels, rightly so, and this is amplified when enabling the SharePoint environment for high-trust apps.

Do not proceed with installing the HPRM Governance and Compliance app if you are experiencing issues with SharePoint.  This will just become a frustrating experience for you when it doesn’t work and become a challenge for our support team to try and fault find.

Some common issues we see:

  • The certificate required for high trust apps is not put correctly on the SharePoint farm including

    • The wrong certificate used

    • Not put in the same location as on the HPRM box

  • When establishing high-trust, scripts are run multiple times resulting in multiple entries when making SharePoint a trusted token issuer.

Both of these issues are covered in the installation guide.

Following the installation guide

Over 90% of the support calls we get for this product result because the person installing did not follow the installation guide.  This was usually as a result of them:

  • Assuming that steps in the guide were optional

  • Assuming that their way of doing something would satisfy the requirements of an instruction and therefore they did not need to follow the guide

  • Just not reading the installation guide at all

  • Accidentally missing steps

  • Repeating steps multiple times

  • When a step failed assuming that it will be ok and proceeding with the installation

  • Not documenting the results of a step therefore not having the configuration values later in  the installation

Unfortunately, particularly around the configuration of SharePoint to support the provider-hosted app model, it can be difficult to troubleshoot what it is that you have done wrong.

It is very important that you follow all steps in the installation guide exactly!

Understanding the app model

The provider-hosted app model requires that most of the “work” be performed on an external server.  In the case of our app, this is one or more of the HPRM Workgroup Servers.

The app uses pages, event handlers and images that are hosted on the HPRM server in an IIS site.  Components on the HPRM server communicate with SharePoint using the client side object model (CSOM)

Image 1.png

Note that if you have a farm of HPRM servers, a load-balancer needs to sit in front of them and distribute the requests across farms.

When it comes to the pages provided by the app, it is not actually SharePoint that interacts with them, it is the end-user.

Use of a hybrid environment

We see many customers using hybrid environments where they are using SharePoint online but have HPRM hosted on premise.  In this scenario, they run into issues because they have not correctly configured their network to allow communication to occur between these services.

There are four communication paths that need to be configured:

Image 3.png

 

Path 1

This is the path that allows your end-user to access SharePoint.  Depending on your organisations requirements, this path may include requests from inside of your corporate network as well as from outside; such as from home or a public place.  Assuming SharePoint Online is configured correctly (and therefore DNS is configured etc) this path simply requires connectivity to the internet.

Symptoms if not configured correctly: user is unable to access SharePoint Online, usually shown a 404 error instead.

Path 2

The second path is the one that allows end users to access HPRM configuration pages used by the app.  Typically this path is automatically enabled for users inside of your corporate network as the required DNS entries are available and ports opened.  But this does not mean that a user outside the corporate network can access these pages.  To ensure that these pages are accessible to external users the requirements are:

  1. The IIS site must be accessible external to your corporate network.  This means that the port that you have this site hosted on must be open to the internet and being forwarded to the site.  The port used will typically be 443 as SharePoint Online only allows using external providers that are using HTTPS.

  2. There must be an internet accessible DNS entry that points to your site.  If your site for example uses a host header of hprmservice.yourdomain.com then there must be a public DNS entry that points this URL to the IP address of your server, or relevant public IP.  If there is not, then an external user will always get a 404 error when trying to show app pages.

You can perform a simple test to confirm you have configured this correctly.  From a machine that is external to your network (your phone via your telco rather than wifi is a good tool for this) browse to: https://yourhostheader/images/appicon.png

If you see an image, then you have configured this correctly.

Symptoms if not configured correctly: when external to your corporate network, a user will be shown a 404 error whenever they attempt to access pages such as the app start page and the management details page as well as if they attempt to manually manage content.

Path 3

The third path is used by SharePoint Online to respond to events.  When an event is fired in SharePoint (such as a change to an item) a web service is called on the HPRM server.  This therefore requires that SharePoint online can access your service across the internet.

The requirements for this path are the same as for path 2.

Symptoms if not configured correctly: When a managed item is modified in SharePoint, the item is not updated in HPRM.  When items are added or changed such that a lifetime management policy should be executing, the LMP fails to even start.

Path 4

The final path is used by the HPRM Governance and Compliance app to communicate with SharePoint from the HPRM server.  To facilitate this path, internet access is required on your corporate network.

Symptoms if not configured correctly: errors in the log file indicating that SharePoint could not be accessed.  The configuration tool reports an error when trying to set up the URL of the default site collection.

Using HTTPS

The use of HTTPS is recommended but not mandatory (except with SharePoint Online).  There are additional steps that are in the installation guide that are required.  These steps must be followed exactly.

The most common issues that we see with customers not being able to configure HTTPS are:

  • They use a self-signed certificate instead of a commercial certificate

  • Forgetting to remove the AllowOAuthOverHttp value when configuring high-trust apps for SharePoint (2.5.3 in  the 8.1.1 installation guide)

Symptoms if not configured correctly: unable to browse to one or more of the pages and services listed in the “Testing that HTTPS is correctly configured” section of the installation guide.

Use the right accounts

The installation guide asks for the identification or creation of some accounts to be used.  You should always use different accounts for these.  If you use the same account, fault finding will be very difficult for you and for our support team (and the first thing they will ask you to do is to use different accounts).

Additionally, do not use accounts that are marked as “System” in SharePoint.  These often cause issues.

The most common issues we see with accounts are:

  • the installation  guide was not followed and not every required is permission granted to the user

  • assuming that because the account has local administrator permissions, it has the required permissions

AppFabric issues

The app uses Microsoft’s product “AppFabric” to provide configuration caching capabilities.  In some environments, this product can be tricky to establish. 

If you get errors or unexpected results during the installation of AppFabric, you must rectify these issues before proceeding.  We have seen a number of customers have trouble with our product only to find that they actually had not configured AppFabric properly and just proceeded anyway.

There is an AppFabric troubleshooting guide in the installation guide as well as a plethora of information on the internet about this Microsoft product.

Ensure you have the right skillset

Establishing this integration requires the use of both SharePoint and HPRM.  Although you don’t need to be a master of these two products, you do need to have an understanding of the fundamentals of the two products.

Not only this, but a working knowledge of AD, DNS, IIS, and networking is also required. SharePoint and the app model touch on many different areas, and require a wide skillset.

If you are asked during install to configure something in SharePoint or HPRM, and the guides in the appendix of the installation document don’t allow you to understand what to do, then take the time to obtain the necessary skills.

As this article started off saying, this is an integration between two highly configurable enterprise applications.  You will not be able to install and configure this installation if you do not have a reasonable understanding of how these systems work.

If you don’t have the necessary SharePoint and environment skills, consider recruiting the help of somebody who does.  If you don’t have the necessary understanding of HPRM, again, consider recruiting the help of somebody who does.  And if you don’t have the necessary networking skills to configure your corporate environment to work with a hybrid scenario, find someone who does.

Summary

All the information you need to install and configure the HPRM Governance and Compliance app is there in the installation guide.  To ensure a successful implementation:

  1. Ensure both SharePoint and HPRM are in a healthy state

  2. Make sure you have the necessary skills.  If not, recruit the assistance of somebody who does

  3. Follow the installation guide

  4. If something goes wrong, reassess steps 1-3

  5. Look at the articles on this blog to see if there is assistance for the issue you are seeing.

  6. If you are still having issues, only then log a support case

Remember, the app is not complicated, but the environment pre-requisites for a provider-hosted app are. Take the time to prepare and understand this before embarking on installation.