{<img src="https://api.travis-ci.org/allynfolksjr/groupr.png?branch=master" />}[https://travis-ci.org/allynfolksjr/groupr]

= groupr

Groupr provides an interface to the University of Washington Groups Service, which allows administrators to leverage a simple yet robust groups system for access control for applications campus-wide.

Groupr strives to followly closely to the naming conventions and functions as outlined in the Groups Service documentation, but does expand certain functionality, notably adding the <tt>group_exist?</tt> method to verify that a group exists.

General group service documentation: https://wiki.cac.washington.edu/x/hgVS

Groups API Documentation: https://wiki.cac.washington.edu/x/ESBy

== Features

* Ability to check if a group exists via Groupr#group_exists?
* Get title, description, name, regid, and contact of a group via Groupr#view_group
* Create a group and optionally add a description via Groupr#create_group
* Delete a group via Groupr#delete_group
* List group members via Groupr#view_membership
* Option to manually specify a different API url; useful if new or testing versions of the Groups Service API become available.

== System Requirements

Groupr is designed to work with a very specific application API, and is likely not useful to users not affiliated with the University of Washington. It is designed to work with a system that has:

* A static UW-assigned DNS hostname, such as hiigara.cac.washington.edu [http://www.washington.edu/computing/network/addresses.html]
* An X509 certificate signed by the UW Certificate Authority (UW CA): [https://iam-tools.u.washington.edu/cs/]
* A copy of the UW CA root [https://www.washington.edu/itconnect/security/ca/uwca.crt]
* Permissions assigned to a stem that it is working in.

=== Note on Permissions

* This utilizes the hostname-based feature of the UW groups service. this hostname is the one assigned to you by the UW Network Operations center, and should be the same as the X509 certificate hostname as outlined above.
* When working on a group that is already created, you must assign this hsotname to one of the permissions available to you. For instance, if working on the 'u_nikky_awesome' group, you must allow 'hiigara.cac.washington.edu' as an administrator if you want to give this host full access to that group.
* When creating new groups, this host is automatically added as an administrator. You can remove this after creating the group, if desired.
* The host in question must have subgroup create or administration permissions in order to create new groups. For instance, if 'hiigara.cac.washington.edu' has subgroup permissions for the 'u_nikky' stem, it can create subgroups such as 'u_nikky_awesomeo'

== Instructions

Once the conditions as outlined in "system requirements" are met, this gem can be utilized. 

	<pre><code>testr = Groupr.new
	testr.key = "path to key file"
	testr.cert = "path to certificate file" 
	testr.group_exists?("u_nikky_awesome") 
	testr.create_group("u_nikky_yeast-lords")</code></pre>

By default, it will look for a UWCA root file in ~/uwca.crt. You can manually change this by running:

	<code>testr.ua_ca_file = "path to uwca root certificate"</code>

In addition to getting all of the information from the HTTP request via Groupr#request, you can also view the return status message via Groupr#status.

== Version History

=== 0.2.5

Add Groupr#get_effective_membership

=== 0.2.4

Code refactoring and refinements

=== 0.2.2

* Add Groupr#get_membership
* Add Groupr#delete_group

=== 0.2.1

Initial documentation release

=== 0.1.0

Initial public release; undocumented.

== Known Issues

* Current error handling is sparse
* Many features not implemented
* Many optional features of current functions not implemented

== To-do

* Continue to expand current available options
* Additional error handling checks
* 

== Copyright

Copyright (c) 2012 Nikky Southerland. See LICENSE.txt for
further details.