wissel.net

Usability - Productivity - Business - The web - Singapore & Twins

By Date: March 2020

eMail etiquette - the 60ties are calling


With WFH being en vogue these days, not only video conferencing and chat, but also eMail.
Dating back to the 1960ties, we had 6 decades to develop etiquette, which seems tobe lost to current users, so here we go again

Addressing

eMail has To, CopyTo (also called CC for Carbon Copy) and BCC (Blind Carbon Copy) as a means of addressing people. They serve distinct purposes:

  • TO: This is the person (or people) we want to act on our message, do something, reply etc. A good email has only few names, ideally one. If we have an ongoing eMail thread that involves multiple actors, we most likely use the wrong channel and are better of using collaborative software like HCL Connections, HCL Sametime, Slack, Teams or Chatter
  • CC: People, we think, who should be keept in the loop. We don't expect any action or reaction of them. A lot of eMail veterans automatically route those messages to a low priority place
    -- BCC: all receipients here get the message and the rest of the addressies won't know. I used to call it the "mobbing copy". BCC is especially fun when someone there hits "reply all" and reveals the readership. There are few legitimate uses for this. One is distribution lists (see below), the other archive/record keeping. Our external readers don't need to know that your compliance archive has the eMail address compliance@acme.com If we really want someone outside the visible thread to take note - forward the message

Subject line

It is like a tweet about our content. The subject needs to justify why it is worth the time and attention to open it. So "Status", "Report" or "Important" don't cut it. Common practise we can see are qualifiers, e.g Opportunity codes or project IDs at the beginning. Something like [T3453] - makes it easier to filter.

The biggest competitor to inbox attention by subject is the sender identity. We probably open a message one or two reporting managers up even with bad subject lines.

Content

Let's keep it crisp and short, best below 5 sentences.

We state:

  • the information we want to provide
  • the exact ask what action we expect, from whom and when
  • name the person "team please look into... " doesn't cut it and is an indicator of a broken process

If there is a lot of information, it might better live in a Wiki, a project place or even a file share. We then provide the news cast overview and a link - Would you like to know more?

There are some interesting cultural differences. In Anglosaxon or Eastern culture we would politely address the person and add a whiff of smalltalk, something along the lines "hope that finds you well". Germans, Dutch and other Nordics consider this a waste of space and time and consider it as the ultimate courtesy to cut through the chase and get to the point.

When we address close co-workers, who value efficiency, it even is OK to skip the greeting. We need to dread carefully here, it needs to be clarified otherwise it is seen ultra rude.

Replies

Do we reply to the sender or all of the addressies together. It seems to be the default for many "replyToAll". This is especially hillarious when a distribution list sneaked on the addressies. The rationale here is: the sender wanted to keep all these in the loop, so I won't break it. For a small group, I hit replyAll, for larger ones only reply.

I would wish the eMail software would warn when you blast a reply. The guardian agrees: don't replyAll.

A special mention: cherry-picking replies. We hit reply all and remove the mailing lists - good. We just remove the project manager we compete with - bad. So we need to be careful of the ramifications. Other receipients might wonder: why are Jane and Joe no longer in this conversation?

Distribution lists

They firmly belong in BCC - avoids ReplyAll armageddon. When we use private distribution list, we need to make sure, they resolve before sending otherwise people can't reply. However - most likely - that group of people would be better served with a shared channel. A good strategy: we put it in BCC, write a two sencent summary and provide a link to the full info. Co-workers who are not into eMail will find in in their [insert the collaborative tool you use]

As usual YMMV


Posted by on 27 March 2020 | Comments (1) | categories: GTD Intercultural

Running Java applications with Notes on macOS


My main work computer is a MacBook running macOS. Thank to Logitech, they keyboard is just fine. As you know macOS neither features Domino Designer or Domino Admin. For recent development I wanted to make sure that my applications can run on the client (I've done that before).

Java, Java on the wall, what's the right path of them all?

(Sorry Schneewitchen)

In Notes/Domino R9.0.1FP8 - (client FP10) the Java runtime was updated to Java8 and in R11 changed to AdoptOpenJDK.

On macOS that led to a particular situation. The jvm packaged with the HCL Notes.app can be found in the path
HCL Notes.app/jre/Contents/Home with bin, lib and lib/ext as we can expect from a JVM. Suspiciously absent are Notes.jar, websvc.jar and njempcl.jar. They can be located at HCL Notes.app/Contents/MacOS.jvm/lib/ext.

While this isn't an issue for the Notes client, it is an obstacle when you try to run an external jar file. java -jar somejar.jar ignores any classpath setting outside the JVM and only loads resources from the default JBM path (lib/ext).

I suspect the separation was neccesary due to the AdoptOpenJDK distribution rules.

To solve this, we can use a start script that creates a symbolic link in the right place. Takeing the usual suspects like DYLD_LIBRARY_PATH and LD_LIBRARY_PATH into account we end with a script like this:

#!/bin/bash
# MacOS Keep Starter file
# Keep locations - update as needed - leave the TLS stuff empty if you don't have it
export KEEPJAR=$HOME/keep/projectkeep.jar
export LOG_DIR=$HOME/keep/logs
export TLSFile=$HOME/keep/private/demoserver.projectkeep.io.pfx
export TLSPassword=supersecret

# Don't change anything below unless you are sure what you are doing
# Java files places unfortunately troublesome, so we link some
cd /Applications/HCL\ Notes.app/jre/Contents/Home/lib/ext
export SRCDIR="../../../../../Contents/MacOS/jvm/lib/ext"
if [ ! -f njempcl.jar ]; then
 ln -s $SRCDIR/njempcl.jar .
    echo "Linked njempcl.jar"
fi
if [ ! -f Notes.jar ]; then
 ln -s $SRCDIR/Notes.jar .
    echo "Linked Notes.jar"
fi
if [ ! -f websvc.jar ]; then
 ln -s $SRCDIR/websvc.jar .
    echo "Linked websvc.jar"
fi

# Local Keep Server
export DEBUG=true
export PATH=/Applications/HCL\ Notes.app/Contents/MacOS:$PATH
export JAVA_HOME=/Applications/HCL\ Notes.app/jre/Contents/Home
export GodMode=true
export DYLD_LIBRARY_PATH=/Applications/HCL\ Notes.app/Contents/MacOS
export LD_LIBRARY_PATH=/Applications/HCL\ Notes.app/Contents/MacOS
echo $LD_LIBRARY_PATH ..
cd $HOME/Library/Application\ Support/HCL\ Notes\ Data
/Applications/HCL\ Notes.app/jre/Contents/Home/bin/java -jar $KEEPJAR
cd ~
echo Done!

This script presumes thay we have admin permissions. We could contemplate to check for existing symbolic links and remove the ones we did set. I decided, that smells too much like YAGNI.

As usual: YMMV


Posted by on 17 March 2020 | Comments (1) | categories: HCL Notes Java macOS

OData - the fine print


For an upcoming event I had to dig a little deeper into OData and learned a few things along the lines.

Same but different

OData's current version is 4.0 and that's the only version I will focus on in this article.

OData is the love child of an effort that joined Microsoft and SAP at the hip to create an universal internet data access standard, that on first sight has a lot of NIH issues to sort out. But I'm sure on a second (or third or forth) look it will all make sense.

Key components of OData

  • a service document in JSON format. It describes what data endpoints are available and where. Depending on the requested scope (more on that later) that JSON contains different levels of details
  • a meta data document. That document is referenced in the service document. The format is XML. It describes the data format found in each record, relations to other record and actions that can be taken. Looks like XML Schema, but not quite. Record is used loosely here, data can be hierarchical and nested
  • a query language squeezed into an URL, so data can be fetched using HTTP GET without using a body submitted. Query allows data selections, filtering, output size and sorting to be specified
  • Query results in JSON format enhanced with OData specific Metadata

What I liked a lot: OData.org offers a rich set of documentation and tutorials, including a Postman collection to learn

Happy soup

So dealing with OData you can enjoy a mix of technologies:

  • JSON for service document and payloads
  • XML for meta data
  • a dot notation (like dotNet or Java) for property values like data types (go learn about it). E.g. Edm.String defines a String value or Org.OData.Core.V1.ResourcePath the path to data
  • another query language
  • individual items by default get addressed in an uncommon format: serviceurl/People('johndoe'). Luckily this is optional and you can use the more common format for a route: serviceurl/People/johndoe. This seems to be born out of squezing the square pin URL into the round hole of database schemas and flexible primary keys

On the upside: Your Salesforce and Excel users will love it. Import and CRUD operations are well supported.

Initially I was looking at Apache Olingo to implement my needs. Unfortunately the library is too close to the Java servlet model and static defined data models (like your one application, not your data platform), so I disected my needs the hard way.

Lessons learned along the way

  • A OData client (think Excel, Tableau, Salesforce) will initially connect to the service document url. It sends a GET request. To specify what level of detail is required the ACCEPT header is used. So when testing your provider implementation you need to take that into account
  • Excel sends ACCEPT application/json;odata.metadata=minimal
  • Salesforce sends ACCEPT application/json;odata.metadata=full
  • OpenAPI can specify the top level application/json or the full qualified content type in the response. If you fully qualify it, you might end up with a 406 and wonder what happens
  • The meta data url gets specified in your service document and is usually the service document url extended by /$metadata
  • I ran into a potential Salesforce bug, where the meta data URL was ignored and the service document URL extended by $metadata. Note the missing /. Caused a bit of grief since Excel does /$metadata
  • Everything is case sensitive, which makes sense, but is fun in Domino that treats item names case insensitive
  • I couldn't get Salesforce to play nice until I added a field ExternalId to my form. Might be my lack of understanding how to change the primary key Salesforce will play nice with or something missing in my Metadata

Same, same, but different

Swap out the GET for a POST and the XML for something not-quite-JSON and you get GraphQL that tries to address a similar set of functionalities. We really love wheels reinvented

More lessons to be learned, stay tuned!


Posted by on 04 March 2020 | Comments (0) | categories: OpenSource WebDevelopment