Overview
Connect data from Element451 to Colleague via the Ellucian Ethos API. Managed integrations from Element451 are customized to your institution's specific needs and maintained by the Element451 team.
Integration Mechanism: REST API
Direction: Bi-directional
Sync Delay: 1-5 minutes
Trigger Type: Manual or Automated
Data Format: JSON
Authentication Method: Bearer Auth Token
Element → Colleague Sync
The sync from Element to Colleague is an independent function within the integration that creates or updates applicant data in Colleague when triggered from Element451.
Triggering the Sync
The Element → Colleague sync can be triggered manually by default and can also be configured to automatically trigger.
Manual Sync
Manual Sync
Add the "Element451 - Trigger Integration Sync" label to any profile to trigger the sync. The label triggers a "Element451 → Ethos Integration Sync" Rule, which runs an "Execute Webhook" step and initializes the sync.
Automatic Sync
Automatic Sync
To automate the sync, consider adding additional triggers to the "Element451 → Ethos Integration Sync" Rule.
A common example is adding a "Decision Released" trigger that will automatically sync applicants to Colleague when their Decision in Element451 is released.
Sync Sequence
Sync Sequence
Webhook initializes the sync.
Contact data is exported, including contact information, demographic data, applications, previous education, relationships, emergency contacts, and citizenship data.
Data is transformed to values compatible with Colleague.
A person matching request is made to Colleague to identify if the contact exists in the System.
If the contact does not exist, a new person is created.
If the contact does exist, the person is identified.
Additional person data is sent to Colleague.
Address data is sent to Colleague.
Visa/Citizenship data is sent to Colleague.
Relative / Family member data is sent to Colleague.
If a family contact does not exist, a new person is created.
If a family contact does exist, the person is identified.
A relationship is created between the applicant and the family member.
Application data is sent to Colleague.
External education data is sent to Colleague.
Emergency contact data is sent to Colleague.
Field Mapping
Below, we provide a list of fields exported from Element and their matching field in Colleague.
View the List
View the List
Element Slug | Colleague Field | Colleague Mnemonic |
user-elementid | PERSON.ALT.IDS | DADD |
user-first-name | FIRST.NAME | NAE |
user-last-name | LAST.NAME | NAE |
user-middle-name | MIDDLE.NAME | NAE |
user-former-last-name | (name type) NAME.HISTORY.LAST.NAME | BIO |
user-preferred-name | (name type) PREFERRED.NAME | BIO |
user-prefix-name | PREFIX | BIO |
user-suffix-name | SUFFIX | BIO |
user-email-address | PERSON.EMAIL.ADDRESSES | NAE |
user-identities-school-email | PERSON.EMAIL.ADDRESSES | NAE |
user-ssn | SSN | NAE |
user-dob | BIRTHDATE | NAE |
user-gender | GENDER | NAE |
user-citizenship-us-statuses | citizenshipStatus | FPER |
user-race-hispanic | PERSON.ETHNNICS | BIO |
user-race-categories | PER.RACES | BIO |
user-citizenship-country | FPER.BIRTH.COUNTRY | FPER |
user-citizenship-country-of-birth |
|
|
user-addresses-type |
| ADR |
user-addresses-street1 | ADDRESS.LINES<1,1> | ADR |
user-addresses-street2 | ADDRESS.LINES<1,2> | ADR |
user-addresses-street3 | ADDRESS.LINES<1,3> | ADR |
user-addresses-city | CITY | ADR |
user-addresses-state | STATE | ADR |
user-addresses-province | STATE | ADR |
user-addresses-zip | ZIP | ADR |
user-addresses-country | COUNTRY | ADR |
user-addresses-home-mailing |
| ADR |
user-phone-home-country-code |
| NAE |
user-phone-home-number |
| NAE |
user-phone-cell-country-code |
| NAE |
user-phone-cell-number |
| NAE |
user-family-relationship |
| REL |
user-family-email | PERSON.EMAIL.ADDRESSES | NAE |
user-family-first-name | FIRST.NAME | NAE |
user-family-last-name | LAST.NAME | NAE |
user-family-middle-name | MIDDLE.NAME | NAE |
user-family-gender | GENDER | NAE |
user-family-phone-number |
| NAE |
user-family-phone-country-code |
| NAE |
user-family-phone-type |
| NAE |
user-family-address-street-1 | ADDRESS.LINES<1,1> | ADR |
user-family-address-street-2 | ADDRESS.LINES<1,2> | ADR |
user-family-address-city | CITY | ADR |
user-family-address-state | STATE | ADR |
user-family-address-zipcode | ZIP | ADR |
user-family-address-country | COUNTRY | ADR |
user-family-address-province | STATE | ADR |
user-applications-status | APPL.STATUS (derived from CDAM) | APPN |
user-applications-submitted-time |
| APPN |
user-applications-major | APPL.ACAD.PROGRAM | APPN |
user-applications-term | APPL.START.TERM | APPN |
user-applications-degree |
| APPN |
user-applications-campus |
| APPN |
user-applications-student-type |
| APPN |
user-applications-board-status |
|
|
user-applications-decision-released-at |
|
|
user-education-academic-load |
|
|
user-education-schools-ceeb | Used to look up Institution Attended | IASU |
user-education-schools-gpa | INSTA.EXT.GPA | IASU |
user-education-schools-start | INSTA.START.DATES | IASU |
user-education-schools-end | INSTA.END.DATES | IASU |
user-education-schools-graduate-date | INSTA.INTG.HS.GRAD.DATE | IASU |
user-citizenship-visa-type | VISA.TYPE | FPER |
📌 Note: Managed integrations are configurable. Additional custom fields in Element or additional resources in Ethos may be included in your institution's integration. Contact Element451 support for more information.
Colleague → Element Sync
The sync from Colleague to Element is an independent function within the integration that creates or updates student and application data within Element451 based on data from Colleague.
Triggering the Sync
The Colleague → Element sync relies on "change notifications" from Ethos, which denote that a change was made to an applicant's data in Colleague. The managed integration reads these notifications every five minutes and updates the applicant's data in Element accordingly.
Ensure that the Element451 Ethos "application" is subscribed to notifications from the persons, addresses, and admission-applications resources in order for change notifications to be received. Remove the subscriptions to disable the Colleague → Element sync.
Sync Sequence
Sync Sequence
Change notification is added to the consume resource.
The managed integration reads the consume resource every five minutes.
Change notification for an applicant is read.
Applicant data is requested from Colleague, including person data, application data, aptitude assessments , addresses, and previous education.
Data is transformed to values compatible with Element451.
Person data is imported to Element.
Application data is imported to Element.
Address data is imported to Element.
Aptitude assessment data (evaluations) is imported into Element.
Previous education data (schools) is imported into Element.
Data Source Sync
Translating data values between Element451 and Colleague is essential for the integration. Translations are managed by syncing Colleague validation table values to Data Sources in Element. This sync is an independent function within the integration.
Sync Schedule
By default, academic-periods (Terms), academic-programs (Majors), and academic-credentials (Degrees) sync every Saturday.
Refreshes of these or other data sources can be requested via Element live support.
Adding New Data Source Values
New values for data sources should always be added in Colleague first.
Update the validation table and then wait for the sync to run.
Once a data source has synced with Colleague, it should not be edited in Element (exceptions apply; ask Element support when in doubt).
Translation Tables
In addition to updating data sources within Element451, the managed integration also maintains "translation tables" behind the scenes.
These tables are directly responsible for the translation between Element and Colleague data values.
If a value is not in the table, it will not be translated properly.
Translation tables are only accessible to Element451 support and will be updated with the data source sync or upon request.
Additional Info + Troubleshooting
Additional information about configuring Ethos can be found in the Integration Guide: https://integrations.element451.com/ellucian-ethos-142
Troubleshooting Common Errors
Errors during Element → Colleague
Errors during Element → Colleague
“Person emergency contacts with ID ... and contact name of ... already exists"
“Person emergency contacts with ID ... and contact name of ... already exists"
{
"type": "<class 'ethos_integration.ethos_api.ethos_api.APIException'>",
"status_code": "400",
"content": {
"errors": [
{
"id": "00000000-0000-0000-0000-000000000000",
"code": "Create.Update.Exception",
"description": "Error occurred in the source system that prevented update or creation of the record.",
"message": "Person.Emergency.Contacts.Contact.Name - Person emergency contacts with ID 'xxxxxxx' and contact name of name already exists. Duplicate contact name is not allowed."
}
]
}
}
Origin: Colleague / Ethos
Description:
This means that the Emergency Contact already exists as a person in Colleague.
Resolution Steps:
Review the NAE to verify. Edit or disregard.
"Person record locked for ID ..."
"Person record locked for ID ..."
{
"type": "<class 'shared_resources.exceptions.APIException'>",
"status_code": "400",
"content": {
"errors": [
{
"code": "Validation.Exception",
"description": "An error occurred attempting to validate data.",
"message": "PersonExternalEducation.Record.Lock: PERSON record locked for ID xxxxxxx"
}
]
}
}
Origin: Colleague / Ethos
Description:
This means someone is in the record in Colleague.
Resolution Steps:
Close the record in Colleague and re-sync
"Person with ID ... is already enrolled in the requested program ..."
"Person with ID ... is already enrolled in the requested program ..."
{
"errors": [
{
"code": "admissionApplication",
"description": "Unknown error code.",
"message": "Person with ID 'xxxxx' is already enrolled in the requested program 'xxxxx'."
}
]
}
Origin: Colleague / Ethos
Description:
This error occurs when attempting to create a new application for the student when syncing Element451→Ethos. If the student is enrolled for the same program, Ethos throws the error.
Resolution Steps:
Close the program for that student in SACP (Colleague) by adding an end date.
reviewRequired
reviewRequired
{
"outcomes": [
{
"type": "initial",
"status": "reviewRequired",
"date": "2025-01-15T11:27:40"
}
],
"originator": "ETHOS",
"id": "xxx-xxxx-xxxx -xxxx-xxxx"
}
Origin: Colleague / Ethos
Description:
A potential duplicate was found in the SIS when attempting to sync from Element.
Resolution Steps:
Review the match on PEMR
Resolve the duplicate
Resync from Element
Relative review required
Relative review required
Origin: Colleague / Ethos
Description:
A potential duplicate was found when attempting to sync a person’s relatives.
Resolution Steps:
Review the match on REL
Resolve the duplicate
Resync from Element
Skipping Invalid Address
Skipping Invalid Address
Skipping invalid address: {
"ethos_id": "",
"type": "home",
"street1": "*** Street Name Ave",
"street2": "",
"street3": "",
"city": "Some City",
"state": "ST",
"province": "",
"zip": "12345",
"country": "",
"is_home_mailing": "",
"county": "" //country is missing in this example
}
Origin: Element451
Description:
The student is missing required data on their Element profile. Ensure the following are present:
Street 1
City
State
Zip
Country
Resolution Steps:
Navigate to student’s Element profile.
Edit Address, ensure all data items are present, save
Resync from Element
'{State Name}' is not defined as a state or province.
'{State Name}' is not defined as a state or province.
{
"type": "<class 'shared_resources.exceptions.APIException'>",
"status_code": 400,
"content": {
"errors": [
{
"id": "176684ff-6cce-4473-ac9b-caa912220a9e", //address identifier
"sourceId": "0862595",
"code": "persons.addresses",
"description": "Unknown error code.",
"message": "'North Carolina' is not defined as a state or province. (Parameter 'addressDto.place.region')" //North Carolina example shown, but State Name may vary
}
]
},
"args": [
"Status code: 400\nContent:\n{\n \"errors\": [\n {\n \"id\": \"176684ff-6cce-4473-ac9b-caa912220a9e\",\n \"sourceId\": \"0862595\",\n \"code\": \"persons.addresses\",\n \"description\": \"Unknown error code.\",\n \"message\": \"'North Carolina' is not defined as a state or province. (Parameter 'addressDto.place.region')\"\n }\n ]\n}"
]
}
Origin: Colleague / Ethos
Description:
The student has bad data on their Element profile. Address has State name instead of State abbreviation. In the case of North Carolina, State should be “NC”.
Resolution Steps:
Navigate to student’s Element profile.
Edit Address, select correct State from dropdown menu, save
Resync from Element
There is no CEEB for the institution
There is no CEEB for the institution
Summary 1: There is no ceeb for the institution. Ensure an institution with CEEB code 1234 is listed on INST in Colleague. If no institution, please create one and notify Element451 support to resync with Colleague.
Full Error 1:
{
"institution_id": "",
"ceeb": "1234"
"type": "highschool",
"entry_type": "highschool",
"gpa": "",
"start": "",
"end": "",
"graduate_date": "2017-04-17",
"institution_country": ""
}
Origin: Colleague / Ethos
Description:
The student selected a prior education institution in Element451 that does not have a match on INST in Colleague.
Resolution Steps:
Create an entry for the institution on INST
Notify the Element451 team via live support to resync with the SIS to pick up new institutions.
Error during Colleague → Element
Error during Colleague → Element
"code": "GUID.Not.Found", "description": "An error occurred translating the GUID to an ID.", "message": "No Guid found, Entity:'OTHER.CCDS', Record ID:'??"
"code": "GUID.Not.Found", "description": "An error occurred translating the GUID to an ID.", "message": "No Guid found, Entity:'OTHER.CCDS', Record ID:'??"
Method: GET
Endpoint: /api/student-academic-programs/aea41913-f795-42d1-80c0-557a0fc25281
Response: {
"errors": [
{
"id": "aea913-f75-42d1-80c00-557a0f5281",
"sourceId": "1396903*{{some_program_code}}",
"code": "GUID.Not.Found",
"description": "An error occurred translating the GUID to an ID.",
"message": "No Guid found, Entity:'OTHER.CCDS',
Record ID:'{{some_record_id}}'"
}
]
}
Origin: Colleague / Ethos
Description
When syncing to Ethos, the managed integration attempts to extract data about the academic program the student has applied to. This error indicates that program data found in the OTHER.CCDS table cannot be found by that GUID.
This error only applies to application data. Other data, such as person, address and emergency contact, should still sync.
Resolution Steps:
Run GNGU on OTHER.CCDS. This will create the GUID association and allow the request to the student-academic-programs resource to return data without error.