A data domain (domain) is a defined grouping of data properties to allow the users to view the data with a perspective that highlights the particular properties of the data. The domain defines the model schema (model) and other properties for that specific focus. Common examples of data domains are customers, students, employees, parts and product orders.
...
The master data for a domain can be stored either as:
CENTRALIZED When the domain master data is centrally stored in YOUnite. This is used when the entire organization is comfortable or mandated to migrate a domain to a single store. Central stores are optimal for reference data such as a list of states countries, zip-codes, etc.
...
The first step in creating a domain is to define the domain name, its type and the owning zone (Although you will have to define the name of the new domain, if you do not define the type and owning zone, then YOUnite will be do it for you by default):
POST /domains
Code Block | ||
---|---|---|
| ||
{ "name": "<domain-name>", "zoneUuid": "<owning_zone_uuid>", "domainType": "<domain-type>" } |
...
property | required | valid values | description |
---|---|---|---|
name | yes | Must 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. |
zoneUuid | no | Owning zone's domain UUID | TODO ROBBIE: The zone that the domain, the domain's versions and its MDRs 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. |
domainType | no | MASTER_CENTRALIZED or MASTER_FEDERATED | The domain type which can be either: MASTER CENTRALIZED (default TODO ROBBIE - still?) When Is when the domain's master data is centrally stored in YOUnite. This is used when the entire organization is comfortable or mandated to migrate a domain to a single store. Central stores are 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* |
...
With the domain in place, its first version can be created. The domain version defines the properties that make up the domain version's model. You may want to create a new version if you want to add more properties to the model, for instance. The domain version numbers are automatically generated and start with 1 and continue in ascending order. The root node of the model schema is the properties
element. See Data Domains and Multi-Domain MDM and Data Domains and Multi-Domain MDM below.
...
- POST the Domain
- POST a Domain Version
- POST (or Map if it was federated data domain) the Master Data
POST the Domain
For example, to create a simple states a simple "states" domain :
POST /domains
Code Block language js { "name": "states", "zoneUuid": "a1aca070-846f-44e5-9471-c73b46c35f4a", "domainType": "MASTER_CENTRALIZED" }
The location header returned provides the URI for POSTing a domain version below.
e.g.
Location /domains/7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc
POST a Domain Version
POST /domains/versions/
7f28180b-7d9f-42b5-b5ed-d4a0e7ec09fc
Code Block language text { "displayProperty": "abbreviation", "uniquenessRules": "abbreviation", "modelSchema" { "properties": { "name": { "type": "string", "min": 2, "max": 80, "required": true }, "abbreviation": { "type": "string", "min": 2, "max": 2, "required": true } } } }
POST Master Data Records to the Domain
Once the domain/version has been created, master data can be POSTed to it using the /mdr endpoint:POST /mdrs
Code Block language js { "name": "states", "version": 1, "json": { "name" : "California", "abbreviation" : "CA" } }
Retrieving Master Data Records
The MDRs for a the default version of a domain can be retrieved with the following:
...
Each domain must have a display property (displayProperty
). The display property acts as a primary key for the domain. For example, the the "states"
domain above uses the abbreviation
property as the display property, Use the /mdrs
endpoint and the appropriate domain and display property to GET an MDR:
...
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 by using the following:
...
- The value provided for the
displayProperty
must be unique between all domain entries of a given domain type (e.g. each entry in the "state"
domain must have a uniquestateName
). - Only one property in a domain can be the
displayProperty. I
f more than one property is required to ensure uniqueness see the Data Domains and Multi-Domain MDM below. - Display properties are limited to type STRING.
- Properties designated as the
displayProperty
are required; i.e. null values are not allowed. - Display properties are case sensitive e.g. "California" is NOT equal to "california".
...
- MDM provides uniqueness rules for MDR duplicate 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 for the domain.
- If not provided, MDM will use the
displayProperty
as theuniquenessRules
. - Uniqueness rule properties are limited to type STRING
- Values in
uniquenessRules
properties are compared case sensitively sensitive e.g. "California" is NOT equal to "california"
...
- Must start with a letter or "\_" (underscore).
- Can contain digits, "-" (dash) and "\_" (underscore) only.
- Can be up to 64 characters in length.
- Are case in-sensitive.
- If two properties have the same name at the same level only one will be used. In the Example 1 below, only one name "property" will be used. In Example 2, both will be used ( because "
name"
occurs at different levels in the JSON structure):.
Code Block | ||
---|---|---|
| ||
{ "properties": { ... "name": {...}, "city": {...}, "state": {...}, "name": {...}, ... } } |
...
A container-node item is a node that contains sub-properties. For example, "address"
is a container node with the sub-items city
and items "city"
and "state
."
Code Block |
---|
{ "properties": { ... "address": { "city": {...}, "state": {...} } } } |
...
Property | Description |
---|---|
required | A non-null value for this item must be provided (false by default). Items inside the container-node canoverride the parent container node's required setting. |
...
String
A string of characters variable. The following properties are applied when data is posted for this item:
Property | Description |
---|---|
min | Minimum string length. |
| Maximum string length. |
regex | String must match the regex pattern. |
default | If the item is not provided or is null, the default value is used. |
required | A non-null value for this item must be provided (false by default). |
...
Int
A numeric, whole number.
Property | Description |
---|---|
min | Minimum value allowed. |
| Maximum value allowed. |
default | If the item is not provided or is null, the default value is used. |
required | A non-null value for this item must be provided (false by default). |
...
Number
A numeric, decimal number with up to 15 bits of precision.
Property | Description |
---|---|
min | Minimum value allowed. |
| Maximum value allowed. |
default | If the item is not provided or is null, the default value is used. |
required | A non-null value for this item must be provided (false by default). |
...
Boolean
A booleanBoolean, allowing only the two values of true
or false
Property | Description |
---|---|
default | If the item is not provided or is null, the default value is used. |
required | A non-null value for this item must be provided (false by default). |
...
Enum
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 in another domain.
Property | Description |
---|---|
enumType | Types of enums:
|
xrefLocation | If For example, if a version of a domain "countries"contains a list of MDR values that represent all countries then a domain can reference it by specifying an enumeration type of
A subset of the MDR values in the domain can be specified using the |
data | An array containing a comma separated list of enum values e.g.
Is a three-item string enumeration. If the
Assuming the display values for Canada, the United States and Mexico are those shown above in the data elements. |
default | If the item is not provided or is null, the default value is used. |
required | A non-null value for this item must be provided (false by default). |
...
URI
A properly formed Uniform Resource Locator (URI). By default, a property of type uri
can be any valid URI or it can be limited by a regex pattern or to a domain cross-reference (xrefLocation: "xref").
...
Property | Description |
---|---|
uriType | The uri type (e.g. url, blob, xref). |
| The location of the domain item or domain item data element. Used in conjunction with "uritype": "xref" . |
regex | String must match the regex pattern. |
default | If the item is not provided or is null, the default value is used. |
required | A non null value for this item must be provided (false by default). |
...
Array
An array can contain any type of value including nodes and nested arrays.
...
- If a domain property has a
default
value defined in itsmodelSchema
, then any domain MDR posted will use the default value if the property is either does not include a value or is sent in with a null value.
For example, if a domain named named "College"
contains a model schema
with a property StateAbbreviation
with a default
value of "CA"
,
then any college posted to the College
domain without the StateAbbreviation
property or with StateAbbreviation
set with a null value, will use the default value "CA"
.
- If a domain property has
required
set totrue
, then a valid non-null value must be posted for it (by defaultrequired
is set tofalse
).
...
Following is a simple example of a model for a domain version.
...