Mr N

It took me a while to figure out how to set up calendars for a company using Google Apps. Part of the problem was that I had not completely understood how the calendar is created and therefore could not understand the mechanism that allowed the calendar to become visible to employees of that company. I hope this document helps you to understand how to set up Google Calendars and explains different policies that you might adopt to make the best use of Google Calendars. I had incorrectly assumed that there would be an administration page that allowed me to create a company wide calendar, once created this calendar would just appear in every employee’s calendar view and all would be good. This however is not the case and it took me a while to realise that this is quite different to other software providers’ calendar applications. Google works by allowing a user to create a calendar then assigning visibility of it to other people. This is opposite to what I had expected. I had expected the company administrator to create a calender that all members of the company would automatically have access to. Simply put: Google has calender at the centre instead of the company. I’m not saying this is a bad thing; speaking as a software implementer this is definitely an easier way to manage things, I’m just saying it’s not what I was expecting. In fact now that I have used it this way, I kind of like it better! I’ll take you through a common scenario to help you understand how this might work. In these examples I will assume that everyone in your company has their account under one Google Primary domain account. Let’s say that your company is split into 2 administrative companies, for example a head office and a sales office which are geographically separated. People in both companies would like to see each other’s calenders so that they can make appointments and meetings between themselves more easily. For the most part both offices run as individual entities. The head office is not really interested in all the sales meetings and the sales office is not really interested in all the bean-counter meetings. In this case we will set up 1 separate calendar for each office.

1. Log into the calendar application at: http://calendar.example.com.
2. On the left of the screen in the My calendars section click Add.
3. You will be presented with a form on the Create New Calendar screen. So fill in the name as HQ Office you can choose what ever makes sense to you.
4. Fill in the Description. This is free text so it could be something like “Calendar for all the people at HQ”
5. Fill in the Location to your geographical location. This is free text so it could be London or Floor 6
6. Next there is a space for time zones which will pick up the default that your administrator has set already.
7. Finally we must set the access permissions. There are 4 options:
   1. Not shared: This will be a calendar that only you can see.
   2. Company only: Anyone in the company can see this calender.
   3. Public: Anyone in the world can see this calendar.
   4. Named: Only listed people can see this calendar.
   In this instance we want everyone in our company to see this calendar but no one else. So we will check the Share this calendar with others and Share this calendar with everyone in the organisation My Organisation.
8. Finally click the Create Calendar button.

You will be taken back to the Calendar screen and after half a second your freshly created calendar will appear on the left in the My calendars section. You should do exactly the same for the sales office calendar. However after the second calendar has been created it has a funny name (not sure why it doesn’t take the Calendar name like it does for the first one - bug probably). Don’t worry this is simple to change.

1. Next to the Add link there is a Settings link, click this.
2. Click the name of the broken calendar which will be something like example_com_random_letters@group.calendar.google.com.
3. Change the Calendar Name back to what it was supposed to be e.g. Sales
4. Click the Save button and everything should look normal.
5. Clicking Back to calendar will take you back to the calendar screen.

Next up is to share this calendar with the rest of the people in the company. This was the bit that confused me as there isn’t an easy way of doing it, you just have to do it the long way.

1. Log into the calendar application at: http://calendar.example.com.
2. In the My calendar section (on the left) click the Settings link.
3. Click the calendar’s name link.
4. At the bottom of the page in the section entitled Calendar Address the Calendar ID is listed. This is the global address of your calendar.
5. Cut and Paste it into an email.
6. Do the same for the other company wide calendars e.g. sales.
7. Email the references to everyone in your company.

Yeh, I know it’s a bit crappy but it’s the only way. Your employees will receive an email with the 2 global calendar reference addresses in it. They must then add the new calendar mappings to their calendar application.

1. Log into the calendar application at: http://calendar.example.com.
2. On the left-hand side in the section Other calendars cut and paste the calendar reference from the email into the text box and press return.

To get rid of it just click the My calendar -> Settings and then the Unsubscribe link for that calendar. You will now see 3 calendars in the My calendars section. Yours, HQ’s and sale’s. Clicking each calendar name will change the colour from something to white. White means not selected and there is a different colour for each calendar. As they toggle on and off, the overlay of calendar events that can be seen in the main calendar view changes to include or exclude the events from that calender. A handy tip is that if you don’t use the other calenders then don’t switch them on because when you create an event it will automatically set the new event to the calendar that is selected. Some other examples of sharing calendars are:

1. Creating a department wide calender: on the Create New Calendar screen, just include the list of department members in the section Share with specific people when creating the calendar.
2. Creating a public calendar: If you organise events for the public you might want to allow anyone to see your calendar so when creating the calendar set the Share this calendar with others to Make this calendar public.

Creating a public calendar is slightly different in that it doesn’t require the user to have a Google Apps account. It really is completely public. Whereas all the others require you to be logged into your Google Apps account in order to validate that you are on the list of users that this calendar is visible to. There’s one other thing worth mentioning, which is that you can restrict how much of the calendar a user can see to either the whole sh-bang or just whether you are busy or free (i.e. hide the details). I think that covers just about everything!

I loved the music to the Guinness advert featuring the Irish men playing hurling. It has a very traditional Irish feel to it mixed in with a very modern build-up and dance theme. I searched high and low across the internet to find the music and the album. The first place to check is YouTube a veritable mix of weirdness and usefulness. It didn’t take too long to find: So I then used search terms like Guinness, hurling and advert (amongst others) but I just couldn’t find any information about it. The only reference I found were forums and comments where other people were asking about it - with no answers. So I put my original research hat on and asked Guinness!

Firstly Guinness is my favourite tipple! Secondly I would like a little bit of information about the music you have used in your Guinness Hurling advert: http://www.youtube.com/watch?v=z7Diqm25NAE I’ve searched across the internet to no avail. The various forums and comments sections of YouTube and similar are filled with people asking but no answers. There is no better source than the horse’s mouth so I thought I’d ask you directly. Please can I have the title and artist of the music in the Hurling advert or even the name of the advertising agency that produced it.

A couple of days later I had a very nice email back from someone in Diageo Consumer Relations:

Dear MrN, Thank you for taking the time to contact us and for expressing your interest in Diageo. In regards to your query, this advert is called ‘Free-In’ from the ‘Believe’ campaign produced by Irish International and dates from 2001. The music was specially composed for this advert, so does not have a specific title. I apologise if this is a source of disappointment to you and i’d like to wish you all the best from Guinness. Yours Sincerely, Diageo Consumer Relations

So now you know!

Ever come across the situation where you need to search for sets of values in a (MySQL) database? SQL along the lines of:

SELECT col1, col2 FROM table1 WHERE (col3 = 5 and col4 = 6) or (col3 = 10 and col4 = 12) or (col3 = 15 and col4 = 3)

I come across it all the time and it occurred to me that I am searching for a set of data and all of SQL is based on sets and subsets of data, so why can’t I search for a set in the same way as I search for a column? and you can! Here’s an example of how to do it. First up we’ll need some test data. I’m using MySQL but it’s standard SQL and should work on anything. So we’ll create a database, table an add some data:

CREATE DATABASE bigsoft_set_test; USE bigsoft_set_test; CREATE TABLE tab( a VARCHAR(1), b VARCHAR(1) ); INSERT INTO tab(a, b) VALUES("a", “b"); INSERT INTO tab(a, b) VALUES("b", “c"); INSERT INTO tab(a, b) VALUES("c", “d"); INSERT INTO tab(a, b) VALUES("d", “e");

Ok, lets start with an example of the old method:

SELECT a, b FROM tab WHERE (a = “b” and b = “c") or (a = “c” and b = “d");

This gives us the middle 2 rows from our table:

+------+------+
| a    | b    |
+------+------+
| b    | c    |
| c    | d    |
+------+------+
2 rows in set (0.00 sec)

Now let’s try it using sets:

SELECT a, b FROM tab WHERE (a, b) in (("b", “c"), ("c", “d"));

Surrounding a comma separated list of values with braces creates a set. Our set could equally be a sub-query for example:

SELECT a, b FROM tab WHERE (a, b) in (SELECT * FROM tab WHERE a = “b” OR a = “c");

The star “*” in the query means all columns which on this table is “a” and “b". The sub query returns a narrowed list of values to the outer query which is just passed upwards. Similarly we can create a 3 step set query as follows:

SELECT a, b FROM tab WHERE (a, b) in (SELECT * FROM tab WHERE a in ("b", “c"));

But why would you want this? Well there could be a couple of reasons:

1. The main one is that of verboseness. Having to define the fields in a AND/OR/braces takes up a lot of space on your query line which is limited.
2. Parse speed. The smaller the query, the less time it takes to parse, and yes it does make more difference than you think. Pre-parsing slowness is the reason we have the prepareStatement commands in all the connectors.
3. Code simplicity. I deal with ranges of values and by dealing with them as sets, not caring about there individual components I have simplified my code base significantly.

Remember this is the conditional part of the query, so it can be used for DELETEs as well as SELECTs. Some databases only have a fixed amount of space for a query and the more conjoined conditions you can squeeze into your buffer the faster throughput your database can achieve.

September 2010 was a very busy month for us so I didn’t really have time to write my usual 4 blogs a month. I’m 2 down at the moment so I thought I’d publish this one as it’s been sitting in my system for a while waiting for me to pad it out with one of my nice stories you like ;) Windows is a bit of a pain when it comes to networking. All that additional security they’ve added is a bit pointless and to be honest I don’t really know anyone who uses it. Anything more than user, group and other adds unnecessary complication. Un*x has survived for the last 30 years without much problem and has helped administrators build working environments which are easy to manage and straightforward to look after. When was the last time you were shouting “Why are you not working” at your Micro$oft machine. It’s seems like a daily event. Don’t even get me started on MicrosoftNLB with multiple NICs - Jesus! But that’s a story for another time. Anyway before I get too carried away I’m adding this to my pet gripes. How do I list all the folders (or shares) I have? In the wonderful world of Windows where there’s no such thing as a command line there’s no way to get this information - you just have to remember yourself. Well if you manage more than 1 machine then things start to get a little more difficult. So here’s what you do, drop to a command line - that’s the black box thing which lets you do all the really useful stuff and type:

C:\>net share
Share name   Resource                        Remark
-------------------------------------------------------------------------------
IPC$                                         Remote IPC
D$           D:\                             Default share
ADMIN$       C:\WINDOWS                      Remote Admin
C$           C:\                             Default share
projects     C:\projects
installer    C:\MyStuff\Installer\AdvInst
q            C:\Shared
The command completed successfully.

I was reading the QMail wiki and came across a project called Qmail Toaster. I thought "ooh... that looks interesting" and wondered what it is. The QMail wiki page doesn't say anything about what the project is for or what problem it solves. It just tells you to read the following web sites:

1. Qmailtoaster home
2. Qmailtoaster documentation wiki
3. Qmailtoaster Plus project page
4. Video tutorials

The Qmailtoaster home page is basically a list of features presented in no particular order. The Qmailtoaster documentation wiki's introduction and history page just goes on about how easy it is to install even for an inexperienced user. The Qmailtoaster Plus project page says it's an extension to Qmailtoaster - whoopy - we're still not getting anywhere! I pinned all my hope on the Video tutorials but the site is down.

I read around the web sites and after 10 minutes, I was still none the wiser as to what the project was actually for and what job it did inside QMail.

Hunted around a little bit more and found out that "QmailToaster-Plus is an RPM package that contains a menu and supporting scripts which add additional features and utilities to your QmailToaster" - great so what is QmailToaster?

Another page says "Miguel's goals were to provide a very stable rpm based Qmail MTA" - ok now we are getting somewhere. So what is a "Qmail MTA" and how does that fit into QMail?

I don't mean to be so flippant, but it took 10 minutes to find out what this project is actually for once I had got passed all the easy-to-use, rpm-packed, more-features-than-you-can-shake-a-stick-at style adverbs.

It constantly surprises me how many projects miss this out and think we can deduce what the project is for by reading a stream of features.

I'm not psychic, and I don't want to spend ages hunting around for answers. Documentation comes in 2 parts. The first part is essential: what is the project for, and the second is optional: how do you use it. The second part maybe deduced by reading source code or forums and so can be omitted. Once you've seen enough open source projects you will realise that how-to-use documentation is a luxury but you can get by without it. Whereas the 1 or 2 sentences that open a project are the most important. They tell you whether or not you need the project. If you don't then you can stop reading straight away and move on to the next project.

Some guidelines

Here are some guidelines to help you with defining your project.

1. Give the section its proper title - The best example of this is a section header called "What is Blar". Most people who are looking for information will sooner or later end up at Google's front door and they are going to type "What is Blar?". Do you want them to be given a link to the front page because Google can't actually tell you what it is, or would you like a link taking you to the section of the documentation which describes what Blar is? Do you want the punter's question to be answered straight away or do you want them to have to hunt around your web site trying to figure it out; all the while wondering why Google didn't display the "What is Blar" page!
2. Have a proper start to the What-Is section - Your What-Is section should start in the standard format beginning with "Blar is a ...". Once you have said what it is (in one sentence), you can follow it up with another sentence to say what it might be used for or what problem it solves.
3. Don't use acronyms - Every time you use an acronym you are giving the reader a chance to leave because they have to go away and look up the acronym. You could argue that if the reader doesn't understand what JPA stands for then they have no business reading your documentation, but you will find that in every given area (especially in computing) about 75% of your readers will be beginners. If they were experts they probably wouldn't be looking for help in your documentation!
4. Don't use jargon - This is the section of your documentation that users are going to read first. They are going to use the outline drawn up from this section to base all their subsequent research on, so make it simple. Anyone should be able to read your What-Is section and know if it is something they would like to invest their time in.
5. Keep it short - If you can't condense your project down into a couple of sentences how are you going to organise your real documentation.
6. Don't reuse words from your project name to describe the project - A nice example of this is "A toaster toasts your bread" - hurray! If I don't understand the concept of toasting then I'm not going to get anywhere.

Examples

Here are a couple of examples to describe what I'm getting at.

1. What is a Toaster? One sentence that really says it all.

   "A Toaster is a device for cooking bread."

2. What is Apache Camel? Only 2 sentences. Even a brick layer or an accountant could have an idea about what this project does:- something about writing industry plugin'able standards.

   "Apache Camel is a rule-based routing and mediation engine which provides a Java object based implementation of the Enterprise Integration Patterns using an API (or declarative Java Domain Specific Language) to configure routing and mediation rules. The domain specific language means that Apache Camel can support type-safe smart completion of routing rules in your IDE using regular Java code without huge amounts of XML configuration files; though XML configuration inside Spring is also supported."

3. What is MantisBT? The first part of the first sentence outlines what the project is, then follows a brief elaboration. Still only 3 sentences, but it tells you everything you need to know to decide if you want it or could use it.

   "MantisBT is a web based bug tracking system that was first made available to the public in November 2000. Over time it has matured and gained a lot of popularity, and now it has become one of the most popular open source bug tracking systems. MantisBT is developed in PHP, with support to multiple database backends including MySQL, MS SQL, PostgreSQL and DB2."

I wrote to the project lead of QMailToaster explaining to him how difficult I found it to figure out what his project was for. So just to show there is no hard feelings here's their new version. It still needs a bit of work (IMO) but it's a start, "What is QMailToaster?"

"QmailToaster is a full blown mail server distribution for use with most rpm based Linux distributions. QmailToaster is distributed as source rpm's which require compiling on the host system before installation. This is done to meet licensing requirements set forth by the original creator of qmail, D. J. Bernstein."