Fellowship One RESTful API is a REST based web application that uses several open protocols and patterns to provide consumers access to secure resources. STANDARDS, PROTOCOLS, and PATTERNS - nothing else. As developers we see where there is major value in sticking with something that is "tried and true." If we could use web based patterns and protocols for a web based API we could not only get instant adoption but gain the efficiencies and effectiveness of technologies that "just work."   

Enjoy all of the features and benefits of being part of the Fellowship One developer community.
• Engage others in the developer community
• Get access to loads of code to use and learn from
• Create / Share applications that consume the Fellowship One REST API

Since we are community focused, we wanted you to have as much code and information that you'd need to get jump started for the REST API so that you'll be able to discuss / communicate your ideas on consuming the REST API throughout the social-sphere. Please take a moment to check out the current code libraries and blogs.

User Case Story from Hope Community Church

Posted By: Tracy Mazelin on October 28, 2013

Today we are featuring a user case story submitted by Todd Darling of Hope Community Church in Raleigh, NC.  Todd has developed a creative solution which utilizes our API to enhance their student check in experience.  Check out the video and post outlining exactly how they are doing this.  Many thanks to Todd and the technology team at Hope Community Church for the work they put into sharing this with our developer community.  Enjoy!

Guest Author: Todd Darling, Web Developer
Hope Community Church in Raleigh, NC



THE SETUP:
For our middle and high school student ministries on the weekend, the students check themselves in, most of the time without a parent. During our midweek middle school service—which often has 300+ middle schoolers—a lot of students bring friends whose families don’t even go to Hope (which is AWESOME!)

How do we let students check themselves in (so we can track attendance in F1), get accurate parent contact info (for safety and communication purposes) for new students and let them update their information as their grade or school changes?

In our previous homegrown database, the custom check-in software allowed students to check themselves in and update their complete information.

THE PROBLEM:
For new students, the only data you could enter/update through the F1 check-in software is a name and date of birth.

We need students’ parent/guardian contact info and their school info so we can do school visits and connect students based on their schools. It also had to be quick, as on our Wednesday night services we often have 300+ middle schoolers checking in in the space of about 30 minutes.

THE SOLUTION:
Through a custom website we built along with a local database, some free software utilities, and the F1 API, we created a great user experience and still got the data we need. Here’s how we did it:

For speed, we wanted to run a local database that stored all the students. This would avoid any latency from going out and making an API call to query F1.

This step is completely optional and was only done for speed of looking up the students. We could have used the F1 API to do people searches and eliminated the local database. For our midweek services that have so many middle schoolers registering in a short amount of time, the faster speed was worth the extra work and ongoing maintenance involved in this step.

We created a report in F1 that grabbed all of our students’ first names, last names, date of births, Fellowship One IDs and barcodes. We imported the information into Excel and a mySQL database on a local server.

This database is also flushed and repopulated every week before our Wednesday services. We run a new report after our staff has done any changes (merging students, adding new students in, etc.) and use that to update the database.

So, how do we check people in from a website without them seeing/using the F1 check-in software?

Well, technically, they’re still USING the F1 check-in software, they’re just not SEEING it. This was the most difficult part of the solution and took us months to get working.

In researching solutions for fingerprint scanners, we found that with the F1 software running in self check-in mode using a free command line utility called WinSendKeys, you could pass a string that contained a barcode number to it. The check-in software would accept that as if you had actually scanned that number yourself and check in the barcode as normal.

The command? Just a single line entered into the Windows command line:

“WinSendKeys -d scanningform 1234567”

This would pass the barcode “1234567” to the check-in software to check that barcode in. What is “scanningform”?  That’s the name of the F1 check-in software (this is shown in the Windows taskbar). So we’re telling WinSendKeys to send the barcode “1234567” to the F1 check-in software

The example we found was a Windows application. We didn’t have any Windows developers who could build a check-in application for us. But we have web developers here who can write PHP.

HMMMMM….

So how would we do this through PHP?  Using the PHP SSH2 extension, you can SSH into the computer you’re running on (assuming you have permission to do so) and fire off command line commands to your heart’s content.

We developed a website running on our local server utilizing a LAMP stack that would ask students for their first name, last name and date of birth. Any server that had PHP with the SSH2 extension running would be fine.

We ran this website in full-screen kiosk mode so the F1 check-in software was hidden. We also found an extension for Firefox that would “pin” the window so you couldn’t switch out of Firefox and do something else on the computer. This was totally optional, but we know that middle schoolers are notorious for doing something like that!

Once students entered their information, it would look them up in the local database with a simple AJAX/PHP call (no F1 API yet at this point). If a single match was found, we would grab their barcode from the database.

Then, using the PHP SSH2 extension, it’s just a few lines of code. Before this will work, however, you need to make sure you actually have permission to SSH into the machine. We used the free SSHd software which, once installed, we just needed to set up a username and password to let us do it:

$clientIP = $_SERVER['REMOTE_ADDR'];

This line simply grabs the IP of whatever machine you’re running on:

$connection = ssh2_connect($clientIP, 22);

Makes the SSH connection over port 22:

ssh2_auth_password($connection,'f1checkin','f1checkin');

Authenticates using the username/password we set up using the freeSSHd software

$stream = ssh2_exec($connection, 'winsendkeys -d scanningform ' . $barcode);

This code issues the “winsendkeys” command, grabbing the person’s barcode from the F1 record and checking them into whatever activity code you had set up. 

What happened if the student wasn’t found?
If the student isn’t found in the local database, we THEN make an F1 API call to look them up. If they’re found in F1, it grabs the barcode from their record and passes it back to the website.

If they’re not found in F1, we assume they are new students. The website presents the student with a screen to enter their full information, including name, email, cell phone, school, school grade, address and parent/guardian contact info. As a result, we can get complete information about the student instead of what’s allowed through the check-in software.

That person is written into F1 through the API, and we automatically assign their F1 individual ID as their barcode, which is then passed back.

What happens if there were multiple matches for the student?
Let’s face it—duplicates happen in Fellowship One no matter how hard we try to keep them out.  With a duplicate entry, since our website wouldn’t know which student to check-in, we present a screen telling the student to move out of the check-in line to a different station manned by a staff member with Portal open and the F1 check-in software in assisted mode. That way, the student can make any changes (merging the duplicates, etc.) to fix the record and then check them in.

3rd-party software used for this solution:

  • FreeSSHd. This is free software that we used to set up SSH so you can log into the computer. You can use whatever method you would use to give someone access to SSH into the computer with a username and password. It’s this username and password that you pass in the PHP code above.
  • WinSendKeys. Install this free download on your machine and set it to run when the computer starts, since it also needs to always run in the background. This software is written by one person and uses the AutoIt scripting language.  This is what lets you send the command containing the barcode to the check-in software.

Posted In: API, News, Tips,
Comments: 0 Comments