Sametime 9 business cards revisited and beaten!

Over the years I have always struggled to get to grips with business cards and particularly photos mainly because I do it for a customer, forget about it and then have to do it again six months later. I have a Sametime 9 build coming up and I wanted to revisit business cards and for once write a conclusive guide which I have decided to share in case it helps anyone else out there.

Note – I have not looked at (yet) the mobile applications and how business cards and photos are obtained from them. I believe that the mobile application needs to have a direct connection to the photo i.e. it needs to be resolvable from the internet, outside your fire wall. There may be a way around this buy using the STProxy setting “The URL where stproxy downloads users’ photos.” This writes to stproxyconfig.xml and instructs STProxy where to obtain photos from so only STProxy needs access to the photos and not the mobile clients in the internet.

I am running the following:

  • IBM Sametime 9 HF1 with latest patch.
  • IBM Domino 9x LDAP.
  • All servers sit on CentOS 6.4.

Where to store your photos?

You have three options although there is only really two:

  1. In your LDAP which is the Domino directory in my case.
  2. Web server.
  3. Domino database.

Option 1 is really a no go. Increasing the size of names.nsf is a no no and can lead to administration problems going forward especially if you have a large user base. So the remaining options are discussed as follows.

Web server

Pretty simple really. Remember though that you cannot force authentication to the web server so anyone can access it but it can be behind a firewall (see notes above). For ease I put my photos on the Community server in /opt/ibm/dominodata/domino/html/sametime/photos/

Domino database

I like this approach for the following reasons:

  • You can build in checks for file size, name and case when attaching an image.
  • You can control the ACL.
  • You could offer a means of bulk uploading files.
  • Replicate the database to a server that is accessible to users.
  • Stop abuse by only allowing users to edit their own photo.
  • Allow a URL template to be followed so all photos are obtainable from a URL such as http://abc.collaborationben.com/bcard.nsf/Ben.Williams@collaborationben.com.jpg. Changing the email address for each user.

I have been using a basic database provided by IBM for my testing purposes so all the good stuff above has been verified by a developer as doable.

Things to remember

  • The case of the photo must be as follows, Ben.Williams@collaborationben.com. Mindful of the capital “B” and “W.”
  • The size of the file should be small, ideally under 10kb though some Technotes say under 64kb. Smaller is better in this case.
  • If you need to clear the cache then delete the following directories (taken from a standalone Connect client on Windows 7).
    • C:\Users\ben williams\AppData\Roaming\IBM\Sametime\.metadata\.plugins\com.ibm.collaboration.realtime.people.impl\PersonCache
    • C:\Users\ben williams\AppData\Roaming\IBM\Sametime\.metadata\.plugins\com.ibm.rcp.bizcard\Cache
  • I do not have a database available which does what I want i.e. provide a URL template so I have to fudge it in my steps but you should get the idea.
    • The URL template is really only required for meetings BUT it makes sense to keep all the values the same.

Photos using a database

Notes client

Create a form in bcard.nsf attaching the image and adding your email address. The email address is used to look up your image.

form

Update your person document with the URL to your photo. Ideally this will use a URL template but for my purposes I have used the fixed URL

persondoc1

Stop your Community server and locate UserInfoConfig.xml. Make a back up of the file and then edit it.

Add your bind username and password whihc will be removed and encrypted automatically later. Importantly add the text in bold.

<?xml version =”1.0″ encoding=”UTF-8″ ?>
<!– ***************************************************************** –>
<!–                                                                   –>
<!– IBM Confidential                                                  –>
<!–                                                                   –>
<!– OCO Source Materials                                              –>
<!–                                                                   –>
<!– (C) Copyright IBM Corp. 2006                                      –>
<!–                                                                   –>
<!– The source code for this program is not published or otherwise    –>
<!– divested of its trade secrets, irrespective of what has been      –>
<!– deposited with the U.S. Copyright Office.                         –>
<!–                                                                   –>
<!– ***************************************************************** –>

<UserInformation>
<Resources>
<Storage type=”LDAP”>
<StorageDetails  HostName=”****.collaborationben.com” Port=”389″  UserName=”” Password=”” UserEncodedAuth=”*****************************” SslEnabled=”false”  SslPort=”636″ BaseDN=””  Scope=”2″ SearchFilter=”(&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)))”/>
<!– Add another StorageDetails tag to support another ldap server. The listing order implies the searching order –>

<!– Scope: 0=OBJECT_SCOPE 1=ONELEVEL_SCOPE 2=SUBTREE_SCOPE–>
<SslProperties KeyStorePath=””  KeyStorePassword=””/>
<Details>
<Detail Id=”MailAddress” FieldName=”mail” Type=”text/plain”/>
<Detail Id=”Name”  FieldName=”cn” Type=”text/plain”/>
<Detail Id=”Title”  FieldName=”title” Type=”text/plain”/>
<Detail Id=”Location”  FieldName=”postalAddress” Type=”text/plain”/>
<Detail Id=”Telephone”  FieldName=”mobile,telephoneNumber” Type=”text/plain”/>
<Detail Id=”Company” FieldName=”ou” Type=”text/plain”  />
<Detail Id=”Photo” FieldName=”jpegPhoto” Type=”image/jpeg”  />
</Details>
</Storage>

<Storage type=”NOTES_CUSTOM_DB”>
<StorageDetails DbName=”bcard.nsf” View=”viewPerson”/>
<Details>
<Detail Id=”Photo” FieldName=”fldPhoto” Type=”image/jpeg”/>
</Details>
</Storage>

</Resources>

<ParamsSets>
<Set SetId=”0″ params=”MailAddress,Name,Title,Location,Telephone,Photo,Company”/>
<Set SetId=”1″ params=”MailAddress,Name,Title,Location,Telephone,Photo,Company”/>
</ParamsSets>
<BlackBoxConfiguration>
<BlackBox  type=”LDAP” name=”com.ibm.sametime.userinfo.userinfobb.UserInfoLdapBB”  MaxInstances=”5″ />
<BlackBox type=”NOTES_CUSTOM_DB” name=”com.ibm.sametime.userinfo.userinfobb.UserInfoNotesCustomBB” MaxInstances=”4″/>

</BlackBoxConfiguration>

</UserInformation>

Save and close and in the SSC (Sametime System Console – Sametime Servers – Sametime Community Servers – Deployment Identifier – Business Card) configure the following in line with the image.

ssc1

Note: The photo value is “user defined” and blank to ensure it is retrieved from the secondary repository (the Notes application) and not from the primary repository, which is the LDAP directory.

mobile,telephoneNumber

I added two values here so that both my office and mobile numbers appear on the same line in the business card. You can read more here.

At this point I hit a snag and a photo wasn’t appearing in my client. I added the following to the sametime.ini.

[Debug]
USERINFO_DEBUG_LEVEL=5

After restarting the Community server I got the following in STUserInfoSA*.txt in the Trace directory.

[ 11:23:27.664 | 19.08.2014 | INFO | 22 ] : ImageExtractor : extractImage : export field to XML is now completed.
[ 11:23:27.678 | 19.08.2014 | SEVERE | 22 ] : ImageExtractor : extractImage : extractImage Exception:
com.ibm.sametime.userinfo.userinfobb.ImageExtractor$ImageNotFoundException: Image file type not supported: williams@collaborationben.com.jpg
at com.ibm.sametime.userinfo.userinfobb.ImageExtractor$ImageParsingHandler.handleFileDataTag(ImageExtractor.java:240)
at com.ibm.sametime.userinfo.userinfobb.ImageExtractor$ImageParsingHandler.startElement(ImageExtractor.java:188)

I changed the file name and attached it to my form in bcard.nsf again and the photo appeared.

A good test at this point is to call the UserInfoServlet from a web browser. The URL will be something like http://communityserver.collaborationben.com/servlet/UserInfoServlet?operation=3&userId=CN=ben%20williams,O=Collaborationben&setid=1

You should see the xml data that makes up the business card. Most importantly you want to see the binary data where the photo should be.

servlet

If you see “UNAVAILABLE” or similar then enable trace.

You should see.

client_bizcard

Sametime Proxy

Open UserInfoConfig.xml and add the values in bold.

<Detail Id=”Location”  FieldName=”postalAddress” Type=”text/plain”/>
<Detail Id=”Telephone”  FieldName=”mobile,telephoneNumber” Type=”text/plain”/>
<Detail Id=”Company” FieldName=”ou” Type=”text/plain”  />
<Detail Id=”Photo” FieldName=”jpegPhoto” Type=”image/jpeg”  />
<Detail Id=”PhotoURL” FieldName=”PhotoURL” Type=”text/plain”/>
</Details>
</Storage>

<Storage type=”NOTES_CUSTOM_DB”>
<StorageDetails DbName=”bcard.nsf” View=”viewPerson”/>
<Details>
<Detail Id=”Photo” FieldName=”fldPhoto” Type=”image/jpeg”/>
</Details>
</Storage>

</Resources>

<ParamsSets>
<Set SetId=”0″ params=”MailAddress,Name,Title,Location,Telephone,Photo,PhotoURL,Company”/>
<Set SetId=”1″ params=”MailAddress,Name,Title,Location,Telephone,Photo,PhotoURL,Company”/>
</ParamsSets>

Restart the Community server and Sametime Proxy.

What is odd is why the address doesn’t appear in the STProxy web client but it does in the thick client. Hmm..

stproxy2

Photos in meetings using web server

The meeting server uses a different approach and does not use the PhotoURL value in you person document. I guess this is because they do not want VMM from having to lookup to LDAP and then follow the URL to another source. So, with this in mind it uses a URL template which I mentioned previously.

Since my database doesn’t allow for anything fancy I have had to cheat and copy the image that is attached to my form in bcard.nsf to /opt/ibm/dominodata/domino/html/sametime/photos/ and save it Ben.Williams@collaborationben.com.jpg. The case matters. It may matter because I am using Linux or it could be because Java cares too.

In the SSC go to (Sametime System Console – Sametime Servers – Sametime Meeting Servers – Deployment Identifier) and change the values as follows:

userInfoImageAttr – You can enter anything here, it doesn’t matter.
userInfoRedirect – true
userInfoUrlTemplate – http://communityserver.collaborationben.com/sametime/photos/{0}.jpg

Explanation:

userInfoImageAttr – this will use an LDAP attribute and is ignored if userInfoRedirect is set to true. This is used when you have uploaded your image to LDAP.
userInfoRedirect – set to true so that the userInfoUrlTemplate is used. Set to false and userInfoImageAttr is used.
userInfoUrlTemplate – This is a URL template where you will store your images.

meetingserver_ssc

Apply and OK the changes and restart the meeting server.

On joining your meeting room you will see the following written to the SystemOut.log.

[8/19/14 15:31:27:797 BST] 0000010b ServletWrappe I com.ibm.ws.webcontainer.servlet.ServletWrapper init SRVE0242I: [Sametime Meeting Server] [/userinfo] [ImageServlet]: Initialization successful.
[8/19/14 15:31:27:802 BST] 0000010b ImageServlet  I   UserInfo template URL changed from[] to[http://communityserver.collaborationben.com/sametime/photos/{0}.jpg], flushing cache

You will see an image but if you initiate the business card that will use STProxy.

meetingserver_browser

In the client the image will be taken from client via UserInfoServlet and the normal client based business card.

meetingserver_client

Finally, if you do not want to use a Domino database and put all your images on a web server then take a look at what follows.

Web server

Edit UserInfoConfig.xml as follows. Take notice of the bold test.

<?xml version =”1.0″ encoding=”UTF-8″ ?>
<!– ***************************************************************** –>
<!–                                                                   –>
<!– IBM Confidential                                                  –>
<!–                                                                   –>
<!– OCO Source Materials                                              –>
<!–                                                                   –>
<!– (C) Copyright IBM Corp. 2006                                      –>
<!–                                                                   –>
<!– The source code for this program is not published or otherwise    –>
<!– divested of its trade secrets, irrespective of what has been      –>
<!– deposited with the U.S. Copyright Office.                         –>
<!–                                                                   –>
<!– ***************************************************************** –>

<UserInformation>
<ReadStConfigUpdates value=”false”/>
<Resources>
<Storage type=”LDAP”>
<StorageDetails  HostName=”ldap.collaborationben.com” Port=”389″  UserName=”” Password=”” UserEncodedAuth=”Y249c3Q5LWJpbmQsbz1jb2xsYWJvcmF0aW9uYmVuOnBhc3N3MHJk” SslEnabled=”false”  SslPort=”636″ BaseDN=””  Scope=”2″ SearchFilter=”(&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)))”/>
<!– Add another StorageDetails tag to support another ldap server. The listing order implies the searching order –>

<!– Scope: 0=OBJECT_SCOPE 1=ONELEVEL_SCOPE 2=SUBTREE_SCOPE–>
<SslProperties KeyStorePath=””  KeyStorePassword=””/>
<Details>
<Detail Id=”MailAddress” FieldName=”mail” Type=”text/plain”/>
<Detail Id=”Name”  FieldName=”cn” Type=”text/plain”/>
<Detail Id=”Title”  FieldName=”title” Type=”text/plain”/>
<Detail Id=”Location”  FieldName=”postalAddress” Type=”text/plain”/>
telephoneNumber” Type=”text/plain”/>
<Detail Id=”Company” FieldName=”companyname” Type=”text/plain”  />
PhotoURL” FieldName=”PhotoURL” Type=”text/plain”/>
ImagePath” FieldName=”PhotoURL” Type=”text/plain”/>
</Details>
</Storage>

</Resources>

<ParamsSets>
<Set SetId=”0″ params=”MailAddress,Name,Title,Location,Telephone,PhotoURL,ImagePath,Company”/>
<Set SetId=”1″ params=”MailAddress,Name,Title,Location,Telephone,PhotoURL,ImagePath,Company”/>
</ParamsSets>
<BlackBoxConfiguration>
<BlackBox  type=”LDAP” name=”com.ibm.sametime.userinfo.userinfobb.UserInfoLdapBB”  MaxInstances=”5″ />

</BlackBoxConfiguration>

</UserInformation>

You’ll notice that the custom database (bcard.nsf) has been removed. There’s no need for it now we are using a web server to host the images.

<ReadStConfigUpdates value=”false”/>
This setting, when set to false, will force the STUserInfo SA to use the configuration information stored in UserInfoConfig.xml rather than the settings in the SSC (Sametime System Console – Sametime Servers – Sametime Community Servers – Deployment Identifier – Business Card). Without setting this value as false you would not be able to add ImagePath which is what the Notes client needs to display the URL based jpg.

PhotoURL
This value will be used by STProxy and is linked in the UserInfoConfig.xml to PhotoURL on the user’s person document.

ImagePath
This is used by the Notes client to find the image from the web server.

Make the changes and restart the Community server and probably STProxy and meetings for good measure. Remember you have already set the URL template for meetings.

The results are the same as in my previous screen shots.

The web server approach can be used for populating images from Connections and there are a number of good Technotes and blogs from others as to what URL template to use. You can even configure STProxy to use the Connections business card which provide Profiles, Blogs and more data in the business card. I haven’t yet populated it with my Connections 5 business card but will get around to it soon.

UPDATE

Cormac O’Leary (Team Lead of Sametime PMR team in Dublin) pinged me an email and suggested that I add the DisplaySeparator detailed here. The documentation says to use…

FieldName=”telephoneNumber,mobile” Type=”text/plain” DisplaySeparator=”/”/>

This didn’t work for me but Cormac’s example had additional spaces which are not documented in the Knowledge Center.

I updated my UserInfoConfig.xml and changed my person document so you don’t know my mobile and home address as follows.

<?xml version =”1.0″ encoding=”UTF-8″ ?>
<!– ***************************************************************** –>
<!–                                                                   –>
<!– IBM Confidential                                                  –>
<!–                                                                   –>
<!– OCO Source Materials                                              –>
<!–                                                                   –>
<!– (C) Copyright IBM Corp. 2006                                      –>
<!–                                                                   –>
<!– The source code for this program is not published or otherwise    –>
<!– divested of its trade secrets, irrespective of what has been      –>
<!– deposited with the U.S. Copyright Office.                         –>
<!–                                                                   –>
<!– ***************************************************************** –>

<UserInformation>
<ReadStConfigUpdates value=”false”/>
<Resources>
<Storage type=”LDAP”>
<StorageDetails  HostName=”ldap.collaborationben.com” Port=”389″  UserName=”” Password=”” UserEncodedAuth=”Y249c3Q5LWJpbmQsbz1jb2xsYWJvcmF0aW9uYmVuOnBhc3N3MHJk” SslEnabled=”false”  SslPort=”636″ BaseDN=””  Scope=”2″ SearchFilter=”(&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)))”/>
<!– Add another StorageDetails tag to support another ldap server. The listing order implies the searching order –>

<!– Scope: 0=OBJECT_SCOPE 1=ONELEVEL_SCOPE 2=SUBTREE_SCOPE–>
<SslProperties KeyStorePath=””  KeyStorePassword=””/>
<Details>
<Detail Id=”MailAddress” FieldName=”mail” Type=”text/plain”/>
<Detail Id=”Name”  FieldName=”cn” Type=”text/plain”/>
<Detail Id=”Title”  FieldName=”title” Type=”text/plain”/>
<Detail Id=”Location”  FieldName=”officestreetaddress,l,st,postalcode,c” DisplaySeparator=” / ” Type=”text/plain”/>
<Detail Id=”Telephone”  FieldName=”mobile,telephoneNumber” DisplaySeparator=” / ” Type=”text/plain”/>
<Detail Id=”Company” FieldName=”companyname,department” DisplaySeparator=” / ” Type=”text/plain”/>
<Detail Id=”PhotoURL” FieldName=”PhotoURL” Type=”text/plain”/>
<Detail Id=”ImagePath” FieldName=”PhotoURL” Type=”text/plain”/>
</Details>
</Storage>

</Resources>

<ParamsSets>
<Set SetId=”0″ params=”MailAddress,Name,Title,Location,Telephone,PhotoURL,ImagePath,Company”/>
<Set SetId=”1″ params=”MailAddress,Name,Title,Location,Telephone,PhotoURL,ImagePath,Company”/>
</ParamsSets>
<BlackBoxConfiguration>
<BlackBox  type=”LDAP” name=”com.ibm.sametime.userinfo.userinfobb.UserInfoLdapBB”  MaxInstances=”5″ />

</BlackBoxConfiguration>

</UserInformation>

I opted for a forward slash to use as the display separator, you could use pipes or whatever, see what works.

The results are as follows and they look better.

client_bizcard2

stproxy3

One thing you might want to consider is if you are using a telephony solution like SUT which relies on telephone numbers in the business cards for click to call. Having various numbers on the same Detail Id may cause problems but it’s something to test.

Stproxyconfig.xml is overwritten with incorrect APNs port and changed when applying an update

I have seen this problem a couple of years ago but didn’t follow it up with IBM through a PMR. For another customer I found the following happened after I applied the latest Sametime Proxy 8.5.2.1 (STProxy) patch available on Fix Central.

After applying the update the stproxyconfig.xml was changed and the bespoke values that were previously there removed. This was odd in itself but after applying the values again through the SSC the values sticked.

The values that were removed are as follows.

Before update:

<appleNotificationHostName>gateway.push.apple.com</appleNotificationHostName>
<appleNotificationPort>2195</appleNotificationPort>
<appleFeedbackHostName>feedback.push.apple.com</appleFeedbackHostName>
<appleFeedbackPort>2196</appleFeedbackPort>

<meeting>
<host>stmeeting.collaborationben.com</host>
<port>80</port>
<type>2</type>
<isSecure>true</isSecure>
</meeting>

After update:

<appleNotificationHostName>gateway.push.apple.com</appleNotificationHostName>
       <appleNotificationPort>2196</appleNotificationPort>
<appleFeedbackHostName>feedback.push.apple.com</appleFeedbackHostName>
<appleFeedbackPort>2196</appleFeedbackPort>

<meeting>
        <host/>
        <port/>
        <type>0</type>
<isSecure>true</isSecure>
</meeting>

After I corrected the Meeting server URL and the appleNotificationPort I synced the node and restarted STProxy.

It wasn’t until making a change to the userTimeout value and applying the change in the SSC I noticed that the value for appleNotificationPort was changed (again) from 2195 to the incorrect value of 2196.

I logged a PMR and was told that the problem with saving the STProxy configuration in the SSC and it changing the appleNotificationPort value was reported in SPR #DMWR8UCR58 and APAR  LO69429.

I have tested on a Sametime 9 Proxy with the latest patch and cannot reproduce the behaviour.

It’s something to be aware of when updating STProxy and making changes in the SSC.