Breaking Changes
Overview
This document provides technical details of the change to Altrata Role ontology to allow a single disclosed committee to be associated with multiple structured committee categories, and to make that structured categorisation available in the Altrata Data Feed.
The change requires migration by Data Feed customers.
Audience
This document is intended for use by customer developers who will perform the technical migration from deprecated schema to new schema.
What is Changing and Why
Scenario: A Role at an Organization on a committee whose disclosed name covers more than one committee function. For example, a Role on a "Nominating & Corporate Governance Committee" - a single disclosed committee that performs both a nominating function and a corporate governance function.
Current Altrata Data: Altrata records the disclosed committee name, as reported by the Organization, in role_group. Altrata also holds a structured categorisation of that committee, role_group_category, which normalises disclosed names into consistent Altrata categories.
The disclosed committee name is available today in both delivery channels. The structured categorisation is not currently available in either channel:
- Data Feed. role_group_category is not part of the Data Feed model. The disclosed name is available as role_group on the roletitlecategory table.
Internally, Altrata has held this categorisation against a structure that permits only one category per disclosed committee. That constraint is the reason a new structure is required rather than an extension of the existing one, and is covered under What is Being Added below.
Improved Altrata Data
Improved Altrata Data: The structured categorisation is being made available, and it carries every category a disclosed committee belongs to rather than a single one.
- role_group = "Nominating & Corporate Governance Committee"
- role_group_category = ["Nominating Committee", "Corporate Governance Committee"]
What Does This Resolve?
Customers can retrieve every Role belonging to a structured committee category, regardless of how the committee was disclosed by the Organization, without maintaining their own list of name variants. Committee coverage on Person and Organization profiles becomes complete and consistent.
Impacted Products
- Datafeed
- Datafeed - SFTP
- Datafeed - Snowflake
- Datafeed - Delta Sharing
- Datafeed - S3
Datafeed
The following diagram shows the key Altrata Data Feed tables impacted by this change, and the deprecated and new data columns.
SFTP, Snowflake & S3 Data Model Change Detail
Change 1 - Role Group Category
We are adding the below table/view.
This table/view replaces the deprecated role_group column on the roletitlecategory table/view.
This change impacts the rolegroupcategory across below two schemas:
- professionalcore
- wealthcore
Change 2 - Role Group Reference
We are adding the below column to the roletitlecategory table/view.
This change impacts the roletitlecategory across below two schemas:
- professionalcore
- wealthcore
Change 3 - Announcement Role Group Reference
We are adding the below column to the announcementroletitlecategory table/view.
This column replaces the deprecated announcement_role_group column on the announcementroletitlecategory table/view.
This change impacts the announcementroletitlecategory across below two schemas:
- professionalcore
- wealthcore
Example SQL Queries - Before and After
Scenario
Find all Current Roles on a Compensation Committee at Organisation Microsoft Corporation
Currently the structured committee category is not available in the Data Feed. The only committee data point available is the disclosed committee name, roletitlecategory.role_group, so the query must match against every disclosed name variant that represents a compensation committee.
Use rolegroupcategory.role_group_category='Compensation Committee' to return all Roles on a compensation committee, regardless of the disclosed committee name.
Overview
This document provides technical details of the change to Altrata Role ontology to combine separate but concurrent Employment and Board Roles into a single Role, for a given Person at a given Organization.
Audience
This document is intended for use by customer developers who will perform the technical migration from deprecated schema to new schema.
What is Changing, and Why?
Scenario: A Person that has a Role at an Organization with both a board and employment component to the Role. For example, A CEO that also sits on the Board of Directors. This is known as an Executive Directorship.
Current Altrata Data: This scenario is currently represented in Altrata data as two separate Role data records (with two distinct unique identifiers). Each Role has a single Role Type - one with Type Board and the other with Type Employment. The current relationship cardinality between Role and Role Type is one-to-one.
Why is this a problem?
This causes an issue where Altrata customers cannot search for CEOs that also serve on the Board because these two components of the role are separate in Altrata data. This role duplication also misrepresents the real-world scenario where this is a single Role with two distinct functions, rather than completely distinct Roles.
Improved Altrata Data:
After the data ontology improvement, Altrata will represent this Role as a single Role record with two Role Types - Board and Employment. The new relationship cardinality between Role and Role Type is one-to-many.
What does this solve?
This will let Altrata customers search for CEOs on the board seamlessly and removes duplicates roles from Person and Organization profiles. This provides a consistent and accurate representation of roles that more closely aligns with real world expectations.
Impacted Products
- Datafeed
- Datafeed - SFTP
- Datafeed - Snowflake
- API
Datafeed
Data Model Change Overview
The following diagram shows the key Altrata Data Feed tables impacted by the is change, and the deprecated and new data columns.
Diagram Key
- Red coloured columns will be deprecated
- Green coloured columns are new and replace the deprecated columns
SFTP Data Model Change Detail
Change 1 - Role Type
We are adding the below column to the roletitlecategory table.
This column replaces the deprecated role_type column on the role table.
This change impacts both the following Data Universe/Packages:
- professionalcore
- wealthcore
Change 2 - Announcement Role Type
We are adding the below column to the announcementroletitlecategory table.
This column replaces the deprecated announcement_role_type column on the announcement table.
This change impacts both the following Data Universe/Packages:
- professionalcore
- wealthcore
Snowflake Data Model Change Detail
Change 1 - Role Type
We are adding the below column to the roletitlecategory view.
This column replaces the deprecated role_type column on the role view.
This change impacts the roletitlecategory across below two schemas
- professionalcore
- wealthcore
Change 2 - Announcement Role Type
We are adding the below column to the announcementroletitlecategory view.
This column replaces the deprecated announcement_role_type column on the announcement view.
This change impacts the announcementroletitlecategory across below two schemas
- professionalcore
- wealthcore
Example SQL Queries - Before and After
Scenario
Find all Current Board Type positions at Organisation Microsoft Corporation
Use Role.role_type='Board Function' to filter all Board Type positions
select
p.person_name,o.organization_name,
r.role_id,
r.role_title,
r.role_start_date,
r.role_end_date,
r.role_current_prior_status,
r.role_type
from
role r
left join person p
on r.person_id=p.person_id
and p.record_change_bit<>'D'
left join organization o
on r.organization_id=o.organization_id
and o.record_change_bit<>'D'
where
r.record_change_bit<>'D'
and o.organization_name = 'Microsoft Corporation'
and r.role_current_prior_status = 'Current'
and r.role_type='Board Function'Use Roletitlecategory.role_type='Board Function' to filter all Board Type positions
select
p.person_name,o.organization_name,
r.role_id,
r.role_title,
r.role_start_date,
r.role_end_date,
r.role_current_prior_status,
rtc.role_type,--This is the new column
rtc.role_title_category_id,
rtc.role_title_category_value,
rtc.role_title_category_value_prefix,
rtc.role_group
from
roletitlecategory rtc
join role r
on rtc.role_id=r.role_id
and rtc.record_change_bit<>'D'
left join person p
on r.person_id=p.person_id
and p.record_change_bit<>'D'
left join organization o
on r.organization_id=o.organization_id
and o.record_change_bit<>'D'
where
rtc.record_change_bit<>'D'
and o.organization_name = 'Microsoft Corporation'
and r.role_current_prior_status = 'Current'
API
Person and Organization Profile Details
A new array field will be added to the Role type (roleTypes : [String!]). This will replace the current Role.type field in the Role (type: String) which will be deprecated and phased out over time. The following types reference Role in the schema and any clients reading the type field in the Role type will need to be updated to read from the new roleTypes field:-
- Role
- Person.rolePrimary
- Person.rolesEmployment
- Person.rolesBoard
- Person.rolesCommittee
- Organization.rolesEmployment
- Organization.rolesBoard
- Organization.rolesCommittee
These are available in the response from the following queries:-
type Query {
...
""" Query to return rolesBoard based on filter and pagination."""
rolesBoard(filter: RoleFilterInput!, pageInfo: PageInfoInput): RolesBoardResponse
""" Query to return rolesEmployment based on filter and pagination."""
rolesEmployment(filter: RoleFilterInput!, pageInfo: PageInfoInput): RolesEmploymentResponse
""" Query to return the set of roles within the organization that are part of a committee, providing information about specific roles related to organizational governance, based on filter and pagination."""
rolesCommittee(filter: RoleFilterInput!, pageInfo: PageInfoInput): RolesCommitteeResponse
personIDSearch(id: ID!): PersonIDSearchResponse
""" Query for bulk search of Person IDs."""
personBulkIDSearch(filter: PersonBulkIDSearchFilterInput!, pageInfo: PageInfoInput): PersonBulkIDSearchResponse
""" Query for keyword search of persons."""
personKeywordSearch(filter: PersonKeywordSearchFilterInput!, pageInfo: PageInfoInput): PersonKeywordSearchResponse
""" Query for searching a single Organization by ID."""
organizationIDSearch(id: ID!): OrganizationIDSearchResponse
""" Query for bulk search of Organization IDs."""
organizationBulkIDSearch(filter: OrganizationBulkIDSearchFilterInput!, pageInfo: PageInfoInput): OrganizationBulkIDSearchResponse
""" Query for keyword search of organizations."""
organizationKeywordSearch(filter: OrganizationKeywordSearchFilterInput!, pageInfo: PageInfoInput): OrganizationKeywordSearchResponse
""" Query to perform a detailed search for organization based on advanced filters and criteria, allowing for more refined and specific queries to retrieve organization data."""
organizationSearch(filter: OrganizationSearchFilterInput!, sort: [OrganizationSortInput], pageInfo: PageInfoInput): OrganizationSearchResponse
...
}The schema update is detailed below with the type field being deprecated and replaced by the new roleTypes field.
type Role {
...
""" Denotes the type of a role a person holds i.e. Board Role or Employment Role."""
type: String @deprecated(reason: "Use the roleTypes field instead.")
""" Denotes the all of types of a role a person holds at an organization i.e. Board Role and Employment Role."""
roleTypes : [String!]
...
}The deployment of the changes will take place in the following order with a gap between to allow clients to migrate:-
- The new roleTypes field will be added to the schema with the current Role.type value populated to all existing roles. The current Role.type will be marked as deprecated but will still hold the correct value.
- Altrata roles will be consolidated and where roles at an organization fulfil multiple types they will be replaced with a single role with all types populated in the roleTypes array. The current Role.type will be present in the API but marked as deprecated and contain only one value. If the role types are ["Board Function","Job Function"] the role type will be populated with "Board Function".
Advanced Search
The Person search input will not change (used in the query personSearch). The PersonSearchResult type will contain an additional field with all roleTypes associated with the person results returned. The current roleType field will continue to be returned. As with the approach above it will contain only one value. If the role types are ["Board Function","Job Function"] the role type will be populated with "Board Function" to allow for sorting.
# The input used for the new Person Search query.
type PersonSearchResult @aws_cognito_user_pools {
""" Defines a field that specifies the type or classification of a role as a string, which can be null if not provided."""
roleType: String
""" Denotes the all of types of a role a person holds at an organization i.e. Board Role and Employment Role."""
roleTypes : [String!]
}