This document can extend to document other supported entities. 

 

 

Entity -  person, instutional contact,  code client (thing calling api), service/priviledged acct, IOT(device), etc. 

Each will have a unique identifier assigned to identify it for use in the IAM architecture to uniquely know this “thing” from all other “things” .  This requires a high level structure in the data to provide uniqueness for all entities.

 

1.       Entity ID – (used internally only, UUID type of value)

2.       Entity Type Code

3.       Date begin

4.       Date End

5.       Entry Description            

6.       Status (suspect, merged, active)

7.       Institutional Identifier (externalized use)

8.       Object Maintenance Fields

a.      Definition – Internal processes maintain these fields on the data object to support logging, auditing and change data capture.  This can be applied to each field or the any object.  Discussion topic for group.

b.      Attributes:

                                                               i.      Begin Time Stamp

                                                             ii.      End Time Stamp

                                                            iii.      Update User ID:

1.       Recommendation is use a federate-able identifier or the entity ID  in preparation for support application federation with partner organizations.

 

Entity Type: person

Note: (we can also define client as Jim Fox has worked on once we move through this as a different entity type)

·         Person:  Attributes:

·         Preferred Language

o   Definition – Spoken and written language that the person prefers

o   Requirement(s) -- must exist in code table xxx; use a spreadsheet for list of code table values

·         Protect/Secured

o   Definition – Person information is publically accessible

o   Requirement(s)  – Allowed values are “Y” or “N”

o   Additional Information - Person information may not be public because of person preferences or for legal protection reasons.   There are persons with specific security roles that have access to Protect/Secured information.  Specific roles have maintain authority Protect/Secured.

·         Active, Inactive and Pending Status

o   Definition – The state of the Person record for usage by authoring systems

o   Requirement(s)  – value must exist in code table

o   Additional Information:

§  “Pending” indicates that an identity resolution event is underway

§  “Inactive” indicates that the record did not survive the collapse process

§  “Active” indicates that the record is to be used for common business usages

 

·         Primary EduPerson Affiliation

o   Definition – Describes an affiliation relationship of person to institutional that is determined to be the one that the Person is most associated with for the public point of view.   The Primary Affiliation is a calculated value that is determined from the institutional Affiliations of Person.    

o   Requirement(s):

o   A Person can have only 1 Primary Affiliation

o   Calculate the value on each change of an institutional Affiliation on Person

o   Additional Information:

o   Primary Affiliations are groups of institutional Affiliations.

o   Primary Affiliation EduPerson values:

§  Faculty

§  Staff

§  Employee

§  Student

§  Member

§  Alumni

§  Affiliate

 

·         Primary Department

o   Definition – “The Primary Department ID is an organizational ID value that is determined for each person through a calculation based on the institutional affiliations and related rule set.  Primary department is the department value that the individual has been determined to be “most” identified with for the IAM point of view.” 

o   Requirement(s):

o   A Person can have only 1 Primary Department

o   Calculate the value on each change of an institutional affiliation on Person

·         Affiliation   (Occurs multiple per Person entity (0-M) )

o   Institutional Affiliation Type Code

§  Definition – Relationships of Person to institution at the most granular level; referred to as institutional Affiliations in this document

§  Requirement(s) -- Must exist in code table xxx

§  Additional Information:

·         institutional Affiliations roll up to one or both of the following hierarchical parent Affiliation types:

o   EduPerson Primary Affiliation

o   EduPerson Affiliations

o   Affiliation Owner

·         institutional Affiliations are set members of 1 and only 1 Primary Affiliation and/or 1 and only 1 EduPerson Affiliation and 1 and only 1 Affiliation Owner

·         On maintain request that includes institutional Affiliation:

o   Department ID is a parameter on the request and must have a value; see Department ID below

o   Affiliation End Date is a parameter on the request and the value can be null; see Affiliation End Date

§  Notification – Send on maintain (Add/update)

§  Special Logic:

·         Change of institutional Affiliation on Person initiates multiple event/logic processes

·         Possible following sections within “Affiliation Event/Logic Requirements” for the special processing is required on each change of institutional Affiliation on Person: (these are examples)

o   Primary Affiliation

o   Primary Department

o   Affiliation End Date

o   Affiliation Mutual Exclusivity

o   Pre-Existing Affiliations

o   Affiliation Visibility

o   Affiliation Ownership Types Used in Conjunction with registry Validation Services

·           Department ID

o   Definition – Department ID from the application that is assigned to the combination of Person and Affiliation

o   Requirement(s)

§  Must exist in code table

§  Required field on maintain request for Affiliation; cannot be null

·         Affiliation Start Date

o   Definition – Date that indicates when the institutional Affiliation becomes active

o   Requirement(s):

§  Date value on maintain request can be null; registry defaults to the current timestamp

§  Date value when passed on maintain request, conforms to date standards

§  Date value can be changed by a maintain request

§  Date value can be in the past, equal to, or in the future from the current date

·         Affiliation End Date

o   Definition – Date that indicates when the institutional Affiliation becomes inactive

o   Requirement(s):

§  Date value can be null except for the following condition(s) where a date value must be passed on the maintain request with the institutional Affiliation:

§  Affiliation Owner = “1.  Anyone”

§  Date value when passed on maintain request, conforms to date standards

§  Date value can be in the past, equal to, or in the future from the current date

§  Date value can be no more than (limited time frame) month/years into the future

§  Date value on an existing institutional Affiliation on Person can be changed

§  Date value must be greater than the Affiliation Start Date

§  On Mutually Exclusive Affiliations, the following logic applies:

·         If there is an active institutional Affiliation in the set

·         if setting the Affiliation End Date breaks the above rule for the Affiliation End Date to be greater than the Affiliation Start Date, then the maintain request is failed and the response is an error message.  It will be up to the submitter to correct the situation.

 

·         Object Maintenance Fields -- See “Contact /Person Object Maintenance Fields” for requirements.

·         PersonName  (Two name type proposed, Legal is required)

o   Name type= Legal

§  Legal Name Prefix

·         Definition –

·         Requirement(s):

o   Optional – Nulls allowed

§  Legal Name First Name

·         Definition –

·         Requirement(s):

o   Value is required

o   Fail transaction if null

§  Legal Name Middle Name

·         Definition –

·         Requirement(s):

o   Optional – Null allowed

§  Legal Name Last Name

·         Definition –

·         Requirement(s):

o   Value is required

o   Fail transaction if null

o   1st position must be a capitalized alphabetic character

§  Legal Name Suffix

·         From a code Table

§  Full Legal Name

·         Definition –

·         Requirement(s):

o   Value is calculated

o   String together Legal Name components as follows:  “Last, First MI S suffix”

·         Additional Information:

o   Change authorization is tightly controlled for components of Legal Name

o   Name type= Display Name

§  Processing suggested rule:

·         Use supplied value on Add/Maintain

·         Use Legal Name if value is not provided on Add

 

§  Prefix Type Code

·         Definition –

·         Requirement(s) – Value must exist in code table

§  Prefix Description

·         Definition –

·         Requirement(s)  – Value must exist in code table

§  Name Usage Type Code

·         Definition –

·         Requirement(s)  – Value must exist in code table xxx

§  Given Name 1-4

·         Definition –  Given Name 1 is required

·         Requirement(s):

o   Accept any text value

o   1st position must be a capitalized alphabetic character

§  Last Name

·         Definition –

·         Requirement(s) :

o   Accept any text value

o   1st position must be a capitalized character

§  Suffix Type Code

·         Definition –

·         Requirement(s)  – Value must exist in code table

§  Full Display Name

·         Definition –

·         Requirement(s):

·         Value is calculated

·         String together Display Name components as follows:  “Last, First MI Suffix”

§  Object Maintenance Fields -- See “Contact /Person Object Maintenance Fields” for

 

·         IDENTIFIERS

o   I have used a bunch of examples (these can vary per institution)

·         Identifier Type Code

o   Entity Owned

·         Those that belong to the individual – person brought into  institution

§  SSN – Government reported invalid SSNs are not to be accepted; Character

§  Passport – Collected in 2 pieces:  passport ID no. concatenated with 2 digit country code; format is a concatenation of country code and Passport

·         Code table with a listing of countries

·         Store expiration date from passport in an expiration date

§  Driver's License Number (out-of-box registry) – no special editing

·         Store expiration date from driver’s license in an expiration date

o   SOR owned

·         Those that are SOR level (recommended strongly for all SOR with a referenceable indetifier)

§  ORCID  --  needs to be provided by the ORCID organization; there is a format that is required;

§  ERA Commons ID -- no special editing; for National Institute of Health

§  NSF -- no special editing; National Science Foundation

§  VIAF -- no special editing; Virtual International Authority File

§  ID Card NO – no special editing; card ID for a  person

§  Library ID  -- no special editing; Library Number

§  Door Badge ID-- no special editing; SOR is ID card interface

§  “ANY SOR ID” -  extend as needed for HR, SIS or whatever

 

o   Access management identifiers (USERIDs various net id local or federated)

§  Institutional Identifier (only required identifier)

§  Net ID         -- no special editing;

§  EPPN – Multiple occurrences of this identifier is allowed

§  Etc as needed 

·         Object Maintenance Fields – set values of Begin Time Stamp, End Time Stamp, Update User ID

 

·         CONTACT METHOD /  EMAIL

o   Contact Method Type Code – EMAIL

§   value must exist in code table Email Address

§  --  Basic email rules

o   Email Address

o   Email validate source – EMAL_VALIDATE_SRC and EMAL_VALIDATE_TS, when self-service calls the API, then attributes are updated; self-asserted validation by the user person themselves that the email is valid; EMAL_VALIDATE_SRC is  institutionID, EMAL_VALIDATE_TS is date/time of update; the meaning of these fields is that the person has logged onto institution self service and clicked the box that “Yes”, the email value is correct; the values can be null until the email is validated Identify the preferred email

o   Object Maintenance Fields – set values of Begin Time Stamp, End Time Stamp, Update User ID

 

·         CONTACT METHOD / TELEPHONE

o   Contact Method Type Code – value must exist in code table Phone

§  Basic Phone Rules apply

o   Device Type – Maintain the type of device (example types are Wired and Cell)

o   Telephone Number – Full number is to be stored

o   Verified Phone Number Indicator  -- indicates that the phone number has been verified Components of Telephone Number are to be stored in PHONENUMBER

§  Country Code

§  Area Code

§  Telephone Number

§  Device Type

§  SMS Capable

§  Secure Text Capable

o   Telephone validate source – TELE_VALIDATE_SRC and TELE_VALIDATE_TS, when self-service calls the API, then attributes are updated; self-asserted validation by the user person themselves that the telephone is valid; TELE_VALIDATE_SRC is   institution id, TELE_VALIDATE_TS is date/time of update; the meaning of these fields is that the person has logged onto My institution self service and clicked the box that “Yes”, the telephone value is correct; the values can be null until the telephone is validated (documented on 01/26)

o   AUTONUM

§   field are to be stored as “+1 country code telephone number”

§  Identify the preferred telephone number or email

§  Requirements for automating SMS etc services (Twilio, etc)  telephone number standardization processes are encouraged. 

o   Object Maintenance Fields – set values of Begin Time Stamp, End Time Stamp, Update User ID

 

 

Organization/Department Code: Code table for org/departments in the registry

·         Organization Type Code

o   Definition – Defines the organization type

·         Organization Code

o   Definition – Defines the organization Code value

·         Organization Description

o   Definition – Name / description of organization Code

·         Object Maintenance Fields  -- See “Contact /Person Object Maintenance Fields” for requirements