The LIS Adapter implements handlers that are used by IPSIS to initiate calls to LIS services hosted by the SIS. Each of these handlers are specific to LIS, but use an IPSIS Platform handler interface.
About the IBulkCancelRequestHandler interface
The plug-in interface for IBulkCancelRequestHandler is used by BulkManager to support producing a cancelBulkDataExchange or ignoreBulkDataExchange request.
The interface implementation is D2L.IM.IPSIS.Bulk.Handlers.IBulkCancelRequestHandler.
The following configuration list provides a starting point for any LIS implementation:
Template - Bulk Cancel (LIS)
- D2L.IM.IPSIS.LIS.BDEMS.Default.CancelBulkDataExchangeHandler (Sort Order = 10)
CancelBulkDataExchangeHandler
Implementation
D2L.IM.IPSIS.LIS.BDEMS.Default.CancelBulkDataExchangeHandler
Expected behavior
The handler performs the following tasks:
- Checks the BulkJobStatus of the IBulkCancelRequest object to determine whether to call cancelBulkDataExchange or ignoreBulkDataExchange (via the proxy client).
- If (BulkRequested || BulkRequestSent), the handler calls cancel. Otherwise the handler calls ignore.
- Sends the appropriate request (Cancel or Ignore).
- Verifies that the response is a success. If the response is not a success, the handler updates the status of the bulk job to Error.
- Takes the source system out of BulkMode (set to Enabled).
About the IBulkFileProcessor interface
The plug-in interface for IBulkFileProcessor is used by BulkManager to parse a received bulk file, pass individual requests to the adapters for processing, and pass results to a report generator.
The interface implementation is D2L.IM.IPSIS.Bulk.Handlers.IBulkFileProcessor.
The following configuration list provides a starting point for any LIS implementation:
Template - Bulk File Processor (LIS)
- D2L.IM.IPSIS.LIS.BDEMS.Default.BulkFileProcessor (Sort Order = 10)
BulkFileProcessor
The BulkFileProcessor parses and processes a single input file, passing the results to a report generator.
Implementation
D2L.IM.IPSIS.LIS.BDEMS.Default.BulkFileProcessor
Expected behavior
The handler performs the following tasks:
- The BulkFileProcessor runs after the file is downloaded locally, and is passed in an IBulkFileUrl with the file location.
- If the passed result object or the ReportGenerator are null, instances are created during preProcessing.
- At the start of processing, the file status is updated to Processing. The file is parsed as a stream, not as a single XML document. Not parsing the entire file at once saves memory and processing power.
- If a file is partially processed and an error is discovered, D2L does not roll back already processed transactions.
- The BDEMS headers are parsed using custom code, and are not auto-generated.
- Once the type of transaction is identified, the transaction body is forced into the namespace for the real-time version and deserialized using auto-generated proxy code.
- The deserialized message is wrapped in fake headers and passed to the adapters for the real-time service.
- The results are passed to the reportGenerator.
- The file status is updated to Completed.
Error behavior
- If an error occurs while processing a transaction, using a real-time adapter:
- The fail code is saved in the reportGenerator normally.
- Processing continues with next transaction.
- If an error occurs in FileProcessor itself:
- An error is logged to the database.
- The processor sets file status to Failed.
- Immediately returns (with return code = false), without processing any further entries.
Logging
- Debug log every time PreProcess creates a missing object on the request.
- Debug log at start and end of main processing.
- Debug once per transaction.
- Error logs on any exception raised during processing.
About the IBulkRequestDataHandler interface
The plug-in interface for IBulkRequestDataHandler is used by BulkManager to support producing a requestBulkDataExchange request.
The interface implementation is D2L.IM.IPSIS.Bulk.Handlers.IBulkRequestDataHandler.
The following configuration list provides a starting point for any LIS implementation:
Template - Bulk Request (LIS)
D2L.IM.IPSIS.LIS.BDEMS.Default.RequestBulkDataExchangeHandler (Sort Order = 10)
RequestBulkDataExchangeHandler
Implementation
D2L.IM.IPSIS.LIS.BDEMS.Default.RequestBulkDataExchangeHandler
Expected behavior
The handler performs the following tasks:
- Validates the endpoint and sets up the client.
- Checks the BulkEntityTypeFilters on the incoming request, and adds a FilterRuleType for each to the outgoing request.
- If any of the EntityTypes do not match the FilterType vocabulary for bulk (see the BDEMS spec for the vocabulary definition) the handler throws a KeyNotFoundException.
- Validates that the save point is of the correct format as defined by the spec. All passed endpoints must be identical, and of the format "YYYY-MM-DDTHH:MM:SS.NNN". T is the letter T and NNN is the milliseconds.
- If either of these conditions fail, the handler throws an InvalidRequestDataException.
- Adds a FilterRuleType to the outgoing request for the savepoint.
- Sends the requestBulkDataExchange request using the client and examines the response.
- If the response back is a success, the handler puts the source system in BulkMode (if it wasn't already). Return true.
- If the response back is an error, the handler take the source system out of BulkMode. The status of the job is updated to Error and the error is logged. Return false.
About the IBulkSendReportHandler interface
The plug-in interface for IBulkSendReportHandler is used by BulkManager to support producing a reportBulkDataExchange request.
The interface implementation is D2L.IM.IPSIS.Bulk.Handlers.IBulkSendReportHandler.
The following configuration list provides a starting point for any LIS implementation:
Template - Bulk Report (LIS)
- D2L.IM.IPSIS.LIS.BDEMS.Default.ReportBulkDataExchangeHandler (Sort Order = 10)
ReportBulkDataExchangeHandler
Implementation
D2L.IM.IPSIS.LIS.BDEMS.Default.ReportBulkDataExchangeHandler
Expected behavior
The handler performs the following tasks:
- Validates the endpoint and sets up the client.
- Gets the BulkBlockReportType from the report generator.
- If the report is null, a basic report that satisfies the minimum requirements for the LIS specification is created and used, and an error is logged.
- The handler creates the reportBulkDataExchangeRequest using the report.
- The reportBulkDataExchangeRequest is sent via the client.
- The response is examined.
- If the response is a success, return true.
- If the response back is an error, the status of the job is updated to Error and the error is logged. Return false.
- The source system is taken out of BulkMode.
About the IPushGradesHandler interface
The plug-in interface for IPushGradesHandler is used by IpsisManager to support the process of pushing grades to an SIS using the following requests: replaceLineItem and replaceResultsForLineItem.
The interface implementation is D2L.IM.IPSIS.Grades.Handlers.IPushGradesHandler.
The following configuration list provides a starting point for any LIS implementation:
Template - Outcome Replace (LIS)
D2L.IM.IPSIS.LIS.OMS.Default.ReplaceLineItemHandler (Sort Order = 10)
ReplaceLineItemHandler
Implementation
D2L.IM.IPSIS.LIS.OMS.Default.ReplaceLineItemHandler
Expected behavior
The handler performs the following tasks:
- Validates the outcomes endpoint and sets up the two clients responsible for sending the requests.
- LineItemManagerSyncPortTypeClient - Outcome endpoint must be used for the LineItemManagerSyncPortTypeClient.
- ResultManagerSyncPortTypeClient - Outcome2 endpoint must be used for the ResultManagerSyncPortTypeClient.
- The handler gets the necessary information for sending the replaceLineItem request.
- This information comes from the IReplaceGradesRequest and is used to obtain:
- lineItemSourcedId
- sisOrgUnitIdentifier
- orgUnitType (e.g. CourseSection)
- lineItemTypeVocabulary
- lineItemTypeLanguage
- gradeType (e.g. Final)
- The handler sends the replaceLineItem request using the LineItemManagerSyncPortTypeClient.
- The handler gets the result record set using the ITranslateReadResultIdsForLineItemWithLineItemTypeResponse translators, and the ReadGradesResult off of the IReplaceGradesRequest.
- The replaceResultsForLineItem request is sent using the ResultManagerSyncPortTypeClient, passing the result record set obtained in the previous step
- The handler gets the result status codes from the response for the replaceResultsForLineItem request.
- The handler sets the result status codes on the IReplaceGradesResult to the codes obtained in the previous step.
- Returns true.
Error behavior
If communication with the SIS fails (e.g. network failure, timeout, etc.), the handler retries up to three times. The following behavior applies to retry attempts:
- A warning is logged before re-trying
- An error is logged if communication fails after three retry attempts
- A slight delay is put in between tries:
- 5 seconds the first time
- 10 seconds the second time
- 15 seconds the last time
Retries only occur on CommunicationExceptions and TimeoutExceptions. Other exceptions fail as an error.
Otherwise, if there is a problem during processing, an exception is thrown, along with as much detailed information as possible.