Version 2
Visibility: Open to anyone

     

    This process is also known as cloning. It is used to create installations for testing that mirror a production installation. It is also used during upgrades when swapping out the underlying machines. This process requires a DBA from the customer to perform database dump/export and restore tasks.

     

    Before Beginning

    • The target installation, typically a UAT or staging environment, must be fully installed and operational.
      • This means that it is connected to all satellite services: EAE, search, etc. You should be able to perform a successful smoke test in the target installation, i.e., log in, create content, search for content, see activity for new content in streams.
      • Analytics should be configured and enabled if upgrading the analytics database.
    • Customizations that are not in the database (themes, wars, etc/spring) can be applied to the target installation on completion of the refresh if they are not already present.
    • If a later version of Jive is on the target installation as in an upgrade.
      • The upgrade console will appear in the browser after the refresh.
      • If a custom war is also on the target installation it must be removed so that it won't interfere with the upgrade.
      • If a custom spring configuration (~jive/applications/sbs/home/etc/spring-etc.xml) is on the target installation it must also be removed.
      • The jivePlugin table must be truncated in the target installation before starting services after the export from the source installation has been restored.

    Execution

    Step 1: Pull Data from Source Installation (Requires DBA)

    1. Block community activity and wait for EAE depths to reach 0; RecommendationQueue can take a while.
      • The queues can be monitored in the admin console page under System -> Settings -> Activity Engine, to confirm that all EAE queue depths are 0.
    2. Stop all Jive services.
    3. Create a database export of the core database.
    4. Create a database export of the EAE database.
    5. Create a database export of the analytics database.
    6. Create an archive of binary storage if it is not in the database
      • be sure to copy the databases and the binstore at the same time to avoid primary key conflicts upon restoring

    Step 2: Back up Target Installation (Requires DBA)

    1. Block community activity and wait for EAE depths to reach 0; RecommendationQueue can take a while.
      • The queues can be monitored in the admin console under System -> Settings -> Activity Engine, to confirm that all EAE queue depths are 0.
    2. Stop all Jive services.
    3. Back up installation. This step is an optional precaution so that the target installation can be restored to its original state if necessary.
      1. Back up ~jive/applications/sbs/home.
      2. Back up core database.
      3. Back up EAE database.
      4. Back up analytics database.
      5. Back up binary storage if not in the core database.

    Step 3: Preserve Data in Target Installation (Requires DBA)

    • Export the following tables in target installation or be prepared to restore the tables from the backup. Skip the tables that don't have any data.
      • Export Jive properties (see Refresh Tool Suite => Generating the SQL)
      • To persist Apps Market configuration in target environment:
        • jiveApp
        • jiveDashboard
        • jiveAppAlert
        • jiveInstanceApp
        • jiveoauthstore
        • jiveAppInstAlert
        • jiveInstAppPref
        • jiveAppView
        • jiveAppAlertAck
        • jiveApiEntitlement
        • jiveMarketOutMsg
        • jiveDevSettings
        • jiveMobileConfig
      • jiveCluster - if target and source installations are Jive 7 or later
      • jiveCredential - for bridged communities and external services requiring authentication
    • If SAML is enabled save SAML IDP metadata and keystore if binary storage is not in the core database (see Refresh Tool Suite => Export SAML Binstore Configuration)
      • SAML IDP metadata
        • Note value of saml.idp.metadata.key in jiveProperty
        • Copy out (cpio works well here) while maintaining the directory structure the key and value files in the binary storage directory
          • Example: saml.idp.metadata.key value is saml.idp.metadata-1331657616210
          • Key and value files will have the base names, 012616756133154atadatem64pdi64lmas.key and 012616756133154atadatem64pdi64lmas.bin, respectively.
      • SAML keystore
        • The key and value files will have the base names, erotsyek64lmas.key and erotsyek64lmas.bin, respectively
      • If only performing this step, be sure to clear the cache to avoid a stale keystore cache
        • ~jive/applications/sbs/home/cache/jiveSBS/*
      • If this step is not correctly addressed these things can happen
        • IDP metadata required for SAML authentication will be lost
        • Integrity of keystore will be lost
          • If the keystore exists, but the keystore password (saml.keystore.password) does not you'll see the following in the application log and the application will fail to start
            • ERROR com.jivesoftware.community.aaa.sso.saml.EOSKeyStoreManager - Keystore exists, but keystore password is blank.
          • If the keystore exists, but the keystore password (saml.keystore.password) does not match you'll see the following error in the application log.
            • ERROR com.jivesoftware.community.aaa.sso.saml.EOSKeyStoreManager - There was an issue retrieving your keystore. Most likely, your keystore password did not match what the keystore was expecting.
        • Beware of stale keystore cache: ~jive/applications/sbs/home/cache/jiveSBS/saml46keystore.bin

    Step 4: Clear Local Caches

    • Clear all caches on the target installation web application nodes (see Refresh Tool Suite => Clearing Local Cache Files)
      • Remove (rm -rf) the following on the target web application nodes.
        • ~jive/var/work/sbs
        • ~jive/applications/sbs/home/attachments/*.txt
        • ~jive/applications/sbs/home/attachments/cache/*
        • ~jive/applications/sbs/home/images/*.bin
        • ~jive/applications/sbs/home/images/cache/*
        • ~jive/applications/sbs/home/documents/*
        • ~jive/applications/sbs/home/documents/cache/*
        • ~jive/applications/sbs/home/cache/jiveSBS/*
        • ~jive/applications/sbs/home/jms/*
        • ~jive/applications/sbs/home/search/search-text-extraction/*
        • ~jive/applications/sbs/home/journal
    • Clear EAE data & streams by removing ~jive/services/eae-service/var on the EAE server.

    Step 5: Import Data in Target Installation (Requires DBA)

    • Fully restore core database export.
    • Fully restore EAE database export. If one does not exist then clear the target EAE schema/database.
    • Fully restore analytics database export. This includes all objects: indexes, sequences, etc. If one does not exist then clear the target analytics schema/database.
    • Copy in binary storage if it is not in the database
      • be sure to restore the databases and the binstore prior to starting up the target installation's services to avoid primary key conflicts upon restoring

    Step 6: Import Preserved Target Data (Requires DBA)

    1. Restore table data from step 3 if the table already exists (this may not be the case for upgrades)
    2. Restore jiveProperty extract (see Refresh Tool Suite => Executing the SQL)
      1. Best accomplished by creating a temporary table to hold the properties that were exported from the target installation
      2. Modify the attached SQL to remove matching properties from jiveProperty (e.g. 'jive.cluster.jgroup.servers.address%')
      3. Copy properties from the temporary table to jiveProperty
    3. Update or remove Jive properties
      • Remove saml.keystore.password if corresponding SAML keystore does not exist in binary storage.
      • Set officeintegration.enabled to false so that the search index will build faster when the application is started.
      • Set mail.smtp.host to dev.null to prevent unwanted email.
      • If upgrading with no EAE database (upgrading from Jive 4.5 to Jive 6, for example)
        • Set jive.eae.upgrade.complete to false
        • Remove jive.eae.current.task.count
        • Set jive.eae.upgrade.content.expire to 180
      • Truncate integration tables
        • jiveExtensionAlert
        • jiveExtensionTag
        • jiveExtensionI18n
        • jiveExtension
        • jiveOAuth2Client
        • jiveOAuth2Code
        • jivewebhookqueue
        • jivewebhook
    4. If upgrading truncate table, jivePlugin, as the plugins may not be compatible with the new Jive version.
    5. Replace SAML metadata and keystore if it is enabled and using file system binary storage. (see Refresh Tool Suite => Restoring SAML Binstore Configuration)

    Step 7: Start Jive Services

    • Start EAE, cache, search and document conversion services.
    • Start only one web application node.
    • If target installation has a newer version of Jive the upgrade console will appear when navigating to the installation with a browser.
    • Restore table data preserved in step 3 that wasn't restored in step 6.
    • Rebuild content and user search indexes unless a rebuild is started automatically by upgrade - Upgrades That Cause Search Index Rebuilds.
    • Smoke test:
      • Log in.
      • Create a discussion.
        • Embed image in discussion body.
      • See activity from discussion in activity stream.
      • Search for discussion.
      • Upload binary document and view preview.
    • Apply customizations.
    • Restart web application node, then start other web application nodes in cluster.

    Common Issues

    • The analytics ETL task never completes because of primary constraint violations.
      • A JIVEDW_OBJECT_PK or JIVEDW_CONTAINER_PK violation is a good indication that jivedw_object_seq or jivedw_container_seq, respectively, was not copied to the analytics database with the tables. Don't bother updating the indexes - other critical objects were most likely also skipped.
    • The database contains more than one Jive schema.
      • There are several metadata queries during the upgrade process. Having more than one Jive schema in the same database can case the queries to return bad results leading to errors during upgrades.
    • The admin user has access via group membership.
      • In Jive 6.0 the federated attribute was added to user groups. Queries against a pre-6.0 database to determine if a user is privileged enough to access the upgrade console can fail if the user has admin privileges via group as opposed to a user override.
    • The analytics database is not connected during upgrade.
      • Some analytics database upgrade tasks depend on a version of the core database. If the core database is upgraded before the analytics database analytics database upgrade tasks will fail.
    • The upgrade hangs on AddBinaryDocumentEditorsTableTask
      • If upgrading through Jive 5.0.0.0 and JiveForOffice-4.5.7.1 was installed before the upgrade then the database table, jiveOfficeCoAuthors, might be the source of the issue. Drop the table and restart the upgrade task.
    • Cannot get past the login page
      • If the source installation is SSL-enabled and the target isn't authentication cookies might not be sent to the target installation. Check Jive property, jive.cookies.secure, and CLI property, webapp.http_secure.
      • If the source installation has SSL enabled only for the login page and the target isn't configured for SSL authentication credentials may fail to post to the target installation when attempting to log in. Check Jive property, jive.auth.forceSecure.
    • Unable to theme the site by clicking "Customize Your Site"
      • The published theme referenced by the system property, skin.palette.published, might be missing. Remove the property.
    • Bad credentials
      • The most common reason for this during a refresh / upgrade is mismatched cryptographic information. The application uses cryptographic keys stored on each webapp server to encrypt and decrypt credentials. If the keys with which database credentials were encrypted are missing then access will be blocked, and the account may become locked. If the matching keys cannot be reinstated then new keys should be generated and the credentials cleared so that they can be re-entered:
        1. Stop the installation, including EAE
        2. Delete the master encryption system properties
          1. delete from jiveProperty where name = 'jive.master%'; (2 rows)
        3. Truncate core database table, jiveCredential.
        4. Delete the encryption keys on webapp node
          1. rm -rf ~jive/applications/sbs/home/crypto