ellucian-developer / experience-ethos-examples

Example Experience Extensions which use Ethos to retrieve data from the ERP.

Experience Ethos Examples

1. Account Detail
2. Account Detail Data Connect
3. API Dashboard
4. Emergency Contacts
5. Instructor Classes Lambda
6. Leave Balance
7. Leave Balance Data Connect
8. Today Classes GraphQL Proxy
9. Today Classes Lambda
10. Today Classes Node

Account Details Example

This example includes a card and page that show the current user their account details and balance. There are two npm projects in this example, an extension, and a microservice. The data for the card and page are acquired through the BP API (Banner Business Process API) through Ethos Integration. Additional data and behavior could include using a Pay Now feature that integrates with your payment provider.

This example is detailed here: account-details

Account Details Data Connect Example

This example includes a card and page that show the current user their account details and balance. There are two directories in this example, an extension, and dataconnect. The data for the card and page are acquired using Data Connect's Serverless API. The Data Connect Serverless API pipeline calls a BP API (Banner Business Process API) through Ethos Integration. Additional data and behavior could include using a Pay Now feature that integrates with your payment provider.

Note: Using Data Connect Serverless API allows the extension code in the browser to directly make the API call to Ethos without the need for a microservice. The browser user's identity is used to restrict the execution of the DC pipeline API through Data Connect permissions. The API Key used in the pipeline is configured in the card server configuration to protect it from the browser.

*Please note that Data Connect Serverless APIs are currently in Select and not Generally Available. If you'd like to get involved, check out this community post in the Ellucian Community

This example is detailed here: account-details-dataconnect

API Dashboard Example

This example includes a card that can be used to observe the other examples of API requests. This simple card is to allow you to do simple comparisons of the various examples by capturing API request times.

This example is detailed here: api-dashboard

Emergency Contacts Example

This example extension includes a card that shows the current user's emergency contacts and allows them to add, edit or remove emergency contacts and the several Data Connect Serverless API pipelines.

This example is detailed here: emergency-contacts

Instructor Classes Lambda Example

This example includes a card that shows an instructor's classes. There are two npm projects in this example, an extension, and a microservice. The data for the card is acquired through the Ethos GraphQL utilizing the same resources as the Today Classes examples.

This example is detailed here: instructor-classes-lambda

Leave Balance Example

This example includes a card and page that show the current user, an employee their leave balance. There are two npm projects in this example, an extension, and a microservice. The data for the card and page are acquired through the BP API (Banner Business Process API) through Ethos Integration.

This example is detailed here: leave-balance

Leave Balance Data Connect Example

This example includes a card and page that show the current user, an employee their leave balance. There are two directories in this example, an extension, and dataconnect. The data for the card and page are acquired using Data Connect's Serverless API. The Data Connect Serverless API pipeline calls a BP API (Banner Business Process API) through Ethos Integration.

Note: Using Data Connect Serverless API allows the extension code in the browser to directly make the API call to Ethos without the need for a microservice. The browser user's identity is used to restrict the execution of the DC pipeline API through Data Connect permissions. The API Key used in the pipeline is configured in the card server configuration to protect it from the browser.

*Please note that Data Connect Serverless APIs are currently in Select and not Generally Available. If you'd like to get involved, check out this community post in the Ellucian Community

This example is detailed here: leave-balance-dataconnect

Today's Classes GraphQL Proxy Example

This example is part of a suite of examples that illustrate multiple methods to access institution data through Ethos from Experience cards and pages. The use case is a card that displays the student's classes that meet today. This example fetches the Ethos data utilizing the Experience GraphQL proxy. Using Experience's GraphQL proxy avoids the need to deploy a microservice. The efficiency of GraphQL also reduces the round trips to Ethos by returning graphs of objects. There is some extra setup effort involved in loading the needed resources into Ellucian Data Access and authorizing the Ethos Application to use those resources.

This example is detailed here: today-classes-graphql

Today's Classes Lambda Example

This example is part of a suite of examples that illustrate multiple methods to access institution data through Ethos from Experience cards and pages. The use case is a card that displays the student's classes that meet today. This example fetches the Ethos data through a Lambda microservice that utilizes Ethos GraphQL. The efficiency of GraphQL also reduces the round trips to Ethos by returning graphs of objects. Using Lambda provides a reduced effort deployment of the microservice endpoints. There is some extra setup effort involved in loading the needed resources into Ellucian Data Access and authorizing the Ethos Application to use those resources.

This example is detailed here: today-classes-lambda

Today's Classes Node Example

This example is part of a suite of examples that illustrate multiple methods to access institution data through Ethos from Experience cards and pages. The use case is a card that displays the student's classes that meet today. This example fetches the Ethos data through a Node microservice which retrieves the data using Ethos EEDM resources (Ellucian Ethos Data Model). Accessing the Ethos EEDM resources reduces the setup effort over using GraphQL. Note, this node application will need to be deployed in a scalable manner.

This example is detailed here: today-classes-node

Copyright 2021–2023 Ellucian Company L.P. and its affiliates.

experience-ethos-examples's Issues

Error running "npm run deploy-and-upload" on api-dashboard

Hello: I am trying to test the api-dashboard card project and not able to run the command. I get the following error:

PS C:\Development-Ish\experience-ethos-examples-main> npm run deploy-and-upload
npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path C:\Development-Ish\experience-ethos-examples-main/package.json
npm ERR! errno -4058
npm ERR! enoent ENOENT: no such file or directory, open 'C:\Development-Ish\experience-ethos-examples-main\package.json'
npm ERR! enoent This is related to npm not being able to find a file.
npm ERR! enoent

Error data gets cached during Card Configuration Preview

The relatively new Card Configuration Preview feature triggers the fetch from the card to the microservice before the card is configured. The error returned before the URL is even defined gets cached, which causes some or all of the cards to throw JavaScript errors.

The fix: don't cache errors :)

DELETE emergency-contacts returning 400 "Failed to get payload" error.

When I try to run the DELETE emergency-conatcts method I get 400 "failed to get payload error". We are a Banner school. I am passing the body as: { "id":"bannerID" }

account-details-dataconnect - user variable error in pipelne

account-details-dataconnect is not working due to user variable issue

account-detail-reviews BP API can return a 400 error for a valid user

The example UI needs to cope with this erroneous response from BP API by treating it as a 404, not found user.

The real issue is bad data and an bug in the BP API but the UI should not break from this :)

Instructor's Classes Extension - what URL do we put in for "Instructor Classes URL"?

It's part of the configuration and I'm unsure which URL it is asking for?

Thanks!

Christine
Saint Xavier University

Quill/react-quill warnings for MS Outlook and OneDrive apps

Receiving quill/react-quill warnings

experience-productivity-extensions-main>npm install

up to date, audited 985 packages in 3s

168 packages are looking for funding
  run `npm fund` for details

8 vulnerabilities (3 moderate, 5 high)

To address all issues possible, run:
  npm audit fix --force

Some issues need review, and may require choosing
a different dependency.

Run `npm audit` for details.

C:\Users\ucs_jrc\OneDrive - Sam Houston State University\experience\experience-productivity-extensions-main>npm audit fix --force
npm warn using --force Recommended protections disabled.
npm warn audit No fix available for @ellucian/react-design-system@
npm warn audit Updating webpack-dev-server to 4.15.2, which is outside your stated dependency range.

added 4 packages, removed 25 packages, changed 4 packages, and audited 964 packages in 4s

165 packages are looking for funding
  run `npm fund` for details

# npm audit report

quill  <=1.3.7
Severity: moderate
Cross-site Scripting in quill - https://github.com/advisories/GHSA-4943-9vgg-gr5r
No fix available
node_modules/quill
  react-quill  >=0.0.3
  Depends on vulnerable versions of quill
  node_modules/react-quill
    @ellucian/react-design-system
    Depends on vulnerable versions of react-quill
    node_modules/@ellucian/react-design-system

3 moderate severity vulnerabilities

Some issues need review, and may require choosing
a different dependency.

C:\Users\ucs_jrc\OneDrive - Sam Houston State University\experience\experience-productivity-extensions-main>npm update quill

up to date, audited 964 packages in 2s

165 packages are looking for funding
run npm fund for details

3 moderate severity vulnerabilities

Some issues need review, and may require choosing
a different dependency.

Run npm audit for details.

C:\Users\ucs_jrc\OneDrive - Sam Houston State University\experience\experience-productivity-extensions-main>npm audit fix --force
npm warn using --force Recommended protections disabled.
npm warn audit No fix available for @ellucian/react-design-system@

up to date, audited 964 packages in 2s

165 packages are looking for funding
run npm fund for details

npm audit report

quill <=1.3.7
Severity: moderate
Cross-site Scripting in quill - GHSA-4943-9vgg-gr5r
No fix available
node_modules/quill
react-quill >=0.0.3
Depends on vulnerable versions of quill
node_modules/react-quill
@ellucian/react-design-system
Depends on vulnerable versions of react-quill
node_modules/@ellucian/react-design-system

3 moderate severity vulnerabilities

Some issues need review, and may require choosing
a different dependency.

How to setup serverless offiline service

Service URL - set this to the URL shown when starting the offline serverless, ending with /api (remove the /account-details-reviews). Likely this will be http://localhost:3000/api

Can you guide here.

Broken link on https://github.com/ellucian-developer/experience-ethos-examples/tree/main/account-details-dataconnect/dataconnect

The link to Publish and execute a serverless API is broken.

Leave Table headers don't render when too many rows from API

They are defined:
Leave Balances

<TableHead>
                                        <TableRow className={classes.leaveTableRow}>
                                            <TableCell align="left" padding={'none'}><Typography variant={'body3'} component={'div'}>{intl.formatMessage({id: 'LeaveBalance.type'})}</Typography></TableCell>
                                            <TableCell align="left" padding={'none'}>{intl.formatMessage({id: 'LeaveBalance.taken'})}</TableCell>
                                            <TableCell align="left" padding={'none'}>{intl.formatMessage({id: 'LeaveBalance.accrued'})}</TableCell>
                                            <TableCell align="right" padding={'none'} style={{"textAlign": "right"}}>{intl.formatMessage({id: 'LeaveBalance.balance'})}</TableCell>
                                        </TableRow>
                                    </TableHead>

but never render.

Account Balances Header isn't even defined.

getItem is not async

experience-ethos-examples/account-details-extension/src/context/account-details.js

Line 50 in 89fd065

const { data: cacheData } = await getItem({key: cacheKey, scope: cardId});

I also adopted getItem, storeItem, and removeItem from the SDK and connected it to react-query! Our approaches are similar, but I was able to remove some of the complexity surrounding this particular line by removing the await in front of getItem. The SDK docs don't indicate it's an asynchronous method, and when I added await, a new promise was being created and causing the component to render without data.

Another simplification I found was to use initialData instead of placeholderData and define it as a function so react-query will only call it on the first render. I would be very interested to know if you picked placeholderData over initialData for a particular reason!

One more thing I wanted to mention to you in case you've encountered this, cardId has the card's ID immediately on render on the dashboard, but it starts as null when used on the page. I ended up hardcoding our scopes and keys and skipping including the cardId because I wanted to avoid useEffects like you have here.

This code snippet isn't super clear because it uses a custom hook, but I hope you'll get a feel for how my solution works:

const cacheSharedScope = "ppl-loi";
const cacheKeySummary = "summary";

// ...

const PplLettersOfIntentCard = (props) => {
  // ...
  const { status, data } = useScapi({
    endpoint: "letters_of_intent",
    requiresJWT: true,

    // COOL FEATURE ALERT: Load cached data for faster card <-> page <-> card interactions!
    // https://react-query.tanstack.com/guides/initial-query-data
    // Docs: If you configure your query observer with initialData, and no staleTime (the default staleTime: 0), the query will immediately refetch when it mounts:
    // Brandon: This seems like appropriate behavior for a card!
    initialData: () => {
      const { data: cacheData } = getItem({
        key: cacheKeySummary,
        scope: cacheSharedScope
      });
      return cacheData;
    },

    // Brandon created this for being able to call Experience SDK storeItem for caching data
    schoolcraftOnSuccessCallback: (data) => {
      storeItem({ data, key: cacheKeySummary, scope: cacheSharedScope });
    }
  });

  // ...
}

error Async arrow function has no 'await' expression require-await

experience-ethos-examples-main\account-details-extension> npm run deploy-dev
npm WARN config global --global, --local are deprecated. Use --location=global instead.

[email protected] deploy-dev
webpack --progress --mode development --env verbose --env upload

6% setup before compile WebpackExperienceValidatorPluginValidating extension definition ...
Extension config validated
6% setup before compile WebpackExperienceUploadPluginExtension upload token validated
37% building 2/4 entries 4/4 dependencies 1/3 modulesBrowserslist: caniuse-lite is outdated. Please run:
npx browserslist@latest --update-db
Why you should do it regularly: https://github.com/browserslist/browserslist#browsers-data-updating
99% done plugins WebpackExperienceUploadPlugin
Upload aborted due to compilation errors and/or warnings

assets by status 1.75 MiB [cached] 2 assets
runtime modules 2.09 KiB 11 modules
modules by path ./node_modules/ 271 KiB 67 modules
modules by path ./src/ 47.6 KiB
modules by path ./src/i18n/ 4.17 KiB 4 modules
modules by path ./src/page/.jsx 12.7 KiB 2 modules
modules by path ./src/data/.js 15.7 KiB 2 modules
3 modules
modules by path external "@ellucian/react-design-system/ 126 bytes
external "@ellucian/react-design-system/core" 42 bytes [built] [code generated]
external "@ellucian/react-design-system/core/styles/tokens" 42 bytes [built] [code generated]
external "@ellucian/react-design-system/core/styles" 42 bytes [built] [code generated]
external "react" 42 bytes [built] [code generated]
external "react-intl" 42 bytes [built] [code generated]
external "prop-types" 42 bytes [built] [code generated]
external "react-dom" 42 bytes [built] [code generated]

ERROR in ./src/context/account-details.js
Module Error (from ./node_modules/eslint-loader/dist/cjs.js):

.\experience-ethos-examples-main\account-details-extension\src\context\account-details.js
48:23 error Async arrow function has no 'await' expression require-await

✖ 1 problem (1 error, 0 warnings)

@ ./src/cards/AccountDetails.jsx 13:0-87 95:27-44 292:42-64

Something Went Wrong, Contact your Administrator

I've installed this to our TEST environment and the card didn't have much on it other than selection boxes. I clicked on Chart or Table (whichever wasn't selected by default) and now I get the following:

Something Went Wrong
Contact your Administrator

Thoughts? Is there a log that I can see any information with what may be going wrong?

Thank you!

CRorer
Saint Xavier University