Tips'n Tricks

All statements below come from our work with AwareIM running on Linux. This means that they might or might not be true on Windows or Mac. Additionally everything is provided "as is" and we are not responsible in any way for damages or data loss caused by these informations !!

AwareIM Functions Quick Reference

I've put together a short reference folder containing all AwareIM functions. It's meant for double sided printing on A4.

It doesn't contain detailed descriptions on how to use a function. There's only the name, an example of usage and somethimes a short note. The data comes from the AwareIM Help System.

PDF-Version       OpenOffice Version

AwareIM on a headless penguin

The manual states that in this case you won't be able to use a horizontal menu and can't export pdf's. Or is there a workaround ?



AwareIM's Session Timeout

Setting a longer session timeout value requires to change 2 files
These are $awareimroot$/bin/BASServer.props and $awareimroot$/Tomcat/webapps/AwareIM/webapp.props.
SessionTimeout is a value given in milliseconds. This means that
SessionTimeout=3600000
gives a timeout of 3600 seconds or 1 hour.

Disabling Browser Buttons in AwareIM

In order to prevent the users from using the browser's back button use this login page.

Simply replace .../AwareIM/Tomcat/webapps/AwareIM/index.html with the following.

  

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<script language="JavaScript">
function doSubmit() {displayWindow = window.open('', "newWin","scrollbars=1,menubar=0,toolbar=0,resizable=1,location=0,status=0");
document.submitForm.submit();document.submitForm.reset();}
</script>
</head>
<body>
<div align="center">
<form name="submitForm" method="post" action="http://localhost:8080/AwareIM/logon.do?actionMethod=commit&amp;domain=CRM" target="newWin">&nbsp; Username<span class="HeaderWhiteBold">:</span> &nbsp;
<input name="username" size="17" type="text"><br>
<span class="HeaderWhiteBold">&nbsp;&nbsp;&nbsp;Password</span>:<span class="style2">&nbsp;</span>
<input name="password" size="17" type="password"><label></label><p> &nbsp;
<input name="button" value="Logon" onclick="doSubmit()" type="button"></p>
</form>
</div>
</body>
</html>

 

Please note that you have to modify the hostname and domain.

Also note that when running AwareIM on Linux the path names are case sensitive.

The above is a slightly modification from brad's original posting on the AwareIM Forum

Importing Data From Another Database into AwareIM

AwareIM contains the ability to import data using a .csv file. However this approach is sometimes a little bit annoying.
This because the .csv has to follow several rules so that AwareIM can recognise everything.  For example you need to have a headline in the form BusinessObject.Attribute which most systems (at least those I know about) can't create without interaction. But if the data comes from another databse which AwareIM can read then there's (IMHO) a better approach.

The following solution has been tested (and used successfully) against another MySQL database but I don't see any reason why this shouldn't work with the other supported DBMS like MS-SQL, Derby or any other ODBC DB.

  1. Create the Business Object with all required attributes in AwareIM where you want to store your data after importing. Lets call this BODestination
  2. Create a new Business Object (lets call it BOexternal) and choose "Database: existing external" from the Persistence Drop Down.  The button [Settings] now brings you to a window where you can specify the desired database connection. From this table you'll be importing the data.
  3. Once you have established the connection you can hit  [Discover attributes] and the fields from your database table should be published as attributes of your BOexternal.
  4. Now create a Process that executes:
    FIND ALL BOexternal UPDATE BOexternal
    This process doesn't make any changes to your data but allows the following rule to be executed.
  5. Attach a rule to BOexternal
    CREATE BODestination WITH
       BODestination.Attribute1=BOexternal.Attribut1
       BODestination.Attribute2=BOexternal.Attribut2
    and so on.

That's it. Now start the process from Step 4 and all your data will be moved from BOexternal to BODestination

If you should use this approach then please don't try this on any valuable productive data but use a backup copy !
I am not responsible for any data loss or damage that might occur !

 

Keeping AwareIM data in sync with data from a MS-SQL Server

Looks like a common scenario, but there are some pitfalls ...

Scenario

Problems

  1. AwareIM's IMPORT function doesn't support adding AND updating data from the same file (correct me if I'm wrong)
  2. We need to do some field assignments like Customer.Name1 to Customer.Company
  3. AwareIM needs the header in the form Table.Field which causes troubles to Microsoft Software because they don't like periods in field names at all.

The MSSql Server Part

dataexport.cmd (gets executed every 15 minutes)


"C:\Programs\Microsoft SQL Server\80\Tools\Binn\DTSRun" /~Z0x7A......54134EFA
cd \data\export
type header.txt > dataexport.txt
type data.txt >> dataexport.txt
pscp -pw xxxxx dataexport.txt admin@appsrv.local:awareim/importexport/dataexport.txt

  1. Using the Data Export Wizard on or MSSql 7.0 server I created a package that writes the whole table to data.txt
  2. Creating a scheduled task on the SQL server's Enterprise Manager that starts this package worked but every scheduled run ended in an obscure error message telling me that a file can't be found. So I used the command line from the scheduled task and put it into a .cmd file that executes fine using Windows' own task scheduler %-)
  3. As stated above the data file needs a header line in the form table.field that can't be produced by Microsoft. So the export must only contain the data with no headers. The headers come from a manually created additional file called header.txt.
  4. Copy could also be used to join these 2 files together but after that the last line contained a strange character that stopped AwareIM's process. Type works fine...
  5. pscp  is used to copy the file via SSH to our linux appsrv

The AwareIM Part

  1. Create a table (or Business Object) dataimport that contains the same attributes than the data.txt
  2. Now it's time to create a process that:
  3. Imports data.txt into dataimport
  4. Activates a rule in dataimport that:
  5. checks if the record is new in this case a new customer has to be created
  6. checks if the record is changed in this case the customer gets updated
  7. clears dataimport

That's what the following process does

IMPORT dataimport FROM SystemSettings.importfile
FIND ALL dataimport
UPDATE dataimport


First it imports the data. After that it finds every record an executes an update on this record. And UPDATE causes the rules of dataimport to get active.

The rule of dataimport contains:

If NOT(EXISTS customer WHERE (customer.KHKID=Thisdataimport.ID)) Then
CREATE customer WITH customer.company=Thisdataimport.Name1,customer.KHKID=Thisdataimport.ID, .......

which checks if the current imported record already exists in customer. If not then the customer is created

If you say that the process could also be made like
IMPORT dataimport FROM SystemSettings.importfile WITH VALIDATION
then be warned ! On a P4 2,4GHz with 1 Gig Ram the whole process ran about 1 hour ! Whereas the solution shown above finished it's work after about 30 seconds. And yes, the data is the same !

Making Tables Inline Editable in AwareIM

Inline editing objects is a nice feature. The only limitation is that the current version of AwareIM (2.2 at the time of this writing) has no direct way to enable this for top level objects. But with some tweaking it can be accomplished easily as show in the following screen.

 

InlineEdit

 

A .bsv file of the above is available here.

 

Modification on Tomcat Config for AwareIM

When calling the http://localhost:8080/AwareIM without logon.do, logon.jsp or whatever a directory listing is shown to the user.

To avoid this go to
$AwareIMroot$/Tomcat/webapps/AwareIM/WEB-INF
open web.xml in any text editor
search for

<welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

now change this to

<welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>index.html</welcome-file>
</welcome-file-list>

In order to make these changes active you have to restart Tomcat.

Since the default index.html shows the message "Loading....Please Wait" it's likely that you'd like to change this into a starting page for you application.

Public Holidays in Austria for AwareIM

A list of Austria's public holidays to be used in BUSINESS_DAY_[FORWARD|BACKWARD].

PublicHolidays in BASServer.props can be used to specify a collection of days identifying public holidays in the country or state of operation. This information is used by BUSINESS_DAY_FORWARD and BUSINESS_DAY_BACK functions of the Rule Language (see “Aware IM Rule Language Reference”). The days must be in the format “dd/MM/yyyy” and must be separated by comma 25/12/2004, 26/12/2004, ... If this propery is not specified BUSINESS_DAY_FORWARD and BUSINESS_DAY_BACK functions will only consider weekends as non-working days.

For 2006 this is 01/01/2006, 06/01/2006, 17/04/2006, 01/05/2006, 25/05/2006, 05/06/2006, 15/06/2006, 15/08/2006, 26/10/2006, 01/11/2006, 08/12/2006, 24/12/2006, 25/12/2006, 26/12/2006, 31/12/2006

The following OpenOffice.org file can be used to calculate these days: HolidaysAustria.ods

Changing the calculation to reflect any other country's holidays should be a snap.

Running AwareIM against MySQL 4.1

using MySQL "almost" works out of the box but not with MySQL 4.1 on linux

If you want to connect AwareIM to a MySQL database you have to make some adjustments to BASServer.props file in awareim/bin. This is well documented in the user's guide.

But in case you have an MySQL 4.1 db (I don't know if this applies to older versions too) then you need to add useServerPrepStmts=false to the 3 lines dealing with you MySQL connection.

DriverURL=jdbc:mysql://localhost/BASDB?user=root&password=idontremember&useServerPrepStmts=false
DriverTestURL=jdbc:mysql://localhost/BASDBTEST?user=root&password=idontremember&useServerPrepStmts=false
BootstrapURL=jdbc:mysql://localhost/?user=root&password=idontremember&useServerPrepStmts=false

 This has also been discussed on the AwareIM Forum

Setting up AwareIM with SSL

A description on how to setup SSL with AwareIM comes from GregK, Kaplan Design.

Although this describes the steps required on Windows it should basically work on Linux and Mac too.

First you need to create a local keystore file, it contains your private key and you add to it your registered certificate. Fortunately AwareIM comes with Java environment.


C:\AwareIM\JDK\bin>keytool -genkey -alias tomcat -keyalg RSA
 

changit is a standard password expected by Tomcat and unless you want to tell Tomcat explicitly that the password is different, I would stick with this one. It creates file . keystore in your home directory, in my case it was C:\Documents and Settings\Administrator.

Next you need to adjust Tomcat settings. Open file server.xml in AwareIM\Tomcat\conf directory and remove comment tags around the element on SSL connector

 <Connector port="8443"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" debug="0" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />
 

Needless to mention that AwareIM should not be running. That is all you need to use secure connection on https://www.yourserver.com:8443/AwareIM/. You do not have to get a certificate signed by a recognised CA if your site is not for external customers who may be scared away by the browser's security message it displays if a certificate is not signed.

If you do need a signed certificate you have to create a certificate request. Use you private key in the .keystore file to create a request and run this line: 


C:\AwareIM\JDK\bin>keytool -certreq -alias tomcat -file certreq.csr
 

You have to enter certain information like names and contacts in your organisation. For most CA's you need to enter your site URL as the name. Check your CA instructions for details.

Some CA's send only one certificate which makes the process slightly easier while many send you the web certificate and require you to download a root or chain certificate. You need to load both certificates to the same .keystore file that you used to create the certificate request. Be aware that some CA's send certificates as text and you need to convert them to binaries with openSSL; check openssl.org and find a link to an installation package.

You have to load a root (chain) certificate to the keystore first:


C:\Documents and Settings\Administrator>C:\AwareIM\JDK\bin\keytool -import -alias yourCA -keystore .keystore -file path-to-your-certificate\certificate
 

Then do the web certificate with


C:\Documents and Settings\Administrator> C:\AwareIM\JDK\bin\keytool -import -alias tomcat -keystore .keystore -trustcacerts -file path-to-your-certificate\certificate
 

Restart AwareIM and it should work on https://www.yourserver.com:8443/AwareIM/...

The Execution Context of AwareIM

One of the most exciting features of AwareIM is it's execution Context.
Once you'ver understood how this magic "Execution Context" is formed  most data processing is a snap. I assume that you've read and (mostly) understood the section "How Context is Formed" from the AwareIM documentation.

For example you can run a process that says


FIND BOExample WHERE BOExample.Attribute1='Yes'
UPDATE BOExample 

This is a simple process that causes rules attached to BOExample to execute.
For example such a rule could contain:


 BOExample.Attribut2=CURRENT_TIMESTAMP

 What's happening is  a SQL statement like

UPDATE BOExample SET Attribute2=CURRENT_DATE WHERE Attribute1='Yes'

OK, 3 lines of AwareIM code compared to 1 SQL statement. But let's take a look on how we could manage this in MS-Access code. (I just typed the code here - so I don't know if the syntax is 100% correct)


set rs=currentdb.openrecordset("select * from BOExample where Attribute1='Yes')
do until rs.eof
   rs.edit
      rs!Attribute2=current_timestamp
   rs.update
   rs.movenext
loop

You might ask what Access code has to do with AwareIM - well I'd like to explain AwareIM's execution context based on a quite common and easy understandable language...

FIND BOExample .... does what set rs = currentdb... / do until rs.eof does. It finds all desired records and puts all of them into the context. Afterwards it executes UPDATE BOExample for every BOExample in context. Just like my do/loop construction above. Calling UPDATE BOExample triggers the execution of the rules attached to BOExample. This rule now has it's own execution context with only 1 instance in it.

 

Now let's assume that we don't want a simple assignment of CURRENT_TIMESTAMP to Attribute1. Now we want to find data from some other Business Object. Our rule could read like

FIND BOTest WHERE BOTest.Attribute1 = 'abc'
BOExample.Attribute2=BOTest.Attribute2

When the rule gets executed then there's the 1 instance of BOExample in it's context. Now we find a BOTest and this BOTest also gets put into the context. Afterwards it gets assigned to BOExample

 

One drawback of this approach ist that the rule doesn't only get executed when the process gets called. It also gets executed every time BOExample is updated. Either by user interaction or by some other Process that modifies BOExample.

Well, so I change the process to:


FIND BOExample WHERE BOExample.Attribute1='Yes'
FIND BOTest WHERE BOTest.Attribute1 = 'abc'
BOExample.Attribute2=BOTest.Attribute2

If you think that we're now done then you are wrong ! The process above will modify only the first BOExample ! Why ? Read on....

FIND BOExample places several instances into the context. After that AwareIM starts to call FIND BOTest for every BOExample, but FIND BOTest destroys the context created from FIND BOExample !
In case you are a little bit familiar with coding in Access then take a look at the following code:

set rs=currentdb.openrecordset("select * from BOExample where Attribute1='Yes')
do until rs.eof
   set rs=currentdb.openrecordset("select * from BOTest where Attribute1='abc')
   do until rs.eof
      rs.edit
         rs!Attribute2=rs!Attribute2
      rs.update
      rs.movenext
   loop
loop

This code won't work too ! If you take a close look then you'll note that I've assigned the variable rs twice. The second "select * from ...." gets assigned to the same variable and destroys the previous content. In Access it would be easy to solve. I'd just change it to

set rs=currentdb.openrecordset("select * from BOExample where Attribute1='Yes')
do until rs.eof
   set rs2=currentdb.openrecordset("select * from BOTest where Attribute1='abc')
   do until rs2.eof
      rs.edit
         rs!Attribute2=rs2!Attribute2
      rs.update
      rs.movenext
   loop
loop

I only changed the second set rs=... to set rs2=...
In AwareIM it's a little bit more tricky.

Process1


FIND BOExample WHERE BOExample.Attribute1='Yes'
Process2

Process2 with BOExample defined as process input 

FIND BOTest WHERE BOTest.Attribute1 = 'abc'
BOExample.Attribute2=BOTest.Attribute2

Now I have 2 processes. The first finds the desired BOExamples and puts them into the context. For every instance in context it executes Process2 and passes the current instance of BOExample over to Process2. That's why we need BOExample as input for Process2. Since there's now only one instance of BOExample in the context of Process2 finding instances of BOTest doesn't destroy the other instances in context.

I hope that I could shed some light on how AwareIM forms its context. Please feel free to register yourself on this site and post comments. 

Upgrading AwareIM to a newer version

Since it doesn't seem to be stated in the documentation here's a quick Howto
This information is based on the professional version running on Linux an comes without ANY warranty !!
Don't even think of doing an upgrade without a valid backup !
1. Export the relevant business spaces from the current version.
2. Stop AwareIM and also make sure that all Java processes being used from Jboss and Tomcat are stopped.
3. Make a backup of both your AwareIM directory and the databases (BASDB and BASDBTEST).
4. Log in to your account on AwareIM.com and download the latest version using the "Update" link.
5. Rename your old AwareIM directory and place the contents of the downloaded archive into original directory.
6. Copy the BASServer.props (and startupOptions.props if you have) from the backup into the new version. If you modified your TimeOut Settings then also copy these files from the backup to your new version.
7. Run productKey.sh and enter the new productkey from your AwareIM account.
8. Start AwareIM and see if everything works.
In case some things don't work as expected (missing Reports or customized Headers and so on) then either
1. Restore the exported Business Space from Step 1
or
1. Copy the contents from .../Tomcat/webapps/AwareIM from the backup to your new version.
2. Copy the contents from .../DocTemplates from the backup to your new version.
In case everything went wrong and nothing works:
1. Stop AwareIM and also make sure that all Java processes being used from Jboss and Tomcat are stopped.
2. Replace the new AwareIM directory with the Backup you made before (you did do it, didn't you ?)
3. Drop the Databases and restore them from the Backup.
4. Now start AwareIM again and it'll look as if nobody ever touched the system...
Please don't ask me how to upgrade on Windows !