Set up a Meta Hub Business Glossary with a Data Hub model
You’re mapping customer data from a legacy system into Data Hub. Halfway down the schema, one column is named cust_stat_01. There’s no description and no owner. Your analyst calls it “Active Customer Status” but you can’t find that written anywhere. So you guess, ship the mapping, and move on. Three months later, a report is wrong. The problem isn’t the data. It’s that nothing tells you what the field means.
That’s exactly what Meta Hub, a Boomi Enterprise Platform feature, is built to fix. Read on to learn how to create, publish, and attach a business glossary to your Data Hub model.
Meta Hub is a set of centralized metadata services for the whole Boomi ecosystem. It stores endorsed business definitions as glossaries and links them to Data Hub models and AI agents. In this post, you’ll learn how to use the Meta Hub REST API to create, publish, and attach those glossaries from a script instead of the UI.
A Meta Hub Business Glossary has a name, a purpose, and Markdown content. Each glossary also has two independent states:
-
Publication status:
DRAFTorPUBLISHED. Controls visibility. -
Endorsement status:
PENDING,ENDORSED, orDEPRECATED. Records a steward’s certification of the definition. New glossaries start asPENDING.
You can also associate a glossary with Data Hub models (DATAHUB_MODEL) or AI agents (AI_AGENT)
When you want to seed terms from an existing data dictionary, you can either use the API, attach a Meta Hub Business Glossary when a model is created, or keep the Meta Hub Business Glossary state in CI/CD.
Prerequisites
Before you begin, make sure you have the following:
-
An active Data Hub and Meta Hub account.
-
A Platform JWT. The Meta Hub API accepts only bearer token authentication, so send the JWT in the
Authorization: Bearer <token>header on every call. For details, refer to the Meta Hub API reference.
Your role also needs the following privileges. Each role gets these privileges by default, or you can assign them to a custom role:
| Role or Privilege | Create/Publish | Endorse | Associate | Delete Glossary |
|---|---|---|---|---|
| Meta Admin | Yes | Yes | Yes | Yes |
| Meta Steward | Yes | Yes | Yes | No |
| Meta User | No | No | No | No |
| Custom role | META - Edit Glossary | META - Edit Glossary Endorsement | META - Edit Association | META - Delete Glossary |
To list glossaries or associations, you need META - View Glossary or META - View Association.
Authenticate
Generate a Platform JWT
Call the auth/jwt/generate endpoint with your Boomi API token. Refer to Authenticating your API.
Use a Platform JWT to authenticate with Meta Hub. Data Hub repository tokens from a repository Configure tab aren’t supported.
Platform JWTs expire 5 minutes after they’re issued, and there is no refresh call. To get a new one, run the auth/jwt/generate call again.
export BASE="https://metahub.boomi.com/metahub"
export ACCOUNT_ID="your account-id"
# JWTs expire after 5 minutes. Re-run this line if a later step returns 401.
export TOKEN=$(curl -s -u "BOOMI_TOKEN.you@company.com:YOUR_API_TOKEN" \
"https://api.boomi.com/auth/jwt/generate/${ACCOUNT_ID}")
Verify your Platform JWT
Confirm your Platform JWT with the following GET request before you write anything.
Use a non-production account, or temporary test names that you can easily recognize and delete later.
curl -i "$BASE/api/accounts/$ACCOUNT_ID/glossaries" \
-H "Authorization: Bearer $TOKEN"
The response status code tells you whether the call worked:
-
200: - Token and
META - View Glossaryprivilege work. -
401: Missing, malformed, or expired token.
-
403: Role lacks view privilege.
Step 1: Create a Meta Hub Business Glossary
Start by creating a glossary in DRAFT status. You’ll publish it in the next step.
To create a glossary, call POST /api/accounts/{accountId}/glossaries, which requires META - Edit Glossary. Only name and status are required. The name field allows up to 150 characters, purpose up to 1,000, and content accepts Markdown up to 10 MB.
curl -i -X POST "$BASE/api/accounts/$ACCOUNT_ID/glossaries" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name" : "Customer Data Glossary",
"type" : "BUSINESS_GLOSSARY",
"purpose" : "Defines and manages customer-related terminology.",
"content" : "## Active Customer\nA customer with at least one purchase in the current quarter and no churn flag.",
"status" : "DRAFT"
}'
The response includes id (UUID) and endorsementStatus (PENDING by default). Keep the id. Replace the sample value with your own:
export GLOSSARY_ID="123e4567-e89b-12d3-a456-426614174000"
Step 2: Publish the glossary
Publish the glossary to make it visible in Agent Designer. Unpublished glossaries aren’t visible there.
To publish, call PUT /api/accounts/{accountId}/glossaries/{id}, which requires META - Edit Glossary. Publishing requires name and purpose in the request. Send the glossary’s fields with the new status:
curl -i -X PUT "$BASE/api/accounts/$ACCOUNT_ID/glossaries/$GLOSSARY_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Data Glossary",
"purpose": "Defines and manages customer-related terminology.",
"content": "## Active Customer\nA customer with at least one purchase in the current quarter and no churn flag.",
"status": "PUBLISHED"
}'
To confirm that the glossary is published, call GET /api/accounts/{accountId}/glossaries/{id}?includeContent=true. The response has "status": "PUBLISHED". Content is omitted unless you ask.
For more information about using glossaries with agents, refer to Connecting a business glossary to your agent.
Step 3: Endorse the glossary
Endorse the glossary to record a steward’s certification of its definition.
To endorse, call POST /api/accounts/{accountId}/glossaries/{glossaryId}/endorsement-status, which requires META - Edit Glossary Endorsement. The endorsementStatus is required (PENDING, ENDORSED, or DEPRECATED). A comment is optional and lands in the endorsement history:
curl -i -X POST "$BASE/api/accounts/$ACCOUNT_ID/glossaries/$GLOSSARY_ID/endorsement-status" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"endorsementStatus": "ENDORSED",
"comment": "Definitions reviewed with Finance and Sales."
}'
To view the endorsement history, call GET /api/accounts/{accountId}/glossaries/{glossaryId}/endorsement-status/history, which requires META - View Glossary Endorsement History:
curl "$BASE/api/accounts/$ACCOUNT_ID/glossaries/$GLOSSARY_ID/endorsement-status/history" \
-H "Authorization: Bearer $TOKEN"
Step 4: Associate the glossary with a Data Hub model
Associate the glossary with a Data Hub model to link its definitions to that model.
To associate, call POST /api/accounts/{accountId}/associations, which requires META - Edit Association. The assetType, assetExternalId, and glossaryId are required.
The assetExternalId is the asset’s ID in the external system. For Data Hub, that is the universe ID, which is also the model ID. To find it, go to Data Hub > Repositories > your repository > your model, and copy the ID from the address bar. The URL contains the account, repository, and universe IDs. You can also list IDs with Get Repositories Summary.
curl -i -X POST "$BASE/api/accounts/$ACCOUNT_ID/associations" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assetType": "DATAHUB_MODEL",
"assetExternalId": "replace-with-universe-id",
"glossaryId": "$GLOSSARY_ID",
"title": "Customermodel"
}'
The title is optional and has a maximum length of 500 characters. For AI_AGENT, the schema also accepts mode of conversational or structured. After the POST, confirm the row on the model’s Associations tab. For more information, visit the Meta Hub FAQ page.
Errors
Application errors use ErrorResponse: error, message, timestamp, and path.
A rejected token or call with no token is a gateway 401 with an empty body and WWW-Authenticate: Bearer. A malformed token returns the same empty body and adds error="invalid_token" to that header. The API reference also shows a JSON 401 example, which is the application format, not the gateway response.
The OpenAPI example that shows a JSON 401 is the application shape. An empty 401 in the middle of a run usually means the token expired. You can generate a new JWT with the auth/jwt/generate call and retry the request.
For a full list of error codes, refer to the Responses section of each operation in the Meta Hub API Reference: Associations and Glossaries.
Related resources
-
To learn more about the Meta Hub APIs, refer to Meta Hub REST APIs overview.
-
To use your glossary with agents, refer to Connecting a business glossary to your agent.
-
To explore additional scenarios, such as decoding cryptic fields, flagging PII, and showing business context alongside Data Hub Quarantine errors, refer to the Meta Hub use cases.
You’ve now created, published, endorsed, and associated a Meta Hub Business Glossary with a Data Hub model, all from a script. The next time someone asks what cust_stat_01 means, the answer is an endorsed definition instead of a guess.
Ready to try this yourself? Pick one field in your data that no one can define with confidence, and give it a glossary in a non-production account. Let us know how it goes!
