cdli/cdlid2lsoap

Object-oriented PHP wrapper for Desire2Learn SOAP API. Formerly zfD2L.

PHP Wrapper for Desire2Learn SOAP API

This project aims to provide a robust object-oriented PHP5 wrapper for interacting with the SOAP web service exposed by the Desire2Learn Learning Management System (LMS).

SYSTEM REQUIREMENTS

###Library Usage###

• PHP v5.3.0+, with the following extensions enabled:
  • dom
  • SimpleXML
  • soap
• Desire2Learn Learning Environment (LE) v9.0+
  • NOTE: Support for earlier versions is untested.

###Unit Test Suite###

• PHP 5.3.0+
• PHPUnit v3.5+

CONTRIBUTING

###How you can help###

This project is still a work in progress, and there is much ground to cover before it can be considered stable. There are a number of ways you can help with reaching our goal of providing a robust, easy-to-use and well-documented finished product:

• Run the unit test suite against your Desire2Learn development environment and report the results back to a member of the core maintainers list
• Report any issues you encounter while using our code to the Issue Tracker
• Add/update documentation and/or code examples on the project wiki
• Fill in gaps in the unit test suite
• Tackle an outstanding issue from the Issue Tracker
• Implement SOAP API methods which are currently missing/incomplete

###Getting Started### If you are interested in contributing source code or documentation updates back to our project, you only need two things to get started:

1. GitHub Account: You can sign up for a GitHub account at www.github.com. It's free and super easy!

2. Git Client Software: Git is a distributed version control system. For instructions on how to install Git on Windows, Mac or Linux and configure it for use with GitHub, see this Help.GitHub page

Once you have completed both of those steps, fork our project into your own GitHub account and get crackin'! If you are new to GitHub, the Beginner section on Help.GitHub is a fantastic resource. Our suggestion is to start with the Fork a Repo page and work your way through the section from there.

###List of Contributors### ####Core Maintainers####

• Adam Lundrigan
  Centre for Distance Learning and Innovation

####Contributors####

• Thomas Hawkins
  Memorial University of Newfoundland

DISCLAIMER

This code is considered proof-of-concept, and has not been vetted or tested for inclusion in a production environment. Use of this code in such environments is at your own risk.

Released under the New BSD license. See file LICENSE included with the source code for this project for a copy of the licensing terms.

cdlid2lsoap's Issues

Test Failure: Department_APILiveTest

D2L LE 10.1.0 SP6

Location: tests/library/D2LWS/OrgUnit/Department/APILiveTest.php:129

1) D2LWS_OrgUnit_Department_APILiveTest::testUpdateDepartment
Exception: Unexpected exception caught by RequestHandler.HandleRequest(), message: Object reference not set to an instance of an object., stack trace:    at D2L.WS.Contracts.Lews.OrgUnits.Messages.UpdateDepartmentRequest.get_OrgUnitId()
   at D2L.WS.Implementation.Lews.Handlers.LewsOrgUnitRequestHandler`2.GetOrgUnit[T](Q request)
   at D2L.WS.Implementation.Lews.Handlers.OrgUnits.UpdateDepartmentRequestHandler.DoHandle(UpdateDepartmentRequest request)
   at D2L.WS.Implementation.Handlers.RequestHandler`2.HandleRequest(TRequest request)
Failed asserting that two objects are equal.
--- Expected
+++ Actual
@@ @@
         'Name' => 'zfD2L Test Department'
-        'Code' => 'zfd2ltestdept_update'
+        'Code' => 'zfd2ltestdept'
         'Path' => '/content/apitest/zfd2ltestdept'
         'IsActive' => true
         'StartDate' => '2013-09-04T13:59:21'
         'EndDate' => '2013-09-04T14:09:21'
     )
 )

User's organization role ID is not loaded when user record fetched

D2LWS_User_API::findBy* methods should load the user's assigned role in the Organization org unit and inject it into the D2LWS_User_Model instance before returning.

SOAP-ERROR: Parsing WSDL: Couldn't load from ...

While investigating Issue #5 I encountered the following error message when attempting to run 1000 consecutive user lookups:

PHP Fatal error:  SOAP-ERROR: Parsing WSDL: Couldn't load from 'https://<snip>/d2l/AuthenticationTokenService.asmx?WSDL' : failed to load external entity "https://<snip>/d2l/AuthenticationTokenService.asmx?WSDL"
 in <snip>/Zend/Soap/Client/Common.php on line 51

This is puzzling as it always happens at the 511th consecutive request. Appears to be some sort of internal throttling mechanism within Desire2Learn Web Services

GetChildOrgUnitIds raises authorization error

GetChildOrgUnitIds SOAP method does not work properly when called on non-Organization org unit types. It will return an authorization error:

Authorization failed for user:xxxxxxxxxx and operation:OrgUnits.GetChildOrgUnitIds

The D2LWS_OrgUnit_API::getChildrenOf method implements a workaround this issue by querying the GetChild<type>s SOAP method for each org unit type individually. This adds a large SOAP overhead, but is the only solution at this point.

Issue has been reported to Desire2Learn technical support (Issue #111078) and acknowledged as a bug in Desire2Learn Web Services, however there is no timeline in place for a fix. Once a fix has been released D2LWS_OrgUnit_API::getChildrenOf will be updated.

User model discriminates against those older than UNIX epoch

If user's birth date is before UNIX epoch, and is provided to D2LWS_User_Model in UNIX timestamp format, it will not be converted to a SOAP-compatible dateTime format due to an error in the regex:

https://github.com/cdli/CdliD2LSoap/blob/master/library/D2LWS/User/Model.php#L227

[LE9.2] CreateUser requires BirthDate to be formatted

CreateUser WS call in LE 9.2 requires that BirthDate be specified in this format: Y-m-d\TH:i:sP
It appears that LE 9.4 (which the D2LWS_User_API::save method was developed against) accepts an integer timestamp as well, but LE 9.2 throws back an "Schema Validation Failed" error.

Auto-renew of security token broken

Issuing a large number of SOAP API calls within the same request will often cause this exception to be raised:

System.Web.Services.Protocols.SoapException: Server was unable to process request. ---> D2L.WS.Security.Authentication.AuthenticationException: Expired authentication token
at D2L.WS.Security.Authentication.TokenAuthenticator.AuthententicateHeader(Int64 orgId, RequestHeaderInfo headerInfo)
at D2L.WS.Implementation.SoapHeaderServiceBase`1.set_RequestHeader(RequestHeaderInfo value)
--- End of inner exception stack trace ---

It's likely that D2LWS_Authenticate::tokenHasExpired is falsely reporting that a token is active when in fact it has expired, or will expire in the time between it's check and when the actual SOAP call is made.

Unit test for UpdateDepartment fails live test

1) D2LWS_OrgUnit_Department_APILiveTest::testUpdateDepartment
D2LWS_Soap_Client_Exception: Unexpected exception caught by RequestHandler.HandleRequest(), message: Object reference not set to an instance of an object., stack trace:    at D2L.WS.Contracts.Lews.OrgUnits.Messages.UpdateDepartmentRequest.get_OrgUnitId()
   at D2L.WS.Implementation.Lews.Handlers.LewsOrgUnitRequestHandler`2.GetOrgUnit[T](Q request)
   at D2L.WS.Implementation.Lews.Handlers.OrgUnits.UpdateDepartmentRequestHandler.DoHandle(UpdateDepartmentRequest request)
   at D2L.WS.Implementation.Handlers.RequestHandler`2.HandleRequest(TRequest request)

GetGroupType returns "not authorized" on non-existent group type

GetGroupType SOAP API method returns "not authorized" on non-existent group type.
Need to contact D2L support to notify them of the issue.

See: 4a1c761

SOAP-ERROR: Parsing WSDL: Couldn't load from ...

While investigating Issue #5 I encountered the following error message when attempting to run 1000 consecutive user lookups:

PHP Fatal error:  SOAP-ERROR: Parsing WSDL: Couldn't load from 'https://<snip>/d2l/AuthenticationTokenService.asmx?WSDL' : failed to load external entity "https://<snip>/d2l/AuthenticationTokenService.asmx?WSDL"
 in <snip>/Zend/Soap/Client/Common.php on line 51

This is puzzling as it always happens at the 511th consecutive request. Appears to be some sort of internal throttling mechanism within Desire2Learn Web Services

D2LWS_OrgUnit_Group_API::delete() does not delete?

When running the live test for D2LWS_OrgUnit_Group_API, the group created during the CRUD group of tests isn't successfully deleted, despite the SOAP call returning the expected output (empty stdClass, no exception thrown)

Run the test suite; all tests pass, and the group is created and updated successfully:

[webadmin@spiral tests]$ phpunit library/D2LWS/OrgUnit/Group/APILiveTest
PHPUnit 3.5.14 by Sebastian Bergmann.

.......

Time: 1 second, Memory: 15.75Mb

OK (7 tests, 10 assertions)

The SOAP call request:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="http://www.desire2learn.com/services/common/xsd/common-v1_0" xmlns:ns2="http://www.desire2learn.com/services/oums/wsdl/OrgUnitManagementService-v1_0">
    <env:Header>
        <ns1:RequestHeader>
            <ns1:Version>1.0</ns1:Version>
            <ns1:CorellationId>...</ns1:CorellationId>
            <ns1:AuthenticationToken>...</ns1:AuthenticationToken>
        </ns1:RequestHeader>
    </env:Header>
    <env:Body>
        <ns2:DeleteGroupRequest>
            <ns2:OrgUnitId>
                <ns1:Id>#####</ns1:Id>
                <ns1:Source>Desire2Learn</ns1:Source>
            </ns2:OrgUnitId>
        </ns2:DeleteGroupRequest>
    </env:Body>
</env:Envelope>

And the response, which indicates the group was deleted successfully:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Header>
        <ResponseHeader xmlns="http://www.desire2learn.com/services/common/xsd/common-v1_0">
            <CorellationId>...</CorellationId>
            <Status>
                <Code>Success</Code>
            </Status>
            <OperationName>DeleteGroupRequest</OperationName>
        </ResponseHeader>
    </soap:Header>
    <soap:Body>
        <DeleteOrgUnitResponse xmlns="http://www.desire2learn.com/services/oums/wsdl/OrgUnitManagementService-v1_0" />
    </soap:Body>
</soap:Envelope>

However, if I go to the groups page in D2L it still shows up.

The testDelete() test does attempt to load the group by OUID via the API after the group has been deleted, and that query returns no results, so this may be a caching issue?