As before, Alfresco DevCon 2011 was a great experience. Events were held in both San Diego and London, and I was able to see different presentations at each event. Unfortunately for me, only about half of the presentations were the same between the two events. That means that even after attending both events I still missed a lot of sessions I was excited to see.

This post is to document some of the best tips that I picked up at DevCon (well, at least the best easy-to-blog-about tips). I apologize that I neglected to keep track of which session provided each tip.

There were lots of good presentations, so I recommend you spend some time browsing the slides which are posted at Slideshare:

http://www.slideshare.net/alfresco

Rendition vs Transformation

The discussion around a question yielded this clear explanation about when to use the Rendition Service and when to use the Transformation Service:

The Rendition service is the main API for customization use. It allows the manipulation of external metadata in Alfresco, and preserves a relationship between the source content and the transformed content which can be used to trigger updates. The Content Transformation Service is for generating transformed content without an association, and can only manipulate the direct content. It is necessary to understand the transformation service when adding new transformations.

Supported Content Formats

In version 4.0 Alfresco lists all of the mimetypes registered with the system and specifies what transformations are supported. Just browse to this URL:

[host-and-port]/alfresco/services/mimetypes

Alfresco API Documentation

The Share Extras project has a great generated documentation for the JavaScript API:

http://sharextras.org/jsdoc/

There are also JavaDocs available for the Java API here:

http://wiki.alfresco.com/wiki/Alfresco_JavaDoc

Packaging Best Practices

Jeff and Will gave an excellent summary of best practices around packaging extensions to Alfresco. Check out slides 24 and 25 of their presentation:

http://www.slideshare.net/alfresco/share-customization-best-practices

I liked it so much, I used it to update this wiki page.

The first half of the presentation by Gary Cox of Blue Fish Development Group also gave excellent advice on this topic.

When did it get so hard to buy a Linux computer? From 2004 to 2010, every computer I bought had Linux pre-installed. I purchased from Dell and Lenovo, but HP and Asus also had them on offer. Sure, I had to make compromises, but it was possible.

I was unpleasantly surprised when in the summer of 2010 I needed to buy a new work laptop and found that the Linux options had disappeared. After much painful searching I gave up and paid the Windows tax—twice, since I needed a separate license for the work VM.

Sure, I could get Linux pre-installed through Emperor Linux, but that does not avoid the Windows tax. I couldn’t justify paying more to put on a free-OS that I was going replace anyway (I can’t help myself—I am a control freak).

What I didn’t realize is that buying a Linux machine is still possible, I just had to give up on the big vendors. In theory, going with a big vendor is supposed to provide a cheaper machine with better support. In reality I don’t think a big vendor is an asset as there are small vendors who compete well on price, and when was the last time you got decent support from any hardware vendor? Going with a small vendor holds little risk when measured against the the low bar set by the competition.

I decided to try again when I needed to buy a basic desktop for my mother-in-law. I found a long list of vendors who would pre-install Linux at the Ubuntu website.

After reading some online reviews, I spent most of my time evaluating machines from ZaReason and System76. Both seemed like reliable companies with decent equipment. The System76 Meerkat Nettop seemed like exactly what I was looking for.

I gave the Meerkat to my mother-in-law for Christmas 2010. It is an attractive machine and appeared to be built with decent components and was assembled in a tidy manner. It shipped with a recent Ubuntu which was well configured and had no crapware installed. They did add their own apt repository for some updated drivers, but everything appears to run fine even without that installed. It was so clean, I resisted the urge to replace it (though I thoroughly tweaked it). I was impressed.

Then the machine started smoking. It was less than two months old.

Let’s put this in context: according to the 2009 SquareTrade Laptop Reliability Study nearly 30% of laptops across all manufacturers fail within 3 years. Even the best manufacturers produce failures over 10% of the time. I wasn’t going to give up on a vendor over one failure. The big question was how would System76 respond.

They replaced the machine at no cost to me and with minimal fuss, though it took a little longer than I had hoped. It took four days (including a weekend) to get a response, but it came from a human. Then a few weeks to get the machine replaced. System76 felt like the problem was due to my using a faulty power strip (it was old, but had always been reliable), so I bought a new one to use with the replaced machine. The machine is now a year old and has not had a problem since.

Summary: buying from System76 is at least as good of an experience as buying from one of the big vendors, and I would say it is even better given that I get a good operating system with no crapware. On the whole, I am very happy I did business with them and I would purchase from them again. (Full disclosure: I have no relationship with System76 and doubt they will even see this blog post. I just want to see a good vendor stay in business.)

Thank you System76, may you live long and prosper!

We just finished another open enrollment period at work. It is always stressful for me to be forced to lock in a health insurance selection for another 12 months. This is one of the most high risk and complicated decisions I make every year; there are loads of options, lots of trade-offs, and thousands of dollars at stake. All that is ignoring that my family’s physical well-being is directly impacted and there is a potential for life-and-death consequences. Perhaps I am a bit of a worrier.

As in years past, I built a spreadsheet model of all of the options and played with various tragic scenarios of how much it would cost me if my family went to the hospital X times. And as in years past, an HDHP + HSA comes out as the cheapest plan regardless of the variables I use.

A High Deductible Health Plan or HDHP is a plan that is meant to put the consumer in control of his or her health spending. The general features of an HDHP are mandated by law and don’t vary much, so I won’t go into great detail. Simply put:

• Preventive care is completely paid for,
• Nothing else is covered until an annual deductible is met,
• At which point everything is covered.

So I am responsible for covering the majority of my family’s health care needs out of my own pocket. However, I pay significantly lower health insurance premiums. This means:

• Less money to insurance,
• More money for my family,
• More flexibility in when we incur costs which fits our variable income,
• And more of a say in what type of medical care I receive.

HDHP’s are usually paired with a Health Savings Account or HSA. This is a special bank account where I can put pre-tax money to grow tax-free. I can only use the contents of the account on medical expenses for my family, but (unlike a Flex Spend Account) the money will always be mine and I can use it even if I go back to a traditional health insurance plan at some point in the future.

An HDHP + HSA has been a winning combination for our family. However, I have found that the features of an HSA vary widely so it takes some caution in selecting your financial institution. Even more than the plan features, I have found that most HSA providers are generally incompetent. I guess there is no pressure to provide a good product when the majority of your customers are forced into the relationship by the insurers. I have a few tips to help you get the most out of an HSA:

Choose who you bank with.

If your employer offers an HDHP, they will likely also setup an HSA for you at the bank which lobbied the HR department (or the insurer) most aggressively. I have not had an insurer suggest I bank with anyone competent. I suspect that they put all their resources into selling the insurer, and none of their resources into actually providing a quality product. Errors abound and hidden fees lurk. I have friends who have worked for some of the largest HSA providers in the country and their horror stories are appalling. These people do not have your best interests at heart.

I have had much better luck with community banks and credit unions. There is a trade-off, however, as these smaller institutions offer a much more limited range of investment options. Per my next point, I don’t think in practice this presents much of a problem.

Save enough to self insure.

This system will not work if you don’t have the discipline to put some of the money you save away to cover future medical expenses.

An HDHP caps your annual out-of-pocket expenses at around twelve thousand dollars for a family. You will probably not have that kind of money the first year, but you will probably not have enough cash to cover a major medical crisis that first year even with average insurance. My strategy is to look at what I would spend on regular insurance, and put the difference between the monthly cost of my HDHP and that insurance plan into my HSA as a direct deposit. You will be surprised how quickly this builds, and most employers that offer an HDHP will also provide some seed-money for the HSA.

Remember, you are acting as your own insurer for non-catastrophic medical events. Your HSA is not an investment that you expect to grow. I recommend keeping your first twenty-four thousand dollars in a secure and accessible savings account. Only once you have more than that two year catastrophe level saved should you worry about investment options. I’m not there yet.

Watch out for hidden HSA fees.

The big guys nickel and dime all over the place. I found the worst fees kicked in when I left my employer and thereby lost their sponsorship of my HSA.

Keep control of your money.

Once I noticed the monthly fees they were taking out, I decided to get my money into a local institution that I could trust. Unfortunately, that bank made it very difficult to get my money in a way that wouldn’t incur huge tax penalties. Be patient, and fill out all of their paperwork. They have to give it to you eventually.

Things to be aware of.

My recommendation is to not use the bank suggested by your insurer, but to use a community bank or credit union that you have can trust. This does have some implications that you should be aware of:

• You are indirectly (through your insurer) paying a bank for services you don’t use. This violates my sense of justice, but there is nothing I can do about it and it is still in my best interests to use another institution.
• Your might not be able to populate your account via payroll deductions if you don’t work with the bank your payroll company or insurer demands. Talk to your HR people, as this is kind of silly—they can direct deposit anywhere they want, so it isn’t a technical limitation. I solved it by doing an automatic withdrawl from my savings account a few days after my pay check is deposited. The accountant makes the post-tax dollars pre-tax at the end of the year.
• Understand that an HSA can only be owned by one person. If you are married, I suggest you pick one name and make all deposits under than name. When I naively allowed my insurer to setup my HSA, they did it under my wife’s name because she is a few months older than me. But my current employer will only contribute dollars under my name. Being able to chose which name gets used is another benefit of managing it yourself instead of letting your employer / insurer do it for you.

Name and shame!

• Wellsfargo—warned away due to horror stories.
• Mellon—really expensive.
• Health Equity—I did some work for them when they were a new startup but they refused to pay me (and were rude about it). Years later I was in the unfortunate position of having to use them as my HSA provider. Big mistake. They act like a bank, but are not regulated like one. It took months to get my money out and ended up being really expensive in terms of fees. Web site was annoying. Customer service couldn’t help me get to my money. They said they would wave fees and then didn’t. It was a real horror story with hospitals wanting to get paid and HealthEquity loosing five thousand dollars. Stay away!
• Chase—worst web site on the planet. Can’t directly deposit money outside of the payroll process. Wouldn’t work with HealthEquity to get my money rolled over to their accounts. Expensive fees.
• America First Credit Union—Aren’t credit unions wonderful! No fees. Good service. However, no investment options.
• Stanford Credit Union—Nationwide membership with only a donation to their museum.

Recommendation: Find a credit union.

YCombinator’s Hacker News recently linked to an interesting post entitled “What every computer science major should know”.

I think it’s a pretty good list, but like others I have seen, it has a hole around the knowledge domain of Content Management, Content Modeling, and Information Architecture.

There are some core tools that every software engineer needs in their toolbox: a programming language, a scripting language, a database, source control, build management, bug tracking, project management skills, and more. If you aren’t already aware of the tools that exist to solve these common problems, you will end up re-inventing the wheel. All too often, software engineers and systems architects reinvent the wheel around content management.

I recognize that I am biased. When I started working for Alfresco two years ago, I thought content management was used for building web sites. It took me a while to realize that every time I built a file store with a flat-file index, every time I stuck collaborative content in Subversion and then struggled with how to get my teammates to update it, and every time I tried to grep Word Documents, I was dealing with content management. These aren’t web-based problems necessarily, and they certainly aren’t easily solved with a database. Like most engineers, I muddled through. I accepted my poor solutions as “how things are done”, and moved on to more (at the time) interesting problems.

Thank goodness for content management. Someone finds these problems interesting enough to worry about them night and day. These people have built some great solutions that are both easy to deploy and free. While working at Alfresco, I have come to enjoy solving content management problems. I think every engineer’s life will be easier if they are considering a good content management tool at least as often as they consider setting up a database.

I recently changed my role at Alfresco. Instead of being a “Solutions Engineer” (our title for Sales Engineers), I am now more involved with helping our Community interact and grow (I never thought I would be joining a Marketing Department, but here I am). As part of that role, I am helping to build awareness of Alfresco and content management in general.

Since this is my blog, I can shamelessly plug the Alfresco QuickTake video I did about “5 Tools that Alfresco Provides Developers”. When I watch the video, I only see my mistakes in presentation style. But my goal with that video was to describe some of the ways Alfresco can assist developers with generic content management problems, and thereby save people from re-inventing that particular wheel. Hopefully it helps you understand why a good content management tool will help you wax strong in all three virtues of a programmer.

As part of my new role, I also have been able to participate in planning our annual Developer’s Conference. I highly recommend you consider attending. either this year or at some point in the future; you will be surprised how many problems that confront you can be solved with an open source tool like Alfresco.

If you are on the fence, (or even if you aren’t), you should check out this decision matrix. Really—check it out; you will thank me later.

So put this tool in your toolbox. It’s free, it’s effective, and then you can get back to solving new problems.

I worked as a one-man shop for an extended period of time. Though it was fun to wear a lot of hats, I really missed having a team of people to collaborate with. To cope, I learned to rely on the IRC community at Freenode. Freenode is a great place to bounce ideas off of intelligent people, get help when stuck on a problem, or simply to connect to other human beings. It is fun to give help, and it is a relief to receive it. Since joining Alfresco, I have had a team of brilliant people to work with, so IRC hasn’t been as important. But with my new role overseeing Community Technology, I was asked to moderate our community IRC channel. In my efforts to encourage participation and fend off the trolls (thankfully none yet), I learned about maintaining an IRC channel on Freenode and wanted to share some tips.

Using IRC

IRC is a great way for people who don’t otherwise know each other to meet and interact. There are lots of IRC servers around the net, some of which are juvenile in tone or focused on illegal activity. Freenode is an IRC server with a very specific mission: “to provide discussion facilities for the Free and Open Source Software communities, for not-for-profit organizations and for related communities and organizations”. It is a very friendly place and active moderators keep it comfortable and inviting. It is a great place for people new to a technology to learn the ropes, meet like-minded professionals, and help others.

The Basics

Pick a client

Which client is best for you depends on your operating system. Here are two places with good lists:

http://www.ircreviews.org/clients/

http://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients

Connect to the server

Configure your client to log into chat.freenode.net .

Register a nick

Registering your nick prevents othemail er people from pretending to be you. On Freenode, you must provide an email to register your nick. That email is only used for password recovery. Your nick will stay registered to you as long as you identify with a password once every 90 days.

1. Run this command: /msg nickserv register <password> <email>
2. Then validate your email

You can probably configure your IRC client to automatically identify your nick each time you log in, but if you need to do it manually use this command:

/msg nickserv identify <password>

Sometimes when you lose a connection IRC won’t notice right away. When you try to rejoin your channel, your nick will still be in use and will not be available to you. People often configure their clients to use an alternate nick in these scenarios, usually by appending one or more underscores (_) to their normal nick. You can also connect to a channel using more than one nick simultaneously. This is often used to play a trick or joke in a channel.

Join a channel

Discussions actually happen in a channel. The name of a “Primary Channel” starts with a single hash (“#”) and is discussion forum for a specific project or community (like Alfresco, or your local LUG). “About channels” start with a double hash and host conversations about a topic or subject (for example: ##security). Feel free to join us in #alfresco for a stirring discussion of social content management! </plug>

Participate

When you join a new channel, take a minute and read any conversation that is going on before saying anything yourself. When you feel comfortable with the context, feel free to ask a question. Just blurt out your inquiry; there is no need to first ask for permission to ask your question. If there are other people listed in the channel, but nothing seems to be going on, then be patient. Busy professionals often leave their IRC clients running all day and just check once in a while to see if there are any interesting questions to answer or discussions to read. Someone might decide to give you a hint on your question hours after you ask it. If no one responds, don’t get offended. Assume that no one knew the answer or had time at that moment and keep participating. Most important, once someone answers your question please stick around and see if you can answer anyone else’s question. You might learn something else while you are at it.

IRC is low bandwidth communication, and it is easy to misunderstand what someone else says. Assume the best in people and ask for clarification when needed. Try to write so that your words will not be misunderstood, and remember that you never know when your last sentence will show up in a search engine’s archive. Also, keep in mind that you are not as anonymous as it at first appears.

Bots

Internet Relay Chat is a very lightweight protocol for group discussions. It doesn’t do fancy things like editing previous posts or archiving discussions. Because it is so light weight, it is very easy to program automated systems to monitor the channel and respond to simple commands. These are called “bots” and can do fun things like look up a word in the dictionary, give you the weather, or archive the discussion. Most bots have a “help” command. The NickServ bot is how you registered your nick earlier. Try /msg nickserv help to see what else it can do.

Useful IRC Commands

Commands start with a “/”. Feel free to try these out.

• /help (display information about a command—works without any command too)
• /me (display text as if it were an action)
• /whois (provide information about a user)
• /info (provide network and channel information)

Administering a Channel

Creating a new channel only requires joining an empty channel—it will be created the first time it is requested. The first person to join a channel is automatically the founder of the channel, and can become an operator (aka admin) at any time. By default channels will disappear when the last external connection ends, but channels can be registered so that they do not disappear. Channels can only be registered by a user with a registered nick.

Channel management is done with the ChanServ bot (try /msg chanserv help).

Becoming an operator

You can’t administer a channel until you become an operator with the op command. Only an operator can create other operators. If no operators are left in a channel, the channel can no longer be administered. You shouldn’t be operator any longer than you have to, as it creates an unhelpful class distinction among channel users and not knowing who is operator can help keep trolls from causing trouble. Once you have finished, drop to normal user status with the deop command.

Register a channel

/msg chanserv register #<channel>

Flags

Settings like operator privileges only last for the current session. To make settings persist, Chanserv must have an entry in that channel for the nick with the appropriate flags. Details on the flags available can be seen with /msg chanserv help flags. Flag manipulation looks like this:

/msg chanserv op #<channel> <username>
/msg chanserv flags #<channel> <username> <flags>
/msg chanserv deop #<channel> <username>

Your community should probably have multiple founders so that the channel is not left without an operator should one founder stop showing up. Here is how to grant founder status to a user in your channel:

/msg chanserv flags #<channel> <username> +*F
/msg chanserv flags #<channel> <username> -OV

The first command grants all flags to a user, including the founder flag (F) which must be explicitly granted (it isn’t part of the *).

The second command removes two flags which normally should not be used. “O” automatically makes the user an operator when they join the channel, which should be avoided as previously explained. “V” automatically voices a user when they join the channel. Voicing is only needed on moderated channels where new users cannot speak upon joining without the voice flag. An open channel for community participation should not require this, and not having the V flag makes it easier to identify a problem with the channel.

You can see all the flags assigned to all users in a channel with:

/msg chanserv access #<channel> list

Channel modes

Channel modes are settings on the channel which determine how the channel operates for all users. The most common two modes are “m” which moderates the channel and means that only voiced users will have their messages broadcast to channel participants, and “i” which makes a channel invite-only. For a community discussion channel you probably want to turn off both of these modes with a command like this:

/mode #<channel> -im

You can check the modes currently assigned to the channel with:

/mode #<channel>

Setting a topic

Setting a topic helps newcomers into your channel identify what discussions should focus on, and any other relevant information (like if the channel is logged). Set the topic with the /topic command.

Recover

There is a shortcut ChanServ command called Recover. I recommend against ever using it as it has a lot of effects that took me a long time to undo.

Kicking and Banning

The main duty of a channel operator is to (on rare occasions) wield the heavy stick of kicking or banning a user who is hurting the atmosphere of the channel.

A kick is a temporary disconnect, and will hopefully remind the user to get along with others. The syntax is:

/kick <username>

A ban prevents that user from reconnecting while the ban is in place. This is done by setting up a filter that if matched on the username or hostname will prevent connection. You set this with a +b mode and filter as follows:

/mode #<channel> +b <filter>

Where a filter is of the format nick!user@host, and any part can be substituted with “*” as a wildcard. If you have trouble banning a user on Freenode, then pop into #freenode and ask a helpful network admin what to do. An IP ban or network-wide ban may be necessary.

To view existing bans in place in a channel use:

/mode #<channel> +b

Conclusion and Acknowledgments

Hopefully this has been helpful. For more information use the help command and read this page:

http://freenode.net/using_the_network.shtml

Thanks goes to Hazmat, who setup #alfresco years ago and helped me get admin rights. I also owe a big thank you to Prodego who volunteered some time to walk me through the necessary incantations to control the channel. And of course, thank you to all of the volunteers who keep Freenode healthy and helpful!