Migrating BITeamwork Comments Between Oracle BI Environments

Transcription

1 Migrating BITeamwork Comments Between Oracle BI Environments April 28, 2017 BITeamwork Development Team

2 BITeamwork Version This document assists with the support of BITeamwork versions: 3.7+ Problem / Issue Description Customers may desire to move the comments entered into their Oracle BI system utilizing BITeamwork into a lower environment. The key use case for BITeamwork is a production environment use case where users having access to a Production environment are able to see production data and also enter feedback and justifications through commentary using BITeamwork relating to that production environment information. Certain customers may wish to move comments to a lower environment such as QA or Development in order to analyze or further examine the commentary entered in production without impacting the performance of the production commentary or worrying about corrupting said commentary metadata stored on the production environment. There are several elements, which impact the migration of the commentary: DBA access to and exporting of the BITeamwork repository schema OBIEE Migration techniques used to migrate the web catalog and reports initially Understanding of the Oracle BI system Ability to write SQL code Understanding of BITeamwork administration DBA restoration of a BITeamwork repository schema on a separate database There is no fully automated process for moving BITeamwork comments from one environment to another. This will be a manual process for the foreseeable future. The use case of a production system running BITeamwork does not include the migration of commentary to then work on a separately installed OBIEE environment with BITeamwork installed. This method is not supported and this document only provides technical guidance for an approach to migrating BITeamwork comments from one environment to another. There is currently no automated commentary migration process or solution through BITeamwork to migrate comments from one OBIEE environment (ex: Production) to another (ex: QA). This is a manual solution. Any assistance you may require, please consult our sales team to engage with you in a professional services effort.

3 End Goal / Resolution Ultimately the goal of this document is to show one or more comments in a source BITeamwork environment such as production compared to an environment with no comments currently in existence at a target BITeamwork environment, and then showing the process of moving the commentary metadata to the target environment, subsequently showing the target environment with the same commentary from the source BITeamwork environment. For example, taking this production dashboard to development environment will be the goal of this document to replace the one below it:

4 This document will go through the steps to migrate comments between two environments in OBIEE working with the BITeamwork repository schema and understanding the key areas where a customer may need to focus their attention or update certain BITeamwork repository schema tables in order to provide successful parity between two environments. There is currently no automated commentary migration process or solution through BITeamwork to migrate comments from one OBIEE environment (ex: Production) to another (ex: QA). This is a manual solution. Any assistance you may require, please consult our sales team to engage with you in a professional services effort.

5 Steps and Pre- Requisites This document assumes that you are using the Oracle RDBMS. The steps below are focused on Oracle RDBMS migration however, if your chosen BITeamwork repository is MS SQL Server, IBM DB2 or Teradata, then consult your DBA to associate the analogous principles as you see them here. Ideal Migration Approach to Moving Artifacts Between OBIEE As a standard practice, the approach taken to migrate artifacts (reports, prompts, dashboards, etc.) should be handled in OBIEE 11g and 12c using the archive and unarchive process. This document assumes that your implementation has followed best practices and that when migrating new development or updates to production artifacts that you have used this approach. Archive the source objects using the Catalog manager. Unarchive to same dashboard and folders on the target environment for all the source objects in question. Source Start (Archive) Target Start There is no object called ILCC Advanced. Save

6 Confirm all objects representing the dashboard page (or any other artifacts desired) are being captured correct from the source. In the example above the archive is for a dashboard page object. Below is the source dashboard page object in edit mode using the dashboard editor to see where the specific artifacts in that dashboard page are stored so we can tactically archive them from the source. Example Objects Being Migrated: Dashboard Dashboard Page Included in dashboard archive Analysis / Report Prompt Text Object /Shared Folders/BITeamwork/Dashboards/BITeamwork Migrations /Shared Folders/BITeamwork/Dashboards/BITeamwork Migrations/ILCC Advanced /Shared Folders/BITeamwork/Dashboards/BITeamwork Migrations/page 1 /Shared Folders/BITeamwork/Inline Cell Commenting/Inline Cell Commenting Double Comment Box /Shared Folders/BITeamwork/_Prompts/dp_product_year_etc_01 (part of dashboard page only) Migrate all objects using archive process to the production environment from test for example, which would be the best practice for moving development work. Then in the target environment unarchive them in the correct locations.

7 This completes the standard migration (re- migration) process best practice for incremental updates to target environments for oracle bi artifacts. Determine Source and Target Misalignment for Comment Metadata Based on the dashboards, reports, etc. being in parity per the above migration best practice, the differences between comment records found in the BITeamwork repository schema may be as follows for cell comments and other cell based annotations. Execute the following SQL Statements in both the Source BITeamwork Repository and the Target BITeamwork repository and record the results. SELECT A.CELLCOMMENTID, A.COMMENTTEXT, A.CONTEXTPROMPTFOCUS, A.GLOBALVIEWSTATEID, A.CONTEXTURLPARAMETERS, A.PROMPTSTATEID, A.DASHVIEWIDFULL, A.REPORTID, A.REPORTPATH, A.VIEWREPORTREF, A.* FROM TW_ANALYSIS_CELL_COMMENT A ORDER BY CREATEDTS DESC ; The following columns are open to suspicion when attempting the migration process: Column Name Description Critical GLOBALVIEWSTATEID The overall dashboard and dashboard page code created by OBIEE which can change based on how dashboard objects are Y migrated or updated throughout the OBIEE lifecycle. CONTEXTURLPARAMETERS The actual string of OBIEE constructed prompt name and prompt selection values used to display a dashboard/page Y

8 PROMPTSTATEID DASHVIEWIDFULL REPORTID REPORTPATH VIEWREPORTREF CELLCOMMENTID CONTEXTPROMPTFOCUS with reports filtered. This also contains the saw.dll structure with portal path to the dashboard page object itself. Recording of the prompt and its structure and potentially selected values. The OBIEE structure referenced to a dashboard view such as a report with the specifics of the report view down to the name of the view (i.e.: table,2 chart,1 etc.) including compound layout number, etc,. ex: d:dashboard~p:42o3dnfpcag976qp~r:g5mbdg3k6ctliq6g ~v:compoundview!1~v:tableview!1viewcontainer This contains a hash which gives the report ID r: and other information potentially used in BITeamwork. The actual OBIEE constructed report ID given on the page at render time. This should be the same obiee report identification provided when the object is created on the OBIEE server. This is also embedded in the OBIEE object XML which can be see through the fat client Web Catalog Manager. The logical path associated with the OBIEE web catalog structure. Usually this starts with /Shared Folders/. Typically the same value as REPORTID The primary key and identifier given to each cell comment using relational database modeling 3 rd Normal Form (3NF) development and modeling techniques. This column s value is the link for any other associates or attributes a comment may have with another table such as notifications, replies, etc. Used to capture values for fixing the prompt context of a comment when using the PromptFix option when adding comments. If PromptFix is used it may not be possible to migrate those specific comments to another environment. Y Y Y Y Y In the next section, the steps will show the required steps to determine the columns that are out of sync, if any, which may require manual intervention in order to sync the source environment s comments to the target environment s comments thus seeing the correct source environment s comments in the target OBIEE environment. Determine Source and Target Misalignment for Comment Metadata In order to determine if the above codes and IDs are similar in both source and target you can: examine existing comment values for the above columns, or

9 creating a new cell comment in the target environment and examining the table column values as shown in the above section This information will be used to help you determine what you need to change in the relational tables when you seek to migrate the comment metadata. Create a new comment in the target environment 1. In the target environment, create a new cell annotation by clicking the cell highlight icon and clicking on a cell. 2. Now use the SQL query above on the target environment and sort by created date descending to see your recorded information. Based on our development team s comparisions the fields values that typically change are the following fields: GlobalViewStateId DashViewIDFull (potentially) ReportID (potentially not captured for a cell annotation) ViewReportRef (potentially) Obviously, CellCommentID and CommentText fields will change. 3. Repeat step #2 above but this time create a new Inline Cell Comment and examine the same field changes and then capture the difference in the values comparing them to the source environment. 4. View the source system in a similar fashion to determine the above field values for the archived and unarchived objects by looking at the same table on the BITeamwork source system repository.

10 Compare the Source and Target Data Elements Stored for Comments By viewing the source and data comments for the same dashboard, where comments are created independently of each environment (specifically only the target environment needs a new comment created), the results can be compared similar to as below to determine next steps: 1. Mark down the respective values for the particular type of comment (ILC, cell annotation dashboard, footnote) per the comparison chart below and determine the deltas between the SQL Queries run on target versus source: Column Name Source Value Target Value GLOBALVIEWSTATEID knucbo4euvci379uopgscqpo7u ftqdlnk6kqb7mlcraolbmmu01e CONTEXTURLPARAMETERS Same Unless Incorrect Migration or BI Version PROMPTSTATEID DASHVIEWIDFULL d:dashboard~p:js422ganvkd0cun6~ r:86p1epb2hn97an1j~v:compoundview!1~ v:tableview!1viewcontainer d:dashboard~p:js422ganvkd0cun6~ r:86p1epb2hn97an1j~v:compoundview!1~ v:tableview!1viewcontainer REPORTID 86p1epb2hn97an1j 86p1epb2hn97an1j REPORTPATH Same Unless Incorrect Migration VIEWREPORTREF 86p1epb2hn97an1j 86p1epb2hn97an1j Result of this study This exercise tell us that for a specific type of comment created in BITeamwork, that OBIEE regardless of using best practice migrations will almost always change the GlobalViewStateID value. This means that in order for BITeamwork to sync its source environment BITeamwork repository to a target environment repository and effectively show comments from the migrated repository, that one must create an update statement after the migration that reflects a change in the table for each time of comment using the analysis above. In this case for Inline Cell Comments (ILCs) one would write the following update statement (or similar): UPDATE TW_ANALYSIS_CELL_COMMENT SET GLOBALVIEWSTATEID = 'ftqdlnk6kqb7mlcraolbmmu01e' WHERE GLOBALVIEWSTATEID = 'knucbo4euvci379uopgscqpo7u' AND REPORTPATH = '/shared/biteamwork/inline Cell Commenting' AND REPORTNAME = 'Inline Cell Commenting - Double Comment Box'

11 What to Migrate for the Solution to Work The OBIEE system and BITeamwork are still completely separate entities. They are only coupled by the BITeamwork repository in regards to how comments appear on the screen in the correct place. If the OBIEE target system is different such as it is not relatively similar to the source system then a migration of comments will be difficult. Any major differences in the following will have an impact to the ability to migrate commentary: 1. Dashboard names 2. Object locations 3. Updates in the BITeamwork repository structure Export a Database Schema in Source and Replace the Target Schema Assuming that your organization has used best practices for migration development content from DEV to TEST to PRODUCTION and that as per the above you ve conducted the tests to show where the deltas in metadata reside, the only remaining steps is to completely move the repository of BITeamwork from one location to another safely, effectively replacing the target environment BITeamwork comment repository. After which you will then need to run the SQL UPDATE statement(s) on the target environment s repository. Begin Migrating the Repository Schema To compare the version of the database to ensure there is parity: SELECT * FROM v$version; Login on the source repository database: 1. Create a physical directory on your database server and track the location 2. Access SQLPLUS 3. Create a new Oracle Directory object and grant permissions to the schema/user CREATE OR REPLACE DIRECTORY testout AS '/app/oracle/oradata/'; GRANT READ, WRITE ON DIRECTORY testout TO BITEAMWORK_OBI; 4. In another terminal window or exit SQLplus kernel, enter the following to begin exporting the schema to a dmp file, for example: expdp system/admin123@pdborcl schemas=biteamwork_obi directory=testout dumpfile=testout.dmp logfile=expdpbitw.log 5. Wait for the output to complete and then prepare to migrate the dmp file from the database server to the target database server.

12 Import the source BITeamwork Repository Schema on the Target After moving the scheme output in the section above to the target machine the following will need to be executed on the target machine: 1. Create a physical directory on your target database server and remember the location and move the output file in that location, for example C:\Oracle\oradata 2. Access SQLPLUS 3. Create a new Oracle Directory object and grant permissions to the schema/user CREATE OR REPLACE DIRECTORY testout AS 'C:\Oracle\oradata '; GRANT READ, WRITE ON DIRECTORY testout TO BITEAMWORK_OBI; 4. Stop the JEE application for BITeamwork. a. The schema will most likely have a lock on it because weblogic server data sources are connected to it, so stop the JEE application b. Navigate to Deployments in WLS, check the box for BITeamwork and choose the stop option. c. Disconnect any other connections to the target BITeamwork_OBI schema.

13 5. DROP the user and schema BITEAMWORK_OBI in order to move the content from the source to the target. a. You do not need to run the uninstall BITeamwork script. You simply need to drop the schema b. NOTE: it makes sense to backup this target schema first using the same export options shown in the previous section. This way you could restore if you bumped into issues. DROP USER BITEAMWORK_OBI CASCADE; NOTE: if needing to kill sessions prior to the DROP command working correctly, use the following logic to create necessary kill scripts to be able to drop the user cleanly, select 'alter system kill session ''' sid ',' serial# ''';' from v$session where username = '<your_schema>' Ref: how- to- drop- a- user- who- is- connected- forcefully/ 6. In another terminal window or exit SQLplus kernel, enter the following to begin importing the schema from the exported dmp file, for example: impdp system/sy$tem64@oracle12c directory=testout dumpfile=testout.dmp logfile=testoutbiteamworkmigrate.log Another option would be to import to a different schema name keeping the old schema intact. This would cause you to repoint several things in the system which is beyond this document but the imported dmp file schema could be imported to another schema name using the remap_schema syntax. 7. Confirm the imported schema results and validate by running a query on the appropriate table that the correct source repository is now on the target

14 8. Update the newly imported schema to ensure the password is the password that was used previous as something could have corrupted during transit MODIFY USER BITeamwork_OBI identified by testing123 Conduct the Update Process Based on the information above the target environment looks as below: The following update script was run, UPDATE TW_ANALYSIS_CELL_COMMENT SET

15 GLOBALVIEWSTATEID = 'ftqdlnk6kqb7mlcraolbmmu01e' WHERE GLOBALVIEWSTATEID = 'knucbo4euvci379uopgscqpo7u' AND REPORTPATH = '/shared/biteamwork/inline Cell Commenting' AND REPORTNAME = 'Inline Cell Commenting - Double Comment Box'; Start the Weblogic Deployment of the JEE BITeamwork application After which the same dashboard page on the target environment was reviewed and the target page appears as below: For reference here is the original source environment dashboard page: