README

UWDOEM/Person

Smoothly poll the University of Washington's Person Web Service (PWS) and Student Web Service (SWS) to aggregate data on a given affiliate, using X.509 certificate authentication.

For example:

    // Intialize the required settings
    define('UW_WS_BASE_PATH', '/path/to/my/private.key');
    define('UW_WS_SSL_KEY_PATH', '/path/to/my/private.key');
    define('UW_WS_SSL_CERT_PATH', '/path/to/my/public_cert.pem');
    define('UW_WS_SSL_KEY_PASSWD', 'myprivatekeypassword');  // Can be blank for no password: ''
    define('UW_WS_VERBOSE', false);  // (Optional) Whether to include verbose cURL messages in error messages.
    
    /* Query the web services */
    $student = Student::fromStudentNumber("1033334");
    
    echo $student->getAttr("RegisteredFirstMiddleName");
    // "JAMES AVERAGE"
    
    echo $student->getAttr("UWNetID");
    // "javerage"
    
    /* Retrieve registration for James Average*/
    $registrations = $student->registrationSearch("2009", "summer");
    echo $registrations[0]["CurriculumAbbreviation"];  // "TRAIN"
    echo $registrations[0]["CourseNumber"];  // "100"
    
    /* Retrieve employee information from the web services */
    $employee = Employee::fromUWNetID("jschilz");
    
    echo $employee->getAttr("Department1");
    // "Student Financial Aid Office"
    
    echo $employee->getAttr("Title1");
    // "Web Developer"

Notice

This is not an official library, endorsed or supported by any party who manages or owns information accessed via PWS or SWS. This library is not endorsed or supported by the University of Washington Department of Enrollment Management.

Installation

This library is published on packagist. To install using Composer, add the "uwdoem/person": "1.*" line to your "require" dependencies:

{
    "require": {
        "uwdoem/person": "1.*"
    }
}

Of course it is possible to use Person without Composer by downloading it directly, but use of Composer to manage packages is highly recommended. See Composer for more information.

Use

This client library provides four data-container classes: Person, Student, Employee, and Alumni.

If you have not already done so, follow PWS's instructions on getting access to PWS. A similar set of steps will allow you to gain access to SWS. You'll need to place both the private private key you created and also the university-signed certificate on your web server, with read-accessibility for your web-server process.

Before querying the web services, you must first initialize the connection by calling ::createInstance:

    // Intialize the required settings
    define('UW_WS_BASE_PATH', '/path/to/my/private.key');
    define('UW_WS_SSL_KEY_PATH', '/path/to/my/private.key');
    define('UW_WS_SSL_CERT_PATH', '/path/to/my/public_cert.pem');
    define('UW_WS_SSL_KEY_PASSWD', 'myprivatekeypassword');  // Can be blank for no password: ''
    define('UW_WS_VERBOSE', false);  // (Optional) Whether to include verbose cURL messages in error messages.

The terms UW_WS_SSL_KEY_PATH and UW_WS_SSL_CERT_PATH correspond to the absolute locations of your private key and university-signed certificate. The UW_WS_SSL_KEY_PASSWD corresponds to the string which unlocks your private key; if your key does not have a password then use a blank string, eg: ''.

The term UW_WS_BASE_PATH corresponds to the base URL shared by UW web services. Currently this is either "https://ws.admin.washington.edu/" for the production-access web services, or "https://wseval.s.uw.edu/" for the testing/development-access web services.

You may now issue queries against the web service:

    // Queries PWS/SWS for a student with StudentNumber "1033334".
    $student = Student::fromStudentNumber("1033334");
    
    // If no such student was found, then $student is null
    if ($student != null) {
        echo $student->getAttr("RegisteredFirstMiddleName");
    }

In the case above, there does exist a student with StudentNumber "1033334": one of the university's notional test students. So this script will output "JAMES AVERAGE".

The following methods may be used to query the database:

    // Available to Person, and all subclasses of Person
    $person = Person::fromUWNetID($uwnetid);
    $person = Person::fromUWRegID($uwregid);
    $person = Person::fromIdentifier("uwregid", $uwregid);
    $person = Person::fromIdentifier("uwnetid", $uwnetid);
    $person = Person::fromIdentifier("employee_id", $employeeid);
    $person = Person::fromIdentifier("student_number", $studentnumber);
    $person = Person::fromIdentifier("student_system_key", $studentsystemkey);
    $person = Person::fromIdentifier("development_id", $developmentid);
    
    // Available only to Student
    $student = Student::fromStudentNumber($studentnumber);
    $registrations = $student->registrationSearch($year, $quarter, [$extraSearchTerms]);
    
    // Available only to Employee
    $employee = Employee::fromEmployeeID($employeeid);
    
    // Available only to Alumni
    $alumni = Alumni::fromDevelopmentID($developmentid);

You can cast between classes each of the container classes' ::fromPerson method:

    $person = Person::fromUWNetID($uwnetid);
    
    // Cast the Person object into a Student
    $person = Student::fromPerson($person);

The ::hasAffiliation method can tell you whether a given person is a student, employee, and/or alumni:

    $person = Person::fromUWNetID($uwnetid);
    
    // The ::hasAffiliation method check is useful, but not required:
    if ($person->hasAffiliation("employee") {
        $person = Employee::fromPerson($person);
    }

Use ::getAttr to retrieve an attribute from a person:

    $person = Person::fromUWNetID($uwnetid);
    $displayName = $person->getAttr("DisplayName");
    
    $person = Student::fromPerson($person);
    $academicDepartment = $person->getAttr("Department1");

The Student::registrationSearch method returns an array of Registration Resources, in associative array format:

   $student = Student::fromStudentNumber("1033334");
   $registrations = $student->registrationSearch("2009", "summer");
   
   foreach ($registrations as $registration) {
       echo $registration["CurriculumAbbreviation"];
       echo $registration["CourseNumber"];
   }

You can include optional parameters in your registration search, per the Registration Search Resource spec:

    $student = Student::fromStudentNumber("1033334");
    $registrations = $student->registrationSearch("2009", "summer", ["is_active" => "true"]);

Exposed Attributes

The container classes expose the following attributes, corresponding to those described in this PWS glossary:

    Exposed by all classes:
        "DisplayName"
        "IsTestEntity"
        "RegisteredFirstMiddleName"
        "RegisteredName"
        "RegisteredSurname"
        "UIDNumber"
        "UWNetID"
        "UWRegID"
        "WhitepagesPublish"
        
    Exposed only by Employee:
        "EmployeeID"
        "Address1"
        "Address2"
        "Department1"
        "Department2"
        "Email1"
        "Email2"
        "Fax"
        "Name"
        "Phone1"
        "Phone2"
        "PublishInDirectory"
        "Title1"
        "Title2"
        "TouchDial"
        "VoiceMail"
    
    Exposed only by Student:
        "StudentNumber"
        "StudentSystemKey"
        "Class"
        "Department1"
        "Department2"
        "Department3"
        "Email"
        "Name"
        "Phone"
        "PublishInDirectory"

    Exposed by Student, when SWS access is enabled:
        "RegID"
        "FirstName"
        "LastName"
        "StudentName"
        "EmployeeID"
        "BirthDate"
        "Gender"
        "DirectoryRelease"
        "LocalAddress"
            "Line1"
            "Line2"
            "City"
            "State"
            "Zip"
            "Country"
            "PostalCode"
        "PermanentAddress"
            "Line1"
            "Line2"
            "City"
            "State"
            "Zip"
            "Country"
            "PostalCode"
        "LocalPhone"
        "PermanentPhone"
        "Veteran"
            "Code"
            "Description"
        "LastEnrolled"
            "Href"
            "Year"
            "Quarter"
        "Notices"[]
            "RegID"
            "Href"
        "PersonFinancial"[]
            "RegID"
            "Href"
        "Resident"
        "VisaType"
        "TestScore"[]
            "RegID"
            "Href"

    Exposed only by Alumni:
        "DevelopmentID"

Troubleshooting

This library will throw warnings and exceptions when it recognizes an error. Turn on error reporting to see these. For errors involving cURL, SSL, and or script execution halts/no output, see UWEnrollmentManagement/Connection troubleshooting.

Compatibility

• Person Web Service v1
• Student Web Service v5

Requirements

• PHP 7.0
• uwdoem/connection 3.*

Todo

See GitHub issue tracker.

Getting Involved

Feel free to open pull requests or issues. GitHub is the canonical location of this project.

Here's the general sequence of events for code contribution:

1. Open an issue in the issue tracker.
2. In any order:

• Submit a pull request with a failing test that demonstrates the issue/feature.
• Get acknowledgement/concurrence.

1. Revise your pull request to pass the test in (2). Include documentation, if appropriate.

PSR-2 compliance is enforced by CodeSniffer in Travis.