Element451Integrations Guide

Colleague - Extending Ethos

Updated Article

Explanation#

In some cases, delivered Ethos endpoints do not include all fields or entities required for integration.

If a required field or entity is included in the partner’s scope of work (SOW), Element451 can support reading or writing that data. However, the field must first be made available through an Ethos extension.

There are two types of extensions:

  • Delivered Entity Extension: Used when the field exists on a standard Colleague screen or entity
  • Custom Entity Extension: Used when the data exists on a custom screen or entity

Delivered Entity Extension#

Use this approach when extending an existing Ethos endpoint.

Selecting the Correct Endpoint#

Choose the endpoint based on where the data exists in Colleague:

  • Person-level data → /api/persons
  • Application data → /api/admission-applications
  • School-specific data → /api/person-external-education
  • Other endpoints as applicable

Setup Steps#

  1. In Colleague, navigate to EAEE
  2. At the lookup prompt, enter the resource name (e.g., persons, admission-applications)
    • If the resource does not exist, select Add
  3. Navigate to EAEV and configure:
    • Description: Extend Element451 integration
    • Version Number: Leave blank (or leave at default value, do not increment)
    • Version Status: R (Released)
  4. Add fields:
    • Colleague Data Element Name: Field name in Colleague
    • Type: Auto-populated
    • Property Name: Auto-generated
    • Path: /
    • Read Only: Set to No if the field should be writable
  5. Save all changes

Custom Entity#

Use this approach when exposing a custom Colleague entity through Ethos.

Setup Steps#

  1. In Colleague, navigate to EAPI
  2. At the lookup prompt, enter the new resource name
    • Use dashes instead of periods
    • Example: XNC.PERSON → xnc-person
  3. Configure the resource:
    • Primary Entity: Custom entity name (with periods)
    • GUID Source/Key: Primary key of the entity
    • Methods:
      • GET (required)
      • Add POST and PUT if updates are needed
  4. Navigate to EAEV and configure:
    • Description: Extend Element451 integration
    • Version Number: 1 (do not change)
    • Version Status: R (Released)
  5. Add fields:
    • Colleague Data Element Name: Field name
    • Type: Auto-populated
    • Property Name: Auto-generated
    • Path: /
    • Read Only: Set to No if writable
  6. Save all changes

Additional Configuration#

  1. Navigate to RFGU:
    • Enter the custom entity name
    • Set the ID/key field
    • Enter the resource name created in EAPI
    • Save
  2. Run GNGU for the custom entity
  3. In Ethos Integration:
    • Navigate to Applications
    • Select your Colleague Web API
    • Open Owned Resources
    • Add the custom resource
  4. Make the resource available:
    • Recycle the application pool cache, or
    • Wait for the system to refresh

Examples#

Delivered Entity Extension#

Use Case: admission-applications#

Extending /api/admission-applications to include:

  • Student Type (APPL.STUDENT.TYPE)

Steps

  1. In Colleague, navigate to EAEE
  2. Enter “admission-applications”
    • Add if it does not exist
  3. Navigate to EAEV and configure:
    • Description: Extend Element451 integration
    • Version Number: Leave blank
    • Version Status: R (Released)
  4. Add the following field:
    • APPL.STUDENT.TYPE
  5. Verify:
    • Property names are generated correctly (camelCase, no spaces)
    • Read Only = No
    • Path = /
  6. Save all changes

Element451 Configuration

In Element451, corresponding configuration is required:

  • Create a custom field (e.g., Colleague Student Type)
  • Create a data source for values (e.g., Colleague Student Types)

The data source values should align with the values defined in Colleague.

Use Case: person-external-education#

Extending /api/person-external-education to include:

  • Graduation Type
  • Years Attended

Steps

  1. In Colleague, navigate to EAEE
  2. Enter “person-external-education”
    • Add if it does not exist
  3. Navigate to EAEV and configure:
    • Description: Extend Element451 integration
    • Version Number: Leave blank
    • Version Status: R (Released)
  4. Add the following fields:
    • INSTA.YEAR.ATTEND.START
    • INSTA.YEAR.ATTEND.END
    • INSTA.GRAD.TYPE
  5. Verify:
    • Property names are generated correctly (camelCase, no spaces)
    • Read Only = No
    • Path = /
  6. Save all changes

Element451 Configuration

In Element451, corresponding configuration is required:

  • Create a custom field
  • Create a data source for values (e.g., Graduation Type)

These should align with the values defined in Colleague.