X

Technical info and insight on using Oracle Documaker for customer communication and document automation

Try Oracle Cloud Platform For Free

Quick Start with ODEE 12.6.3 on a VM

Andy Little
Technical Director

If you're tasked with evaluating Oracle Documaker Enterprise Edition (ODEE) and some of its integration capabilities, you might find it to be a somewhat daunting task, given that ODEE is a multitiered application and requires a database and a WebLogic application server. What if you need to see how its schemas are deployed to Oracle DB? Or perhaps you want to explore deployment on WebLogic Server (WLS), or its integration with WebCenter Content (WCC), or perhaps how you might set up load balancing with Oracle HTTP Server (OHS). Raise your hand if you have free time enough to locate, download, install and configure all of these  components. If you raised your hand, by all means, forge onward. If you're pressed for time, then consider the approach I'm going to discuss here, which starts with a virtual machine available on OTN that contains Oracle DB, WLS,  Oracle HTTP Server (OHS) already configured. This is a slightly different approach than my previous post, in which we installed Oracle Linux from scratch. You can use that approach as well, but this much quicker, and it's portable.

Oracle has made available a VirtualBox disk in compressed format (OVA) that you can download here - ensure you take a look at the readme guide that discusses the overall set up of the machine. Download and install VirtualBox, then download the OVA file and the readme. Follow the instructions in the readme to start importing the VirtualBox appliance. It's going to take some time, so take this opportunity to obtain ☕️?. Also, just FYI, the installed version of Fusion Middleware (FMW, which includes WebLogic and the ancillary components used by ODEE) is 12.2.1.0. If you've reviewed the system requirements document for Documaker 12.6.2 (I'm taking care specifically to reference 12.6.2 here since the documentation for 12.6.3 hasn't been released yet)  you'll note that the prerequisite version of FMW is 12.2.1.2. Since we're just doing this for exploratory purposes we should be fine - I haven't found any issues running in this configuration, but I wouldn't use it for production by any means! While that's importing, head over to edelivery.oracle.com and grab a copy of ODEE 12.6.3 for Linux.

By now you should have a virtual machine called Oracle WebCenter Portal 12c R2 (12.2.1) in your list of VMs in VirtualBox. The Readme mentions creating a shared folder between your host computer and the virtual guest, so don't forget to do that. You may see an "invalid settings detected" message in VirtualBox, depending on your particular host hardware/software configuration, and you can choose how to handle those. I ignored the message about too little video memory (we only need a terminal, so no X Server will be running). Fire up the machine and in a few moments you should see a terminal window, and you can login using the credentials provided in the readme. By default the machine is configured with a host-only network, so you won't need to configure anything to get the network to function. I prefer using iTerm on macOs for my terminal work, but macOs already has ssh running on port 22, so I need to set up the port forwarding on the VM. At the bottom of the VirtualBox window, click the network icon and select Network Settings... then under Advanced, click Port Forwarding. Set the Host port to a suitable port (I chose 7722) and leave the guest port set to 22. Click Ok twice. You should be able to ssh from your host machine to the guest machine on the port you specified. Note that my host is macOs, which has SSH support already, so I'm starting from the terminal on my MacBook. If you're running on Windows, you can use PuTTy or other SSH client as you see fit.

% ssh oracle@wcp12cr2 -p 7722
The authenticity of host '[wcp12cr2]:7722 ([127.0.0.1]:7722)' can't be established.
RSA key fingerprint is ****.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '[wcp12cr2]:7722' (RSA) to the list of known hosts.
oracle@wcp12cr2's password:
Last login: Wed Mar 25 07:17:31 2020 from localhost
[oracle@wcp12cr2 ~]$

At this point we can start up some of the basic services, however, if you just start by following the instructions in the Readme, you will find that you can't get all the services started. I'll spare you the lengthy details, but in short, the database passwords for various users are expired by the time you read this, and you will not be able to start any WebLogic servers. So, we need to unexpire the passwords. To do that, we need to:

  1. Start the database using vmctl, a handy script included to control the services. I'll just give you the commands you need to enter.
$ vmctl
a
start db
x
  1. Start SQL*Plus
$ . oraenv
The Oracle base has been set to /oracle/db
$ sqlplus / as sysdba

SQL*Plus: Release 12.1.0.1.0 Production on Wed Mar 25 08:03:04 2020

Copyright (c) 1982, 2013, Oracle.  All rights reserved.
Connected to: Oracle Database 12c Enterprise Edition Release 12.1.0.1.0 - 64bit Production With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options
  1. Set the default profile to not expire passwords.
SQL> alter profile DEFAULT limit PASSWORD_REUSE_TIME unlimited;
Profile altered.
SQL> alter profile DEFAULT limit PASSWORD_LIFE_TIME unlimited;
Profile altered.
  1. Get a list of specific users that we need to fix (they start with the prefix WCPVM_).
SQL> select username from dba_users where username like 'WCPVM_%';
USERNAME 
WCPVM_OPSS 
WCPVM_IAU_APPEND
WCPVM_IAU_VIEWER
WCPVM_MDS 
WCPVM_OCS 
WCPVM_WEBCENTER
WCPVM_ACTIVITIES
WCPVM_DISCUSSIONS
WCPVM_DISCUSSIONS_CRAWLER 
WCPVM_IAU 
WCPVM_PORTLET 
WCPVM_STB
  1. Reset passwords for specific users. I have a bit of SQL that we can use to reset the passwords to be exactly what they are now, without having to know what they are, and we can set them to unexpired status. Edit the script below and replace the username where indicated based on the results above, keeping in mind that usernames are case-sensitive. Cut and paste into SQL*Plus and repeat for all users.
SET DEFINE '&'
SHOW DEFINE
DEFINE USER_NAME = '**REPLACE WITH USERNAME **'
DEFINE OLD_SPARE4 = ""
DEFINE OLD_PASSWORD = ""
COLUMN SPARE4HASH NEW_VALUE OLD_SPARE4
COLUMN PWORDHASH NEW_VALUE OLD_PASSWORD
SELECT  '''' || SPARE4 || '''' AS SPARE4HASH,  '''' || PASSWORD || '''' AS PWORDHASH FROM SYS.USER$ WHERE NAME = '&USER_NAME';
ALTER USER &USER_NAME IDENTIFIED BY VALUES &OLD_SPARE4;

You should see User altered after each copy-paste-enter into SQL*Plus.

  1. Exit SQL*Plus:
SQL > exit
  1. Start the services. I like to start fresh, so first I'll stop everything. If you run vmctl and everything is supposed to be stopped, but something is still running, note the ID number (pid) of the process, exit vmctl, then run kill -9 pid. Restart vmctl and start basic services.
$ vmctl
0
Starting Database Listener ...
.
Starting Oracle Database ...
.
Database Services Successfully Started.
.
Starting Web Tier [OHS] ...
...............................
Starting WebLogic Admin Server ...
...............................
Starting Portal [WC_Portal] ...
...............................

If you care to review the logs for some of these services you can tail them here:

  • OHS: /oracle/fmw/ohs/user_projects/domains/base_domain/servers/ohs1/logs/ohs1.log
  • AdminServer: /oracle/domains/webcenter/servers/AdminServer/logs/AdminServer.log
  • Portal: /oracle/domains/webcenter/servers/WC_Portal/logs/WC_Portal.log

Once that's complete, you can stop the Portal server (we don't need it for ODEE).

$ vmctl
a
stop portal

Next, we need to configure yum and update a few packages, which we can do while the above operations are completing. Open another terminal window and enter the following:

$ sudo -i
# cd /etc/yum.repos.d
# mv ./* ~/
# wget http://public-yum.oracle.com/public-yum-ol6.repo
# cd ..
# sed -i 's/proxy=/#proxy=/g' yum.conf
# yum install -y libaio libaio.i686
# exit

Now, you can use scp to copy over the ODEE installer. Note: because the ODEE installer uses X Windows, you'll need to have an X Emulator on your machine (I use XQuartz, if you're on Windows you can using Xming. Copy the ODEE 12.6.3 installer to the guest using scp (don't forget to specify the correct port), then connect via ssh to the guest with the -Y option so X11 forwarding happens, and unzip the installer.

% scp -P 7722 V995344-01.zip oracle@wcp12cr2:~/
% ssh oracle@wcp12cr2 -p 7722 -Y
oracle@wcp12cr2's password:
Warning: No xauth data; using fake authentication data for X11 forwarding.
Last login: Wed Mar 25 07:29:54 2020 from 10.0.2.2
/usr/bin/xauth:  creating new authority file /home/oracle/.Xauthority
[oracle@wcp12cr2 ~]$ unzip V995344-01.zip
[oracle@wcp12cr2 ~]$ ./Disk1/runInstaller
Starting Oracle Universal Installer...

If everything has worked to this point, you see the ODEE installer window pop up. Let's walk through the installation. We are going to install DocFactory to a new Oracle Home directory, but we will be deploying the WebLogic artifacts to an existing domain and server, which makes things interesting. Why? Because we want to reduce the amount of resources consumed by the virtual machine, and it's something technically interesting to do.

  1. Click Next on the welcome screen.
  2. Set the Oracle Home directory as /oracle/odee and click Next.
  3. Set a password for the documaker user. Click Next.
  4. Set the Oracle database details. Host=localhost, Port=1521, Database name=orcl, Connection Type=ServiceName, Advanced Compression=checked. Click Next.
  5. Set a password for the dmkr_admin database user. Click next.
  6. Set a password for the dmkr_asline database user. Click next.
  7. Set the WebLogic details. User=weblogic, Password=welcome1 (this is from the Readme doc for the VM, since the AdminServer already exists!), Host=localhost, Oracle Home=/oracle/fmw/wcp12c, Project Path=/oracle/domains, Domain Name=webcenter, Admin Server/Port=AdminServer, Port=7001. Set the remaining values to empty, and click Next.
  8. Set the JMS Server details. Normally an ODEE installation will create a new managed server to deploy JMS resources, however, WebCenter Content already has a JMS server so we will co-deploy it. Provider URL=t3://localhost:16200, Principal=weblogic, Credentials=welcome1. Click Next.
  9. Use the default hot folder and click Next.
  10. Set an SMTP server if you wish, otherwise click Next.
  11. Set UCM (WebCenter Content) details. Enable=True, User=weblogic, Password=welcome1, ConnectionString=idc://localhost:4444, Document URL=<leave as-is>. Click Next.
  12. Click next through UMS Details.
  13. Click install to start installation. While this is progressing, on your virtual machine host you can open a browser and navigate to http://localhost:7777/console and login with the weblogic/welcome1 credentials.
  14. Click Next, then Finish once the installation is complete.

Now that the installation has completed, it's time to do the post install steps. Go back to your terminal, and issue the following commands. I will omit the responses back in the terminal for brevity.

	$ . oraenv
	$ cd /oracle/odee/documaker/database/oracle11g
	$ sqlplus / as sysdba @dmkr_admin.sql
	SQL > exit
	$ sqlplus / as sysdba @dmkr_asline.sql
	SQL >
	$ sqlplus / as sysdba @dmkr_admin_user_examples.sql
	SQL >exit

If needed you can execute additional SQL scripts to install other languages besides English. Next is deployment of the WebLogic resources. This is slightly different from a typical install since the domain already exists. Follow closely.

  1. $ cd /oracle/odee/documaker/j2ee/weblogic/oracle11g/scripts
  2. $ nano weblogic_installation.properties
    1. Search and replace '<SECURE VALUE>' with the appropriate passwords specified in the installation. The passwords are stored encrypted in the database however they are not scripted in the deployment scripts since they are stored in plaintext. Replace them here with the values you used in the installer.
      1. jdbcAdminPassword : DMKR_ADMIN password
      2. jdbcAslinePassword : DMKR_ASLINE password
      3. jmsCredential : welcome1
      4. adminPasswd : documaker user password
      5. weblogicPassword : welcome1
    2. Locate the following settings and set them all to UCM_server1 - this is case-sensitive so be aware.
      1. nameDmkrServer
      2. nameJmsServer
      3. nameIdmServer
    3. Locate the following settings and set them all to 16200
      1. portdmkrServer
      2. portJmsServer
      3. portIdmServer
    4. Save your changes and exit nano.
  3. Run wls_addto_domain.sh. Press enter to start the load of ODEE resources to the existing domain.
  4. Run wls_add_correspondence.sh. Press enter to start the load of Documaker Interactive to the existing domain. You may see several errors about the domain already existing; these can be ignored.
  5. Start AdminServer and UCM_Server1 using the vmctl script:
    1. $ vmctl
    2. (a)dvanced Options
    3. stop admin - wait for this to complete.
    4. start admin
    5. start content
  6. Run additional scripts:
    1. $ create_users_groups.sh
    2. $ create_users_groups_correspondence_example.sh
    3. $ curl http://localhost:7001/jpsquery/ -- if you're wondering why, it's because we have OHS sitting in front of WebLogic, and that's the front-end when we attempt to access web apps outside of the guest system. We haven't configured the WebLogic plugin for Documaker applications yet that will allow us to access it from our host, so we can run curl on the guest for this configuration.
  7. Deploy the reference implementation MRL:
    1. $ cd /oracle/odee/documaker/mstrres/dmres
    2. $ ./deploysamplemrl.sh
  8. At this point we can start DocFactory, and drop a test file in. Return to the terminal, and:
    1. $ /oracle/odee/documaker/docfactory/bin/docfactory.sh start
    2. $ cp /oracle/odee/documaker/mstrres/dmres/input/local_print.xml /oracle/odee/documaker/hotdirectory
  9. In order to be able to access the web applications from the host machine, we need to configure the WebLogic proxy plugin and add our applications to it.
    1. $ nano /oracle/fmw/ohs/user_projects/domains/base_domain/config/fmwconfig/components/OHS/ohs1/mod_wl_ohs.conf
    2. Paste in the following, next to the other settings:
<Location /DocumakerAdministrator>
WebLogicHost wcp12cr2
WebLogicPort 16200
SetHandler weblogic-handler
</Location>

<Location /DocumakerDashboard>
WebLogicHost wcp12cr2
WebLogicPort 16200
SetHandler weblogic-handler
</Location>

<Location /DocumakerCorrespondence>
WebLogicHost wcp12cr2
WebLogicPort 16200
SetHandler weblogic-handler
</Location>
  1. Press CTRL-O <enter> CTRL-X.
  2. Now we need to restart OHS to pick up the change, which you can do via vmctl:
    1. $ vmctl
    2. a
    3. stop ohs
    4. start ohs

And finally, because these applications want to use HTTPS, we have two choices: we can either disable HTTPS on the applications or we can enable SSL on the UCM_server. However, there's an added complication here in that we're using OHS on the front end and configuring SSL to work on two levels (browser-OHS and OHS-WebLogic) is another blog post. So for the time being, we'll disable HTTPS on the applications, but just know that if you're evaluating WebLogic and Documaker on the basis of security, this is not a recommended approach. It's just for convenience.

  1. Turning off HTTPS in Documaker applications is a two-part process. The first part is configuring the applications. The second is redeploying the applications. Note that the default deployment uses the DD Only model, which means that you cannot administer the application's configuration from WebLogic console and have to manually adjust it then redeploy. You may consider changing this behavior when you redeploy the application, but that is again another blog post. For now, perform the following steps in the terminal. I'm omitting the $ so you can copy/paste:
cd /oracle/odee/documaker/j2ee/weblogic/oracle11g/dashboard
cp ODDF_Dashboard.ear ODDF_Dashboard.ear.original
mkdir temp
mv ODDF_Dashboard.ear temp
cd temp
jar -xf ODDF_Dashboard.ear
rm ODDF_Dashboard.ear
mkdir temp
mv Dashboard*war temp
cd temp
jar -xf Dashboard_ViewController_webapp1.war
rm Dashboard_ViewController_webapp1.war
sed -i 's/CONFIDENTIAL/NONE/g' WEB-INF/web.xml
jar -cf ../Dashboard_ViewController_webapp1.war *
cd ..
rm -rf temp
jar -cf ../ODDF_Dashboard.ear *
cd ..
rm -rf temp
  1. Open a browser and navigate to http://wcp12cr2:7777/console (make sure you followed the instructions in the Readme for configuring your host with this information. Login with weblogic/welcome1
    1. Under Domain Structure click Deployments
    2. Tick the box next to Documaker Dashboard and click Update
    3. Click Finish
  2. Back in console, repeat the build for Documaker Administrator...
cd /oracle/odee/documaker/j2ee/weblogic/oracle11g/documaker_administrator
cp documakerAdmin.ear documakerAdmin.ear.original
mkdir temp
mv documakerAdmin.ear temp
cd temp
jar -xf documakerAdmin.ear
rm documakerAdmin.ear
mkdir temp
mv Docu*war temp
cd temp
jar -xf DocumakerAdministrator_ViewController_webapp1.war
rm DocumakerAdministrator_ViewController_webapp1.war
sed -i 's/CONFIDENTIAL/NONE/g' WEB-INF/web.xml
jar -cf ../DocumakerAdministrator_ViewController_webapp1.war *
cd ..
rm -rf temp
jar -cf ../documakerAdmin.ear *
cd ..
rm -rf temp

... and in WebLogic Console, tick the box next to DocumakerAdministrator and click Update, then click Finish.

  1. And back in console for the last time, repeat for Documaker Interactive (aka Correspondence)...
cd /oracle/odee/documaker/j2ee/weblogic/oracle11g/idocumaker_correspondence
cp idm.ear idm.ear.original
mkdir temp
mv idm.ear temp
cd temp
jar -xf idm.ear
rm idm.ear
mkdir temp
mv iDocu*war temp
cd temp
jar -xf iDocuMaker_adf_main_ViewController_webapp1.war
rm iDocuMaker_adf_main_ViewController_webapp1.war
sed -i 's/CONFIDENTIAL/NONE/g' WEB-INF/web.xml
jar -cf ../iDocuMaker_adf_main_ViewController_webapp1.war *
cd ..
rm -rf temp
jar -cf ../idm.ear *
cd ..
rm -rf temp

... and in WebLogic Console, tick the box next to DocumakerCorrespondenceAL1 and click Update, then click Finish.

At this point you should be able to login to http://wcp12cr2:7777/DocumakerDashboard and see the one test job that we've pushed into the system.

If you want to go a bit further and push documents to WebCenter Content, you need to login http://wcp12cr2:7777/DocumakerAdministrator and click Assembly Line 1 and then click Batchings. From here, you can pick a batching such as LOCALPRINT and go to the Distribution tab to enable Archive - Destination : WebCenter Content.  Save your changes and then go to Assembly Line 1 > Archiver and click Configure. Expand DESTINATION - WebCenterContent and select Configuration, and ensure the destination.name property has the Property Active box checked. Add a new property under Configuration called UCM.retry.count with a value of 0, and save it.Then you need to start the Inbound Refinery (IBR):

$ vmctl
a
start ibr

Finally, push another transaction. You can do this in the terminal:

$ cp /oracle/odee/documaker/mstrres/dmres/input/local_print.xml /oracle/odee/documaker/hotdirectory

Go back to the dashboard, and you should see your transaction. You can even login to WebCenter Content using the basic Content Server interface -- use the weblogic credential and search for documents authored by "documentfactory"

For extra credit, you can look into deploying the WebCenter Content User Interface application which is much more user-centric. Believe it or not, we're done. We have a functional web server front end, the WebLogic backend, ODEE 12.6.3 and WebCenter Content all running. I hope you found this useful -- let me know in the comments or over on the Documaker community how you fared!

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.

Recent Content