Banner Ethos API Extensibility - Fairmont State University · not limited to any one single Ellucian application. The Ellucian Ethos Data Model is a platform technology component

Banner Ethos APIBanner Ethos API Extensibility

March 2019

Notices and Privacy

Notices and Privacy© 2019 Ellucian.

Contains confidential and proprietary information of Ellucian and its subsidiaries. Use of thesematerials is limited to Ellucian licensees, and is subject to the terms and conditions of one or morewritten license agreements between Ellucian and the licensee in question.

In preparing and providing this publication, Ellucian is not rendering legal, accounting, or othersimilar professional services. Ellucian makes no claims that an institution's use of this publicationor the software for which it is provided will guarantee compliance with applicable federal or statelaws, rules, or regulations. Each organization should seek legal, accounting, and other similarprofessional services from competent providers of the organization's own choosing.

Ellucian's Privacy Statement is available at: www.ellucian.com/privacy.

Ellucian shall have the right to (a) use, store, process, modify, reproduce, distribute and displaycustomer data, and to grant sublicenses to third parties, for the sole purposes of providing thesoftware, performing Ellucian's obligations under its agreements with customers and complying withapplicable law or legal requirements; (b) use, store, process, modify and reproduce customer datafor Ellucian's internal business purposes, including development, diagnostic, forecasting, planning,analysis and corrective purposes in connection with the software, and for otherwise improving andenhancing the software; and (c) use, store, process, modify, reproduce, display, perform, distribute,disclose and otherwise exploit in any manner Aggregated Data for Ellucian's business purposes,including disclosure within its public statements and marketing materials describing or promotingEllucian or the software. “Aggregated Data” means any data obtained or generated by Ellucian,including data pertaining to the software, Ellucian's systems and software, and the use of any ofthe foregoing, and includes data derived from customer data, which in all instances (i) does notidentify any individual and (ii) is not attributed or attributable to a specific customer. AggregatedData includes data that has been combined into databases which include third party data.

Ellucian2003 Edmund Halley DriveReston, VA 20191United States of America

Ellucian - Confidential and Proprietary 2

https://www.ellucian.com/privacy

Contents

Contents

Banner Ethos API Extensibility............................................................................................5Extensibility example.....................................................................................................................5Prerequisites..................................................................................................................................6Banner Ethos API Extensibility - Use case.................................................................................. 6

Process overview........................................................................................................................ 7

Requirement definition..............................................................................................................8

Customize the schema..............................................................................................................9

Configure Banner...................................................................................................................... 10Expose access to the Banner table and column........................................................................10SQL query for READ.................................................................................................................. 10Add the SQL query to the GORRSQL page.............................................................................. 11

Configure the API......................................................................................................................12Add an extension code............................................................................................................... 12Define the extension................................................................................................................... 13Enable the extension.................................................................................................................. 14

Results............................................................................................................................................16

Constraints................................................................................................................................... 17

Configure Extensibility Using JSON Text....................................................................... 18

Configure JSON Path Using Nested Paths.................................................................... 20JSON path restrictions................................................................................................................ 21

Extension Code Definition (GTVAPEC)............................................................................ 22

Version Mapping Table (GURAPVR)..................................................................................23

Extension Definition (GURAPEX)....................................................................................... 24

Banner Configuration API......................................................................................................25


Contents

JSON templates..........................................................................................................................26

Configure Extensibility with the SDE............................................................................... 28SDE field operations................................................................................................................... 28Query SDE fields........................................................................................................................ 30

Extensibility examples.............................................................................................................33Simple data types....................................................................................................................... 33Complex data types.................................................................................................................... 34Sample GORRSQL..................................................................................................................... 35

Read from a Banner table....................................................................................................35Read from the SDE.............................................................................................................. 35Write to a Banner table........................................................................................................ 36Write to the SDE.................................................................................................................. 37

Extensibility with MEP.............................................................................................................39

Troubleshooting..........................................................................................................................40


Banner Ethos API Extensibility

Banner Ethos API ExtensibilityEthos API Extensibility enables an institution or Ellucian partner to extend Ellucian Ethos DataModels.

Ellucian Ethos Data Models represent distinct concepts with the higher education domain. EllucianEthos Data Model definitions are designed to be generic to support global requirements andnot limited to any one single Ellucian application. The Ellucian Ethos Data Model is a platformtechnology component designed to provide a rationalized method by which applications canexchange information in a pre-defined set of data structures. The Data Model provides an open viewof where the defined patterns and data structures can be expressed and understood by the entiredevelopment community including customers, partners, and internal development organizations.

Behind every Ellucian Ethos Data Model, is an Authoritative Source system, such as Banner,and its Ethos API. The Ethos API is responsible for adhering to the data contract set forth in theEllucian Ethos Data Model as well has adhering to the behavior contract as described in Ethos APIStandards.

Institutions, or a group of institutions could have additional or refined specifications that requireadditional properties or attributes in the Ellucian Ethos Data Model to support their local businessprocesses. Ethos API Extensibility is a collection of tools, practices, and patterns that enableinstitutions to customize or extend published Ethos based Data Models to meet those businessneeds.

In Banner, Ethos API Extensibility is implemented through both changes in API behavior and aseries of new configuration settings that enable user defined extensions in the API.

Extensibility example

The 'Building' resource in the Ellucian Ethos Data Model is defined as 'Physical structures withrooms located in specified physical locations.'

A small sub-set of the published schema for a Building instance in the JSON format is as follows:

{ "id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00", "code": "UNION", "title": "Student Union Building"}

Consider a case where an institution needs to see the capacity of a building with the resource. Thedata for building capacity already exists in Banner, or the equivalent authoritative source system,but the Ellucian Ethos Data Model does not support it yet. With Extensibility, there are a couple ofways to enable this.

You could create a new data model for capturing capacity and relate it to the Ellucian model, bydeploying the custom Ethos API application. This could be expensive and time-consuming.


Banner Ethos API Extensibility

Or, as the authoritative source system supports Extensibility, another way would be to add a newJSON property for capacity and pull the value from the existing location in the source system.

The first step is to tell the system, on what baseline model (version) the extensions is built upon.In this case, a Buildings resource is based on the EEDM v6 of Buildings. This tells the base APIwhat it needs to process first, and it will then apply the extended property later. After retrieving thebase resource, the API detects there is a defined extension and retrieves the additional sourceinformation and adds it to the JSON response body in the required location.

{ "id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00", "code": "UNION", "title": "Student Union Building", "capacity":"500"}

Prerequisites

Adding and enabling an extension requires a knowledge of PL/SQL and a familiarity with the tablestructure of Banner.

You will require access to and should be able to modify Banner administrative pages such asBusiness Rules (GORRSQL). You will need to know how to use Ethos Extend to customize aschema for a data model resource. In addition, you will need to understand how Ethos integrationswork and how to use a REST/JSON API calling utility such as Postman.

Banner Ethos API Extensibility - Use case

The persons resource is being used for a custom integration at an institution.

The veteran file number information for a person exists in Banner but is not a part of the EEDMresource. The requirement is to add the veteran file number from Banner to a custom version of anEthos person so that the reporting system can use that data.


Process overview

Process overviewThere are four steps involved in adding and enabling an extension.

The process to define and add an extension to an Ellucian Data Model Resource is:

1. Define Requirements – to understand what kind of extension is required and where it is sourcedfrom in Banner.

2. Customize the existing Schema – to add the new extension to a published Ellucian schema.3. Configure the Ethos API – to enable the schema to connect to the data in Banner.4. Publish the Schema - to notify users that the new extension is ready to use.

The sections that follow describe each step by means of the use case example.


Requirement definition

Requirement definitionUse the Banner administrative pages, the Ethos Schema, and Banner Documentation to gatherinformation and build requirements for the extension.

FromBanner, you can obtain the name of the table that contains the field you want to use, thecolumn type, and the GUID location. From the Ellucian Customer Center, you can review thepersons data model resource schema to look all the existing properties and determine where youneed to add the new property.

The Banner administrative page that contains the Veteran File Number field is the General PersonIdentification (SPAIDEN) page.

Looking at this page and examining the Veteran File Number field will provide the table name,SPBPERS and the column name, SPBPERS_SPBPERS_VETC_FILE_NUMBER. Looking at thetable information, you can see that the property type is a String.

After gathering the table information, you need to determine how GUIDs are related to the resource.See the Ethos API Handbook to locate GUID information. The GUID for the persons resource is inlocated in the GORGUID table. This information is required to connect a row in the base table to theGUID.


Customize the schema

Customize the schemaUse Ellucian Ethos Extend to locate and modify the persons schema to add the new property forveteran file number.

About this task

A schema defines the shape of a resource (or collection of data properties). The schema is themechanism by which a calling system can understand what is required during inbound processingsuch as creating or updating data, or during outbound processing such as retrieving or accessingdata.

Procedure

1. Log in to Ellucian Ethos Extend.The list of all data models that are in your repository is displayed.

2. Search for and click on Persons to access the data model schema.The title, name and description of the data model are displayed on the left and the propertiesthat are present in the schema are displayed on the right. Those properties that have beenpublished by Ellucian and cannot be modified are indicated by a 'lock' symbol.

3. Click Add to add the new property.The Add Property window is displayed.

4. Type veteranId for the Title.5. Type in a brief Description.6. Select String in the Type drop-down list.7. Click Add.8. Click Save on the persons schema page.

Results

The veteranId property is added to the properties on the persons schema. Click Source to see theproperties in the JSON schema view.


Configure Banner

Configure BannerConfigure Banner to enable the new property extension.

Connect the Banner data for veteran identification number to the Ethos API so that the extendedschema and data is used when the persons API is called.

Because the new property is contained in a Banner table, you need to provide access to that datathrough the Business Rules (GORRSQL) administrative page by exposing the information in thetable. Then you need to configure and enable the extension through the Ethos API in Banner.

Expose access to the Banner table and column

Expose access to the table and column so that APIs can read that data.

Implement a PL/SQL query on the GORRSQL administrative page to access the extended data.Through the GORRSQL administrative page, you can provide Banner with SQL statements thatAPIs use to read data from the Banner form.

There are additional pages such as GTVSQPA, GTVSQPR, GTVSQRU, and GORSQPA which areused for validation. For example, parameter names that are used by GORRSQL must be addedto these forms. See the Banner documentation for more information on GORRSQL and validationtables.

SQL query for READ

To support the extension for reading, add the SQL code that will retrieve the additional property.

The SQL statement has two requirements, first you must include access to the row in the extendedtable by the GUID. In some tables the GUID could be a column on the base tables, on others youwill have to join the GUID table row with the base table rows.

The other requirement for READS is that the WHERE clause must contain a filter for a list of GUIDs,in (:GUID_LIST). This is required to look up a single row or a set of rows to support a paged APIrequest.

To access the veteran ID column, the SQL would look like the following:

select gorguid_guid as guid,spbpers_vetc_file_number from gorguid,spbpers,spridenwhere gorguid_ldm_name='persons' andgorguid_domain_surrogate_id = spriden_surrogate_id and spriden_pidm = spbpers_pidmand gorguid_guid in (:GUID_LIST)


Configure Banner

Add the SQL query to the GORRSQL page

Add the SQL query for READ on the GORRSQL administrative page.

Before adding the query, you need to setup a process and a rule code for GORRSQL that will helpidentify the SQL statement. Set up a rule called PERSONS_READ and attach it to a process inGORRSQL called HEDM_EXTENSIONS. Ensure that the rule is active on GORRSQL.

The HEDM_EXTENSIONS and PERSONS_READ names are user-defined and can be any validvalue. The following examples use these values for illustrative purposes only:

• Go to page GTVSQPR to create a Process Rule Code (HEDM_EXTENSIONS) if it doesn’texist.

• Go to page GTVSQRU to create a Rule Code (PERSONS_READ) if it doesn’t exist.• Go to page GTVSQPA to create the parameter GUID_LIST with a type of CHARACTER

(required, unless it already exists).• Go to page GORSQPA and associate parameter code GUID_LIST with the process code

HEDM_EXTENSIONS if it doesn’t exist.

You can include as many columns as required but one column must be referenced with the nameGUID. See Constraints on page 17 for additional considerations. Ensure that a valid Start Dateis entered and select the Active check box. Before saving, click Validate SQL.


Configure the API

Configure the APIAfter adding the SQL to GORRSQL, use the JSON REST API to enable the extension to be usedwhen the API is run.

First set up an extension code, define the extension, and attach it to a specific Ellucian Ethos DataModel version. Use a REST testing utility such as Postman to work on the APIs.

Add an extension code

Extension codes are simple Banner validation codes. They are used to group individual extensionstogether and make it easy to apply rules to an EEDM version.

Extension codes contain the following JSON properties:

• id - The surrogate id of the row. This is generated by the Postman utility on a POST.• code - The group of extensions to be applied.• description - The description of the extension code group.

Extension codes are exposed through REST/JSON APIs in the Banner API. You can create anextension code by calling a POST. You can call a PUT and DELETE, in addition to a GET to viewthe code.

POST \IntegrationApi\api\extension-codes

Access the Postman utility and create the following extension code:

{ "code": "EEDM_EXTENSIONS", "description": "Custom Extensions for EEDM"}


Configure the API

Define the extension

An extension definition connects the GORRSQL statement to the EEDM API framework or schema.It is a declaration of the extended data including the GORRSQL mapping, the destination rules, andthe data description.

Extension definitions contain the following JSON properties:

• id - The surrogate id of the row. This is generated by the Postman utility on a POST.• columnName - The columnName in the GORRSQL logic that is used to reference the source

value. Must be specified using all upper-case characters.• description - A note about the extension.• extensionCode - The group of extensions to be applied. Use the code from the extension-codes

API.• jsonLabel - The string label used for the JSON property name.• jsonPath - The JSON Path used to build a JSON Patch for the addition of the extension. See

Configure JSON Path Using Nested Paths on page 20.• jsonPropertyType - The JSON data type to be used when read or writing the value. The possible

values include S=String, N=Number, D=Date, T=Timestamp, J=JSON text, see ConfigureExtensibility Using JSON Text on page 18.

• resourceName - The resource name the extension is to be applied to.• sqlProcessCode - The GORRSQL process code.


Configure the API

• sqlReadRuleCode - The GORRSQL rule code used when reading the source value(s).• sqlWriteRuleCode - The GORRSQL rule code used when writing, which includes insert-update-

delete, the extension back to its source.

You can create an extension code by calling a POST.

POST \IntegrationApi\api\extension-definitions

Access the Postman utility and create the following extension definition:

{ "columnName": "SPBPERS_VETC_FILE_NUMBER", "description": "Extensions for persons model", "extensionCode": "EEDM_EXTENSIONS", "jsonLabel": "veteranId", "jsonPath": "/", "jsonPropertyType": "S", "resourceName": "persons", "sqlProcessCode": "HEDM_EXTENSIONS", "sqlReadRuleCode": "PERSONS_READ",}

Enable the extension

Enable the extension by connecting the extension code to a data model release version.

Extension versions contain the following JSON properties:


Configure the API

• id - The surrogate id of the row. This is generated by the Postman utility on a POST.• comment - A comment about the version.• extensionCode - The group of extensions to be applied. Use the code from the extension-codes

API.• knownMediaType – The full media type (Ethos version) of the resource that the extensions are

applied to.• resourceName - The resource name the extension is to be applied to.

You can create an extension version by calling a POST.

POST \IntegrationApi\api\extension-versions

Access the Postman utility and create the following extension version that is applied to version 8 ofthe persons API:

{ "comment": "Latest version of EEDM", "extensionCode": "EEDM_EXTENSIONS", "knownMediaType": "application/vnd.hedtech.integration.v8+json", "resourceName": "persons"}


Results

ResultsAfter configuring the new extension, call the Ethos API for persons to view the extended property.

Every time the API is called, the API framework for Banner accesses all the data required to buildan EEDM Resource and produces the JSON representation. The framework applies all extensionsthat are added and updated, and the results are displayed.


Constraints

ConstraintsThere are some constraints that apply when extending an Ethos API resource.

Reading GORRSQL:

• Must select the GUID as a column named 'GUID'.• Must include a in (:GUID_LIST).• Must access through the GUID.

Banner SDE: Not all administrative forms and data representations are supported. See the BannerGeneral documentation for more details.

Writing GORRSQL:

• Must access through the GUID.• Must support unspecified properties.• Write SQLs are designed to be called for all creates, updates and deletes. Use the

HTTP_METHOD parameter to determine the syntax.• Write statements in GORRSQL are not enabled by default. The institution will have to grant

the administrative user temporary permissions for the creation of the GORRSQL. Permissionsshould be granted, SQL statement added, and then revoked.

– Use the Banner GUAOBJS form to verify that the ENABLE_GORRSQL_DML securityobject exists. If ENABLE_GORRSQL_DML does not exist on GUAOBJS, add it withType=DLL, System=G, and Display Option = Banner8 Only.

– After ENABLE_GORRSQL_DML is added to GUAOBJS, it needs to be added to theObjects tab of GSASECR (GURAOBJ).

– Then use the Banner GSASECR form to grant ENABLE_GORRSQL_DML directly to theBanner user that will be creating write statements on GORRSQL.

JSON:

• JSON labels MUST be unique to ensure proper extraction on PUT/POSTs. If the extended labelis the same as an existing field either in the grails domain item or grails pojo used for extraction,an error will be generated.

• JSON Paths use '/' for extensions defined at the root level of a resource. See Configure JSONPath Using Nested Paths on page 20 for information on adding extensions elsewhere in theresource.

• JSON property type definitions:

– S=String, means the value will be inside quotation marks.– N=Number, means the value will appear as a number (no quotation marks).– D=Date would be displayed as a string in the Ethos Standard format.– T=Timestamp would be displayed as a string in the Ethos Standard format.– J=JSON text, see Configure Extensibility Using JSON Text on page 18 for more

information.


Configure Extensibility Using JSON Text

Configure Extensibility Using JSON TextJSON text is the technique in which Ethos API Extensibility can handle extending the resource witharray data. It is left up to the client implementation how to persist and retrieve the data within theJSON text.

JSON text can be the string representation of a JSON object or an array of JSON objects. ComplexJSON structures are encoded directly in the JSON string representation.

The Extension Definition resource defines the JSON property type (jsonPropertyType) of anextension value. In addition to support for simple strings, numbers, dates, and timestamps, complexJSON objects can be encoded as JSON text. You must specify the jsonPropertyType as 'J' whenusing JSON text.

No parsing of the JSON text is performed, other than validating that it is valid JSON text. An errormessage that starts with 'Unparseable JSON text' is returned if the JSON text is not syntacticallycorrect. An error message that starts with 'Unable to apply JSON patch' is returned if the JSON textis valid, but not valid within the patching mechanism.

Examples of JSON text values are shown below. In all examples, assume a jsonPath of '/', ajsonLabel of 'extensions', and a jsonPropertyType of 'J' for the marital-statuses extension definition.

Example 1: Given JSON text of ‘{"name": "value"}‘, this results in the following being added to theresource.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced","extensions": {"name": "value"}}

Example 2: Given JSON text of ‘{"name1": "abc", "name2": 123, "name3": "2017-09-18"}‘, thisresults in the following being added to the resource.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced","extensions": {"name1": "abc", "name2": 123, "name3": "2017-09-18"}}

Example 3: Given JSON text of ‘[{"name1": "value1"}, {"name2": "value2"}, {"name3": "value3"}]‘, thisresults in the following being added to the resource.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced",


Configure Extensibility Using JSON Text

"extensions": [{"name1": "value1"}, {"name2": "value2"}, {"name3": "value3"}]}


Configure JSON Path Using Nested Paths

Configure JSON Path Using Nested PathsYou can choose to define extensions using an existing resource path or a new root-level nestedpath.

The Extension Definition resource defines the JSON path (jsonPath) for an extension label. AjsonPath value of '/' is used for extension labels defined at the root level of a resource. Extensionspaths can be deeply nested to form a more complex JSON structure. Examples of various jsonPathvalues are shown below. In all examples, assume that there are two marital-statuses extensiondefinitions defined; one for financeConversion (with a value of '1') and one for ediEquivalent.(with avalue of '2').

Example 1: Given a jsonPath of '/extensions', this results in the following being added to theresource root.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced","extensions": {"financeConversion": "1", "ediEquivalent": "2"}}

Example 2: Given a jsonPath of '/extensions/levelA' for financeConversion and '/extensions/levelB'for ediEquivalent, this results in the following being added to the resource root.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced","extensions": { "levelA": {"financeConversion": "1"}, "levelB": {"ediEquivalent": "2"} }}

Example 3: Given a jsonPath of '/extensions/nested/levels' for both, this results in the followingcomplex JSON structure being added to the resource root.

{"id": "a2bedb7e-7b7c-4199-9446-4c5c636caa00","code": "D","title": "Divorced","extensions": {"nested": {"levels": {"financeConversion": "1", "ediEquivalent": "2"} } }}


Configure JSON Path Using Nested Paths

Any combination of jsonPath values can be specified for a resource to create any deeply nestedcomplex JSON structure.

JSON path restrictions

There are a few restrictions on the use of JSON paths.

• You cannot create a complex JSON structure for an existing resource path. Complex JSONpaths can only be created at the root level of the resource where the first part of the path doesnot already exist for the resource. You can create an extension for a label on an existing path, ornested path, but it must be directly under that path and not contain any other nesting level. Forexample, if a path of /xxxxxx already exists in the resource, you can use a jsonPath of /xxxxxx,but you cannot use a jsonPath of /xxxxxx/yyyyyy if yyyyyy does not already exist. Only if /xxxxxxdoes not already exist, will yyyyyy be created.

• You cannot specify a jsonPath for an existing path that is an array. Directly extending arrays isnot allowed. An error message that starts with 'Unable to apply JSON patch for array path' isdisplayed if attempting to extend a label that is an array.


Extension Code Definition (GTVAPEC)

Extension Code Definition (GTVAPEC)GTVAPEC is used to define an extension code to easily group the settings together.


Version Mapping Table (GURAPVR)

Version Mapping Table (GURAPVR)GURAPVR defines a version map for a given extension code. This will be used to map a catalogidentifier (alias) to a known EEDM version that the API supports.


Extension Definition (GURAPEX)

Extension Definition (GURAPEX)GURAPEX is used to define a single literal extension to a model. It includes the path and propertyname in addition to the GORRSQL code/process for running custom SQL to retrieve the value.


Banner Configuration API

Banner Configuration APIIn Banner, the API Extensions are configured through a REST API.


JSON templates

JSON templatesAPIs can be used to setup and view configuration. JSON document samples can be used for APIcreation.

All of the APIs are in the context of the Banner Integration application deployment.

Banner security objects control access to the APIs. These security objects are all included withthe BAN_GENERAL_API_C security class. Banner users calling these APIs must have access toBAN_GENERAL_API_C or to the individual security objects.

Table 1:

API Resource Name Security Object

extension-codes API_EXTENSION_CODES

extension-definitions API_EXTENSION_DEFINITIONS

extension-versions API_EXTENSION_VERSIONS

Creating an extension-code:

{ "code": "ethos_910", "description": "Extensions for version 9.10"}

POST https://{host}:{PORT}/IntegrationApi/api/extension-codes/ HTTP/1.1

When posted, use the following to view the newly created code:

GET https://{host}:{PORT}/IntegrationApi/api/extension-codes/ HTTP/1.1

Creating an extension-definition:

{ "columnName": "{the upper-case Banner column name}", "extensionCode": "ethos_910", "jsonLabel": "", "jsonPath": "/", "jsonPropertyType": "", "resourceName": "", "sqlProcessCode": "", "sqlReadRuleCode": "", "sqlWriteRuleCode": ""}

POST https://{host}:{PORT}/IntegrationApi/api/extension-definitions/ HTTP/1.1


JSON templates

When posted, use the following to view the newly created definition:

GET https://{host}:{PORT}/IntegrationApi/api/extension-definitions/ HTTP/1.1

Creating an extension-version:

{ "comment": "", "extensionCode": "ethos_910", "knownMediaType": "{the EEDM version}", "resourceName": "{the EEDM resource name}"}

POST https://{host}:{PORT}/IntegrationApi/api/extension-versions/ HTTP/1.1

When posted, use the following to view the newly created version:

GET https://{host}:{PORT}/IntegrationApi/api/extension-versions/ HTTP/1.1


Configure Extensibility with the SDE

Configure Extensibility with the SDEEthos API Extensibility can be used with Supplemental Data Engine (SDE) fields.

SDE fields are fields that can be added to Banner but which do not exist in a formal Banner baseline table. These fields are present in theSDE and are associated to a row of data in a parent baseline Banner table. Extensibility supports the use of SDE fields in extending a givenEthos API data model.

SDE field operations

To perform insert or update operations on extended fields that reside in the SDE, you need to follow a specific pattern.

1. The rowid of the parent baseline Banner table associated with the SDE field is retrieved.2. The HTTP method is checked to determine if an insert (POST) or an update (PUT) is being done.3. For both insert and update, the primary key of the parent Banner table is retrieved by rowid.4. The SDE field is checked to see if it is an unspecified number, or string, or date. This check is done because if the SDE field does not

exist in the request, then it is set to this unspecified value to prevent it from being added with a null value or from wiping the value outupon an update.

The following pseudo code is an example of the insert/update pattern:

DECLARE rowid cursor definition; local variable definitions;BEGIN Query rowid cursor; IF HTTP_METHOD IN ('POST','PUT') THEN -- Doing either insert or update Query primary key from parent baseline Banner table by rowid; IF SDE_FIELD != UNSPECIFIED_NUMBER (or STRING, or DATE) THEN Convert the SDE field to SYS.ANYDATA type; Save (insert or update) the SDE field in SDE by primary key; END IF; END IF;END;



In most cases, the logic is the same for an insert and an update. However, if the logic is different, separate IF blocks for each HTTP methodcan be coded. Deletion of SDE data is handled through a trigger on the parent baseline table when SDE is setup and does not need to becoded here.

Insert/Update scripts for SDE with Extensibility are be added to GORRSQL through the Banner Admin Pages. The Extensibility feature thenretrieves the script from GORRSQL at run-time and executes it. The following code is an example of a script that does an insert/update:

-- Anonymous PL/SQL block used to update fields in the -- instructional-methods model which resides in SDE. The specific model to-- be updated is identified by the GUID passed in the GUID parameter. The-- SDE fields updated in this example are HEDM_DURATION, HEDM_INSTRUCTOR,-- and HEDM_START_DATE.

DECLARE CURSOR rowid_c (p_guid VARCHAR2) IS SELECT s.rowid FROM gorguid g, stvschd s WHERE g.gorguid_ldm_name = 'instructional-methods' AND g.gorguid_domain_surrogate_id = s.stvschd_surrogate_id AND g.gorguid_guid = p_guid; lv_rowid VARCHAR2(18); lv_result VARCHAR2(500); lv_pk gorsdav.gorsdav_pk_parenttab%TYPE; lv_anydata SYS.ANYDATA;BEGIN OPEN rowid_c(:GUID); FETCH rowid_c INTO lv_rowid; CLOSE rowid_c; IF :HTTP_METHOD IN ('POST','PUT') THEN select gp_goksdif.f_get_pk('STVSCHD', lv_rowid) into lv_pk from dual; IF :HEDM_DURATION != dml_common.UNSPECIFIED_NUMBER THEN lv_anydata := SYS.ANYDATA.convertNumber(:HEDM_DURATION); lv_result := gokhedm.f_save_sde_data(p_table => 'STVSCHD', p_column => 'HEDM_DURATION', p_rowid => lv_rowid, p_pk => lv_pk, p_value => lv_anydata); END IF; IF :HEDM_INSTRUCTOR != dml_common.UNSPECIFIED_STRING THEN lv_anydata := SYS.ANYDATA.convertVarchar2(:HEDM_INSTRUCTOR); lv_result := gokhedm.f_save_sde_data(p_table => 'STVSCHD', p_column => 'HEDM_INSTRUCTOR', p_rowid => lv_rowid,



p_pk => lv_pk, p_value => lv_anydata); END IF; IF :HEDM_START_DATE != dml_common.UNSPECIFIED_DATE THEN lv_anydata := SYS.ANYDATA.convertDate(:HEDM_START_DATE); lv_result := gokhedm.f_save_sde_data(p_table => 'STVSCHD', p_column => 'HEDM_START_DATE', p_rowid => lv_rowid, p_pk => lv_pk, p_value => lv_anydata); END IF; END IF;END;

Query SDE fields

Querying or retrieving extended fields that reside in the SDE follows a specific pattern.

The following pseudo code is an example of the query pattern:

select gorguid_guid as guid, sys.anydata.access<DATA TYPE>(g1.gorsdav_value) as <YOUR SDE FIELD>from gorguid g, <PARENT BANNER TABLE>, gorsdav g1 where g.gorguid_ldm_name = <RESOURCE NAME> and g.gorguid_domain_surrogate_id = <PARENT BANNER TABLE>_surrogate_id and g1.gorsdav_table_name(+) = <PARENT BANNER TABLE> and g1.gorsdav_attr_name(+) = <SDE FIELD> and g1.gorsdav_pk_parenttab(+) = <PARENT BANNER TABLE PRIMARY KEY FIELD> and g.gorguid_guid in (<GUID_LIST>);

• select gorguid_guid as guid, - The gorguid_guid must be called guid in the result set.• sys.anydata.access<DATA TYPE>(g1.gorsdav_value) as <YOUR SDE FIELD> - This line is repeated for each SDE field.

The data type can be Number, Varchar2, or Date.• from gorguid g, <PARENT BANNER TABLE>, gorsdav g1 - Repeat gorsdav g1 for each SDE field. For example, gorsdav

g2, gorsdav g3.



• and g1.gorsdav_table_name(+) = <PARENT BANNER TABLE>, and g1.gorsdav_attr_name(+) = <SDE FIELD>, andg1.gorsdav_pk_parenttab(+) = <PARENT BANNER TABLE PRIMARY KEY FIELD> - These lines are repeated for each SDEfield.

Each SDE field is repeated according to the data type for each field. An example of a SELECT clause with three SDE fields:

SELECT gorguid_guid as guid, sys.anydata.accessNumber(g1.gorsdav_value) as HEDM_NUMERIC_APPLES, sys.anydata.accessVarchar2(g2.gorsdav_value) as HEDM_STRING_ORANGES, sys.anydata.accessDate(g3.gorsdav_value) as HEDM_DATE_BANANAS

The table alias for gorsdav_value is different (g1, g2, or g3) for each SDE field.

In the WHERE clause, the table_name, attr_name, and pk_parenttab are repeated for each SDE field. An example of a query with two SDEfields (HEDM_APPLES and HEDM_ORANGES):

WHERE g.gorguid_ldm_name = <RESOURCE NAME> AND g.gorguid_domain_surrogate_id = <PARENT BANNE TABLE>_surrogate_id AND g1.gorsdav_table_name(+) = 'SOME_TABLE' AND g2.gorsdav_table_name(+) = 'SOME_TABLE' AND g1.gorsdav_attr_name(+) = 'HEDM_APPLES' AND g2.gorsdav_attr_name(+) = 'HEDM_ORANGES' AND g1.gorsdav_pk_parenttab(+) = 'SOME_TABLE_CODE' AND g2.gorsdav_pk_parenttab(+) = 'SOME_TABLE_CODE'

The (+) in the WHERE clause for each gorsdav column represents an outer join, meaning that null values are added to the result set forcolumns where there is no corresponding row.

A complete example of an SDE query for Extensibility is shown below. This example shows three SDE fields: HEDM_DURATION,HEDM_INSTRUCTOR, and HEDM_START_DATE.

-- SQL used to extend the instructional-methods model using SDE. Data will-- be selected from the list of guids passed in the GUID_LIST parameter.-- The result set must contain a column named GUID for matching the-- extended data to the correct model entry.

select gorguid_guid as guid, sys.anydata.accessNumber(g1.gorsdav_value) as HEDM_DURATION, sys.anydata.accessVarchar2(g2.gorsdav_value) as HEDM_INSTRUCTOR, sys.anydata.accessDate(g3.gorsdav_value) as HEDM_START_DATE, from gorguid g, stvschd s, gorsdav g1, gorsdav g2, gorsdav g3



where gorguid_ldm_name = 'instructional-methods' and g.gorguid_domain_surrogate_id = s.stvschd_surrogate_id and g1.gorsdav_table_name(+) = 'STVSCHD' and g2.gorsdav_table_name(+) = 'STVSCHD' and g3.gorsdav_table_name(+) = 'STVSCHD' and g1.gorsdav_attr_name(+) = 'HEDM_DURATION' and g2.gorsdav_attr_name(+) = 'HEDM_INSTRUCTOR' and g3.gorsdav_attr_name(+) = 'HEDM_START_DATE' and g1.gorsdav_pk_parenttab(+) = s.stvschd_code and g2.gorsdav_pk_parenttab(+) = s.stvschd_code and g3.gorsdav_pk_parenttab(+) = s.stvschd_code and gorguid_guid in (:GUID_LIST)]

Prefix SDE fields with the value 'HEDM_' to avoid any result set column naming conflicts with other fields in Banner. Query scripts for SDEwith Extensibility are added to GORRSQL through the Banner Admin Pages.


Extensibility examples

Extensibility examplesExtensibility makes use of client-written SQL stored on GORRSQL to read/write data. If you can write SQL queries to read and write thedata, you can make that data available through Extensibility.

There is no difference in data that comes from existing columns in Banner baseline tables, from client-created tables, or from data storedusing the Supplemental Data Engine (SDE). All examples have Extensibility field names prefaced with 'hedm' to avoid naming conflicts withfields in the published Ethos API model.

Simple data types

There are four simple data types.

• S=String (up to 4,000 characters)• N=Number (may be integer or decimal numbers)• D=Date (date with no time component)• T=Timestamp (date with time and time zone component)

The following JSON shows each of these data types using an example for the buildings resource.

{ "id": "04f2f623-61c7-454b-8e7f-2789e4e5089a", "code": "SCI", "title": "Science Hall", "hedmLandmark": "STONE WALKWAY", "hedmCapacity": 300, "hedmRoomCount": 80, "hedmConstructionDate": "2012-02-10", "hedmWallClock": "2017-10-12T18:07:10+00:00"}

• hedmLandmark is an example of a String.• hedmCapacity and hedmRoomCount are examples of Numbers.



• hedmConstructionDate is an example of a Date; there is no time component.• hedmWallClock is an example of a Timestamp; the time and time zone are relative to UTC (an Ethos standard), so the timestamp shown

is actually 2:07pm EDT.

Complex data types

Complex data is represented as raw JSON text.

J=JSON-text (will be stored as-is in the Oracle database – up to 4,000 characters).

JSON text can be the string representation of a JSON object or an array of JSON objects. Complex JSON structures are encoded directly inthe JSON string representation. Banner Ethos API Extensibility handles extending the resource with array data through JSON text. It is leftup to the client implementation how to persist and retrieve the data within the JSON text. No parsing of the JSON text is performed, otherthan checking that it is valid JSON text.

The following JSON shows complex data using an example for the buildings resource.

{ "id": "04f2f623-61c7-454b-8e7f-2789e4e5089a", "code": "SCI", "title": "Science Hall", "hedmHistory": [ { "date":"2002-01-13", "status":"FT", "level":7 }, { "date":"2000-12-06", "status":"PT", "level":5 } ]}

hedmHistory is an example of JSON text; the value stored in the database is actually '[{"date":"2002-01-13","status":"FT","level":7},{"date":"2000-12-06","status":"PT","level":5}]' and all parsing and construction of the JSON text is left up to the client implementation.



Sample GORRSQL

Samples to read and write from Banner tables and the SDE.

Read from a Banner table

Sample GORRSQL to read from a Banner baseline table.

---- SQL used to extend the buildings model. Data will be selected from-- the list of guids passed in the GUID_LIST parameter. The result set-- must contain a column named GUID for matching the extended data to-- the correct model entry.--select gorguid_guid as guid, slbbldg_maximum_capacity, sysdate as wall_clock from gorguid, slbbldg where gorguid_ldm_name = gokhedm.f_buildings and gorguid_domain_surrogate_id = slbbldg_surrogate_id and gorguid_guid in (:GUID_LIST)

Read from the SDE

Sample GORRSQL to read from the SDE.

---- SQL used to extend the buildings model. Data will be selected from-- the list of guids passed in the GUID_LIST parameter. The result set-- must contain a column named GUID for matching the extended data to-- the correct model entry.--select gorguid_guid as guid, sys.anydata.accessVarchar2(g1.gorsdav_value) as HEDM_BLDG_LANDMARK, sys.anydata.accessNumber(g2.gorsdav_value) as HEDM_BLDG_ROOM_COUNT, sys.anydata.accessDate(g3.gorsdav_value) as HEDM_BLDG_CONSTR_DATE



from gorguid g, slbbldg s, gorsdav g1, gorsdav g2, gorsdav g3 where gorguid_ldm_name = gokhedm.f_buildings and g.gorguid_domain_surrogate_id = s.slbbldg_surrogate_id and g1.gorsdav_table_name(+) = 'SLBBLDG' and g2.gorsdav_table_name(+) = 'SLBBLDG' and g3.gorsdav_table_name(+) = 'SLBBLDG' and g1.gorsdav_attr_name(+) = 'HEDM_BLDG_LANDMARK' and g2.gorsdav_attr_name(+) = 'HEDM_BLDG_ROOM_COUNT' and g3.gorsdav_attr_name(+) = 'HEDM_BLDG_CONSTR_DATE' and g1.gorsdav_pk_parenttab(+) = s.slbbldg_bldg_code and g2.gorsdav_pk_parenttab(+) = s.slbbldg_bldg_code and g3.gorsdav_pk_parenttab(+) = s.slbbldg_bldg_code and gorguid_guid in (:GUID_LIST)

Write to a Banner table

Sample GORRSQL to write to a Banner baseline table.

---- Anonymous PL/SQL block used to update fields in the buildings-- model. The specific model to be updated is identified by the GUID-- passed in the GUID parameter. The HTTP_METHOD parameter will indicate-- the HTTP method (POST,PUT,DELETE) for which this SQL is called.--begin if :HTTP_METHOD in ('POST','PUT') then if :SLBBLDG_MAXIMUM_CAPACITY != dml_common.UNSPECIFIED_NUMBER then update slbbldg set slbbldg_maximum_capacity = :SLBBLDG_MAXIMUM_CAPACITY, slbbldg_activity_date = SYSDATE where slbbldg_surrogate_id = (select gorguid_domain_surrogate_id from gorguid where gorguid_ldm_name = 'buildings' and gorguid_guid = :GUID); end if; end if;end;



Write to the SDE

Sample GORRSQL to write to the SDE.

---- Anonymous PL/SQL block used to update fields in the buildings-- model which reside in SDE. The specific model to be updated is identified by the GUID-- passed in the GUID parameter. The SDE fields updated in this example are-- HEDM_BLDG_LANDMARK, HEDM_BLDG_ROOM_COUNT, and HEDM_BLDG_CONSTR_DATE.--DECLARE CURSOR rowid_c (p_guid VARCHAR2) IS SELECT s.rowid FROM gorguid g, slbbldg s WHERE g.gorguid_ldm_name = gokhedm.f_buildings AND g.gorguid_domain_surrogate_id = s.slbbldg_surrogate_id AND g.gorguid_guid = p_guid; lv_rowid VARCHAR2(18); lv_result VARCHAR2(500); lv_pk gorsdav.gorsdav_pk_parenttab%TYPE; lv_anydata SYS.ANYDATA;BEGIN OPEN rowid_c(:GUID); FETCH rowid_c INTO lv_rowid; CLOSE rowid_c; IF :HTTP_METHOD IN ('POST','PUT') THEN select gp_goksdif.f_get_pk("SLBBLDG", lv_rowid) into lv_pk from dual; IF :HEDM_BLDG_LANDMARK != dml_common.UNSPECIFIED_STRING THEN lv_anydata := SYS.ANYDATA.convertVarchar2(:HEDM_BLDG_LANDMARK); lv_result := gokhedm.f_save_sde_data(p_table => 'SLBBLDG', p_column => 'HEDM_BLDG_LANDMARK', p_rowid => lv_rowid, p_pk => lv_pk, p_value => lv_anydata); END IF; IF :HEDM_BLDG_ROOM_COUNT != dml_common.UNSPECIFIED_NUMBER THEN lv_anydata := SYS.ANYDATA.convertNumber(:HEDM_BLDG_ROOM_COUNT); lv_result := gokhedm.f_save_sde_data(p_table => 'SLBBLDG', p_column => 'HEDM_BLDG_ROOM_COUNT', p_rowid => lv_rowid, p_pk => lv_pk, p_value => lv_anydata);



END IF; IF :HEDM_BLDG_CONSTR_DATE != dml_common.UNSPECIFIED_DATE THEN lv_anydata := SYS.ANYDATA.convertDate(:HEDM_BLDG_CONSTR_DATE); lv_result := gokhedm.f_save_sde_data(p_table => 'SLBBLDG', p_column => 'HEDM_BLDG_CONSTR_DATE', p_rowid => lv_rowid, p_pk => lv_pk, p_value => lv_anydata); END IF; END IF;END;


Extensibility with MEP

Extensibility with MEPThe way that Extensibility is configured for Multi-Entity Processing (MEP) enabled institutionsdepends on the way that extension rules are setup across the institutions.

Banner Ethos API Extensibility is MEP compliant. Data that is read, created, updated, or deleted inthe database through extensibility rules on GORRSQL will be based on the institution code that ispresent on the URL. It is possible to have different extensibility configurations for each institutioncode; however, most institutions will use the same extension rules across all institution codes.

If you will use the same extensibility rules for all institutions, no additional configuration for MEP isneeded. If you need to use different extensibility rules for each of your institutions, and you havealready MEP-enabled the Extensibility database, you will need to MEP-enable the GURAPEX(Extension Definition) extensibility configuration table.

The GORRSQL table is seldom MEP-enabled, therefore the GORRSQL rules referenced onGURAPEX must be either named to differentiate between the various institution codes, or bewritten to interrogate the current institution code and take different actions for each institution code,depending on whether logic is differentiated by differently named GORRSQL rules, or within a singleGORRSQL rule that has logic to retrieve the institution code, and perform different logic based onthat code.

If you decide to retrieve the institution code in your GORRSQL rule, use the g$_vpdi_security.g$_vpdi_get_proc_context_fnc function.


Troubleshooting

TroubleshootingUse the checklist to troubleshoot extensibility configuration issues.

When configuring extensions, you should first create your SQL on GORRSQL, as that will determinewhat you need for your extension-definitions. Next, use a REST utility to create your extension-codeas it is required for both extension-definitions and extension-versions. Then create your extension-definitions for each column (other than GUID) that is returned by the SQL. Finally, create one ormore extension-version records depending on how many different representations of a resource areto be extended.

If your configured extensions fail to appear in the response, go through the following checklist:

1. Verify that your READ and WRITE SQL on GORRSQL is validated and active. SQL that has notbeen validated or is not active is ignored.

2. All GORRSQL parameters referenced in WRITE SQL must be coded using all uppercasecharacters.

3. Try manually running the GORRSQL you created to make sure it executes properly. Eithermanually enter a list of valid GUIDs or remove the part of the where clause that references theGUID_LIST parameter.

4. Verify that your extension-definition is configured correctly.

a. The columnName must be specified using all uppercase characters as that is how it will beextracted from your GORRSQL results.

b. The sqlProcessCode and sqlReadRuleCode must by uppercase and match theGORRSQL_SQPR_CODE and GORRSQL_SQRU_CODE of your SQL on GORRSQL.

c. The jsonPropertyType must match the data type of the column in the Banner database.5. Verify that your extension-version is configured correctly.

a. The knownMediaType must be exactly the same as the x-media-type header returned froma GET request.

b. Create separate extension-version records for each unique media type representation thatyou want extended for a resource.

c. The x-media-type header will always be returned as a fully versioned value. It is notnecessary to create a record for application/json as it always gets resolved to a fullyqualified media type version.

6. Multiple SQL statements can be specified for a single GORRSQL process and rule code ifretrieving data from Banner is too complex to be executed using a single SQL statement.

a. Each SQL will have a unique sequence number and they are executed in order (providedeach has been validated and is active).

b. Using a UNION ALL in a single SQL statement is usually more efficient than executingmultiple SQL statements to retrieve the same data.


Documents

Banner Ethos API Extensibility - Fairmont State University · not limited to any one single Ellucian application. The Ellucian Ethos Data Model is a platform technology component