Loading Profile...
API Documentation
I realize things are super busy after launch, but I have to ask!: what are your plans for releasing documentation on your REST API? We're planning on building a members section of our site that would either update or read from Stafftool and we're eager to get started! :)
I’m excited
1
person has this question
I have this question, too!
Tell me when someone answers.
The more people who ask this question, the more it gets noticed.
The more people who ask this question, the more it gets noticed.
The best answers from the company
-
Cool, thanks grapeice925, I'd definitely love for you to help with testing the API and fleshing out ideas. I'm sure we'll get what you're looking for figured out...you're right, you are kind of looking for Stafftool to act as a sort of LDAP which was not what was really intended, but I'm sure we'll be able to reach something that works. I'll continue on the documentation over the next couple weeks and be sure to let you know as soon as the first pass is ready for you to dig in to!
The company says
this answers the question
-
Hey grapeice925, here we go. Sorry it took so long to get back on this, but I had a lot to think about and write up. I basically copied your entire message and have my thoughts in the appropriate places, so I apologize in advance for the absurd length :)
> Basically, what I want to do is setup a login area on our website for church
> members in Stafftool so that they can quickly update their contact information
> and see any pertinent information about the ministries they are involved in.
> We could just grant login to Stafftool, but we want to integrate the
> experience with our website so that we give them the right information where
> it's most appropriate.
> Some of the actions they can do:
> 0. Login to the members site - hmm, use logins assigned in Stafftool or just
> keep our own? Is there a way to test authentication using the API?
> 1. Add or update any contact or personal information about themselves,
> including photos.
So I've been thinking a lot about the very situation you lay out in 0 and 1, and I think the way I'm going to look at proceeding is to work on implementing oAuth support - http://oauth.net - it's built pretty much exactly for this. If you're not familiar with oAuth, it's a framework created by the people behind sites like Twitter, Flickr, etc., for allowing people to access their information from one site on another without giving the middle site their credentials. The classic example is something like allowing picnik.com access to your flickr.com photos for editing without giving picnik your yahoo id that you use to log into flickr. So, similarly, your site would implement the oAuth consumer functionality using their PHP library (http://oauth.googlecode.com/svn/code/...), and it would allow people to authenticate themselves on your site using their Stafftool account so they can view and edit their Stafftool account and information there. Let me know what you think about this approach...you could probably do all that you need using the standard REST API, but from what I gather, oAuth was made for this situation.
A question I have, though, is this - if you create an account for them on Stafftool, they'll receive an email with that login information, and they'd be able to log into Stafftool directly. With oAuth implemented, they'd also be able to log into your site with the same login info. But, I'm not sure that's what you really want, since it sounds like you want them to only interact with your public site... so I suppose an alternative approach would be to retain your public site's own login system and do something like assigning their Stafftool record id to their record in your system. That way, when they authenticate on your system you could have your app access their assigned Stafftool record via the API and update it that way. Does that make sense? Would that be preferable? Or do you want them to have a Stafftool login but usually interact with it through your public site?
> 2. View all ministries they are a part of and read about all of the
> ministries that are available - signing themselves up for one if they are so
> inclined.
Once we can get the user identified, viewing all the ministries they're a part of (that you've placed them within in Stafftool) is certainly doable via the API. As for them signing themselves up for ministries, that is something I'll need some more feedback on. I can imagine letting them add themselves to public ministries that they're interested in keeping track of, but I'd think that it would be best for your staff to add them to more private ministries themselves. I think that if their user within Stafftool only has normal permissions, they'd only see the public ministries and they'd follow ones that they're not already a part of, but private ones such as a worship team group would only be addable by staff or the group leader.
> 3. Change their contact preferences: this is not only for ministries and
> getting emails from them through Stafftool, but also for situations like when
> services are cancelled - do they want to be emailed, or have a text message
> sent to their cell? That data will probably be stored in a DB on our side,
> unless Stafftool can handle the storage of this data somehow.
At this time, Stafftool doesn't store any sort of information specifically about their contact preferences. I do plan on working in automatic notifications directly from Stafftool for upcoming events, which would necessitate these types of per-user preference, but until then it would be best stored on your own DB.
> 4. Manage their family connections - this one still needs to be thought out
> a little, and will probably come at a later phase.
This one is interesting...this also seems like something that would be best handled by staff, as it's somewhat sensitive information that will be reflected on other peoples' profiles. For instance, a high school kid putting that he's the parent of some other student, or something like that...what do you think?
> On top of this, we want to keep the entire calendar of events of all of our
> ministries, etc. through Stafftool. So we'd like all public-marked events to
> show up on the church's site, and specifically, if you are logged in as a
> member, have the ministries you are involved in show up on the calendar by
> default.
Like I said in the previous message, this one will probably be the first to be usable. I've already got some of this in place, just a bit more development time to finish some aspects up. For this, since it will be such a common use, I'm working on embeddable widgets that you can just drop into your HTML. You'll also be able to grab the raw xml and do whatever you need with it if you want too. And, the widget-style one will be exactly what you said - all public marked events. You can actually use a very basic public calendar JS widget right now with the following code:
<script src="http://yoursubdomain.stafftool.com/pub/events.widget"></script>
Just drop that on an HTML page and load it and you'll get a barebones html calendar of the current month's public events.
There's also a basic HTML version at http://yoursubdomain.stafftool.com/pu... that would be suitable for an iframe if you wanted to go that route as well, although it's not completely fleshed out at this point.
And you'll be able to grab XML using the API as well.
> Then the plan is to allow all church ministry leaders access to Stafftool
> directly so that they can manage their groups, send messages, etc.
Yeah, that will work well. That's actually the way it works optimally - all the staff and leaders can be "admins" with specified permissions, and everyone else in the church could have normal login accounts. The leader would log in and have access to everything you assign their permissions to and everyone else would only see things that pertain to them.
> We have later plans to add all sorts of tools to allow ministries to grow
> and be more efficient in their communications - such as a way for ministries
> to have their own sections of content, news, etc. For example, if you belong
> to the Choir ministry, it might be possible to digitally distribute the tracks
> that will be used for next month's song on this page/section, and get updated
> about the new files as a message in Stafftool.
Yes, this is actually something I have planned as one of the next big updates. I'm going to make each group have its own page that will aggregate all that group's related records - people, messages, events, files, etc.
> And we'd like to start integrating other pieces of information with member
> information, like possible online giving or just general giving information
> for the year, where members at the end of the year can print out an
> auto-generated report of their giving for the year for tax purposes.
I'd love to do this and am thinking about how to best integrate this into Stafftool. It would be perfect for the church to record all the giving in Stafftool, and have the congregants be able to check their up-to-the-date giving record, as well as for the end of the year like you said. It's definitely on the roadmap, I'm mostly thinking through security concerns.
> Lastly, I think it might be cool to use the API to generate a high-quality
> PDF document that mimics a printed directory that church members can have.
> With a PDF in hand, we can go elsewhere (perhaps Lulu?) to have the books
> printed.
Yeah, this would definitely be great... At this time you can currently export your entire people database (or slices of it) at any time to vCard, XML and CSV formats...I just looked at the Apple Address Book app, which imports vCard files seamlessly, and it has numerous printing options, such as envelopes, lists, mailing labels, etc. I'm sure Outlook or something else has similar options. You could also use the API to dynamically create a PDF with your own methods as well. I'd love to have PDF exporting directly from Stafftool at some point, but I most likely won't be able to complete that in the very near future. One thing I could probably implement sooner, though, is print-specific stylesheets that would format the people pages better for paper. I'd have to have it open in a new window or something like that to get around the pagination, but it would probably work pretty well. It's on my list :)
> And the list goes on, but at the least the basic pieces are in items 0-4.
> Thanks for your help on this!
Ok, cool. So, I'm going to be continuing work on documenting the API... I'd say at this point give me a couple weeks to get the docs fleshed out. I'm also going to be working on the public events functionality some more as well to clean those up. Like I said, you can use the basic public versions right now, but they're a bit rough at this point.
Thanks again for all the ideas of what you'd like to accomplish with the API... it's naturally immature at this point since we're just barely getting started, but I'm very much dedicated to making this type of stuff work well for needs such as yours, and feedback like this is really going to shape what it becomes.
The company says
this answers the question
-
Hey, let me look all this over and write up a more detailed response. Off the top of my head, I think as far as the membership stuff goes, granting them access to Stafftool itself would be the much easier route to take, as it already has all the permissions and updating functionality built in. However, let me look over the API and see what would be the best way to approach this from a remote perspective.
As for the calendar functionality, that will be easier to get going and there's already some work complete for the public events inclusion in the works. So that should be doable soon.
And, for the rest of the stuff, I'll think about them all and let you know what will be possible now, in the near future and a bit further out. Thanks for the info and great ideas!
The company says
this answers the question
-
Hey grapeice925, that's awesome you're going to be using the API so soon! You're right, things are crazy right after launch, and unfortunately the API is not yet completely documented...however, why don't you let me know what you'd like to do to get started and I can work on getting that part up and running for you so you can start implementing it as soon as possible. Go ahead and post your specific plans here, or go ahead and email me at toby AT stafftool DOT com with what you're going to work on exactly and we'll get it worked out. Also, if you're using Ruby on Rails on your site, working with the API will be a breeze with ActiveResource!
I’m looking forward to people using the API
The company and 1 other person say
this answers the question
-
Inappropriate?Hey grapeice925, that's awesome you're going to be using the API so soon! You're right, things are crazy right after launch, and unfortunately the API is not yet completely documented...however, why don't you let me know what you'd like to do to get started and I can work on getting that part up and running for you so you can start implementing it as soon as possible. Go ahead and post your specific plans here, or go ahead and email me at toby AT stafftool DOT com with what you're going to work on exactly and we'll get it worked out. Also, if you're using Ruby on Rails on your site, working with the API will be a breeze with ActiveResource!
I’m looking forward to people using the API
The company and 1 other person say
this answers the question
-
Inappropriate?Hey Toby, I actually don't use Ruby on Rails (I wish I had time to learn it!) so I'll be using PHP instead, but I'm hoping it's just as easy to use!
Basically, what I want to do is setup a login area on our website for church members in Stafftool so that they can quickly update their contact information and see any pertinent information about the ministries they are involved in. We could just grant login to Stafftool, but we want to integrate the experience with our website so that we give them the right information where it's most appropriate.
Some of the actions they can do:
0. Login to the members site - hmm, use logins assigned in Stafftool or just keep our own? Is there a way to test authentication using the API?
1. Add or update any contact or personal information about themselves, including photos.
2. View all ministries they are a part of and read about all of the ministries that are available - signing themselves up for one if they are so inclined.
3. Change their contact preferences: this is not only for ministries and getting emails from them through Stafftool, but also for situations like when services are cancelled - do they want to be emailed, or have a text message sent to their cell? That data will probably be stored in a DB on our side, unless Stafftool can handle the storage of this data somehow.
4. Manage their family connections - this one still needs to be thought out a little, and will probably come at a later phase.
On top of this, we want to keep the entire calendar of events of all of our ministries, etc. through Stafftool. So we'd like all public-marked events to show up on the church's site, and specifically, if you are logged in as a member, have the ministries you are involved in show up on the calendar by default.
Then the plan is to allow all church ministry leaders access to Stafftool directly so that they can manage their groups, send messages, etc.
We have later plans to add all sorts of tools to allow ministries to grow and be more efficient in their communications - such as a way for ministries to have their own sections of content, news, etc. For example, if you belong to the Choir ministry, it might be possible to digitally distribute the tracks that will be used for next month's song on this page/section, and get updated about the new files as a message in Stafftool.
And we'd like to start integrating other pieces of information with member information, like possible online giving or just general giving information for the year, where members at the end of the year can print out an auto-generated report of their giving for the year for tax purposes.
Lastly, I think it might be cool to use the API to generate a high-quality PDF document that mimics a printed directory that church members can have. With a PDF in hand, we can go elsewhere (perhaps Lulu?) to have the books printed.
And the list goes on, but at the least the basic pieces are in items 0-4. Thanks for your help on this!
I’m looking forward to using the API!
-
Inappropriate?Hey, let me look all this over and write up a more detailed response. Off the top of my head, I think as far as the membership stuff goes, granting them access to Stafftool itself would be the much easier route to take, as it already has all the permissions and updating functionality built in. However, let me look over the API and see what would be the best way to approach this from a remote perspective.
As for the calendar functionality, that will be easier to get going and there's already some work complete for the public events inclusion in the works. So that should be doable soon.
And, for the rest of the stuff, I'll think about them all and let you know what will be possible now, in the near future and a bit further out. Thanks for the info and great ideas!
The company says
this answers the question
-
Inappropriate?Hey grapeice925, here we go. Sorry it took so long to get back on this, but I had a lot to think about and write up. I basically copied your entire message and have my thoughts in the appropriate places, so I apologize in advance for the absurd length :)
> Basically, what I want to do is setup a login area on our website for church
> members in Stafftool so that they can quickly update their contact information
> and see any pertinent information about the ministries they are involved in.
> We could just grant login to Stafftool, but we want to integrate the
> experience with our website so that we give them the right information where
> it's most appropriate.
> Some of the actions they can do:
> 0. Login to the members site - hmm, use logins assigned in Stafftool or just
> keep our own? Is there a way to test authentication using the API?
> 1. Add or update any contact or personal information about themselves,
> including photos.
So I've been thinking a lot about the very situation you lay out in 0 and 1, and I think the way I'm going to look at proceeding is to work on implementing oAuth support - http://oauth.net - it's built pretty much exactly for this. If you're not familiar with oAuth, it's a framework created by the people behind sites like Twitter, Flickr, etc., for allowing people to access their information from one site on another without giving the middle site their credentials. The classic example is something like allowing picnik.com access to your flickr.com photos for editing without giving picnik your yahoo id that you use to log into flickr. So, similarly, your site would implement the oAuth consumer functionality using their PHP library (http://oauth.googlecode.com/svn/code/...), and it would allow people to authenticate themselves on your site using their Stafftool account so they can view and edit their Stafftool account and information there. Let me know what you think about this approach...you could probably do all that you need using the standard REST API, but from what I gather, oAuth was made for this situation.
A question I have, though, is this - if you create an account for them on Stafftool, they'll receive an email with that login information, and they'd be able to log into Stafftool directly. With oAuth implemented, they'd also be able to log into your site with the same login info. But, I'm not sure that's what you really want, since it sounds like you want them to only interact with your public site... so I suppose an alternative approach would be to retain your public site's own login system and do something like assigning their Stafftool record id to their record in your system. That way, when they authenticate on your system you could have your app access their assigned Stafftool record via the API and update it that way. Does that make sense? Would that be preferable? Or do you want them to have a Stafftool login but usually interact with it through your public site?
> 2. View all ministries they are a part of and read about all of the
> ministries that are available - signing themselves up for one if they are so
> inclined.
Once we can get the user identified, viewing all the ministries they're a part of (that you've placed them within in Stafftool) is certainly doable via the API. As for them signing themselves up for ministries, that is something I'll need some more feedback on. I can imagine letting them add themselves to public ministries that they're interested in keeping track of, but I'd think that it would be best for your staff to add them to more private ministries themselves. I think that if their user within Stafftool only has normal permissions, they'd only see the public ministries and they'd follow ones that they're not already a part of, but private ones such as a worship team group would only be addable by staff or the group leader.
> 3. Change their contact preferences: this is not only for ministries and
> getting emails from them through Stafftool, but also for situations like when
> services are cancelled - do they want to be emailed, or have a text message
> sent to their cell? That data will probably be stored in a DB on our side,
> unless Stafftool can handle the storage of this data somehow.
At this time, Stafftool doesn't store any sort of information specifically about their contact preferences. I do plan on working in automatic notifications directly from Stafftool for upcoming events, which would necessitate these types of per-user preference, but until then it would be best stored on your own DB.
> 4. Manage their family connections - this one still needs to be thought out
> a little, and will probably come at a later phase.
This one is interesting...this also seems like something that would be best handled by staff, as it's somewhat sensitive information that will be reflected on other peoples' profiles. For instance, a high school kid putting that he's the parent of some other student, or something like that...what do you think?
> On top of this, we want to keep the entire calendar of events of all of our
> ministries, etc. through Stafftool. So we'd like all public-marked events to
> show up on the church's site, and specifically, if you are logged in as a
> member, have the ministries you are involved in show up on the calendar by
> default.
Like I said in the previous message, this one will probably be the first to be usable. I've already got some of this in place, just a bit more development time to finish some aspects up. For this, since it will be such a common use, I'm working on embeddable widgets that you can just drop into your HTML. You'll also be able to grab the raw xml and do whatever you need with it if you want too. And, the widget-style one will be exactly what you said - all public marked events. You can actually use a very basic public calendar JS widget right now with the following code:
<script src="http://yoursubdomain.stafftool.com/pub/events.widget"></script>
Just drop that on an HTML page and load it and you'll get a barebones html calendar of the current month's public events.
There's also a basic HTML version at http://yoursubdomain.stafftool.com/pu... that would be suitable for an iframe if you wanted to go that route as well, although it's not completely fleshed out at this point.
And you'll be able to grab XML using the API as well.
> Then the plan is to allow all church ministry leaders access to Stafftool
> directly so that they can manage their groups, send messages, etc.
Yeah, that will work well. That's actually the way it works optimally - all the staff and leaders can be "admins" with specified permissions, and everyone else in the church could have normal login accounts. The leader would log in and have access to everything you assign their permissions to and everyone else would only see things that pertain to them.
> We have later plans to add all sorts of tools to allow ministries to grow
> and be more efficient in their communications - such as a way for ministries
> to have their own sections of content, news, etc. For example, if you belong
> to the Choir ministry, it might be possible to digitally distribute the tracks
> that will be used for next month's song on this page/section, and get updated
> about the new files as a message in Stafftool.
Yes, this is actually something I have planned as one of the next big updates. I'm going to make each group have its own page that will aggregate all that group's related records - people, messages, events, files, etc.
> And we'd like to start integrating other pieces of information with member
> information, like possible online giving or just general giving information
> for the year, where members at the end of the year can print out an
> auto-generated report of their giving for the year for tax purposes.
I'd love to do this and am thinking about how to best integrate this into Stafftool. It would be perfect for the church to record all the giving in Stafftool, and have the congregants be able to check their up-to-the-date giving record, as well as for the end of the year like you said. It's definitely on the roadmap, I'm mostly thinking through security concerns.
> Lastly, I think it might be cool to use the API to generate a high-quality
> PDF document that mimics a printed directory that church members can have.
> With a PDF in hand, we can go elsewhere (perhaps Lulu?) to have the books
> printed.
Yeah, this would definitely be great... At this time you can currently export your entire people database (or slices of it) at any time to vCard, XML and CSV formats...I just looked at the Apple Address Book app, which imports vCard files seamlessly, and it has numerous printing options, such as envelopes, lists, mailing labels, etc. I'm sure Outlook or something else has similar options. You could also use the API to dynamically create a PDF with your own methods as well. I'd love to have PDF exporting directly from Stafftool at some point, but I most likely won't be able to complete that in the very near future. One thing I could probably implement sooner, though, is print-specific stylesheets that would format the people pages better for paper. I'd have to have it open in a new window or something like that to get around the pagination, but it would probably work pretty well. It's on my list :)
> And the list goes on, but at the least the basic pieces are in items 0-4.
> Thanks for your help on this!
Ok, cool. So, I'm going to be continuing work on documenting the API... I'd say at this point give me a couple weeks to get the docs fleshed out. I'm also going to be working on the public events functionality some more as well to clean those up. Like I said, you can use the basic public versions right now, but they're a bit rough at this point.
Thanks again for all the ideas of what you'd like to accomplish with the API... it's naturally immature at this point since we're just barely getting started, but I'm very much dedicated to making this type of stuff work well for needs such as yours, and feedback like this is really going to shape what it becomes.
The company says
this answers the question
-
Inappropriate?Toby, your response times are fantastic - thanks for the detailed response. I guess all of my thoughts about how to use the API sound like I am treating Stafftool like an LDAP of sorts, and I guess this may not have been intended. I viewed it as a really beautiful admin interface for staff and ministry leaders to log in and manage their information, where members wouldn't have login access but get the info they needed through the church site and its API calls to Stafftool. I don't want to force you down a path you didn't intend either, but the stuff you've mentioned so far sounds really amazing. If there's any way I can help with testing, fleshing out ideas farther, etc., let me know. Looking forward to seeing what can be accomplished!
I’m excited!
-
Inappropriate?Cool, thanks grapeice925, I'd definitely love for you to help with testing the API and fleshing out ideas. I'm sure we'll get what you're looking for figured out...you're right, you are kind of looking for Stafftool to act as a sort of LDAP which was not what was really intended, but I'm sure we'll be able to reach something that works. I'll continue on the documentation over the next couple weeks and be sure to let you know as soon as the first pass is ready for you to dig in to!
The company says
this answers the question
-
EMPLOYEE
