Merge pull request #151 from jburns54712/main

Managing Account Statuses via API

Author: daveyherrera

docs/student/best-practices/AccountStatuses.md

@@ -0,0 +1,53 @@
+---
+title: "Updating Account Statuses"
+id: studentapi-updateaccountstatus-details
+sidebar_position: 1
+author: Jim Burns
+published: ""
+edited: ""
+---
+
+There is capability within Anthology Student to associate one or more account statuses with a student enrollment period record.  This makes it possible for an institution to perform various actions on groups of students based on the account status values associated.  Many times, the assignment of an account status will be triggered by an action that occurs or a specific data point.  For example, an account status of "Delinquent" may be associated with a student who has one or more expected installments for a payment plan that have not been received but have a due date in the past.  In many cases, managing the account statuses for students is a key use case that needs to be accomplished within an overall integration project.  This document will cover the details for how to effectively manage account statuses for students utilizing the available API endpoints.  
+
+## Data model notes
+
+The entity that stores account statuses associated with a given student is StudentAccountStatus. A couple of important points to note are that each account status is associated with a StudentEnrollmentPeriod and not a Student.   Thus, you will see a StudentEnrollmentPeriodId property on this entity but there is not a StudentId property.  Additionally, a student enrollment period can have multiple statuses assigned.  It is also important to note, that this entity can hold account status associations for two different types.   There are account statuses that are used for the Collections feature in the Student Accounts domain as well as account statuses that are utilized for the student's main ledger card account.  When configuring account statuses, there is a property that specifies how that account status will be used.  It can be configured to be used only for the Collections feature, only for the main ledger card or be used for both.  The entity that stores the account statuses that have been configured is AccountStatus.
+
+To see the account statuses that have been configured, execute an odata query as follows:   ds/odata/AccountStatuses?$select=Id,Code,Name,IsActive,CampusGroupId,Usage
+
+The IsActive property specifies if the record is active.  If this value is 0, then the account status is inactive and not able to be assigned to a student.  The Usage property specifies the type of account status.  As mentioned above, if the value is 'C', then it is used exclusively for the Collections feature.  If this is the case, then this status cannot be associated with a student via the updateStudentAccountStatus endpoint outlined below.   If the value is 'A' (used for main ledger card account status) or 'B' (used for both) then the account status can be assigned via the endpoint below.
+
+## API endpoint
+
+The API to use for managing account statuses associated to an enrollment is api/commands/StudentAccounts/StudentAccountTransaction/updateStudentAccountStatus .  
+
+To access the Swagger documentation, append 'swagger' to the end of the base URI that is used to launch the Anthology Student web client application.  Once the Swagger landing page is loaded, use the Domain and Functional Area dropdown filters at the top of the swagger page to access the documentation.  To access this API endpoint, select 'Student Accounts' for Domain and 'Ledger Card' for Functional Area and then select Refresh.  Find the StudentAccountTransaction entity in the displayed list of entities and then click the lightning bolt icon.  The list of APIs for this entity will be displayed.  The api/commands/StudentAccountTransaction/updateStudentAccountStatus will be one of the endpoints in the displayed list.
+
+![AccountStatuses](/assets/img/AccountStatuses1.png) 
+
+
+Some important points regarding this API:
+
+The only two properties that need to be provided in the request payload are the StudentEnrollmentPeriodId and the StudentAccountStatusList.  The StudentAccountStatusList is defined as a List of type int.  Provide the AccountStatusId for each account status that will be associated with the student enrollment period.  The other properties defined in the request can be ignored.
+
+Account statuses are assigned at the StudentEnrollmentPeriod level and not the Student. So if a student has more than 1 enrollment period record, an initial step may need to be done to determine which enrollment period you need to associate the account status(es) to. See additional details below
+
+An enrollment period can have multiple account statuses associated.  The logic within this API will fully replace any account statuses that are currently associated with the provided StudentEnrollmentPeriodId with the AccountStatusIds specified in the StudentAccountStatusList property. So if a student enrollment already has one account status associated and an additional account status needs to be associated, make sure the StudentAccountStatusList property includes the Id of the existing account status already associated plus the Id of the new account status being associated.
+
+### Determining the StudentEnrollmentPeriodId
+
+If you do not have the correct value for the StudentEnrollmentPeriodId property, then this can be determined using one of two approaches.  The prerequisite to using either of these approaches is that you must have the StudentId of the student that the account statuses are being updated for.  The first approach is to use an available API endpoint that will take the StudentId as an input parameter and return the StudentEnrollmentPeriodId of the "current" enrollment.  Anthology Student has built in logic that uses the school status and enrollment date for enrollment period records for a student to determine the "current" enrollment.  This option works well if it is uncommon for a student to have more than one enrollment record that has an Active school status at any given point in time.  The endpoint that returns the current enrollment is ds/campusnexus/Students/CampusNexus.GetCurrentEnrollmentByStudentId. To find this in Swagger, select 'Common' as the Domain and 'Students' as the Functional Area and then click Refresh.
+
+![AccountStatuses](/assets/img/AccountStatuses2.png) 
+
+If concurrently active enrollment records is a common scenario at an institution, then it is recommended to use the second approach which is to execute an OData query to return the enrollment records for a given StudentId.  Additional logic must be applied on the result set returned to determine which StudentEnrollmentPeriodId to associate the Account Statuses to.   This logic will depend on the requirements of the institution on what criteria/rules are in place for knowing which enrollment record is the correct enrollment to associate the account statuses to.  The basic odata query to execute for returning enrollment records for a student is ds/odata/StudentEnrollmentPeriods?$filter=StudentId eq #######&$select=Id,SchoolStatusId,EnrollmentDate,ProgramVersionName&$expand=SchoolStatus($select=Code)  where ######## is the StudentId of the student.  The specific data to return via the $select clause will depend on what data from the StudentEnrollmentPeriod entity needs to be evaluated in order to determine the correct StudentEnrollmentperiodId to associate the account statuses to.
+
+## Authorization
+
+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. You must have access to the Security Console application in order to set the needed permissions. In order to execute the updateStudentAccountStatus API, the user must be authorized for the Student Accounts - Student Account Transaction - Edit task.
+
+![AccountStatuses](/assets/img/AccountStatuses3.png) 
+
+## Conclusion
+
+There can likely be additional nuances/details around utilizing this API that are not covered within this document. If there are any questions after reviewing this document, you can submit them by sending an email to developers@anthology.com.

docs/student/best-practices/ManageCustomFields.md

@@ -18,9 +18,10 @@ The original implementation of custom fields in Anthology Student is referred to
 There is no API that has a single responsibility of managing data for School Defined Fields. The endpoints you will need to use for updating data for School Defined Fields are api/commands/Common/Student/SaveNew and api/commands/Common/Student/Save. The SaveNew operation is used when creating a new student record and the Save operation is used when updating an existing Student record. For additioal details on using the Save and SaveNew operations please refer to:
 
 [Tips for using Get and Save API Operations](https://docs.anthology.com/docs/student/best-practices/get-save-bestpractices)
+
 [Tips for using Create and SaveNew API Operations](https://docs.anthology.com/docs/student/best-practices/create-savenew-bestpractices)
 
-The vast majority of use cases will be to update school defined fields data for an existing student. The remainder of this section will use the Save operation as an example. The first step will be to retrieve the instance of the Student record that school defined fields data is being update for. Execute the api/commands/Common/Student/Get operation. Existing data for the school defined fields for the student will be in the CustomProperties and/or MultiValueCustomProperties properties in the response. If a school defined field has been configured to allow multiple values to be specified, then the values for this school defined field will be contained in the MultiValueCustomProperties property. For single value custom properties (majority of school defined fields), the data will reside in the CustomProperties property. These properties are defined as a collection of key/value pairs. The only difference is that the value for the MultiValueCustomProperties is of type ICollection`<string>` whereas the value type for the CustomProperties collection is string. The key contains the Code value for the configured school defined field. This value must match exactly to the Code value for the school defined field in order to be correctly updated (see screenshot below).
+The vast majority of use cases will be to update school defined fields data for an existing student. The remainder of this section will use the Save operation as an example. The first step will be to retrieve the instance of the Student record that school defined fields data is being updated for. Execute the api/commands/Common/Student/Get operation. Existing data for the school defined fields for the student will be in the CustomProperties and/or MultiValueCustomProperties properties in the response. If a school defined field has been configured to allow multiple values to be specified, then the values for this school defined field will be contained in the MultiValueCustomProperties property. For single value custom properties (majority of school defined fields), the data will reside in the CustomProperties property. These properties are defined as a collection of key/value pairs. The only difference is that the value for the MultiValueCustomProperties is of type ICollection`<string>` whereas the value type for the CustomProperties collection is string. The key contains the Code value for the configured school defined field. This value must match exactly to the Code value for the school defined field in order to be correctly updated (see screenshot below).
 
 ![ManageCustomFields](/assets/img/ManageCustomFields2.png)
 
@@ -85,7 +86,7 @@ There is no need to specify if the value for the extended property is being prov
 
 ### Retrieving Data
 
-Extended property values are all stored in a entity called ExtendedPropertyValues. Unless there is a need to retrieve extended property data for multiple entities in one query, it is not recommended to use this entity for data retrieval. Instead, there is a database view created for each entity that is enabled to support extended properties. The entity name in the query model for each of these views is ##########ExtendedProperties where ######### is the name of the entity. For example, the db view entity name for extended property values for the AreaOfStudy entity is AreaOfStudyExtendedProperties. A navigation property called ExtendedProperties will exist on every entity enabled to support extended properties. This allows for you to easily add filter conditions as well as include extended property values in any query where the base entity is an entity that is enabled to support extended properties. For example, to retrieve extended property values for all rows in the ClassSections entity, the odata query would look like this: ds/odata/ClassSections?$expand=ExtendedProperties
+Extended property values are all stored in an entity called ExtendedPropertyValues. Unless there is a need to retrieve extended property data for multiple entities in one query, it is not recommended to use this entity for data retrieval. Instead, there is a database view created for each entity that is enabled to support extended properties. The entity name in the query model for each of these views is ##########ExtendedProperties where ######### is the name of the entity. For example, the db view entity name for extended property values for the AreaOfStudy entity is AreaOfStudyExtendedProperties. A navigation property called ExtendedProperties will exist on every entity enabled to support extended properties. This allows for you to easily add filter conditions as well as include extended property values in any query where the base entity is an entity that is enabled to support extended properties. For example, to retrieve extended property values for all rows in the ClassSections entity, the odata query would look like this: ds/odata/ClassSections?$expand=ExtendedProperties
 
 ## Authorization