Knowledge Base

Integrating Ellucian Ethos and Terminalfour

Last Modified:
30 Apr 2021
User Level:
Administrator

This outlines the steps to take to assist in the creation of an accessible site in Terminalfour. 

What is Ellucian Ethos?

Ellucian Ethos provides a cloud-based unified data model for Ellucian’s higher education solutions. This provides institutions with a single source of truth for all stakeholders which reduces overhead and prevents information silos. 

Universities and Colleges using Ellucian Ethos can benefit from quickly and securely integrate third-party solutions with the Ellucian investment, and build on top of a powerful and extensive API endpoint. 

You can find information about Ethos integration by creating an account and logging into the Ellucian Resources site.

Integrating Ethos with Terminalfour

Terminalfour brings integration with Ellucian Ethos so you can ensure that academic and student information published on your website or portal is the same for everyone in and outside your organization. Use cases include powering website course/degree search or people finder features or showing content from Ellucian solutions on a staff or student portal.

Diagram describing how Terminalfour can use Ellucian Ethos data

The integration described here is intentionally read-only and does not post data to Ethos.

In Terminalfour you can connect to Ellucian Ethos using the External Content Syncer. To do this first set up the Data Source. From version 8.3.9, Terminalfour ships with a native Ethos Connector. This driver is not compatible with older versions of Terminalfour.

You can add Ellucian Ethos as a Data Source when you are setting up the Content Syncer.

The fields are as follows:

Name

Provide a meaningful name for your Data Source

Username

This is not applicable here so you can leave it blank

Password/API Token

The API token provided by Ellucian Ethos so Terminalfour can integrate with it. 

URL

https://integrate.elluciancloud.com/

This is used to connect to Ethos. The authentication appends "/auth/" to the URL to get the JWT Token.

Driver

<com.terminalfour.database.t4ethosjdbc.core.JDBC

This is the name of the driver used to connect to Ethos.

Screen showing set up of an Ellucian Ethos data source

In Content > Integration Tools > External Content Syncer select Add new data store:

Screen identifying the new data store option

If you’ve used the External Content Syncer before many of these settings will be familiar however there are some differences. 

Have a look at the External Content Syncer configuration page for more information.

Many clients use the Content Syncer to fetch database results using SQL but when Ellucian Ethos is used as the Data Source the options to select a table or add SQL are replaced by other web services focused options:

Screen showing how to configure a data store for Ellucian Ethos

 

Web service query

This is the query used to return results from Ethos.

In this example:

api/courses?limit=10

In this case, ten courses will be returned.

The "api" part of the web service query is required.

Endpoint properties

application/vnd.hedtech.integration.v16+json

This is the accept header that passes the Ethos version number (in the example we’ve used version 16 is used). The data models vary between versions so you should confirm which version your instance is using, 

Fetch example data

Retrieves the data from the query so you can see the JSON object that’s returned. 

The resulting JSON object will be flattened to a key/value pair so the key can be mapped to a Content Element in the “Type Mapping” tab.

 

Some data model entities

All data models are supported by Terminalfour. Some examples of these are:

  • Courses

  • Course Topics

  • Course Title Types

  • Course Statuses

  • Course Levels

  • Course Categories

  • Academic Programs

  • Academic Catalogs

  • Academic Credentials

  • Academic Disciplines

  • Academic Honors

  • Academic Levels

Example Resource

The following is an example of the “Courses” resource:

{
        "id": "dcf79a45-b399-4ada-bfd4-bd797d3259b1",
        "titles": [
          {
            "type": {
              "id": "f40562c9-684e-42da-96ae-44316fed2aa3"
            },
            "value": "Math 101"
          },
          {
            "type": {
              "id": "5a1e2ac3-7f87-40c5-b435-39168b6e235d"
            },
            "value": "Engineering Mathematics 101"
          }
        ],
        "description": "Beginning mathematics",
        "subject": {
          "id": "25892e17-80f6-415f-9c65-7395632f0223"
        },
        "topic": {
          "id": "8599a236-958d-4710-97da-cafa9efd3b7e"
        },
        "categories": [
          {
            "id": "529493fa-c8f4-422f-a45e-4d5b26dd4c1b"
          },
          {
            "id": "be6ceea4-c2f8-4b41-a784-c8d7df8067ce"
          }
        ],
        "courseLevels": [
          {
            "id": "e33898de-6302-4756-8f0c-5f6c5218e02e"
          }
        ],
        "instructionalMethodDetails": [
          {
            "instructionalMethod": {
              "id": "3a768eea-cbda-4926-a82d-831cb89092aa"
            },
            "instructionalDeliveryMethod": {}
          }
        ],
        "hours": [
          {
            "administrativeInstructionalMethod": {
              "id": "d3680341-fd24-40f6-bdf0-76dca1316fb5"
            },
            "minimum": 3,
            "maximum": 9,
            "increment": 3,
            "interval": "day"
          }
        ],
        "owningInstitutionUnits": [
          {
            "institutionUnit": {
              "id": "61820135-a36b-4308-99f7-28697ab7a0b1"
            },
            "ownershipPercentage": 50
          },
          {
            "institutionUnit": {
              "id": "00cd9680-9090-4b38-92ce-7b72d50421ba"
            },
            "ownershipPercentage": 50
          }
        ],
        "schedulingStartOn": "2014-10-16",
        "schedulingEndOn": "2014-11-30",
        "number": "101",
        "academicLevels": [
          {
            "id": "11cdd494-de5b-460e-9ddf-4e84bad6f596"
          }
        ],
        "gradeSchemes": [
          {
            "gradeScheme": {
              "id": "fd3f06e5-84cd-4d2b-82df-406ae9c39650"
            },
            "usage": "default"
          },
          {
            "gradeScheme": {
              "id": "f14a648d-c757-4c7a-b283-1fa74e561d63"
            },
            "usage": ""
          }
        ],
        "credits": [
          {
            "creditCategory": {
              "creditType": "institution",
              "detail": {
                "id": "bd582974-7421-4502-8fd4-b3966e08923e"
              }
            },
            "measure": "credit",
            "minimum": 1,
            "maximum": 4,
            "increment": 1
          }
        ],
        "billing": {
          "minimum": 1,
          "maximum": 5,
          "increment": 1
        },
        "waitlistMultipleSections": "notAllowed",
        "reportingDetail": {
          "type": "nebraska",
          "courseWeight": 10
        },
        "administrativePeriod": {
          "id": "060d0dd1-75aa-4c43-989c-0015b6f01d6e"
        },
        "status": {
          "id": "ed348068-d0ff-4aa8-bb13-acf8c165b354"
        },
        "additionalClassifications": [
          {
            "cipCode": {
              "id": "8814cd44-8dd2-4825-8ce9-6ce50c9e91e2"
            }
          }
        ]
      }

This is the flattened key/value pair that is output by the “Fetch example data” button and can be used map to Content Elements:

Key (Column name)

Value

id

dcf79a45-b399-4ada-bfd4-bd797d3259b1

titles[0].type.id

f40562c9-684e-42da-96ae-44316fed2aa3

titles[0].value

Math 101

titles[1].type.id

5a1e2ac3-7f87-40c5-b435-39168b6e235d

titles[1].value

Engineering Mathematics 101

description

Beginning mathematics

subject.id

25892e17-80f6-415f-9c65-7395632f0223

topic.id

8599a236-958d-4710-97da-cafa9efd3b7e

categories[0].id

529493fa-c8f4-422f-a45e-4d5b26dd4c1b

categories[1].id

be6ceea4-c2f8-4b41-a784-c8d7df8067ce

courseLevels[0].id

e33898de-6302-4756-8f0c-5f6c5218e02e

instructionalMethodDetails[0].instructionalMethod.id

3a768eea-cbda-4926-a82d-831cb89092aa

instructionalMethodDetails[0].instructionalDeliveryMethod

 

hours[0].administrativeInstructionalMethod.id

d3680341-fd24-40f6-bdf0-76dca1316fb5

hours[0].minimum

3

hours[0].maximum

9

hours[0].increment

3

hours[0].interval

day

owningInstitutionUnits[0].institutionUnit.id

61820135-a36b-4308-99f7-28697ab7a0b1

owningInstitutionUnits[0].ownershipPercentage

50

owningInstitutionUnits[1].institutionUnit.id

00cd9680-9090-4b38-92ce-7b72d50421ba

owningInstitutionUnits[1].ownershipPercentage

50

schedulingStartOn

16/10/2014

schedulingEndOn

30/11/2014

number

101

academicLevels[0].id

11cdd494-de5b-460e-9ddf-4e84bad6f596

gradeSchemes[0].gradeScheme.id

fd3f06e5-84cd-4d2b-82df-406ae9c39650

gradeSchemes[0].usage

default

gradeSchemes[1].gradeScheme.id

f14a648d-c757-4c7a-b283-1fa74e561d63

gradeSchemes[1].usage

 

credits[0].creditCategory.creditType

institution

credits[0].creditCategory.detail.id

bd582974-7421-4502-8fd4-b3966e08923e

credits[0].measure

credit

credits[0].minimum

1

credits[0].maximum

4

credits[0].increment

1

billing.minimum

1

billing.maximum

5

billing.incremen

1

waitlistMultipleSections

not Allowed

reportingDetail.type

nebraska

reportingDetail.courseWeight

10

administrativePeriod.id

060d0dd1-75aa-4c43-989c-0015b6f01d6e

status.id

ed348068-d0ff-4aa8-bb13-acf8c165b354

additionalClassifications[0].cipCode.id

8814cd44-8dd2-4825-8ce9-6ce50c9e91e2

A slightly more complex query uses criteria. In this case, using the InstitutionUnit ID:

Screen showing complex Ethos Web Service Query

A good way to get acquainted with how queries are constructed is to use the Postman API Development Environment. With this you can look up GUID values (like the owningInstitutionUnits ID above).

We’ve created an article on using Postman with Ethos and you can read it here.

 

Back to top