This document describes how Housing.Cloud can push Occupancies (a.k.a. Housing Assignments) to Ethos. It is expected that the Institution executed the proper due diligence to determine that the Ellucian Ethos API Models can satisfy their Institution specific Business requirements. 

Banner Customers, please see additional information below the Housing Assignment content.

API Details:

• Endpoint: /housing-assignments
  • Version: application/vnd.hedtech.integration.v16+json
• Required HTTP Methods: POST, PUT, and GET

Housing Assignments Data Model:

Understanding Statuses:

The integration framework will derive on of the four Ethos statuses (assigned, prorated, canceled, and terminated) based on the Housing.Cloud status and the context in which the Occupancy was created/ended.  Housing.Cloud has no control over the quantity of Ethos statuses.

It is the responsibility of the Institution to map the Ethos statuses to Colleague/Banner statuses and Special Billing Processes.

Default Status Logic:

• assigned: The Occupancy was created normally, with a standard context
• prorated: The Occupancy was created normally, but an Admin prorated the Transaction associated with the Occupancy creation
• canceled: The Occupancy was ended normally, via the standard Cancellation Flow in Housing.Cloud
  • If the Housing.Cloud Occupancy has the status Cancelled, then the Ethos status canceled will be utilized
• terminated: The Occupancy was end normally, via the Room Transfer or Swap Residency Flow in Housing.Cloud or marked explicitly marked as an Early Termination during the Cancellation Flow
  • If the Housing.Cloud Occupancy has the status Transferred or Early Termination, then the Ethos status terminated will be utilized

Custom Status Logic:

Housing.Cloud has the ability to customize how Housing.Cloud statuses are mapped to the Ethos statuses. The override logic is static and cannot change based on context.

• Example: All Occupancies with the Transferred Housing.Cloud Status will utilize the canceled Ethos status, instead of the default status: terminated

Configuring Ethos Statuses to Banner/Colleague Statuses:

• Colleague configuration page: VTHM
• Banner configuration page: SLRMSCD

Room Rates Derivation Logic:

The Room Rate GUID and Room Rate Period is derived by the following steps:

1. For the Occupancy in question, the Bed Type in Housing.Cloud is obtained and the External Room Rate Code is parsed from the object
2. Housing.Cloud then polls the room-rates Ethos API endpoint (No query arguments are supported for the room-rates endpoint for the code value)
   1. For each response batch, Housing.Cloud attempts to match all of the following:
      1. The External Room Rate Code in Housing.Cloud to the Room Rates code value
      2. Subsequent logic is dependent on the SIS:
         1. Banner: The Cycle's External Id in Housing.Cloud to the Room Rate Academic Period Id
         2. Colleague: The Room Rate with the latest active startOn date that is less than or equal to the Occupancy Start Date
   2. Once those two criteria are met, the Room Rate GUID is parsed out and we derive the Rate Period by using the following logic:
      1. If there is one valid Rate Period included in the Room Rate, then that period is utilized
      2. If there are multiple valid Rate Periods included in the Room Rate, then Housing.Cloud defaults to the term rate period

Configurations:

These values can be set in the Integration Configuration Data Mappings object.

• roomRatesRequired: If TRUE, the roomRates and ratePeriod attributes will be included in the POST payload
  • Note: This is required for institutions that utilize the Billing features within Colleague/Banner 

Banner Customers

During the Housing Assignment creation process, Banner requires an additional API call made to the Housing Requests endpoint.

Banner Configuration:

• HEDM.ROOM.PERMIT.OVERRIDE setting in GORICCR must be set to: Y

   

API Details:

• Endpoint: /housing-requests
  • Version: application/vnd.hedtech.integration.v10+json
• Required HTTP Methods: POSTand GET

Banner Table:

• SLBRMAP

Housing Requests Data Model:

This additional API request is only required for Banner