Versions Compared

Old Version 69

changes.mady.by.user Mark Fitzpatrick

Saved on

compared with

New Version 70

changes.mady.by.user Mark Fitzpatrick

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Once a version of a domain is created and its  data records (DRs) are loaded (or mapped in a federated model), it can be referenced by other data domains, adaptors and by API consumers as a source of truth. Domains have version numbers so that other domains, adaptors and applications can bind to a specific domain and version (e.g. students:v3). Data governance can designate data at specific adaptors as the master data and can control who has the appropriate ACLs to access and update it.

Domain Types

The master data records for a domain can be stored either as:

YOUnite Data Store: When the domain master data is records are stored in YOUnite. This is used when the entire organization is comfortable or mandated to migrate a domain to a single store. The YOUnite data store is optimal for reference data such as a list of states countries, zip-codes, etc. 

Federated domains do not store their data centrally in YOUnite but retrieve and update the data on the systems in which it resides.  For example, MIS, ERP or CRM systems. Federated domains require adaptors and metadata and scope configurations and are covered in detail *TODO: TUTORIAL ON FEDERATED*

...

propertyrequiredvalid valuesdescription
nameyesMust be at least 3 characters long but no longer than 128.The domain name. Must be unique to the entire YOUnite deployment since domains are typically shared. TODO NEED SOME DESCRIPTION OF VALID CHARACTER PARAMETERS.
zoneUuidnoOwning zone's domain UUIDTODO ROBBIE: The zone that the domain, the domain's versions and its MDRs data records will be tied to. If this is omitted the caller's current zone will be used. Note that the caller must have permissions to create a domain for the zone.
domainTypenoMDM_DATA_STORE or MASTER_FEDERATED

The domain type can be either:

MDM_DATA_STORE (default TODO ROBBIE - still?) Is when the domain's master data is records are stored in YOUnite. This is used when the entire organization is comfortable or mandated to migrate a domain to a single store. MDM_DATA_STORE is optimal for reference data such as a list of states, countries, zip-codes, etc. 

MASTER FEDERATED domains do not store their data centrally in YOUnite, but reference and update data on the systems in which it resides. Federated domains require adaptors and metadata and scope configurations and are covered in detail *TODO: TUTORIAL ON FEDERATED*

...

For example, we'll create a centralized MDM_DATA_STORE data domain and load one MDRdata record:

  1. POST the Domain
  2. POST a Domain Version
  3. POST (or Map if it was federated data domain) the Master Data record


  1. POST the Domain 

    For example, to create a simple "states" domain :

    POST /domains

    Code Block
    languagejs
    {
	"name": "states",
	"zoneUuid": "a1aca070-846f-44e5-9471-c73b46c35f4a",
	"domainType": "MASTERMDM_DATA_CENTRALIZEDSTORE"
 }

    The location header returned provides the URI for POSTing a domain version below.

    e.g.

    Location /domains/7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc

  2. POST a Domain Version

    POST /domains/versions/7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc

    Code Block
    languagetext
    {
	"displayProperty": "abbreviation",
	"uniquenessRules": "abbreviation",
	"modelSchema" {
		"properties": {
			"name": {
				"type": "string",
				"min": 2,
				"max": 80,
				"required": true
			},
			"abbreviation": {
				"type": "string",
				"min": 2,
				"max": 2,
				"required": true
			}
		}
	}
}



  3. POST

    Master

    Data Records to the Domain

    Once the domain/version has been created, master data records can be POSTed to it using the /mdr dr endpoint:

    POST /mdrsdrs

    Code Block
    languagejs
    {
	"name": "states",
	"version": 1,
	"json": {
		"name" : "California", 
		"abbreviation" : "CA"
	}
 }


Retrieving

...

Data Records

The MDRs data recordds for a the default version of a domain can be retrieved with the following:

POST /mdrsdrs?filters=name:<domain-name>

Retrieving the MDRs data records for a given domain and version:

POST /mdrsdrs?filters=name:<domain-name>,version:<version>

...

Each domain must have a display property (displayProperty). The display property acts as a primary key for the domain. For example, the "states" domain above uses the abbreviation property as the display property, Use the /mdrsdrs endpoint and the appropriate domain and display property to GET an MDRa data record:

GET /mdrsdrs?filters=name:states,displayProperty:CA

If there are multiple versions of a domain, and a domain other than the default is needed, the version number can be included in the URI. For example, assume there are three versions of the "states" domain and the current version is version 3. The consumer can retrieve the California version 1 MDR data record by using the following:

GET /mdrsdrs?filters=name:states,version:1,displayProperty:CA

...

Uniqueness Rules

  • MDM provides uniqueness rules for MDR duplicate rules to prevent data record duplication prevention in the case where a simple displayProperty won't suffice.
  • Optionally, specify a comma-separated list of domain properties whose values, in aggregate, must be unique across all the MDRs data records for the domain.
  • If not provided, MDM will use the displayProperty as the uniquenessRules.
  • Uniqueness rule properties are limited to type STRING
  • Values in uniquenessRules properties are case sensitive e.g. "California" is NOT equal to "california"

...

Enumerations (enums) can be either a primitive type (string, int, or a number) or, a cross-reference to an entire set or subset of MDRs data records in another domain.

PropertyDescription
enumType

Types of enums:

  • int: A numeric whole number.
  • number: A numeric, decimal number with up to 15 bits of precision.
  • string: A string of character variables. 
  • uri: A cross-reference to another domain; use in conjunction with xrefLocation.
xrefLocation

If enumType is set to uri then xrefLocation points to the domain that makes up the elements of the enumeration.

For example, if a version of a domain "countries"contains a list of MDR data record values that represent all countries then a domain can reference it by specifying an enumeration type of uri and the desired domain and version number:

enumType: uri

xrefLocation: /domains/countries:v1

A subset of the MDR data record values in the domain can be specified using the data property.

data

An array containing a comma separated list of enum values e.g.

"data":["Mays", "McCovey", "Marichal"]

Is a three-item string enumeration.

If the enumType is uri the list of values in the xrefLocation can be limited to the subset of MDRs data records whose display values contained in the data array. For example, if /domains/countries:v1 contains a list of all countries but the domain should only reference countries in North America, then the data entries would be:

"data":["CANADA", "USA", "MEXICO"]

Assuming the display values for Canada, the United States and Mexico are those shown above in the data elements.

defaultIf the item is not provided or is null, the default value is used.
requiredA non-null value for this item must be provided (false by default).

...

See type enum and the data property to limit the cross-reference to a subset of the domain's MDRs data records (e.g. if a domain Company exists of all Global 1000 companies, an enumeration of EU_Companies could be created referencing only the Global 1000 companies in the European Union).

...

  • If a domain property has a default value defined in its modelSchema, then any domain MDR data records posted will use the default value if the property either does not include a value or is sent in with a null value.

...