Netcommunity single sign-on

I wittered on last time about Netcommunity's Single sign-on feature, so this post will talk about one way of implementing it, along with some code at the end. To get this to work I looked at the very helpful sample code on Blackbaud Labs (alas, in VB.net).

We have an intranet here that is hosted by Netcommunity, and only logged in users with a certain role (staff) can view it. However, staff were finding it a pain to have to log in to the website to be able to view the intranet. Therefore, after our recent upgrade to a newer version of Netcommunity that supports single sign-on (SSO), I thought I'd try and save them the work.

In Netcommunity configuration, there's a section where you can set up SSO - you need to specify a 'shared key', a bit of text that only you and Netcommunity know. You'll be using it in your code. The principle behind SSO is that you use this shared key, along with the username of the person you want to log in and a couple of other bits of information, to generate a special URL that signs them in automatically without requiring a password. It's very cunning and very helpful.

How I did it

The approach I took was this - I hosted an ASP.NET page on a server on our internal network (not exposed to the internet). This page identified the user (by fetching their active directory / windows username), and then matched that username to a BBNC username (held in a database).

Once it had done that and figured out their BBNC username, the page went through the necessary steps of generating the URL to sign them in. It redirects the user to that URL, and bang - they're signed in. Really easy.

We set the homepage of staff to the URL of the internal server, which then does all the hard work identifying them and forwarding them on to the URL, all quite quickly, which means they get logged in to the website and can happily browse without ever having to type anything in.

This doesn't require any reference to BBNCExtensions, however it does require a couple of inclusions in the code-behind (System.Cryptography for example). Have a look through the sample code and give it a try - make sure you go through the code and add in your shared key and a couple of other bits you need to change. It's all commented so it shouldn't be hard to work out.

As always, if anyone knows of a better way of doing this... let me know about it. I'm still learning.
The link:

http://www.wii-uk.net/media/sso.zip

There's just a text file with the c# for the code-behind in there. Let me know via a comment if you have any problems.

Cheers.

Netcommunity single sign-on

Been a bit busy lately and as such haven't had much time to work on custom parts. Out of interest, has anyone tried the sample code from the last post, or found anything I've posted remotely helpful in terms of figuring out Netcommunity customisations? Please let me know, it'd be interesting to hear about!

Single sign-on

The most recent thing I've been working on relates to Netcommunity - it uses the single sign-on feature that versions of BBNC newer than 5.5 have.

Single sign-on allows you to automatically sign someone into your Netcommunity website, as long you know their username and a 'secret key' (that you define in the Netcommunity admin). If you have those bits of information, you can generate a special URL that (when entered) signs the user in without requiring a password or any interaction on their part. (it is a bit more complicated than that, but I'll go into it in more detail in another post)

A good example that illustrates this system is what I've been working on. We have an Extranet where I work, that is hosted by Netcommunity. It's a set of pages that only users within a certain role can see. However, because only logged in users within a certain role can access the Extranet, staff have to log in each time they want to view the pages.

Therefore I've developed a page that identifies the current user (by fetching their username from Windows), and then queries a database to match their Windows username to their Netcommunity username. Once it's found their Netcommunity username, it builds the special URL required by the single sign-on system and redirects them to it. They get signed in, everyone is happy because they don't have to remember their password.

I'll post up the code & an explanation of how to do it in a subsequent post. There's actually a good tutorial over at Blackbaud Labs, but it's in VB.NET rather than C#. My code is all in C#.

Project: Custom Form (source code) for Netcommunity

You can download the source code for the form I've been describing in the past few posts by following the link at the end of this post. You'll need to make some changes, though - inside the zip are a series of text files. You can put them into Visual Studio and compile them yourself by doing the following:

Firstly, create a new web application in VS. Then delete 'default.aspx' and the accompanying code-behind file. Then, add 2 new Web User Controls to your project (read previous posts for an explanation of how to do that if you're not sure) - name them 'MyPartEditor' and 'MyPartDisplay' or similar.

Copy and paste the code from the text files into the relevant visual studio files. For example, 'editor-codebehind.txt' should be pasted into the code-behind of the 'MyPartEditor' control. I haven't included everything in the text files in terms of headers, so you'll have to add a reference to and include BBNCExtensions (see previous posts for an example). Use common sense and refer back to the previous posts if you get stuck - if you still can't do it, leave a comment.

One file - 'mailvars-codefile.txt' - needs to be placed somewhere special. Add a new item to your project, and select 'C# codefile'. Paste the contents of the text file into that. It's a standalone class declaration that both your editor part and display part can use to create instances of the 'mailvars' object, an object I've created to house certain properties such as the email address the form will use. Read through all the code and hopefully you'll understand how it all links together.

Once you're happy with how it works, you'll need to go through and change a couple of bits - for example, in the part of the display control that gets and sets a cookie, you'll need to change the name of the cookie to something a bit more meaningful. You'll also need to change the url that visitors are redirected to, as in the text files it points them to 'www.yoursite.org/netcommunity' etc.

Do all that, and you're ready to build and then deploy the project. Again, there are instructions for that in previous posts.

If anyone can be bothered to deploy this I'd love to hear about it.

Oh, and bear in mind that if you're running BBNC 5.1 you might have problems, as some of the calls reference parts of the API that weren't available in that version of Netcommunity. It's easy to get it to work with 5.1, though - find statements that look like this:

if (CurrentUser.IsInRole('Registered users')) {

And change them to this:

if (Netcommunity.CurrentUser.IsInRole('Registered users')) {

That should do the trick. (I think, the above is from memory, so if not let me know)

Oh, and the link. Download the source code here:

http://www.wii-uk.net/media/display-acsx.zip

Enjoy.

Project: Custom Form for Netcommunity

Well, I've pretty much finished off the form I was talking about in the last post. The purpose of the form is to ensure that we capture details from people who are interested in downloading our publications. It's been delayed a bit due to other things, but the final functionality is this:

• It checks to see if the user is logged in - if they are, it redirects them straight to the document (registered users will already have submitted their details once).
• If they aren't logged in, it checks for a cookie left behind when the form is submitted. If it finds a cookie, it redirects them to the document (as they must have filled in the form previously).
• If it can't find a cookie, it displays a form for them to fill in. Once they submit the form, a thank you message and a link to the relevant document is displayed.

The custom part uses querystring parameters to determine which document the user is trying to download. This means that instead of linking directly to documents on a page, like this:

www.mywebsite.com/netcommunity/Document.doc?id=560

We instead route the user to the URL of the page housing the custom part, with some parameters so the part knows where to direct the user:

www.mywebsite.com/netcommunity/Page.aspx?id=10&docid=1&doctitle=My%20Doc

This URL can be changed to point to whatever document is necessary - it extracts the document ID from the querystring (docid=1) and uses it to forward the user to that document once the form has been filled in / they have been identified. The 'doctitle=My Doc' parameter is purely for display - when the form comes up, it says 'Ah, you're trying to download My Doc - you need to fill in this form' (or words to that effect).

However, some content editors without much html experience might have trouble building a URL with parameters like this, so the next step is to create another custom part that will build the URL for them and include it on a page. Bonza.

Source code for the form and other stuff soon.

Project: Custom Form for Netcommunity

I've been asked to make a form for our website that will capture the details of the person who filled it in, send their details to us, and then display a link to a downloadable document - the idea being that they only get the download if they allow us to capture their details. Additionally, if a box on the form is ticked, the form needs to email another part of the organisation to instruct them to post out a hard copy of the document.

This is exactly the kind of thing that would be pretty much impossible to do with Netcommunity out of the box, but it should be pretty straightforward to do with a custom part.

My plan is to create a standard asp.net form within a custom part, with validation for the form fields. When the form is posted back to the server, the server will double-check all of the values in the form fields, send us the details, and then check to see if the tickbox has been checked. If it has, a request for a hard copy of the document will be sent to us also. The server will then display the link to download the document. All of that will occur in the display part.

The editor part will allow the Administrator / Content Editor to change some settings, such as the SMTP server name (for the mail), the subject title of the email, the from address, and so on. It would be possible to extend this to allow the editor to customise form fields, but that's not necessary in this case as the form has a very specific purpose. All of these settings will be saved in the BBNC database, and retrieved by the display part and used accordingly when the form is posted back to the server.

I'm going to try to get the form pre-filled with details from Netcommunity, such as name and so on - however, as we're currently running BBNC 5.1, I don't think the API will allow me to retrieve much more than the username of the person on the page without talking to Raiser's Edge (the 5.5 API seems to have a few more options with regards to getting user information). I haven't yet learnt how to talk to Raiser's Edge in a Custom Part (I haven't yet needed to), so I think I might give that one a go and see how I get on.

I'll post up the source code if I can get it all to work. Either way we're upgrading to BBNC 5.6 in a few weeks.

This must seem pretty basic and simple to a 'proper' developer but I'm having fun figuring it all out nonetheless.

Tutorial: Creating a Netcommunity custom part #1

Once you've got Visual Studio (or similar - see below blog post) installed, you can begin creating a custom part. Open VS and create a new ASP.NET Web Application project. If the option to use 'code-behind' is available, make sure that you do.

You can also select the language you'd like to use to program your application - I use C#, you can use whatever you like. I simply prefer the syntax of C# as it's more similar to 'classic' programming languages like C/C++ and less classic but more familiar scripting languages like Javascript (Javascript is awesome). VB.NET doesn't look right somehow. I like curly braces.

If you're not familiar with the VS environment, go and find some tutorials.

Assuming that you know your way around VS, you should see that a Default.aspx page and accompanying code-behind page (Default.aspx.cs) has been created. Delete those - you won't need them.

Add a reference to the BBNC API

First thing to do is add a reference to the BBNCExtensions DLL. This lives in the 'bin' folder of your Netcommunity installation. If you're developing on the web server where BBNC lives, then you can reference it directly. If not, copy the DLL from the 'bin' folder to your development environment and reference it from there. (to add a reference, right click on 'References' in the Solution Explorer on the right hand side of VS, and click 'Add new Reference')

Depending on the version of BBNC you're developing for, you might also need to alter the version of the .NET framework that your custom part uses. For example, Netcommunity 5.1 uses version 2.0 of the .NET framework. By default, recent versions of Visual Studio will reference a more recent version of the framework. This shouldn't present a problem if you're on a more recent version of BBNC, like 5.6, but if not - change the framework for your application by clicking on 'Project' and then '[nameofyourapp] Properties'. Simples.

(bear in mind that if you do change the .net version to 2.0, you'll need to delete some of the references to newer classes that VS automatically puts in to your application - click the 'References' tab on the right of the VS window and delete any that have a little warning sign next to them. you might also have to remove some of the 'using' statements from the top of your code-behind pages when you create them. if that doesn't make sense read this article from Microsoft )

Create some web user controls

Once all that's been done, click on 'Project' then 'Add new item'. Add a Web User Control and name it 'DisplayTest.ascx'. This user control will be added to your Solution Explorer on the right of the VS window. Double click 'DisplayTest.ascx' and the accompanying code-behind to open them up. If you're not familiar with what you see, there'll be another blog post explaining it all. For now, click on 'design' - it's underneath the main display window in VS when you're looking at DisplayTest.ascx. Type "Hello, this is DisplayTest" or whatever you'd like to say. This is what will (hopefully) appear to users looking at a page containing your custom part.

Don't worry about the code-behind, for now - the code-behind is where you can do all the clever stuff with C#. For now simply displaying some HTML should suffice. The design mode in VS is essentially a WYSIWYG editor - it'll convert whatever you type into HTML.

Next, create another Web User Control and name it 'EditorTest.ascx'. Follow the same steps as before, but this time enter different text such as "Hello, this is EditorTest".

Add some code to the EditorTest code-behind

Sadly, for the EditorTest section of our custom part, we will need to add some C# to the code-behind. To go over what we've done so far, the DisplayTest control is what the end user will see on a page. The EditorTest control is what a Content Editor or Admin using the BBNC Administration will see when they click 'Edit'. BBNC needs to know what to do when an Editor / Admin clicks 'Save' after editing any part, even a custom part, so you need to fill in some code to tell it what to do.

Firstly, open up the code-behind for EditorTest. You'll need to add another 'using' statement - add it underneath the others:

using BBNCExtensions;
using BBNCExtensions.Parts;

This allows you to use the classes defined in the BBNCExtensions DLL that you added a reference to earlier.

You next need to set the main class for your Control to inherit from the CustomPartEditorBase - that sounds horrendous, doesn't it? Look in the code-behind - there'll be a namespace declaration containing the name of your project (ie. namespace MyTestProject) and then underneath there will be a class containing the name of the Control you're working on - it should say something like this:

public partial class EditorTest : System.UI ETC ETC ETC

Change this so that it inherits from something else instead, namely this:

public partial class EditorTest : BBNCExtensions.Parts.CustomPartEditorBase

That colon means 'inherit from'. You need to add a similar bit of code to the code-behind for your Display part also, except that it will instead inherit from 'BBNCExtensions.Parts.CustomPartDisplaybase'. It will also need a 'using' statement. So go and do that.

Once you've done that, go back to the EditorTest code-behind file. You need to add a couple of new methods to override the default behaviour of the page when it loads. This is where the intellisense comes in handy -VS guesses what you're typing and tries to help. Underneath the Page_Load method, add another one that says this (intellisense might try to help you out with it):

public override void OnLoadContent() {

}

It doesn't need to contain anything right now, but for future reference this is the area where you can ask your application to interface with the BBNC database and grab data to present to whoever might be editing the custom part.

You also need to add this, to tell the program what to do when a user clicks 'Save':

public override bool OnSaveContent(bool bDialogIsClosing){

return true;

}

Again, we don't need our program to save anything or do anything at the moment, but this method requires a 'boolean' (yes or no) value to be returned anyway. We return true, and therefore the Editor window will close nicely. If you don't include this method, when a user tries to leave the Editor window they will encounter a server error.

Build your project

Now you need to build your project and check it for errors - click 'Build' and then 'Build [myprojectname]'. The compiler will let you know if there have been any errors that need to be rectified.

Deploy your project

If you're confident that everything is ok, you next need to deploy the files to the Netcommunity installation. If you're developing on the web server where your Netcommunity installation lives, you can publish directly to the relevant folders. If not (and I'll assume not), you'll need to FTP or RDC them to the right place. The two .ascx files (DisplayTest.ascx and EditorTest.ascx) need to be deployed into the 'custom' folder in your Netcommunity folder. Another file, which will be inside the 'bin' folder of your project and will be called '[myprojectname].dll', needs to be deployed into the 'bin' folder in your Netcommunity folder.

Let Netcommunity know

Once you've done that, you need to let Netcommunity know that you've deployed a new custom part. Login as an Administrator / Supervisor and click on 'Administration' then 'Custom Parts'. This is the Custom Parts gallery. Click on 'New custom part'.

You'll need to enter a name, and a description, and then you'll need to enter the path to where your custom part files are. The only files BBNC is interested in are the .ascx files - it can find the .dll on its own.

In the 'Display Control Source' box enter the relative path to the DisplayTest.ascx file - it might be something like:

~\custom\DisplayTest.ascx

In the 'Editor Control Source' box enter the relative path to the EditorTest.ascx file - it might be something like:

~\custom\EditorTest.ascx

Click on 'Save', and bang. Almost done. Now you need to create an instance of your part using Netcommunity and test that it works. Go to a test page you've created before, and click 'New part' somewhere in your layout where you'll be able to see it. On the list of available parts, you'll now see whatever you decided to call your Custom Part. Select it, and click next. The Editor text you typed in earlier should appear. Click Save, and then preview the page to see if it works.

It should do. So there's a very lengthy but hopefully relatively thorough introduction to how to create a simple custom part. If it looks horrendously complicated, I guess it kind of is, but you soon get into the swing of it.

Any experienced Netcommunity developers feel free to point out any mistakes I've made!

Netcommunity custom parts & helpful links

Customising Netcommunity is all based around 'custom parts' - these are custom web controls that you create, that then get integrated into the CMS. For example, you could create a custom part that just prints some text to a page - "Hello World" or whatever. Once you've created the custom part, you push it onto the web server where Netcommunity lives, and then tell Netcommunity where it is. After that, it can be used and reused like any other Netcommunity part - it becomes fully integrated.

It's up to you to decide the level of complexity of the custom part you've created. If you just want to include some HTML or Javascript into the page (something you can't always do with the formatted text part that comes with Netcommunity), it's very simple to do. However, if you want to make the custom part resemble an application, with settings that can be changed by your content editors / web editors, and with data that gets stored in the Netcommunity database, it's a bit more complicated.

I'll start with what I first tried - creating a custom part that, when included into a Netcommunity page, printed out a line of text. Sounds simple, eh. First, you'll need a few things if you haven't got them already:

Visual Studio
Full version of Visual Studio would be nice, if not, grab this one (it's free):
http://www.microsoft.com/express/vwd/

Access to the BBNC server
You'll need access to the server that your Netcommunity installation sits on. It'll probably live somewhere like C:\Program Files\Blackbaud\Netcommunity - in there is a folder called 'bin', and another folder named 'custom'. Those two folders are where you place the various files related to your custom part. If you don't have access to these folders (if you're hosted by Blackbaud for example), then you're not going to be able to deploy your custom parts.

Other useful links:

Blackbaud Labs - http://labs.blackbaud.com/NetCommunity/Page.aspx?pid=211

This is a fairly helpful resource, albeit brief when it comes to helping beginners. There's some downloadable samples of custom parts Blackbaud have made. The first example just prints some text to the page. The last one is far more complicated. All the code examples are in VB.NET.

Blackbus - http://www.blackbus.org/forum/netcommunity-bbnc

Forum for users of Blackbaud products, there's a Netcommunity section. Lots of knowledgeable people there, with plenty of questions answered that you might find helpful.

Next

I'll explain how to create and deploy a simple custom part.

Welcome

Hello, welcome - this blog will serve as a manual of sorts for me to keep track of how I'm getting on with using the Blackbaud Netcommunity API. It might be helpful for you if (like me) you're fairly new to ASP.NET and all the associated malarky.

Blackbaud Netcommunity (BBNC) is a content management system for websites, aimed at non-profit organisations - see http://www.blackbaud.com/ for an overview. Out of the box, it's quite inflexible in terms of what you can achieve, but luckily there's an API that is exposed to developers that allows them to customise the CMS quite heavily. Less luckily, it's not very well documented and fairly alien to anyone that isn't quite familiar with ASP.NET programming and that sort of stuff.

I haven't let that put me off though, so I've been learning C# and wading through the sparse examples provided by Blackbaud to try and figure out how they work. I've also reverse-engineered some other samples I've found. All of this means that I'm slowly starting to get it. Bonza.

Since starting to look at all this stuff, I've been able to do a number of things that would previously have been outsourced to web development company at great expense. With relatively little effort, I can now create custom web forms exactly how I would like them, that submit data to a database or fire off emails to receipients; I can customise previously inaccessible sections of the website such as the page head; and I can include custom HTML and Javascript easily and painlessly.

The most recent customisation I've made is a fully-functioning 'notice board', that allows users to post up notices and advertisements. It interfaces with a simple database, and uses Javascript to allow the user to customise how it looks. I also created a 'widget' for the homepage that grabs the last 10 items and lists them. All of this is fully integrated into the website as if it was a part of Netcommunity itself. However, there's a lot more for me to learn, especially when it comes to using the BBNC database and interfacing with Raiser's Edge, another Blackbaud application (a database).

Most of the examples you'll find floating around on the web related to BBNC customisation are written in Visual Basic.NET (VB.NET) - I really don't like the syntax of VB, so I've opted to use C# instead. Unfortunately, it appears that I'm pretty much on my own with that decision - however, it's not too difficult to convert VB to C#, especially if you use a number of nifty tools that are out there. One particular tool I've found very handy allows you to disassemble compiled .DLL assemblies - in other words, you can poke through existing customisations and convert them into the source language of your choice, VB or C#. I'll talk about that one in a subsequent post.

I'll just reiterate that I'm not a programmer, so I imagine I'll frequently use the wrong words, explain things entirely incorrectly, and quite possibly only ever come out with badly-optimised and stupid code. However, there's a small chance it might all be alright, and either way - I'm learning. Hopefully you might find some of it helpful.

Cheers.