diff --git a/docs/student/best-practices/ManageClassSections.md b/docs/student/best-practices/ManageClassSections.md index 1dcdbba1..ec39d1a3 100644 --- a/docs/student/best-practices/ManageClassSections.md +++ b/docs/student/best-practices/ManageClassSections.md @@ -11,13 +11,13 @@ Creating and managing class sections is a fundamental requirement for the Academ This document will cover the following endpoints: -api/commands/Academics/ClassSection/SaveNew -api/commands/Academics/ClassSection/Save -api/commands/Academics/ClassSection/SaveClassSectionPeriods -api/commands/Academics/ClassSection/SaveInstructorAndPortalOptions -api/commands/Academics/ClassSectionMeetingDate/SaveNew -api/commands/Academics/ClassSectionMeetingDate/Save -api/commands/Academics/CrossListClassSection/SaveCrossListClassSection +- api/commands/Academics/ClassSection/SaveNew +- api/commands/Academics/ClassSection/Save +- api/commands/Academics/ClassSection/SaveClassSectionPeriods +- api/commands/Academics/ClassSection/SaveInstructorAndPortalOptions +- api/commands/Academics/ClassSectionMeetingDate/SaveNew +- api/commands/Academics/ClassSectionMeetingDate/Save +- api/commands/Academics/CrossListClassSection/SaveCrossListClassSection ## Data model notes @@ -119,61 +119,27 @@ This endpoint should be used for updating any aspect of the meeting schedule for - ClassSection - this property is of type ClassSectionEntity and should be ignored. There are no dependencies within the execution logic of the API on any data in this property - MeetingPatterns - this property is a collection of type ClassSectionMeetingPatternEntity. - - - Id - populate with 0 if a new instance of ClassSectionMeetingPatternEntity is being created. Populate with Id of ClassSectionMeetingPatternEntity record if an existing instance - is being updated. - - - MeetingPatternId - if the recurring meeting pattern is a pre-configured meeting pattern, then set this to the Id of the MeetingPattern entity instance being used. If a new - recurring meeting pattern is being created, then set to 0. If an existing meeting pattern is being updated that was not created from a pre-configured meeting - pattern, then set to the Id value of the ClassSectionCustomMeetingPatternEntity that is being updated - - - Type - If the recurring meeting pattern is a pre-configured meeting pattern, then set to 'L'. If the recurring meeting pattern is not created from a pre-configured meeting - pattern, then set to 'D'. - - - ClassSectionId - populate with Id of class section the meeting schedule data is being updated for - - - DayOfWeekRooms - this is a complex type and is a collection. One element should be populated in this property for each day of week in the recurring schedule meeting pattern - - - DayOfWeek - This is an Enum with the following values: 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday - - - BuildingId - populate with Id of Building that the scheduled meeting will occur in - - - RoomId - populate with Id of Room that the scheduled meeting will occur in - - - LocationId - populate with Id of Location that the scheduled meeting will occur in - - - PrimaryInstructorId - populate with Id of primary instructor that will be teaching this class section meeting - - - SecondaryInstructorList - this is collection property and should be populated with one element for each secondary instructor that will be teaching this class section - meeting. Only the InstructorId property in the element needs to be populated. - - - MeetingPattern - this is a complex type - ClassSectionCustomMeetingPatternEntity - - - StartTime - populate with the start time of the class section scheduled meeting. This is a datetime type. However, only the time portion of the value is relevant. - Populate the date portion of the value with "1899/12/30". - - - EndTime - populate with the end time of the class section scheduled meeting. This is a datetime type. However, only the time portion of the value is relevant. Populate - the date portion of the value with "1899/12/30". - - - IsMeetingOn properties - a boolean type property exists for each day of the week. Set the applicable bool properties to 1 for the days of the week that the class section - will be meeting on - - - Id - if the recurring meeting pattern is a pre-configured meeting pattern, then set this to the Id of the MeetingPattern entity instance being used. If a new recurring - meeting pattern is being created, then set to 0. If an existing meeting pattern is being updated that was not created from a pre-configured meeting pattern, then set - to the Id value of the ClassSectionCustomMeetingPatternEntity that is being updated - - - MeetingLength - set to the duration of the scheduled meeting in minutes - - - PatternType - W= Weekly, M= Monthly - - - Frequency - set to frequency of pattern type. For example, if pattern type is Weekly and recurring pattern is the same every week, then Frequency would be set to 1. If - recurring pattern is every other week, then Frequeny would be 2. - - - RecurrenceStartWeeks - if recurring meeting pattern will start sometime AFTER the class section begins meeting, then specify the number of weeks after the start of the - class section when the recurring meeting pattern will begin. If the meeting pattern begins when the class section starts, then set this value to 0. - - - RecurrenceEndNumber - if recurring meeting pattern will occur only a set number of times and not carry through to the end date of the class section, then set this value - to the number of times it will occur. Otherwise, set to 0. + - Id - populate with 0 if a new instance of ClassSectionMeetingPatternEntity is being created. Populate with Id of ClassSectionMeetingPatternEntity record if an existing instance is being updated. + - MeetingPatternId - if the recurring meeting pattern is a pre-configured meeting pattern, then set this to the Id of the MeetingPattern entity instance being used. If a new recurring meeting pattern is being created, then set to 0. If an existing meeting pattern is being updated that was not created from a pre-configured meeting pattern, then set to the Id value of the ClassSectionCustomMeetingPatternEntity that is being updated + - Type - If the recurring meeting pattern is a pre-configured meeting pattern, then set to 'L'. If the recurring meeting pattern is not created from a pre-configured meeting pattern, then set to 'D'. + - ClassSectionId - populate with Id of class section the meeting schedule data is being updated for + - DayOfWeekRooms - this is a complex type and is a collection. One element should be populated in this property for each day of week in the recurring schedule meeting pattern + - DayOfWeek - This is an Enum with the following values: 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday + - BuildingId - populate with Id of Building that the scheduled meeting will occur in + - RoomId - populate with Id of Room that the scheduled meeting will occur in + - LocationId - populate with Id of Location that the scheduled meeting will occur in + - PrimaryInstructorId - populate with Id of primary instructor that will be teaching this class section meeting + - SecondaryInstructorList - this is collection property and should be populated with one element for each secondary instructor that will be teaching this class section meeting. Only the InstructorId property in the element needs to be populated. + - MeetingPattern - this is a complex type - ClassSectionCustomMeetingPatternEntity + - StartTime - populate with the start time of the class section scheduled meeting. This is a datetime type. However, only the time portion of the value is relevant. Populate the date portion of the value with "1899/12/30". + - EndTime - populate with the end time of the class section scheduled meeting. This is a datetime type. However, only the time portion of the value is relevant. Populate the date portion of the value with "1899/12/30". + - IsMeetingOn properties - a boolean type property exists for each day of the week. Set the applicable bool properties to 1 for the days of the week that the class section will be meeting on + - Id - if the recurring meeting pattern is a pre-configured meeting pattern, then set this to the Id of the MeetingPattern entity instance being used. If a new recurring meeting pattern is being created, then set to 0. If an existing meeting pattern is being updated that was not created from a pre-configured meeting pattern, then set to the Id value of the ClassSectionCustomMeetingPatternEntity that is being updated + - MeetingLength - set to the duration of the scheduled meeting in minutes + - PatternType - W= Weekly, M= Monthly + - Frequency - set to frequency of pattern type. For example, if pattern type is Weekly and recurring pattern is the same every week, then Frequency would be set to 1. If recurring pattern is every other week, then Frequeny would be 2. + - RecurrenceStartWeeks - if recurring meeting pattern will start sometime AFTER the class section begins meeting, then specify the number of weeks after the start of the class section when the recurring meeting pattern will begin. If the meeting pattern begins when the class section starts, then set this value to 0. + - RecurrenceEndNumber - if recurring meeting pattern will occur only a set number of times and not carry through to the end date of the class section, then set this value to the number of times it will occur. Otherwise, set to 0. ### Managing Secondary Instructor Assignments and Instructor attribute data @@ -190,19 +156,12 @@ When calling this endpoint, make sure the request is populated with each seconda - HideLocation - ignore. not used in API execution logic - Instructors - this is a collection property and will hold one element per instructor that is assigned to the class section. The primary instructor for the class section should always be in element 0. - - - Id - set this to the Id of the StaffEntity instance for the Instructor that is assigned to the class section - - - CanPostAttendance - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post attendance for the class section. - - - CanPostFinalGrades - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post final grades for the class section. - - - CanPostLessons - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post lesson scores for the class section. - - - StaffPositionAssignmentId - Only applicable is using the Faculty Workload Management module. Set to the Id of the StaffPositionAssignmentEntity instance associated to this - instructor for this class section. - - - Attributes - this is a collection of int. Specify the Id of each InstructorAttribute (ds/odata/InstructorAttributes) that is associated to the instructor for this class section. + - Id - set this to the Id of the StaffEntity instance for the Instructor that is assigned to the class section + - CanPostAttendance - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post attendance for the class section. + - CanPostFinalGrades - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post final grades for the class section. + - CanPostLessons - Only applicable if this is a secondary instructor. If set to 1, the instructor will be able to post lesson scores for the class section. + - StaffPositionAssignmentId - Only applicable is using the Faculty Workload Management module. Set to the Id of the StaffPositionAssignmentEntity instance associated to this instructor for this class section. + - Attributes - this is a collection of int. Specify the Id of each InstructorAttribute (ds/odata/InstructorAttributes) that is associated to the instructor for this class section. ### Managing data for individual scheduled class section meetings diff --git a/docs/student/best-practices/PaymentVendorPartnerOverview.md b/docs/student/best-practices/PaymentVendorPartnerOverview.md index 185e95d9..c2b691a3 100644 --- a/docs/student/best-practices/PaymentVendorPartnerOverview.md +++ b/docs/student/best-practices/PaymentVendorPartnerOverview.md @@ -31,7 +31,7 @@ To see additional details for the APIs within Student, access the Swagger output ### Post Payment -The most basic use case for an integration between a payment provider and Anthology Student is to be able to process a payment within the payment vendor application and then post that payment to the student's ledger card within Anthology Student. At a high level, there are two different kinds of payments within the Student application. The first is a payment that is not associated with expected funding and the second is a payment that is associated to an expected disbursement. One of the features in Student is the ability to package a student for Financial Aid which results in a list of scheduled disbursements being created. Included in this are Student payment plans. A student payment plan will have 1 or more expected payments/installments created as part of the payment plan data. When posting a payment that is made against a payment plan, the payment will be "associated" with the expected disbursement record. Regardless of whether the payment being posted is for an expected disbursement or is not associated to an expected disbursement, the same API endpoint will be used. There are properies in the request payload that inform the API execution logic as to if the payment being posted is associated to an expected disbursement record or is not associated to an expected disbursement record. +The most basic use case for an integration between a payment provider and Anthology Student is to be able to process a payment within the payment vendor application and then post that payment to the student's ledger card within Anthology Student. At a high level, there are two different kinds of payments within the Student application. The first is a payment that is not associated with expected funding and the second is a payment that is associated to an expected disbursement. One of the features in Student is the ability to package a student for Financial Aid which results in a list of scheduled disbursements being created. Included in this are Student payment plans. A student payment plan will have 1 or more expected payments/installments created as part of the payment plan data. When posting a payment that is made against a payment plan, the payment will be associated with the expected disbursement record. Regardless of whether the payment being posted is for an expected disbursement or is not associated to an expected disbursement, the same API endpoint will be used. There are properies in the request payload that informs the API if the payment being posted is associated to an expected disbursement record or is not associated to an expected disbursement record. The API to use for posting payments is POST api/student-accounting/ledger-payment-transactions @@ -39,30 +39,34 @@ The API to use for posting payments is POST api/student-accounting/ledger-paymen #### Installment on Payment Plan -If a payment is being posted for an expected installment on a payment plan, then the request payload will include this information either by providing the Id of the expected installment record the payment is for (ScheduledDisbursementId property) or setting the UseNextScheduledPayment property to true. If this is not done in the request, then the API execution logic will assume that the payment being posted is NOT for an expected disbursement. If UseNextScheduledPayment property is true, then the payment being posted will be associated to the expected disbursement record for the payment plan that has a status of scheduled and the earliest expected payment date. If the amount of the payment being posted does not match the amount of the expected disbursement it is being associated to, then the expected payment schedule will be auto adjusted accordingly. If the amount of payment is less than the amount of the expected disbursement, then a new expected disbursement record with a status of scheduled will be created with an amount that is the difference between the amount that was expected and the payment amount. If the amount of the payment being posted is greater than the the amount of the expected payment it is being associated to, then the difference will be applied to the next expected payment. See examples below: +If a payment is being posted for an expected installment on a payment plan, then the request payload will include this information either by providing the Id of the expected installment record the payment is for (ScheduledDisbursementId property) or setting the UseNextScheduledPayment property to true. If this is not done in the request, then the API will assume that the payment being posted is NOT for an expected disbursement. If UseNextScheduledPayment property is true, then the payment being posted will be associated to the expected disbursement record for the payment plan that has a status of scheduled and the earliest expected payment date. If the amount of the payment being posted does not match the amount of the expected disbursement it is being associated to, then the expected payment schedule will be auto adjusted accordingly. If the amount of payment is less than the amount of the expected disbursement, then a new expected disbursement record with a status of scheduled will be created with an amount that is the difference between the amount that was expected and the payment amount. If the amount of the payment being posted is greater than the the amount of the expected payment it is being associated to, then the difference will be applied to the next expected payment. See examples below: -Expected payment schedule: +**Expected payment schedule:** -Payment # Expected Amount Expected Date Paid Amount Status -1 $100 04/01/2024 $0 Scheduled -2 $100 05/01/2024 $0 Scheduled -3 $100 06/01/2024 $0 Scheduled +| Payment # | Expected Amount | Expected Date | Paid Amount | Status | +|-----------|-----------------|----------------|-------------|-----------| +| 1 | $100 | 04/01/2024 | $0 | Scheduled | +| 2 | $100 | 05/01/2024 | $0 | Scheduled | +| 3 | $100 | 06/01/2024 | $0 | Scheduled | -Payment is posted and is associated to Expected payment # 1 above. Payment amount is $125. Payment schedule after API execution completes is as follows: -Payment # Expected Amount Expected Date Paid Amount Status -1 $100 04/01/2024 $100 Paid -2 $25 05/01/2024 $25 Paid -2 $75 05/01/2024 $0 Scheduled -3 $100 06/01/2024 $0 Scheduled +Payment is posted and is associated to Expected payment # 1 above. Payment amount is $125. Payment schedule after API completes is as follows: -Payment is posted and is associated to Expected payment # 1 above. Payment amount is $75. Payment schedule after API execution completes is as follows: +| Payment # | Expected Amount | Expected Date | Paid Amount | Status | +|-----------|-----------------|----------------|-------------|-----------| +| 1 | $100 | 04/01/2024 | $100 | Paid | +| 2 | $25 | 05/01/2024 | $25 | Paid | +| 2 | $75 | 05/01/2024 | $0 | Scheduled | +| 3 | $100 | 06/01/2024 | $0 | Scheduled | -Payment # Expected Amount Expected Date Paid Amount Status -1 $75 04/01/2024 $75 Paid -1 $25 04/01/2024 $0 Scheduled -2 $75 05/01/2024 $0 Scheduled -3 $100 06/01/2024 $0 Scheduled +Payment is posted and is associated to Expected payment #1. Payment amount is $75. Payment schedule after API completes is as follows: + +| Payment # | Expected Amount | Expected Date | Paid Amount | Status | +|-----------|-----------------|----------------|-------------|-----------| +| 1 | $75 | 04/01/2024 | $75 | Paid | +| 1 | $25 | 04/01/2024 | $0 | Scheduled | +| 2 | $75 | 05/01/2024 | $0 | Scheduled | +| 3 | $100 | 06/01/2024 | $0 | Scheduled | The above auto adjust logic will execute as part of the post payment transaction unit of work. If the Payment vendor application creates and manages payment plans for students and is considered the system of record for payment plans, then the Payment Plan APIs will be utilized to push the payment plan data into Student. These APIs are designed to allow for data to be pushed into Student and replace the expected payment plan data that is auto adjusted per logic explained above keeping the payment plan data in Student synchronized with the payment plan data in the Payment provider data store. @@ -86,7 +90,7 @@ The minimum required properties for this payload are StudentId, BillingTransacti ### Apply Posted Payments -The apply payments endpoint is used when there is a need to explicitly specify which charge/adjustment transactions a given payment transaction will be applied to. Anthology has a feature that allows for payments to be automatically applied to charge and adjustment transactions using the auto apply configuration. If all of the institutions requrements for how payments should be applied to charges are satisfied via the configuration, then this endpoint is not needed. However, if there are cases, where the rules for how to apply payments are not fully covered via the auto payment apply configuration OR the setting to auto apply payments is turned off, then there may be a need to utilize this endpoint. If/how this endpoint is utilized will need to be clarified with the institution being worked with. +The apply payments endpoint is used when there is a need to explicitly specify which charge/adjustment transactions a given payment transaction will be applied to. Anthology has a feature that allows for payments to be automatically applied to charge and adjustment transactions using the auto apply configuration. If all of the institution's requirements for how payments should be applied to charges are satisfied via the configuration, then this endpoint is not needed. However, if there are cases, where the rules for how to apply payments are not fully covered via the auto payment apply configuration OR the setting to auto apply payments is turned off, then there may be a need to utilize this endpoint. If/how this endpoint is utilized will need to be clarified with the institution being worked with. The API to use for applying payments is POST api/student-accounting/ledger-transactions-applypayments @@ -107,7 +111,7 @@ Many Payment providers have a capability for processing refunds that are schedul #### Retrieve scheduled refunds -The first step is to retrieve the scheduled refunds that need to be processed. The best way to do this is to constuct an odata query to retrieve the needed information. The scheduled refunds will reside in the Refunds entity. One of the filters needed in the query will be on the Status property. A value of 'N' in the Status property indicates that the refund is scheduled but has not yet been processed/paid. Other valid values for this property are P= Processed/Paid, V= Was paid but has since been Voided and S= Selected for Processing. The other key filters needed in the OData query will be on the DueDate property which indicates the date that the refund is due. Also, there will likely need to be filtering based on the fund source the refund is for. In many cases, refunds that are being returned to Title IV fund sources are not processed by Payment providers. The StudentAward navigation property on the Refunds entity will need to be utilized to construct the filtering condition needed to filter on the fund source(s) that should be included. +The first step is to retrieve the scheduled refunds that need to be processed. The best way to do this is to constuct an odata query to retrieve the needed information. The scheduled refunds will reside in the Refunds entity. One of the filters needed in the query will be on the Status property. A value of 'N' in the Status property indicates that the refund is scheduled but has not yet been processed/paid. Other valid values for this property are P= Processed/Paid, V= Processed but has since been Voided and S= Selected for Processing. The other key filters needed in the OData query will be on the DueDate property which indicates the date that the refund is due. Also, there will likely need to be filtering based on the fund source the refund is for. In many cases, refunds that are being returned to Title IV fund sources are not processed by Payment providers. The StudentAward navigation property on the Refunds entity will need to be utilized to construct the filtering condition needed to filter on the fund source(s) that should be included. #### Flag the selected refund records @@ -169,11 +173,11 @@ There is also a PATCH endpoint that allows for updating a previously posted misc In order to execute the APIs that have been discussed above, proper authorization needs to be configured. Whether using Basic Auth or OAuth with application key to authenticate, the user context the APIs are executing under will be a user record from the Staff entity. This is the user that authorization needs to be configured for. Access to the security console application is needed in order to set the needed permissions. Unlike the Anthology Student command APIs, the API endpoints discussed above have separate explicit tasks that need to be authorized. The Anthology Student command APIs are coupled with UI tasks. In order to properly authorize an API user to execute a command API, the applicable UI task needs to be identified and added for that user. For the APIs discussed in this document that exercise is not needed. Details are outlined below. -Within the Security console, the API - Student Accounting and API - Student Payment Plan tasks should be added for the user. These 2 tasks will authorize the user to execute every operation contained within the Student Accounting and Student Payment Plan sections within the swagger document. If more refined permissions are needed and you want to authorize the execution of specific operations with Student Accounting or Student Payment Plan, then the applicable individual operations will need to be authorized. Typically, this level of granularity is not needed and authorizing the two tasks mentioned above is all that is needed. +Within the Security console, the API - Student Accounting and API - Student Payment Plan tasks should be added for the user. These 2 tasks will authorize the user to execute every operation contained within the Student Accounting and Student Payment Plan sections within the swagger document. If more refined permissions are needed and you want to authorize the execution of specific operations with Student Accounting or Student Payment Plan, then the applicable individual operations will need to be authorized. Typically, this level of granularity is not needed and authorizing the two tasks mentioned above is all that should be done. ![PaymentVendorPartnerOverview](/assets/img/PaymentVendorPartnerOverview12.png) -For any OData queries that will be executed, additional authorization is needed. The authorization model for the odata endpoint is to either grant permission to query all entities contained within the data model or to authorize each individual entity that data will be extracted from. Currently there are no tasks available for authorizing by business area of domain. Best practice is to NOT authorize access to the entire query data model so it will be necessary to create an inventoried list of each entity that data will be retrieved from and add the applicable operation for the user. In order to authorize at the operation level, select the role that the user is a member of. Then select Add Permissions. On the resulting page that is displayed, check the Show Operations checkbox. To make the resulting list easier to navigate, you may want to uncheck the Show Tasks, Show Built In Tasks and Show Roles check boxes. Click Apply. +For any OData queries that will be executed, additional authorization is needed. The authorization model for the odata endpoint is to either grant permission to query all entities contained within the data model or to authorize each individual entity that data will be extracted from. Currently there are no tasks available for authorizing by business area of domain. Best practice is to NOT authorize access to the entire query data model so it will be necessary to create a list of each entity that data will be retrieved from and add the applicable operation for the user. In order to authorize at the operation level, select the role that the user is a member of. Then select Add Permissions. On the resulting page that is displayed, check the Show Operations checkbox. To make the resulting list easier to navigate, you may want to uncheck the Show Tasks, Show Built In Tasks and Show Roles check boxes. Click Apply. ![PaymentVendorPartnerOverview](/assets/img/PaymentVendorPartnerOverview13.png)