Tag: Tutorials

Alfresco Developer Series Tutorials Upgraded to SDK 4.0

Alfresco SDK 4.0 has not been released yet, but it is in beta and developers are starting to use it.

To help developers who want to learn the platform using SDK 4.0 and Alfresco 6, I’ve created an sdk-4.0 branch on the Alfresco Developer Series tutorials project. The tutorials on that branch have been upgraded to the new SDK 4.0 structure.

Aside from the project reorganization and the introduction of the Docker modules the underlying code did not have to change.

In addition to the tutorial source code projects, I also updated the tutorial content bodies to reflect the Docker and Docker Compose features of SDK 4.0 and the minor changes regarding how projects are run and tested. While I was in there I enhanced the markdown with syntax highlighting for code snippets.

Once SDK 4.0 goes GA I will merge the sdk-4.0 branch in the tutorials project into master. Those needing tutorials that leverage the old SDK 3.0.1 will still be able to get them via the sdk-3.0.1 tag.

Incidentally, I used the Alfresco SDK Upgrader script to upgrade these projects and it saved me a lot of time. If you want to know more about upgrading your 3.0 projects to 4.0, either manually or via the script, see this blog post on upgrading.

So, if you are going to learn Alfresco using the latest release, give the updated tutorials a try. If you find any issues, please create an issue on GitHub, or, better yet, fix the issue and open a pull request.

Photo Credit: Veere: tools, by docman, CC BY-NC 2.0

Exploring Blockchain

I’ve been exploring blockchain technology lately. In this post I’ll share what I’ve learned so far. I should point out that my interest is squarely on how blockchain can be applied to solving business problems–I’m less interested in cryptocurrency.

Blockchain: A Brief Intro

A blockchain, as the name suggests, is a linked chain of blocks. Each block contains arbitrary data and a link to the previous block. Because these links are created using cryptographic hashes, blocks are hard to alter. The chain is continuously growing. Transactions run which add new blocks, and those transactions are validated by other servers before they are accepted into the chain.

So a blockchain is like a database, but instead of running on a central server controlled by a single entity, the blockchain is distributed across many servers, and, depending on which blockchain you are talking about, the blocks in the chain may be visible to the public.

The reason blockchain is often referred to in the context of cryptocurrency is because cryptocurrencies use a blockchain as a distributed ledger to track cryptocurrency trades. But that is only one of many possible use cases.

Wrapping up this brief intro, realize there is no single blockchain. You can run your own private blockchain internally. Or, you could set up a private blockchain between your company and your partners. Or, you could leverage one of the public blockchain networks. It really depends on exactly what you are trying to do.

For more on the origins of blockchain, see The Wired Guide to the Blockchain.

Use Cases

To identify problems that are good candidates for blockchain applications it helps to summarize the technology’s most noteworthy characteristics:

  • Data blocks are immutable. Once added to the chain they can never be changed. This will lend itself to problems where we need to retain the data for a long time or where we need to ensure that once created, the data does not change. Currency trades have already been mentioned, but you can easily come up with other examples such as health records, vehicle service records, government documents, or electronic votes.
  • Distributed/No single point of control. The distributed nature of the blockchain is attractive for multiple reasons. First, there is no single point of failure. If a server goes down or a company goes out of business, the chain is still intact and functional. Second, the data is automatically made available to every node in the network. This means you don’t have to solve data sync or replication–it just happens.
  • Transparency. In a public blockchain, every block is visible to everyone. Some of the data might be encrypted or hard to make sense of out-of-context, but you can inspect it, if you want.
  • Trustworthiness. I’ve already mentioned the difficulty in hacking the data. Another aspect of trustworthiness is about making sure that any logic that runs as part of the blockchain runs the same way every time. Yes, that logic could contain bugs, backdoors, or bad actors doing nefarious things, but the blockchain guarantees that it will always execute the same way every time.

Here’s a simple example that leverages all of these strengths. Suppose we decide to start a temperature prediction market in which participants try to predict the temperature in a given city on some date months into the future. We could store the prediction (predicted temperature, city, date, user) on the blockchain as well as the actual daily temperature readings.

We’re capturing data and that data is distributed across the network, which is cool, but we can also store logic on the blockchain–some implementations call these “smart contracts”, but they are really just scripts. In this example, when an actual temperature reading is saved the script will determine winners and losers by comparing the actual temp with the predictions.

If we wanted to add a reward mechanism to our prediction market, a prediction could have an associated wager amount. The smart contract would then not only be responsible for tracking the predictions that came true, but could also move funds from losers to winners, all without any middleman to make sure that happens.

This example takes advantage of the strengths of blockchain:

  • Once a prediction is made or an actual temperature reading is captured it cannot be changed (immutability).
  • If a server shuts down the actual readings can still be captured, predictions can be validated, and wagers can be paid (distributed).
  • If someone wants to make sure their prediction was captured correctly, they can inspect the block (transparency).
  • And, finally, no intermediary is needed to pay off the bet–the contract is guaranteed to be executed as written when the conditions that trigger it are met (trustworthiness).

A Developer’s Perspective

I wanted to experiment with some of these concepts on my own, so I started with Ethereum. Ethereum is an open source blockchain platform. You may have heard of people trading a cryptocurrency called Ether (ETH). You can use the same Ethereum platform to develop and run your own distributed applications (“dapps”) regardless of whether or not they are related to cryptocurrency.

Ethereum developers use a command line tool called geth to perform tasks with their Ethereum nodes and a tool called Solidity to compile JavaScript into smart contracts.

To try this out I spun up an Ubuntu server, installed geth and Solidity, then worked through the Greeter example. It’s not very exciting–Greeter is essentially a hello world example. But, it does help you understand what it takes to start up a local test network and to write and compile smart contracts.

One of the immediate learnings is that transactions on Ethereum cost money (called “gas”). Even if you are running a test network, you must first mine enough Ether on your test network before you can run a transaction. On the live network, the cost of running a transaction goes to the miners who are running servers that are busy validating transactions and updating the blockchain.

Another gotcha for me was that your miner has to keep working while you deploy your smart contract. It makes sense now–the smart contract is stored on the blockchain and therefore it must be validated like any other transaction, but it was definitely not clear to me while working through the tutorial.

Ethereum was definitely interesting, but I was looking for something a little more business-oriented. That’s when I found Hyperledger Fabric.

Hyperledger is an umbrella open source project that includes several blockchain related sub-projects. One of those is called Fabric, which, like Ethereum, is a blockchain implementation, but Fabric has some features that make it more attractive to businesses, such as a modular architecture and the ability to assign permissions to data and smart contracts.

Another very attractive sub-project is Hyperledger Composer. Composer is a set of tools that abstract away some of the nitty-gritty details related to creating and managing smart contracts (called “chaincode” in Hyperledger parlance).

The easiest way to try Fabric and Composer is the IBM Blockchain Platform Playground Tutorial (IBM Is a major contributor to the Hyperledger project). This is essentially a quick intro that you work through in your web browser.

The Playground Tutorial is worth it to get exposed to the concepts, but I wanted to run everything locally. You can do that easily with Docker. IBM’s Developer Tutorial walks you through setup and then takes you through a very simple “commodity trading” example. This tutorial is just a little deeper than the Playground, but at least you are running everything in containers running on your machine.

Finally, I came across J Steven Perry’s Hyperledger tutorial on developerWorks. This three part tutorial was awesome. You essentially build a “perishable goods business network” that models how contracts, shipments, and payments work with growers, shippers, and importers. By the time you are done, you’ve got GPS and temperature sensors sending data to the blockchain, chaincode that is looking at the contract and sensor data to determine how much stakeholders should get paid based on contract terms, and a RESTful API that you can call to make the whole thing work.

This tutorial really highlights how a Hyperledger solution can be used to share data between business partners in a distributed fashion while ensuring that only relevant operations and data are exposed depending on stakeholder role.

The developer-friendly tooling also flattened the learning curve significantly when compared to my out-of-the-box experience with Ethereum. I’m not saying one platform is inherently better than the other–it depends on what you are trying to do. I just felt much more productive with Hyperledger Fabric and Composer.

Tangential Topics

As I was exploring blockchain I went down a few interesting “bunny trails” here and there. Rather than go into details, I’ll just provide links in case any of it looks interesting:

Summary

I’m really glad I took the time to dig into blockchain. The hype is definitely at a fever pitch. They say blockchain engineers are in high demand right now. I suspect that one day we’ll all have blockchain in our toolbox, selecting it to be part of our solutions when it make sense, just like we do with any other technology.

Photo Credit: Chain, by Astro, CC-BY 2.0

Updated tutorial: Creating custom advanced workflows in Alfresco

I have published a major revision of my “Creating custom advanced workflows in Alfresco” tutorial. Major changes include:

  • The tutorial now uses the Alfresco Maven SDK to instantiate the projects and to produce and install AMPs.
  • The tutorial no longer refers to jBPM, except to give brief historical context as to why the platforms includes both jBPM and Activiti.
  • The tutorial no longer includes any references to the old Alfresco Explorer client, except where it pertains to using the Alfresco Workflow Console, which is only available as part of the Alfresco Explorer Client.
  • Significant wordsmithing and re-organization to improve style and clarity.

I have tested the steps and the code against Alfresco 4.2.e Community Edition and version 5.14 of the Activiti Process Designer for Eclipse.

By the end of the tutorial, you will know how to:

  • Create, deploy, and run business processes using Activiti embedded within Alfresco.
  • Configure Alfresco Share to display custom forms when starting Activiti workflows or managing workflow tasks.
  • Use the Alfresco Workflow Console to deploy process definitions, start workflows, and delete workflows.
  • Add business logic to your process definitions using JavaScript and Java.
  • Assign workflow tasks to users and groups.
  • Add timers to your process definitions to take an action automatically after a specific time period.

The tutorial assumes you already know how to use the Alfresco Maven SDK. If you have never used it, take a look at this tutorial. The workflow tutorial also assumes you have worked through the Custom Content Types, Custom Actions, and Intro to Web Scripts tutorials.

The source code and the tutorial itself reside in GitHub. If you find problems or want to make improvements, please fork the project, make the change, and send me a pull request.

Updated tutorial: Introduction to Alfresco Web Scripts

I have published a new version of my Introduction to Web Scripts tutorial. This is a major revision that refactors the tutorial to leverage the Alfresco Maven SDK and AMPs. In addition, I have done a little bit of reorganization to improve clarity and a lot of wordsmithing to make the tutorial more consistent with the others in the Alfresco Developer Series.

By the end of this tutorial, you will know how to:

  • Extend Alfresco with your own custom RESTful API.
  • Write web scripts that respond to GET, POST, and DELETE requests over HTTP/S and return data in both HTML and JSON.
  • Use the web scripts console to display documentation and debug info on your custom and out-of-the-box web scripts.
  • Make AJAX calls to your custom web scripts.

The tutorial assumes you already know how to use the Alfresco Maven SDK. If you don’t, take a look this tutorial.

The tutorial text and all of the source code related to it are on GitHub. If you see problems or opportunities for improvement, please fork the project and send me a pull request.

Updated tutorial: Creating Custom Actions in Alfresco

I have published an updated version of the Creating Custom Actions in Alfresco tutorial. Similar to the recently updated Working With Custom Content Types in Alfresco tutorial, this version has been updated to match the refactored code which now assumes you are using the Alfresco Maven SDK to produce AMPs and that you are using Alfresco Share as the user interface. I’ve removed all references to Alfresco Explorer.

The Custom Actions tutorial covers:

  • What is an action
  • How to write your own custom action in Java
  • How to invoke the custom action from a rule or from the Alfresco Share UI
  • Configuring an evaluator to hide the UI action when certain conditions are true
  • Configuring an indicator to show an icon in the document library when documents meet certain conditions
  • Writing and executing unit tests with the Alfresco Maven SDK

If you aren’t familiar with the Alfresco Maven SDK and you need help diving in, take a look at this tutorial.

All of the tutorial source code and text for the Alfresco Developer Series of tutorials is on GitHub. Please fork the project, make improvements, and send me pull requests.

Next on the to-be-updated list is the Custom Behaviors tutorial. I expect that to go live sometime next week.

End-User How-To Videos for Alfresco Community Edition

I’ve started creating some how-to videos for performing common end-user tasks on Alfresco Community Edition. You can get to them all on this YouTube Playlist or take a look at the ones created so far, below…

The playlist currently includes:

  • Reviewing the sample site
  • Adding users (one at-a-time and by importing a CSV)
  • Creating groups
  • Create a new site
  • Five ways to create content
  • Versioning a document
  • Starting a workflow
  • Updating your profile
  • Exploring social features
  • Configuring user and site dashboards
  • Adding new features to your site

In the very near future I’d like to add some technical how-to’s for Community Edition, including LDAP configuration, CIFS/WebDAV/FTP/IMAP configuration, installing the SharePoint Protocol, installing the Google Docs Integration, configuring inbound and outbound SMTP, basic content model extensions, and basic dashlet development.

If you have ideas for Alfresco Community Edition videos you’d like to see that would help make your Alfresco Community Edition rollout more successful, let me know.