Element451Integrations Guide

Integration Errors - Troubleshooting (Ethos)

Updated Article

Explanation#

Use this page as your first step when troubleshooting errors in the Integration Log during syncs between Element451 and Ethos.

General Errors#

DOB Does Not Match

Description

This error occurs when the birthdate in Element451 does not match the birthdate in the SIS.

  • This behavior is controlled by a configuration option set during implementation

Resolution

  • Update the birthdate in either Element451 or the SIS so that both systems match
  • Re-sync the record by removing the “Element451 - Ethos Match Error” label off the record (this will auto re-sync the record)
  • Alternatively, contact Element support to disable this validation if desired

More Than One Possible Match (reviewRequired)

Description

The SIS matching process identified multiple possible matches for the record and cannot determine which one to use.

The integration is paused until a match is resolved.

Resolution – Banner

  1. Open GOAMTCH in Banner
  2. Review the potential matches
  • If a correct match exists:
    • Copy the Banner ID
    • In Element451:
      • Open the record (with label Element451 - Ethos Match Error)
      • Add the Banner ID to the School ID field in the Identities card
      • Remove the Element451 - Ethos Match Error label
  • If no match is correct:
    • Create a new record in SPAIDEN (minimum required data)
    • Copy the new Banner ID
    • In Element451:
      • Add the Banner ID to the School ID field
      • Remove the Element451 - Ethos Match Error label

The integration will automatically retry. No additional trigger is required.

Resolution – Colleague

  1. Open PEMR in Colleague
  2. Review the potential matches
  • If a correct match exists:
    • Copy the Colleague ID
    • In Element451:
      • Open the record (with label Element451 - Ethos Match Error)
      • Add the Colleague ID to the School ID field in the Identities card
      • Remove the Element451 - Ethos Match Error label
  • If no match is correct:
    • Create a new record in NAE (minimum required data)
    • Copy the new Colleague ID
    • In Element451:
      • Add the Colleague ID to the School ID field
      • Remove the Element451 - Ethos Match Error label

The integration will automatically retry. No additional trigger is required.

Name or DOB Does Not Match

Description

This error occurs when the name and/or date of birth in Element451 does not match the corresponding record in the SIS.

  • This behavior is controlled by a configuration option set during implementation

Resolution

  • Update the data in either Element451 or the SIS so that both systems match
  • Re-sync the record by removing the “Element451 - Ethos Match Error” label off the record (this will auto re-sync the record)
  • Alternatively, contact Element support to disable this validation if desired

Cannot Access Protected Field in the Persons Resource

Description

Some Banner fields (such as SSN) are protected and require explicit API access.

If access is not granted, Ethos cannot read or write to these fields.

Resolution

This is typically a configuration issue.

  • In Banner, go to GORDMSK
  • For the following objects:
    • API_PERSONS
    • API_PERSON_CREDENTIALS
  • Ensure the Visible box is checked

See Banner Configuration (Step 4.8) for more details.

Curriculum Requires College, Level, Degree, Priority, and Term

Description

This error occurs when required curriculum fields are missing or not properly configured.

See Ellucian KB000509909 for additional details.

Resolution

  • In Banner, go to SOACTRL
  • Under the Institutional Defaults tab:
    • Set Default Priority Number = 1

See Banner Configuration (Step 4.10).

Curriculum Invalid

Description

The selected program/major combination is not valid based on Banner configuration (SOACURR).

During implementation, Element451 syncs multiple combinations of:

  • Program
  • Major
  • Concentration / minor

If an invalid combination is active in Element451, Banner will reject it.

Resolution

  • Review the Majors data source in Element451
  • Ensure only valid combinations (per SOACURR) are active
  • Update the student’s application to use a valid major

For more details, see the Banner Majors documentation.

Degree Not Found

Description

This error indicates a missing or invalid default degree value in Banner.

See Ellucian PD0018084.

Resolution

  • In Banner, go to STVDEGC
  • Ensure a default value of 0000 is configured

Important: The value must be exactly 0000.

See Banner Configuration (Step 4.2).

Property [classRank] of class [class net.hedtech.banner.student.overall.PersonRelatedHighSchoolBase] with value [-1] is less than minimum value [1]

Error Example

Property [classRank] ... value [-1] is less than minimum value [1]

Description

The class rank value stored in Banner is outside the allowed range.

Resolution

  • In Banner, go to SOAHSCH
  • Update the class rank to a valid value

There is no ceeb for the institution. Ensure an institution with CEEB code ‘xxxx’ is listed on STVSBGI in Colleague. If no institution, please create one and notify Element451 support to resync with Banner

Description

The selected previous school in Element451 does not have a matching CEEB entry in Banner.

Resolution

  • In Banner, go to STVSBGI
  • Create a new institution entry with the required CEEB code
  • After creating the institution:
    • Contact Element451 support via Live Support
    • Request a data resync to load the new institution

Updates to a Transfer Institution Are Not Supported

Description

The previous school has already been transcripted in Banner.

Once transcripted, Banner does not allow updates to that institution record via Ethos.

Resolution

  • No action is required for this error

This error does not prevent the rest of the record from syncing successfully.

Colleague Errors#

Address type ‘xxxx’ for address record ID '#######' is not valid

Description

This error is caused by an Ethos defect related to address type handling.

See Ellucian PD0025342.

Resolution

  • Install the patch referenced in PD0025342, or
  • Enable the DAS Data Reader for the API site

An email type cannot be duplicated for ‘xxxxx’, type ‘xxxx’

Description

An Ethos email type is mapped to more than one Colleague email type.

Each Ethos (Data Model Value) must map to a single Colleague email type.

Resolution

  1. In Colleague, go to CDIP
  2. Navigate to:
    • Demographic Data (CDHP) → Email Types
  3. Review the Data Model Value mappings:
    • Ensure each Ethos value maps to only one Colleague email type

Note: Only email types with a Data Model Value are exposed to Ethos.

Emergency Contact cannot be null. It must be Yes or No for emergency contact name

Description

Before the integration will write an emergency contact, it first does a read of all emergency contacts associated with the student (to make sure it doesn’t already exist).  This error occurs when Element reads an existing emergency contact in Colleague and a required boolean field (Y/N) on an emergency contact record is blank (inside Colleague).

Ethos requires these fields to have a value when it does the read and without a value, Ethos errors preventing our code from being able to write anything.

Resolution

  • Option 1 (manual):
    • Go to EMPC
    • Update the field in error to be Y or N
  • Option 2 (bulk fix):
    • Identify affected records using:
plaintext
MIOSEL PERSON.EMER WITH (EMER.MISSING.CONTACT.FLAG = '' OR EMER.EMERGENCY.CONTACT.FLAG = '')
  • Update records to default values (Y/N) using another script/process.

Missing-Person Contact cannot be null. It must be Yes or No for emergency contact name

Description

Same root cause as Emergency Contact cannot be null. It must be Yes or No for emergency contact name.

Resolution

Follow the same steps outlined in that error.

Insufficient access rights to process CREATE.PERSON.MATCH.REQUEST

Description

This error occurs due to incorrect Colleague configuration when running person matching.

Resolution

Person with ID 'xxxxx' is already enrolled in the requested program 'xxxxx'

Description

The integration is attempting to create an application for a program where the student is already enrolled.

Resolution

  • In Colleague, go to SACP
  • Add an end date to the existing program
  • Ensure the end date is before the application term start date

Person.Emergency.Contacts.Contact.Name - Person emergency contacts with ID ‘xxxxxxx’ and contact name of name already exists. Duplicate contact name is not allowed

Description

The emergency contact already exists as a person in Colleague.

Resolution

  • Review the record in NAE
  • Update if needed, or
  • Ignore the error if no changes are required

Person.Invalid.Language - The language ISO code ‘xxx’ is not mapped in Colleague.

Description

The language value in Element451 is not mapped in Colleague.

Resolution

  1. In Colleague, go to CORE-VAL
    • Add the missing language
  2. Go to CDHP → Languages
    • Map the value appropriately

Record.Lock: PERSON record locked for ID ‘xxxxxxx’

Description

The record is currently open in Colleague and cannot be updated.

Resolution

Student program not found for: xxxxxxx*.xxxxxxx

Description

An invalid or broken reference exists for the student program.

Resolution

  • Varies by case
  • Contact Institutional IT or Ellucian Support

The educational institution ‘xxxxxxxxxx’ does not have a valid institution type

Description

An institution in Colleague is missing a valid type or is incorrectly configured.

Resolution

  1. In Colleague, go to FGUD
    • Lookup the Ethos GUID from the error
  2. Identify the institution and open it in INST
  3. Set a valid Institution Type

To identify all affected records:

plaintext
MIOSEL INSTITUTIONS WITH INST.TYPE EQ ''

Additional Check

  • In CORE-VAL → INST.TYPES:
    • Ensure the type includes H or C in Special Processing Field 1

The phone type of ‘xxxx’ cannot be used in this context. Only personal phone types are allowed

Description

The phone type is not configured as a valid personal phone type in Colleague.

Resolution

The site is required for the requested academic program ‘xxxx’

Description

The program requires a campus, but one was not provided or is invalid.

Resolution

  • Option 1:
    • Update PROG to remove the campus requirement
  • Option 2:
    • Ensure a valid campus is populated in Element451

There is no ceeb for the institution. Ensure an institution with CEEB code ‘xxxx’ is listed on INST in Colleague. If no institution, please create one and notify Element451 support to resync with Colleague

Description

The selected previous school does not exist in Colleague.

Resolution

  • In Colleague, go to INST
  • Create the institution with the required CEEB
  • Then:
    • Contact Element451 support
    • Request a data resync

Unable to find GUIDs for valcode records

Description

Ethos GUIDs are missing for one or more valcode values.

This is related to Ellucian defect PD0025342.

Resolution

  • Install the patch referenced in PD0025342, or
  • Enable the DAS Data Reader for the API site