Hangin' with the Ministry Platform API Part 1

This is the second installment of the Ministry Platform API series. For a complete look, take a look at my other posts here:

MP API Part 2
MP API Part 3

So your church just got Ministry Platform. You're excited. You got tons of ideas on how it's gonna make your church better. Cool graphs, new apps, integrations, etc. Your mind is filled with candy-laden streets and marshmallow skyscrapers. I get it. I do. Honest. But first things first - you need to know how to get things in and out of that brand new treasure chest. Let's take a look at how to get things in and out of Ministry Platform using its API.

Setting Up Access

All communication with Ministry Platform's API is done through SOAP protocol. Not my favorite in this day and age, but it is what it is. I'm going to go over how to set up access using Visual Studio but if you're running on a different stack, most languages and platforms already have libraries that can connect via SOAP, so just do a quick Google search on how to connect to it.

Let's get started. First, open Visual Studio and create a new web application. Next, right click on the project application and select the "Add Service Reference..." option.

The url for the API will be (usually) in the following format: https://(your MP url here)/ministryplatform/public/api.asmx If you're unsure about where your Ministry Platform installation was installed, get in touch with the boys at Think Ministry, they'll tell you what it is. Plug in the url, hit go, give it a meaningful namespace, and then hit okay. BAM! You're ready to go. Well Almost.

Get your Creds

Every request made to the API requires the domain GUID (it's sort of like a username) and the API password. These both should've been given to you when Think Ministry installed the software, but if you've forgotten them for some reason, they're in the Ministry Platform database under the domains table.

Creating a New Record

Creating a record is relatively simple. Say you want to add a new contact, you could do the following.

apiSoapClient mp = new apiSoapClient();
string RequestString = "Company=0&First_Name=" + APIEncode(FirstName) +
                "&Last_Name=" + APIEncode(LastName) +
                "&Nickname=" + APIEncode(FirstName) +
                "&Display_Name=" + APIEncode(LastName) + ", " + APIEncode(FirstName) +
                "&Mobile_Phone=" + Phone +
                "&Email_Address=" + Email;
string response = mp.AddRecord(apiGUID, apiPassword, UserID, "Contacts", "Contact_ID", RequestString);

Okay - the apiGuid and apiPassword parameters I explained before. The UserID here is just whomever is "adding" the record. Used to keep track of who's doing what. You can pass a zero here if it's an anonymous or system thing. The fourth paramater is the table name (or object, however you want to look at it) you're adding a record to, and the fifth one is the primary key of that table. The request string always follows the 'name=value&name2=value2' pattern, virtually identical to query strings in urls. You don't need to supply a primary key value here, as it's automatically generated for you in the DB. The APIEncode method is just a method that encodes things like ampersands and other characters that the API uses to interpret the request. You can make one like this:

public string APIEncode(string toEncode)
{
    if (string.IsNullOrEmpty(toEncode))
        return "";

    return toEncode.Replace("#", "dp_Pound")
                       .Replace("&", "dp_Amp")
                       .Replace("=", "dp_Equal")
                       .Replace("?", "dp_Qmark")
                       .Trim();     
}

Alot of the API methods return a pipe-delimited string to inform the developer what happened. You can parse it as follows:

string[] result = response.Split('|');
if (int.Parse(sptResult[0]) == 0) //this will be zero if an error occured, otherwise it will return the affected record id
{
    throw new Exception(sptResult[2]); //the third item in the array will give you the reason why something went wrong
}

Quick Aside

You may be wondering what's the big deal here with this ChMS. The real gem here is the fact that you can create your own tables that's accessible via the API. Let that sink in for a hot second. Remember that one thing everyone wanted you to build? Now you don't have to spend time building an admin interface - that's what MP does for you automatically. But you probably already know that because you're that awesome. Check out the Knowledge Base for more info on how to create new tables/objects in MP.

Updating an Existing Item

apiSoapClient mp = new apiSoapClient();
mp.UpdateRecord(apiGUID, apiPassword, UserID, "Contacts", "Contacts_ID", RequestString);

This is basically the same as creating a record, only here you have to make sure you include the correct primary key column name in the request string, or the API will throw an error.

Retrieving Data

Believe it or not, the only way to get data out of Ministry Platform through the offical API is to write a stored procedure and use the ExecuteStoredProcedure method. When you create a new stored procedure in the database, it must have the "api_" prefix or it won't work.

apiSoapClient mp = new apiSoapClient();
mp.ExecuteStoredProcedure(apiGUID, apiPassword, "api_Common_GetUserID", RequestString);

ExecuteStoredProcedure is it for getting things out of MP. You could use the "GetGridData" method, but it's been deprecated, so good luck with that. This is definitely my biggest gripe with the API. Reading one or two things out of the database works fine for small applications, but scaling it out across multiple applications, and large ones at that, becomes a nightmare managing all the stored procedures. Plus, it puts another barrier up for developers. Some churches may be wary of letting 3rd party developers have any access to their database server. There definitely is a need to retrieve the basic stuff out of Ministry Platform without having to write a stored procedure every time. That's why things like ORMs were invented to alleviate these issues. But we'll get to some of that in another post.

Authetication etc.

There are a few other methods worthy of mentioning...

        int UserID;
        int ContactID = 0;
        int DomainID = 0;
        string DomainGUID = "";
        string UserGUID = "";
        string DisplayName = "";
        string Contactemail = "";
        string ExternalUrl = "";
        bool CanImpersonate = false;

        mp.AuthenticateUser(UserName, Password, ServerName, out UserID, out ContactID, out DomainID, out DomainGUID,
            out UserGUID, out DisplayName, out Contactemail, out ExternalUrl, out CanImpersonate);

The API is a big fan of pass by reference apparently. Anyways, to test whether authentication was successful or not, do the following:

if (UserID > 0)
{
    //do stuff in here
}

The API returns a value for the UserID variable if authentication was successful. There are other useful account methods, like UpdateUserPassword or ResetUserPassword. Pretty self explanatory.

Delete it or not?

You may be wondering why there isn't a way to delete records. It's one of the "pillars" of Ministry Platform - don't delete anything. It's actually a good practice for a ChMS. You'll always have a record of something, even if it happened in the past. I think accountants or the like really like that part (I have no idea). Deleting should only be done in special circumstances. So, how can you work around this? Well, use the "UpdateRecord" method and set the record's "EndDate" field (most tables have them). This is the proper way to "delete" something in MP. If you want to be especially tricky, you can use a (sigh) stored procedure and just delete it. Use caution when doing this of course.

Wrap Up

Well I hope you enjoyed this first part in a series of posts dedicated to looking at how to develop with Ministry Platform. This was just the low-level nitty gritty first run at things. Next post we'll look at how to speed and simplify things with a wrapper class. System.Reflection here we come baby!

Tagged with ASP.NET Ministry Platform