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

 
 

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.  
 
  

 
 

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:  
 

 
 
  

 
 

 
 
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.  

   
  

 
 

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  

 
 
 
 
 
  

 
 
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   /Shared  Folders/BITeamwork/Dashboards/BITeamwork  Migrations  
Dashboard  Page    
Included  in   /Shared  Folders/BITeamwork/Dashboards/BITeamwork  Migrations/ILCC  
dashboard   Advanced  
archive  
  /Shared  Folders/BITeamwork/Dashboards/BITeamwork  Migrations/page  1  
Analysis  /   /Shared  Folders/BITeamwork/Inline  Cell  Commenting/Inline  Cell  Commenting  –  
Report   Double  Comment  Box  
   
Prompt   /Shared  Folders/BITeamwork/_Prompts/dp_product_year_etc_01  
Text  Object   (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.    
 
  

 
 

 
 
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  
The  overall  dashboard  and  dashboard  page  code  created  by  
GLOBALVIEWSTATEID   OBIEE  which  can  change  based  on  how  dashboard  objects  are   Y  
migrated  or  updated  throughout  the  OBIEE  lifecycle.  
The  actual  string  of  OBIEE  constructed  prompt  name  and  
CONTEXTURLPARAMETERS   Y  
prompt  selection  values  used  to  display  a  dashboard/page  
  

 
 
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  
PROMPTSTATEID   Y  
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:  
DASHVIEWIDFULL   d:dashboard~p:42o3dnfpcag976qp~r:g5mbdg3k6ctliq6g   Y  
~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  
REPORTID   identification  provided  when  the  object  is  created  on  the   Y  
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  
REPORTPATH   Y  
structure.  Usually  this  starts  with  /Shared  Folders/.  
VIEWREPORTREF   Typically  the  same  value  as  REPORTID    
The  primary  key  and  identifier  given  to  each  cell  comment  
using  relational  database  modeling  3rd  Normal  Form  (3NF)  
CELLCOMMENTID   development  and  modeling  techniques.  This  column’s  value  is   Y  
the  link  for  any  other  associates  or  attributes  a  comment  may  
have  with  another  table  such  as  notifications,  replies,  etc.  
CONTEXTPROMPTFOCUS   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.  
     
 
 
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  
  

 
 
• 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.  
  

 
 
 
 
 

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   1646095062   1646095062  
d:dashboard~p:js422ganvkd0cun6~   d:dashboard~p:js422ganvkd0cun6~  
DASHVIEWIDFULL   r:86p1epb2hn97an1j~v:compoundView!1~   r:86p1epb2hn97an1j~v:compoundView!1~  
v:tableView!1ViewContainer   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'  
 
 
 
  

 
 
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.  
  

 
 

 
6. ….  
7. …  
 
 

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.  
  

 
 
 
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:  https://javaworks.wordpress.com/2009/10/29/oracle-­‐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  
 
  

 
 

 
 
 
 
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    
  

 
 
 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: