Best Practices for Installing Bamboo Products

Best Practices for Installing Bamboo Products

You are here:
< Back
APPLIES TO:

  • All Bamboo Products
  • SharePoint Foundation 2010/2013, and SharePoint Server 2010/2013/2016

This article contains best practices for installing, licensing, and activating Bamboo products. The information provided below will guide you through the installation process and assist you with product licensing and activation. It also includes troubleshooting tips for installation problems. For more specific installation instructions, refer to the Online Documentation for your product.

Click a topic below to get started.

 

Before Installing a Bamboo Product

  • Back up your system before making any changes.
  • Verify the system requirements for the product you are installing. The system requirements can be found in the Online Documentation for the product you are installing.
  • Carefully review the installation instructions in the Online Documentation for the product you are installing.
  • If you are installing the product in a SharePoint farm, verify the installation location requirements for the product you are installing.
  • Verify the permissions required for the installation account you are using to install the product. Most Bamboo products require at least the following permissions for the installation account:
    • Must be a member of the local server Administrators group to install application files.
    • Must be a member of the SharePoint Farm Administrators group to deploy solutions to the farm.
    • Must have the db_owner role for the SharePoint configuration database.

 

  • Prepare your SharePoint farm for the installation. On all servers in the SharePoint farm running the Microsoft SharePoint Foundation Web Application service (SharePoint 2010/2013/2016), go to Start > Administrative Tools > Services and stop or restart the following services:
    • Stop the web application pools for the content web applications and for Central Administration via the IIS Manager.  (If you stop the World Wide Web Publishing Service and you are using Claims Based Authentication, the installation will fail (Note: Read KB.12732 for more information)).
    • Restart the SharePoint Timer service (SharePoint 2010/2013/2016) on all servers. Do this step even if the service is currently running.
    • Restart the SharePoint Administration service (SharePoint 2010/2013/2016) on all servers. Do this step even if the service is currently running.
  • If you are migrating a product from a SharePoint 2010 to SharePoint 2013, read KB.12896: Migrating Bamboo Products from SharePoint 2010 to SharePoint 2013, from SharePoint 2013 to SharePoint 2016, read KB.13057: Migrating Bamboo Products from SharePoint 2013 to SharePoint 2016.

About the Setup Process

In April 2017, with the Q1 Cumulative Update (CU) Bamboo introduced updated install/uninstall processes for component products (web parts). Instead of the Setup.exe Installation Application, we now supply two PowerShell scripts – one for Install/Upgrade and the other for Uninstall – to be used to install, upgrade, or uninstall the product. The install package downloaded from My Bamboo is now a *.zip file rather than a self-extracting executable.

The installation process was updated based on feedback from our customers. We are excited about the benefits the new processes offer:

Benefits
The processes are now very transparent; you know exactly what happens during the install/upgrade/uninstall. If you want/need to modify the scripts for your farm, you can do that.
If you are upgrading to a new version of a Bamboo product or if a new install updates a shared component used by another Bamboo product installed previously, the installed solution is saved before the upgrade. If the new install fails, you can easily rollback to the previously installed solution.
Rather than deploying each solution individually, deployments are queued which minimizes farm disruption by reducing the IIS Resets on the farm.
By design, the scripts are written to be compatible with PowerShell versions found on a SP2010 WFE server. Written to use the features of the older version of PowerShell, the scripts are simple and should work the same in all environments. If you would prefer to employ some PowerShell features available in new versions (e.g., output results to the grid/table), you can modify the scripts to use the PowerShell features available in your environment.

Please note the following for the new scripts:

  • The script installs all the WSPs found in the installation folder, in alpha order
  • The install/upgrade script deploys to all content web apps. If you would prefer to deploy to a single web app, you can modify the script or deploy via Central Administration.
  • Uses Upgrade instead of Install for existing components.

 

 

Installing Product Components

To install a product component, you will need to download your products installation package’s .zip and place it on the server where you will be installing the product. If you are installing your product in a farm environment, make sure to start the installation on the correct server in your farm. In general, Bamboo product components must be installed in one of the following locations:

  • On one Web front-end (WFE) server in your farm. WFE servers run the Microsoft SharePoint Foundation Web Application service (SharePoint Foundation 2010/2013 and SharePoint Server 2010/2013/2016). The product will be automatically deployed on all other WFE servers in your farm.
  • On one server in your farm running the Central Administration service. The product will be automatically deployed to all other servers in your farm running this service.
  • On ALL WFE servers in your farm. Some products must be installed separately on each WFE.
  • Some Bamboo products are desktop/server applications and do not have to be installed on a SharePoint server at all.

Required Installation Permissions For a successful installation, the installation account must have required permissions on the server and in SharePoint. The following installation permissions are required for most Bamboo products:

  • Must be a member of the local server Administrators group to install application files.
  • Must be a member of the SharePoint Farm Administrators group to deploy solutions to the farm.
  • Must have the db_owner role for the SharePoint configuration database.

You will then want to reset IIS on all web front end servers (Any server running the web application service)

Once finished you will then want to recycle the SharePoint Timer Service as well as the World Wide Web publishing service on those same web front end servers.

Once you have finished recycling these services please open IIS Manager on each web front end and stop the app pools where the product will be installed, this does not include your Central Admin App pool, leave this App pool running.

Please open a PowerShell window on the server as administrator by right clicking the PowerShell icon and click run as administrator (Preferably on a server in the farm that is running the Central Admin Service).

Once at the PowerShell command line, please type CD as in change directory and type the location where you extracted your product installer.

Example:

Once you press enter your folder location will change as shown below. You should now be in the directory where you extracted the files from the .zip installation package, this can be verified by typing DIR into the PowerShell command line and then pressing enter.

Once you press enter you should see an install and uninstall script as well as your products .wsp files as shown below:

 

Once you have verified that you are in the directory where you extracted the files please type .\install.ps1 and press enter as shown below.

 

This will start the installation process of the product, you will be asked if you would like to install to a specific web application or to all web applications:

 

Once finished restart all of the stopped app pools on each of the web front ends within IIS manager.

Please recycle the SharePoint Timer Service and the World Wide Web Publishing service on each of the web front ends.

You can now reset IIS on each of the web front ends.

This should complete the process of the install. You can verify the install by navigating to Central Admin > System Settings > Manage Farm Solutions and you should see the said product listed within this section of Central Admin.

 

Once a product feature is installed and activated, it is ready to use. The Online Documentation for your product contains information about configuring and using the product.

 

Product Licensing and Activation

Bamboo products include a fully-functional 30-day trial that starts the date the product is installed. After the trial period, you must purchase and activate a license for the product to continue to use it. Licenses for Bamboo products that are installed on SharePoint servers are activated using Bamboo Web License Manager. Bamboo Web License Manager enables management of Bamboo product licenses in SharePoint Central Administration. To activate a license, first install Bamboo Web License Manager, then activate the license as described in this section.

Note: Licenses for desktop/server applications such as List Bulk Import, User Profile Sync, and Office to PDF Conversion are activated using a standalone version of the licensing application, called Bamboo License Manager. Products that require license activation with Bamboo License Manager will include it (instead of Bamboo Web License Manager) with the Setup application. For a complete list of products licensed with Bamboo License Manager and links to instructions for activating the license for these products, read the Bamboo Knowledge Base article KB.12629: Products Activated Using Bamboo License Manager.

Installing Bamboo Web License Manager

Bamboo Web License Manager is included with the Setup program for all Bamboo products that require licensing. You only need to install it once. After that, it will be available in Central Administration and can be used to activate and manage Bamboo product licenses. To install Bamboo Web License Manager:

  • Select Bamboo Web License Manager from the Setup program.
  • Verify the installation location and required permissions listed in the component description, and then click the Install button.  Note: Bamboo Web License Manager must be installed on the SharePoint server running the Central Administration service. The installation account must be a member of the local server Administrators group and a SharePoint Farm Administrator.
  • In the installation Welcome screen, click Next to continue.
  • A system check is performed to determine if your server is ready for installation. Once all checks are successful, click Next. If a system check fails, click Abort, fix any problems, and then restart the installation.
  • Review and accept the End-User License Agreement, and then click Next.
  • In the Deployment Targets screen, the Central Administration Web application is selected by default. Leave it selected and click Next.
  • The Bamboo Web License Manager feature is installed. When installation is finished, click Next.
  • Setup displays an installation summary screen. Check that the solution was successfully deployed, and then click Close.

You are now ready to activate a product license.

 

Activating a Product License

  • Open SharePoint Central Administration.
  • SharePoint 2007: Click the Operations link. In the Bamboo Solutions Corporation section, click Bamboo Web License Manager.       SharePoint 2010: In the Bamboo Solutions section in Central Administration, click Manage My License Keys.
  • In the Bamboo Web License Manager page, expand the section (Suites and Packs or Individual Products) that contains the product you purchased, and click the link for the product name.
  • The license Status will display as Trial or Not Active for each front-end Web server until you have activated your license. Click the Status link to display the Activation page.
  • In the Activation page, enter the License Key provided when you purchased the product (also available in My Bamboo), and then click the Activate button. You need a separate license key for each front-end Web server.     Note: If your server does not have an Internet connection or if you prefer to activate your license offline, follow the instructions below for offline activation.
  • Optional Step: If you have multiple servers in your farm, you can select which front-end Web servers to license. In the Bamboo Web License Manager page, click the Choose License Server(s) link. Read the descriptive text and make your selections. You must have a license key for each front-end Web server where you install Bamboo products.

Offline Activation

If your server does not have an Internet connection or if you prefer to activate your license offline, follow the instructions below to activate a license using My Bamboo or by e-mail.

Activating a License in My Bamboo (Preferred Method)

  • Follow steps 1 through 4 in the Activating a Product License section above to access the Bamboo Web License Manager Activation page for your product.
  • In the Activation page, enter the License Key provided when you purchased the product (also available in My Bamboo).
  • Check the option Activate by E-mail, and then click the Activate button. You will be presented with a License Key and Machine Key, as shown below. Leave this Offline Activation page up or copy the two keys down – you will need them in the next steps.
  • To activate the license immediately, log in to My Bamboo with the account you created when you purchased your product. Go to the My Orders > Manage License page.
  • In the Product Licenses page, enter the License Key and Machine Key from step 3 in the boxes provided in the Activate Your License tool.
  • Click the Generate Activation Key button. You will be presented with an activation key for your product. Copy this key – you will need it in the next step.
  • Return to the Bamboo Web License Manager Offline Activation page. Enter the activation key from My Bamboo into the boxes provided, and then click Activate.

Activating a License by E-mail (Alternate Method)

If you prefer to activate your license by e-mail, you can do so. Be advised that e-mail activation takes additional time. For immediate license activation, active your license online or use My Bamboo.

  • Follow steps 1 through 4 in the Activating a Product License section above to access the Bamboo Web License Manager Activation page for your product.
  • In the Activation page, enter the License Key provided when you purchased the product (also available in My Bamboo).
  • Check the option Activate by E-mail, and then click the Activate button. You will be presented with a License Key and Machine Key, as shown below.
  • E-mail the License Key and Machine Key to Bamboo Support.
  • Bamboo Support will reply with your activation key.
  • Return to the Bamboo Web License Manager Offline Activation page (you can follow steps 1 through 3 again to return to the page). Enter the activation key provided by Bamboo Support into the boxes provided, and then click Activate.

 

Manual Feature Activation/Deactivation

Product feature activations can be done automatically at the site collection level when the product is installed. There are several reasons why you may need to manually activate (or deactivate) Bamboo product features:

  • You add a new site collection and want to add Bamboo features to it.
  • You want to remove Bamboo product features from an existing site collection.

To manually activate (or deactivate) Bamboo product features, follow the instructions below. The steps are the same for SharePoint 2010, SharePoint 2013, and SharePoint 2016.

Note: You must be a SharePoint site collection administrator to activate or deactivate features. Site collection administrators are assigned in SharePoint Central Administration.

  • From the top-level site in the site collection, go to Site Actions or the COG wheel > Site Settings > Site Collection Administration > Site Collection Features.
  • Locate the Bamboo product feature and click Activate to activate it for the entire site collection, or click Deactivate to deactivate it.

 

 

Troubleshooting Tips

If your installation fails or appears to be successful but you are unable to use your product, please perform the following troubleshooting steps before contacting Bamboo Support.

Review the Online Documentation

The first places to look for installation troubleshooting assistance are the Installing the Product section of the Online Documentation for your product and the installation requirements listed in the product Setup program.

  • Review all installation steps in the Online Documentation carefully to make sure you completed them all.
  • Make sure you installed the product on the correct server in your farm, as listed in the Setup program.
  • Verify that the installation account you used has the correct permissions, as listed in the Setup program.

If you missed an installation step or find that you need to correct a problem and run the installation again, read the information in the section Retry the Installation.

The Online Documentation may also contain additional installation troubleshooting steps, links to relevant Bamboo Knowledge Base articles, and the location of log files where you might find more information.

Search the Bamboo Knowledge Base

The Bamboo Knowledge Base contains troubleshooting, instructional, and informational information about Bamboo products. You can browse the section of the Knowledge Base for your product, or search using keywords that describe the problem or error message. To access the Bamboo Knowledge Base, click the Knowledge Base link in the Support section of the Bamboo Website or in the Help section of the Setup program.

Retry the Installation

You can run through the installation for one or more product components again if you need to. Simply run the PowerShell script again and reinstall the product.

If you have to reinstall a product, pay special attention to the following:

Stop the World Wide Web Publishing Service System checks are performed at the beginning of the installation to make sure your system is ready. You must correct any errors before proceeding. You may see a warning to stop the World Wide Web Publishing Service. If you did not do this the first time you performed the installation and the installation failed, make sure to do it the second time. Stopping the World Wide Web Publishing Service ensures that system files that must be updated are not in use. Note: If your SharePoint environment is configured for Claims Based Authentication, you should not stop the World Wide Web Publishing Service if you want to automatically activate product features during installation. You will stop the web application pools via the IIS Manager. Read KB.12732 for more information.

Install New or Remove and Reinstall? If you run the installation for a component a second time, you may want to completely remove the product first by running the uninstall.ps1 script, or by navigating to Central Admin > System Settings > Manage farm Solutions and then manually retract and remove the product solution .wsp files. You can than reinstall the product by running the install.ps1 script as described earlier.

 

Restart the SharePoint Timer Service

The SharePoint Timer service runs timer jobs that propagate the configuration changes made during product installation to all the servers in the farm. If there is a problem with the timer service, these changes may not be made on all servers. To restart the SharePoint Timer service, perform the following steps on each server in the farm:

From the command line:

  • sc stop sptimerv3
  • sc start sptimerv3

From the Control Panel:

  • Go to Start > All Programs > Administrative Tools > Services.
  • In the services list, right-click SharePoint Timer Service or SharePoint 2010 Timer, and then click Restart.

Restart the SharePoint Administration Services

The SharePoint Administration Service performs the actual configuration changes scheduled by the SharePoint Timer service during installation. If restarting the SharePoint Timer service did not fix the problem, you can try restarting the SharePoint Administration service.

From the command line:

  • sc stop spadmin
  • sc start spadmin
  • sc query spadmin will show you the service status

From the Control Panel:

  • Go to Start > All Programs > Administrative Tools > Services.
  • In the services list, right-click SharePoint Administration or SharePoint 2010 Administration, and then click Restart.

Stop and Restart the World Wide Web Publishing Service

You should stop the World Wide Web Publishing Service on all Web front-end servers in your farm during installation. This ensures that system files that need to be updated are not in use during installation. Once installation is finished, you can restart the service. Instructions for stopping and starting the service are below.

If you are troubleshooting a problem with installation and the problem appears to be with your Web server, try restarting the W3SVC service on one or all of your front-end Web servers.

From the command line:

  • sc stop w3svc
  • sc start w3svc
  • sc query w3svc will show you the service status

From the Control Panel:

  • Go to Start > All Programs > Administrative Tools > Services.
  • In the services list, right-click World Wide Web Publishing Service, and then click Stop (to stop the service), Start (to start it after it has been stopped), or Restart (to restart the service when it is running).

Restart IIS

If all other troubleshooting steps have failed, try restarting IIS.

From the command line:

  • iisreset /noforce

Open a Support Ticket

If you are unable to resolve your installation issues with the troubleshooting steps above, open a ticket with Bamboo Support. You can open a Support ticket even if you have not yet purchased a product (response times vary by support plan).

To open a Support ticket, log in to My Bamboo by clicking the link at the top of the Bamboo Support Web site. If you have not yet created a My Bamboo account, you can do so from the My Bamboo login page (see below). After you log in, select your product from the product list in the Home page, and click the Create Ticket button.

So that we may better assist you, be sure to follow KB.12456: Help Desk Ticket Submission Best Practices.

 

My Bamboo

Access to My Bamboo is free and does not require a product purchase. My Bamboo gives you access to product download and purchase history, up-to-date product information, access to Bamboo Support, and more.

To get started, click the My Bamboo link at the top of the Bamboo Solutions page. If you created an account when you purchased or downloaded your product, enter the account information you provided. To create a new account, click the new member signup link at the top of the login page.