Extending Orchard Workflows with Custom Activities

Extending Orchard Workflows with Custom Activities

I stayed awake way too late last night having fun extending the Workflow Module in the upcoming Orchard CMS 1.7. Just like I have done several times similar with the Orchard Rules Engine, I wanted to create my own custom Workflow Activity that displayed in the toolbox and could be dragged onto the workflow surface. Given this was my first custom workflow activity I wanted something fairly simple, but useful. After a few minutes of thought, I decided to create an activity that started a workflow when a user logged into Orchard - a Login Activity!

Login Activity for Orchard Workflows

As I browsed the built-in workflow activities in the toolbox I didn't notice an activity that started a workflow when a user logged into Orchard. Of course, you could use the Signal Activity as a generic method, but I would like to be a little more explicit in this case. In the past I have built workflow-like functionality for clients in Orchard that occurred when a user logged in. One recent example is when the Terms of Service ( ToS ) agreement had changed for an application. The client wanted the user redirected after login to the ToS and have them agree to it before continuing. There are numerous other examples so a login actitivity could be useful.

Workflow Activity in Orchard CMS 1.7

The best way to learn how to create an activity is to look at the Orchard Workflow Module source code. In general, all activities implement IActivity and activities are divided into events ( like Login ) and tasks. The main difference I see between events and tasks are that events are blocking. It all comes down to one simple property: bool IsEvent. For events, IsEvent returns true. Activities are populated in the toolbox by the ActivitiesManager.

Workflow Forms

Each activity will probably require a form to add information. In my case, I wanted to filter logins by role. This would allow the Orchard Developer to specify that the workflow should start only when a user with a certain role logs into Orchard. Just like with the Orchard Rules Engine, you create forms using a combination of the Forms API and Tokens in Orchard.

As luck would have it, there is already a form included with the Orchard Workflow Module for choosing roles, called SelectRolesForm. This is used by the built-in IsInRole Activity and possibly others. This saved me the effort of having to create my own form. [Aside: As it turns out, the IsInRole Activity would turn out to be much more valuable than the SelectRolesForm as it has code for determining the role of the user who logged in and comparing it to the roles chosen in the SelectRolesForm. I used this same code with some simple modifications. I also grabbed the icon for display in the Orchard Workflow Module. This saved me a lot of effort as well. ]

Custom Workflow Form in Orchard CMS 1.7

There is a Forms Property on the activity that returns the name of the form that should be displayed to the user. In this case it returns "SelectRoles". You also have to create a view and a stylesheet to get this all up and running. Just use the built-in activities as a guide to make it all really simple.

Custom Orchard CMS Workflow Activity

When all is said and done I created a simple workflow using the new Login Activity to trigger a workflow. In this case I just displayed a notification message on the website as a test to see if the activity was indeed working.

Orchard CMS Workflow

The Notify Task uses tokens to display "{User.Name} logged in!" When I select the role of Administrator to start the Orchard workflow and log in as admin, I get the following notification as expected.

Orchard CMS Workflow Notify Task

Conclusion

The best way to learn how to create activities for the new Orchard Workflow Module in Orchard CMS 1.7 is to dive into the source code! I created this Login Activity fairly quickly using the IsInRole Activity for inspiration. I am hoping Orchard CMS 1.7 will be released this week, but the Orchard 1.x source code is always available on CodePlex for you to use right away!

Check out some of my other Orchard Tutorials that deal specifically with new features being added to Orchard 1.7: