Page tree
Skip to end of metadata
Go to start of metadata

Managing Multiple Environments

Depending on your system, needs, and resources, it can be advantageous to set up a development or testing environment separate from your production knowledgebase (KB). With a dedicated development space, complex or experimental buildout can be done without locking important production tables or records, and without risk to essential business functions in the production KB. When changes in the development environment are complete and have been tested, they can be moved to the production environment, either using Pushing Changes to Production or by rebuilding manually.

In either case, if changes are made directly in production, either to fix immediate issues or to add simple functionality, it is important to refresh all development or testing KBs with these changes before using them for new buildout.

This page offers recommendations and tips for successful management of multiple environments. For more information about maintaining the environments using sync functionality, see Pushing Changes to Production.

For information on how to make a copy of your production KB, see Transferring Knowledgebases Across Servers.   

You must have access to the admin console in order to copy a KB and to perform some of the steps discussed below.


Distinct Look and Feel

Working with multiple environments introduces the risk of users accidentally making changes to the wrong system. To help prevent these mistakes, it is important to make it obvious which environment is open. There are two common solutions, sometimes used together:

  • Set up a different Look and Feel scheme in each KB. The schemes should be very different, so the users can recognize each scheme as belonging to its environment. For example, you might use a company color palate in the production KB, but a completely different set of colors in the other KB.
  • Add a message at the top of the page, such as THIS IS THE TEST KB. This can be added to any or all of the following.  We generally recommend using the page header, as it does not take up extra space:
    • The page header on the toolbar. To edit the page headers, first check that the global variable is on - go to Setup > System > Manage Global Variables and find the Header Text global variable.  If it appears on the Customized Variable tab, then it is ready to use.  If not, go to the Variables with Default Values tab and click the Edit icon to add the header - don't add the text here, just save it without changes.
    • Then navigate to Setup > System > Edit Page Headers and use the HTML editor to add the header text you want.  The text will appear between the global search and the Welcome text at the top of the page.
    • The HTML header above the toolbar. To edit the HTML header, go to Setup > Look and Feel > Power User Interface, edit the scheme, go to the Content tab, and set the HTML Header Text field.
    • The logo. To replace the logo with something else, go to Setup > Look and Feel > Power User Interface, edit the scheme, and use Change Logo on the Global tab.

Make sure the end result gives you a development or test environment that looks very different from the production environment. You typically don't want to use custom headings like this in the production system, so people may not notice they are in the production system unless they develop a recognition for the distinct look of the other environments.

Environment Configurations

There are several configurations and/or integrations that must be kept distinct between the test and the production systems.

DocuSign

If you use DocuSign, you must disconnect the production Docusign account from the development or test environment immediately after creating it. You can set up a development DocuSign account afterward if needed, and then link the development KB to that dev account.

These steps should be taken each time you refresh content from production to other environments by copying the KB.

Disconnect the Production DocuSign Account

  1. Open the development or test environment. Do not follow these steps in the production environment.
  2. Go to Setup > Integration > DocuSign Extension and click Configure.
  3. Click Reset Access. This will disconnect the production Docusign account without damaging it in the production KB.

Connect the Development DocuSign Account

First, locate and collect the server and account information for the development account you want to connect. This is typically on a different DocuSign server than the production account.

  1. Open the development or test environment. Do not follow these steps in the production environment.
  2. Go to Setup > Integration > DocuSign Extension and click Configure.
  3. Click Change Server. You might need to click the button twice to open the server dialogue.
    Tip: If you click the button a few times and it doesn't work, click Disable Docusign Connect and then click Change Server.
  4. Enter the new server information.
  5. In the DocuSign Users section, remove any users who won't be used in this environment. 
  6. In the same section, create a new user with the email address for the administrative DocuSign user for the development account.
  7. Click Grant Access.
  8. Add any other users you need for this environment.
  9. Click Enable DocuSign Connect. A new Connect ID should appear and the system should be ready to use.

Reconnect DocuSign in the Production Environment if Needed

On the DocuSign site, log in to the production DocuSign account and go to Admin > Connect. Make sure you see an active  Agiloft connection.

If you don't see an active connection, you need to reset it:

  1. Open the production environment.
  2. Log in as the user whose account uses the same email address as the DocuSign administrative account.
  3. Go to Setup > Integration > DocuSign Extension and click Configure.
  4. Click Disable DocuSign Connect.
  5. Click Enable DocuSign Connect.

SAML and LDAP

If you use SSO with SAML, you usually need to set up a secondary SAML endpoint, and a separate SAML configuration for each system. If you have a development LDAP server, you need to configure that as well. In both cases, you will likely need a separate login page for the development instance.

Inbound Email Accounts

If your system is using inbound email accounts, you will need to create separate inbound accounts for each environment, so the development environment does not "steal" the inbound email for the production server.  It is best to create a separate test account for each production inbound account, and then to set all accounts up in the production system, but disable the test accounts there.  That way, each time you copy production to refresh the dev environment, you will just need to disable the production accounts and enable the test ones.

To disable or enable an inbound email account, go to Setup > Email > Inbound Email Accounts, edit the account in question, and on the Account tab, set the option:

Optional Email Tagging

If you are concerned about users being confused about which system is sending them email, you may want to tag the test emails.  There are a couple of ways to do this.

Set a Distinct Default Outbound Address

If most of your emails appear to come from the default outbound email address, you can simply change that address to one with the word TEST prominently featured.  To do this, go to Setup > Email and SMS > Email Server Settings.  This is good practice in any case.

Include a Tag in the Email Subject

If you want even more differentiation between production and test emails, you can set up a field variable and use it in all email templates to insert a signifying word, such as TEST, in front of the subject line of emails sent by the test system. This is more involved to set up. 

  1. Create a table called Email Prefix and create one short text field in it called Prefix.
  2. In the Production system, add one record with a blank value in that field.  In the Dev system you will change that value to TEST.
  3. In the People table, add a link to selected fields showing Email Prefix ID and Prefix values from that new table.  Set it to a default value of ID=1 (or whatever the ID is of the record you created).  This will create a global variable that can be used anywhere in the system.
  4. Mass edit users to set all of them to have this default value in the new linked field.
  5. Now update all email templates to insert the global variable at the front of the subject line, i.e.: "$global.my_prefix  Your contract has been updated"

When an email is sent from the production system, the variable will be blank.  When you send email from the dev system, if you have changed the value to TEST, that value will be displayed at the front of the subject line.

Handling Email Addresses

In the test system, it is often safest to mass edit all users to remove the email value from all users except those who will be doing the testing or development.  Otherwise, any scheduled reports or escalation rules may send email and spam users unnecessarily. 

Of course, you can also just turn off all outbound email from the dev server, but that will prevent actual testing of the changes as they relate to outbound email.

Refresh Checklist

With multiple environments, at the beginning of each development or testing cycle, if any changes have been made directly in the production system, the dev system will often need to be refreshed with those changes.  This is usually done by just copying the production system and importing it onto the test system as a new test KB.  Alternatively, sync can be used to transfer just the configuration changes, but this generally takes more time, and is only appropriate if you need to cleanse data from the dev system and deletion would be more time consuming.

To refresh other environments successfully and avoid issues and troubleshooting, it is best to create a checklist specifically to prepare for and perform a successful refresh from production.

The checklist depends on your system and configurations, so it is strongly recommended you modify this example checklist to suit your needs.

 Sample Refresh Checklist
Before Refresh
  • Make sure the non-production system is running a release that is as current or later than the production system
  • Export any necessary test data (standard test users, background data, etc.) so that you can import it back after the refresh
  • Locate appropriate license keys for the test system; it is best to store these keys in the checklist document for easy reference
After Refresh
  • Either turn off outbound email entirely or delete email addresses from all except the test users to avoid spamming people with scheduled reports, escalation rules, and normal notifications
  • Disable the production DocuSign account
  • Turn off inbound and outbound email on the test system immediately; later, reconfigure them:
    • Disable the production email accounts
    • Enable or configure the test inbound email accounts
    • Modify the default outbound email address as needed.
  • (Optional) Update the email variable record with different text (such as "TEST: ")
  • Change the main global variables, such as login URL, exit URL, staff title.  If your Dev KB is on a different server, change the hotlinkserverroot variable to point to that server's hostname.
  • Apply a different Look and Feel scheme and make any other visual changes to the test KB to make it really obvious which system you are in
  • Reinstall appropriate licenses using the test system license keys
  • Reconfigure any SSO, such as SAML or LDAP, if there is a development system; it is best to store all the configuration information in screenshots and text in your checklist document so you can just copy and paste it
  • Reconfigure DocuSign with the development DocuSign account
  • Review any scheduled imports or other integrations:
    • Replace any links that reference an environment-specific SFTP URL, such as import or export actions
    • Turn off scheduled imports or reconfigure as needed
  • Update scripts as needed; they may need to be updated or redirected, or have their global variables changed
  • Delete production data as necessary
  • Check redlining or Word API functionality to determine whether it needs to be reconfigured on the server
  • No labels