Populating Business Metadata
The Herd metadata model includes both technical and business metadata. Technical metadata includes everything publishers and consumers need to use data from processing or analytical tools, i.e. format and physical location.
Business metadata includes everything that data consumers need to discover and understand data, i.e. descriptions, categorization, and contact information. Business metadata is indexed for searching.
A common approach to populating the Herd catalog is to have teams start with the technical metadata and later populate the business metadata. It's also common for different groups to be responsible for populating business vs. technical metadata. For these reasons there are separate endpoints for business metadata. This allows teams to use only technical metadata if they wish and it allows Herd administrators to configure the business metadata endpoints with different permissions.
Here is a list of endpoints that are used to populate business metadata that is directly related to Business Object Definitions (BDefs). The table also lists the location of where the business metadata displays in Herd-UI. When navigating Herd-UI, remember that 'Data Entity' is the business-friendly name for BDef.
| Endpoints | Description | Herd-UI Location |
|---|---|---|
| BDef Descriptive Information Put | Manages Display Name, Description, and a reference to the Descriptive Format | Display Name and Description appear in search results and BDef listings on Category pages. They also appear on the Data Entity page. The Descriptive Format dictates which of the (potentially) multiple Formats is used to display columns on the Data Entity page |
| BDef SME Post/Get/Delete | Manages references to SMEs (subject matter experts) on this BDef. The reference is stored in the form of a userId which is used to look the contact up at runtime. Multiple SMEs can be associated with a BDef. | Contact information for the expert appears on the hight-hand side of the Data Entity page |
| BDef Column Post/Get/Put/Delete | Manages Column Display Name and Column Description for the Descriptive Format. BDefs initially do not have any BDef Columns. When adding BDef Columns, the schemaColumnName must match a Column Physical Name of a column in the Descriptive Format. | BDef Columns appear in the 'Columns' tab of the Data Entity page. Note that a BDef without any BDef Columns will only display technical metadata (right-most columns with Column Physical Name, Datatype). |
| BDef Tag Post/Get/Delete | Manages the association between a BDef and one or more Tags. TagTypes and Tags must be created (see Endpoints-Tags) prior to associating them with BDefs. | Tags associated with a BDef appear on the right-hand side of the Data Entity page, listed as 'Categories'. Tags also drive the Category browse structure ('Explore') on the Home page. Tags also appear in the faceted filtering section on the left-hand side of the Search Results page. |
The following images show how the BDef-related metadata appears in Herd-UI
Data Entity page - Overview tab
Data Entity page - Columns tab
Search Results page
Here is a list of endpoints that are used to manage Tags and TagTypes. These drive the categorization that is used for browsing BDefs and filtering search results.
| Endpoints | Description | Herd-UI Location |
|---|---|---|
| TagType Post/Get/Put/Delete | Manage TagTypes which are used to group like tags together. | TagTypes appear as headers on the 'Explore' area of the Home page. TagTypes also appear as headers in the faceted filtering section on the left-hand side of the Search Results page. |
| Tag Post/Get/Put/Delete | Manage Tags which are used to categorize BDefs for filtering searches and browsing. | Tags appear on the 'Explore' area of the Home page and the faceted filtering section on the left-hand side of the Search Results page. There is also a Category page for each Tag that lists all BDefs with that Tag. Tags can be hierarchical and the Category page includes all BDefs associated with the Tag and all child Tags. |
The following images show how the Tag-related metadata appears in Herd-UI
Home page
Search Results page
Here is a set of calls that creates a TagType, a Tag, and then populates business metadata for a single BDef. These are the calls used to populate Demo_Object_A that is created by the Herd Demo Install. The calls are presented in curl syntax.
Create TagType and Tag
/usr/bin/curl -s -X POST --header 'Content-Type: application/json' -d '{"\"tagTypeKey\": {\"tagTypeCode\":\"Category_Type_A\"}, \"displayName\":\"Category Type A\","\"tagTypeOrder\": 0, \"description\":\"Tag Type for testing.\""}' http://localhost:8080/herd-app/rest/tagTypes
/usr/bin/curl -s -X POST --header 'Content-Type: application/json' -d '{"\"tagKey\": {\"tagTypeCode\":\"Category_Type_A\",\"tagCode\":\"Category_A\"},"\"displayName\":\"Category A\",\"description\":\"Tag for testing.\""}' http://localhost:8080/herd-app/rest/tags
Update BDef Descriptive Information
/usr/bin/curl -s -X PUT --header 'Content-Type: application/json' -d '{"\"description\": \"Object_A is transactional data with important information including X, Y, Z\","\"displayName\": \"Data_Object_A\", \"descriptiveBusinessObjectFormat\": { \"businessObjectFormatUsage\": \"FOR\","\"businessObjectFormatFileType\": \"TXT\", \"businessObjectFormatVersion\":0 }"}' http://localhost:8080/herd-app/rest/businessObjectDefinitionDescriptiveInformation/namespaces/Demo_App_A/businessObjectDefinitionNames/Data_Object_A
Create BDef Columns
/usr/bin/curl -s -X POST --header 'Content-Type: application/json' -d '{"\"businessObjectDefinitionColumnKey\": { \"namespace\": \"Demo_App_A\", \"businessObjectDefinitionName\": \"Data_Object_A\",\"businessObjectDefinitionColumnName\": \"Column_1\" }, \"schemaColumnName\": \"COLUMN1\", \"description\": \"Column 1 for Data Object A\"}' http://localhost:8080/herd-app/rest/businessObjectDefinitionColumns
/usr/bin/curl -s -X POST --header 'Content-Type: application/json' -d '{\"businessObjectDefinitionColumnKey\": { \"namespace\": \"Demo_App_A\", \"businessObjectDefinitionName\": \"Data_Object_A\",\"businessObjectDefinitionColumnName\": \"Column_2\" }, \"schemaColumnName\": \"COLUMN2\", \"description\": \"Column 2 for Data Object A\"}' http://localhost:8080/herd-app/rest/businessObjectDefinitionColumns
Associate BDef with Tag
/usr/bin/curl -s -X POST --header 'Content-Type: application/json' -d '{\"businessObjectDefinitionTagKey\": {\"businessObjectDefinitionKey\": {\"namespace\":\"Demo_App_A\", \"businessObjectDefinitionName\":\"Data_Object_A\"},\"tagKey\": {\"tagTypeCode\": \"Category_Type_A\", \"tagCode\": \"Category_A\"}}}' http://localhost:8080/herd-app/rest/businessObjectDefinitionTags
- Getting Started with herd
- herd Usage Pages
- herd API documentation
- herd Workflow Tasks
- herd Tools