Progress Report Web service Technical documentation Version 1.0
Progress Report Web service Technical Documentation
Last updated on May 25, 2011 1
Progress Report Web service Technical documentation Version 1.0
Table of contents 1.
About this document .................................................................................... 3
2.
EF Web services – General information ...................................................... 3
2.1. 2.2. 2.3. 2.4.
3.
The EF Online School Web services platform .................................................................. 3 Implementing EF Web services ........................................................................................ 3 Authentication ................................................................................................................... 3 Testing the Web service.................................................................................................... 4
Progress report ............................................................................................ 4
3.1. Description of the GetProgressReportListByCorporate function ...................................... 4 3.1.1. Purpose ...................................................................................................................... 4 3.1.2. Parameters ................................................................................................................ 5 3.1.3. Results ....................................................................................................................... 5 OperationResultData ............................................................................................................ 5 StudentProgressList ............................................................................................................. 5 When successful ................................................................................................................... 6 When unsuccessful............................................................................................................... 6 3.2. Description of the GetProgressReportListByDivision function .......................................... 6 3.2.1. Purpose ...................................................................................................................... 6 3.2.2. Parameters ................................................................................................................ 6 3.2.3. Results ....................................................................................................................... 7 OperationResultData ............................................................................................................ 7 StudentProgressList ............................................................................................................. 7 When successful ................................................................................................................... 7 When unsuccessful............................................................................................................... 8
Last updated on May 25, 2011 2
Progress Report Web service Technical documentation Version 1.0
1. About this document This document aims to give the reader a working knowledge on the implementation of the Progress Report Web service offered by EF.
2. EF Web services – General information 2.1. The EF Online School Web services platform The EF Online school Web services platform uses open protocols: XML defines the message structure, SOAP acts as the message envelope and HTTP/HTTPS is used for the transport layer. XML provides a language which is platform and programming language agnostic and can still express complex messages and operations. HTTP is the protocol for normal web surfing and as such few firewalls or routers blocks it, ensuring maximum Internet penetration. HTTPS provides security by ensuring that the traffic is encrypted. 2.2. Implementing EF Web services EF will provide an URI: a link to the Web service. The URI will be in the form of https://secure.englishtown.com/ <path-to-service> / <servicename> .svc Example: https://secure.englishtown.com/comercial/services/DemoService.svc
A WSDL file describing the Web service in XML is available at http:// <partnersite> .englishtown.com/partner/corp/wsdl/ <servicename> / <servicename> .svc.wsdl.xml Example: http://demo.englishtown.com/partner/corp/wsdl/demoservice/demoservice.svc.wsdl.xml
Once the WSDL file is obtained, the extension “.xml” can be removed. A client to interact with the Web service can be automatically generated from the WSDL file. Note Using a browser to go to the Web service URI will lead to an automatically generated page of little value because the Browser uses the HTTP GET method when accessing the URI. The Web service is designed to use the HTTP POST method. The automatically generated client will use the POST method and get different results than the browser will. 2.3. Authentication To be able to use the Web service, the customer organization must authenticate itself. The available methods are: 1. Username and password 2. Certificate exchange If using username and password, the username and password are specific to Web service usage. The credentials are passed with each call to the Web service.
Last updated on May 25, 2011 3
Progress Report Web service Technical documentation Version 1.0 Example: •
John Smith is an employee of Democorporation. He has an EF username of “johnsmith008” and a password of “seret08Pass”.
•
Democorporation has a Web service username of “democorp” and a password of “ckWe02&JHn”.
Only Web service username and password can be used to authenticate to EF Web services, in this case “democorp” and “ckWe02&JHn”.
2.4. Testing the Web service EF’s test environment should be used to test the Web service. This environment is available at staging.englishtown.com. Thus, the Web service test URI will be in the form of https://staging.englishtown.com/ <path-to-service> / <servicename> .svc Example: https://staging.englishtown.com/comercial/services/DemoService.svc
The staging data bases are completely separate from the live production data bases. This means that any action completed in the staging environment did not happen in the production environment. Only progress made by students existing on the staging environment can therefore be reported on with the staging environment Web service. Note The staging environment is updated regularly. During this update, staging behavior may not be reliable. Please contact EF for information on when the next update is expected.
3. Progress report The Progress Report Web service consists of two functions, GetProgressReportListByCorporate and GetProgressReportListByDivision. Each function is used to collect information on a predefined set of students. In EF terms, a Corporate code is an identifier for a large organization that is a customer to EF. Divisions are customer defined subsets of the Corporate customer. Division codes are identifiers for each division. For example, marketing could be one division, and engineering another. In another example, a division could be all employees reporting to the same manager. 3.1. Description of the GetProgressReportListByCorporate function 3.1.1. Purpose GetProgressReportListByCorporate is used to report progress of students belonging to an EF corporate code.
Last updated on May 25, 2011 4
Progress Report Web service Technical documentation Version 1.0 3.1.2. Parameters GetProgressReportListByCorporate takes two types of parameters. The first one, CorporateCodes, is one or several codes that identify the organization(s) the students belong to. The second one, called GetProgressMode, defines whether to return all of the students, or just students that have made progress since the function last was called. See Table 1 and Table 2. Identifier (CorporateCodes) Corporate code
Description
Requested set of students (GetProgressMode) All Delta
Description
An identifier for a large organization that is a customer to EF, consisting of four letters. For most customer organizations, this will be fixed value. Table 1.The first parameter for the GetProgressReportListByCorporate function.
All students associated with a corporate code. Students - associated with the given corporate code(s) - that have made progress since the last Web service call.. Table 2.The second parameter for the GetProgressReportListByCorporate function. 3.1.3. Results GetProgressReportListByCorporate will return an element named ProgressReportResult. This element has two child elements, OperationResultData and StudentProgressList. OperationResultData OperationResultData is an enumerated value which carries information on the Web service call status. The enumerated values are seen in Table 3. Value of OperationResultEnum Fail_BusinessLogic Fail_ErrorParameter
Description
Deprecated value. Should not occur. Error message. Informs the invoker that the desired results could not be obtained. Fail_Exception Error message. Informs the invoker that the desired results could not be obtained. Success Informs the invoker that the Web service call was successful. The list of students may still be empty. Table 3. The OperationResultData enumerated value. As can be seen from Table 3, the two values Fail_ErrorParameter and Fail_Exception serve as error messages. StudentProgressList StudentProgressList is a list of students. The information available for each student is seen in Table 4. Values returned with each student First name Last name Employee ID
Description The student’s first name. The student’s last name. The student’s employee id. This value is usually defined by the Last updated on May 25, 2011 5
Progress Report Web service Technical documentation Version 1.0 customer organization and corresponds to a unique identifier on its side. The studentâ&#x20AC;&#x2122;s email address. The date on which the student registered with the Online School. The date on which the student no longer has a valid subscription.
Email address Registration date Subscription expiration date Starting level The level on which the student begun studying, for example 1.0 Achieved level The level the student currently has reached, for example 5.4 Table 4. The information returned for each student.
When successful A successful call of GetProgressReportListByCorporate will set the OperationResultEnum to Success and return a list of students defined by the call parameters. Note that students must have an active subscription to be included in the results. The list of students may be empty. When unsuccessful An invocation of GetProgressReportListByCorporate is considered unsuccessful if OperationResultEnum returns with a Fail_<*>-value. In these cases, StudentProgressList will be null. Error descriptions are available in Table 5. Value of OperationResultEnum Fail_BusinessLogic Fail_ErrorParameter Fail_Exception
Description Deprecated value. Should not occur. Verify that the used parameters are correct and contact EF if the problem persists. HTTPS required. Any POST to the Web service must be called using HTTPS, not HTTP.
Table 5. Error messages.
3.2. Description of the GetProgressReportListByDivision function The GetProgressReportListByDivision function works in the same way as the GetProgressReportListByCorporate function. GetProgressReportListByDivision is described in detail below. 3.2.1. Purpose GetProgressReportListByDivision is used to collect information on a specific group of users belonging to a customer organization. The primary purpose is to report studentsâ&#x20AC;&#x2122; progress in the Online School. 3.2.2. Parameters GetProgressReportListByDivision takes two types of parameters. The first one, DivisionCodes, is one or several codes that identify groups, divisions, of the customer organization. These divisions are chosen by the customer organization. Each student will belong to one division. The second one, called GetProgressMode, defines whether to return all of the students, or just those students that have made progress since the function last was called. See Table 6 and Table 7. Identifier (DivisionCodes) Division code
Description
Requested set of
Description
An identifier for a subset of students. Which students belong to which division is decided by the customer organization. Table 6. The first parameter for the GetProgressByDivision function.
Last updated on May 25, 2011 6
Progress Report Web service Technical documentation Version 1.0 students (GetProgressMode) All Delta
All students associated with a division code. Students - associated with the given division code(s) - that have made progress since the last Web service call. Table 7.The second parameter for the the GetProgressReportListByDivision function. 3.2.3. Results GetProgressReportListByDivision will return an ProgressReportResult element. This element has two child elements, OperationResultData and StudentProgressList. OperationResultData OperationResultData is an enumerated value which carries information on the Web service call status. The enumerated values are seen in Table 8. Value of OperationResultEnum Fail_BusinessLogic Fail_ErrorParameter
Description
Deprecated value. Should not occur. Error message. Informs the invoker that the desired results could not be obtained. Fail_Exception Error message. Informs the invoker that the desired results could not be obtained. Success Informs the invoker that the Web service call was successful. The list of students may still be empty. Table 8. The OperationResultData enumerated value. As can be seen from Table 8, the two values Fail_ErrorParameter and Fail_Exception serve as error messages. StudentProgressList StudentProgressList is a list of students. The information available for each student is seen in Table 9. Values returned with each student First name Last name Employee ID
Description The student’s first name. The student’s last name. The student’s employee id. This value is usually defined by the customer organization and corresponds to a unique identifier on its side. The student’s e-mail address . The date on which the student registered with the Online School. The date on which the student no longer has a valid subscription.
Email address Registration date Subscription expiration date Starting level The level on which the student begun studying, for example 1.0 Achieved level The level the student currently has reached, for example 5.4 Table 9. The information returned for each student.
When successful A successful call of GetProgressReportListByDivision will set the OperationResultEnum to Success and return a list of students defined by the call parameters. Note that students must have an active subscription to be included in the results. The list of students may be empty. Last updated on May 25, 2011 7
Progress Report Web service Technical documentation Version 1.0 When unsuccessful An invocation of GetProgressReportListByDivison is considered unsuccessful if OperationResultEnum returns with a Fail_<*>-value. In these cases, StudentProgressList will be null. Error descriptions are available in Table 10. Value of OperationResultEnum Fail_BusinessLogic Fail_ErrorParameter
Description
Deprecated value. Should not occur. Verify that the used parameters are correct and contact EF if the problem persists. Fail_Exception HTTPS required. Any POST to the Web service must be called using HTTPS, not HTTP. Table 10. Error messages.
Last updated on May 25, 2011 8