This documentation supports the 21.3 version of BMC Helix Digital Workplace Advanced.To view an earlier version, select the version from the Product version menu.

Configuring multitenancy

As an administrator, you configure multitenancy to restrict end user access to a specific company. The multitenancy capability also provides an ability to restrict the configuration data to a specific company.

If you have deployedBMC Helix Digital Workplace on-premises, BMC provides the Managed Service Provider (MSP) Config utility. Follow the instructions in this topic to run the utility and to create and activate the master tenant and subtenants. SaaS customers cannot run this utility. 

If you have a SaaS subscription of BMC Helix Digital Workplace, contact BMC Customer Support to enable the MSP mode or to create subtenants. 

Related topics

Company-level-access-to-subtenants-in-BMC-Helix-Digital-Workplace

Managing-customers

Important

You cannot use the multitenancy feature and the External Users feature at the same time.

  • If you configure multitenancy, the External Users menu is not available in the Admin console.
  • If you have already configured External users, you cannot use multitenancy as an MSP.

For more information about the External Users feature, see Portal-for-external-users and Administering-an-external-BMC-Helix-Digital-Workplace-portal.


How multitenancy works in BMC Helix Digital Workplace

  • Master tenant—The first tenant that you create by running the (MSP) Config utility is the master tenant. The master tenant is associated with a company in BMC Helix ITSM. Administrators who are members of the master tenant company can set and modify provider settings from the BMC Helix Digital Workplace Admin console.
  • Subtenant—After creating the master tenant, you run the utility again to create subtenants. If you want to create multiple subtenants, you run the utility each time you want to create a subtenant. A subtenant is also associated with a company in BMC Helix ITSM. Subtenants use the provider settings from the master tenant. 


Before you begin

Make sure you complete the following tasks before running the MSP Config utility:

Area or Product

Description

Infrastructure

  • Use a Linux machine to run the utility to create tenants. 

Best practice: We recommend you use Cent OS 7.x. 

  • Ensure that BMC Helix Innovation Studio is up and running.
  • Ensure that BMC Helix Digital Workplace is deployed.

Action Request System

  • Create a user with AR Admin permissions in Action Request System.

  • Create companies in BMC Helix ITSM by the same name that you want to create the master tenant  and subtenants in BMC Helix Digital Workplace. To learn more, see Creating companies.

BMC Helix ITSM


Task 1: To download the BMC Helix Digital Workplace MSP Config utility

  1. In the Linux machine, run the following command to create a directory to unzip the utility folder:
    mkdir/opt/dwp-tool
  2. Download the MSP Config utility to this directory.
  3. Run the following command to extract the utility folder:
    unzip  dwp-msp-config-utility

The dwp-msp-config-utility folder has the following content: 

  • rxscripts folder
  • scripts folder
  • README file


Task 2: To set the environment parameters

Set the environment parameters for the subtenant that you want to create. If you want to create multiple subtenants, you must run the script for each time by changing the values of export DWP_MSP_SUBTENANT_COMPANY_NAME and export DWP_MSP_SUBTENANT_COMPANY_USER_PASSWORD parameters. 

  1. From the extracted dwp-msp-config-utility folder, in the rxscripts folder, open the setenv.sh file in a text editor. 

  2. Set the following parameter values for logging in to the BMC Helix Innovation Studio instance: 

    Parameter

    Value

    Example value

    export IS_URL

    BMC Helix Innovation Studio URL with protocol and port

    export IS_ADMIN

    BMC Helix Innovation Studio administrator user name

    hannah_admin

    export IS_ADMIN_PASSWORD

    BMC Helix Innovation Studio administrator password

    Not applicable

  3. Set the following parameter values to define the MSP configuration:

    Important

    For parameters that you do not want to configure, set the value to blank. 

    Example: <Parameter>=" "

    Parameter

    Value

    Example value

    export DWP_MSP_SUBTENANT_COMPANY_NAME

    The subtenant company name

    Important: If you are running the utility for the first time, by default, this company will be the master tenant.

    Apex

    export DWP_MSP_SUBTENANT_COMPANY_USER_PASSWORD

    Password for the subtenant company user

    Not applicable

    export DWP_MSP_RUNMODE_VALUE
    • 2031313—BMC Helix Digital Workplace Basic license
    • 2169487—BMC Helix Digital Workplace Advanced license

    2169487

    export DWP_MSP_CHAT_URL

    Live Chat URL

    export DWP_MSP_MYIT_BACKEND_URL

    BMC Helix Digital Workplace URL

    export DWP_MSP_SENDER_EMAIL

    Sender's email address

    export DWP_MSP_SBE_URL

    BMC Helix Digital Workplace Catalog URL

    Note: Enter this value only if you have subscribed to the BMC Helix Digital Workplace Catalog, otherwise leave it blank. 

    export DWP_MSP_EXTERNAL_HOST_DOMAINS

    BMC Helix Single Sign-On URL that is common for BMC Helix Digital Workplace and BMC Helix ITSM: Smart IT to allow questionnaires to be embedded in BMC Helix ITSM: Smart IT. 

    export DWP_MSP_SBE_SYSTEM_USER

    BMC Helix Digital Workplace Catalog user name

    hannah_admin

    export DWP_MSP_SBE_SYSTEM_USER_PASSWORD

    BMC Helix Digital Workplace Catalog password

    Not applicable

  4. Save the file. 


Task 3: To run the BMC Helix Digital Workplace MSP Config utility

  1. On the Linux machine, run the following command to navigate to the scripts directory:
    cd /opt/dwp-tool/scripts

  2. Run the following command to onboard the subtenants:
    ./call_onboard_subtenant.sh
    The utility script starts executing and you can observe the progress in the console. The script includes a validation that displays whether the subtenant is successfully created or not. 

    The following image shows an example of the message after a subtenant is successfully created:

    Subtenant created successfully.png


Important

Ensure that you run the utility for to create all subtenants. Users from companies for which subtenants are not created cannot log in to BMC Helix Digital Workplace.


Task 4: To verify master tenant creation from the BMC Helix Innovation Studio UI

  1. As an administrator, log in to BMC Helix Innovation Studio. 
  2. On the Workspace tab, click Digital Workplace.
  3. On the Record Definitions tab, select the check box for Subtenant and click Edit data. 
  4. Click the record definition instance that is created when you run the script for the first time.

The fields in the record definition and populated automatically. Verify the following fields:


    1. Default is selected.
    2. Name contains the subtenant company name that you used in export DWP_MSP_SUBTENANT_COMPANY_NAME parameter. 

The following image is an example of the Subtenant record definition instance:

Verify master tenant from IS.png


Troubleshooting

The following table describes common errors that can occur when you create subtenants and steps to resolve them:

Error

Steps to resolve

The following error is displayed if you attempt to create a subtenant for a Company that is not created in BMC Helix ITSM:
image2022-9-8_18-2-19.png

Make sure that you create a company by the same name in BMC Helix ITSM.

The insufficient permission message is displayed when you run the following command:

./call_onboard_subtenant.sh

Execute the chmod +x call_onboard_subtenant.sh command instead. 


Where to go from here

Action

Reference

To set up configuration data for subtenants

To rebrand BMC Helix Digital Workplace, you must rebrand it for each subtenant

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*