Use Cases

A use case describes the value your data products help create: churn prediction, campaign ROI, fewer shelf warmers. Assigning data products to the use cases they serve shows why each product exists, and lets consumers find data by what they want to achieve.

You maintain use cases under Governance → Use Cases (/{organization}/governance/usecases), and browse them under Marketplace → Use Cases (/{organization}/usecases). Until the first use case is defined, the marketplace shows nothing about use cases: no menu entry, filter, or card.

The use case format

A use case is a YAML document of its own, shaped like an ODPS data product. The YAML is the source of truth: the form, the YAML editor, the API, and agents all read and write it.

apiVersion: v0.1.0
kind: UseCase
id: churn-prediction
name: Churn prediction
status: active
team:
  name: marketing
description:
  purpose: Retention can call customers who are likely to cancel within 90 days, before they leave.
authoritativeDefinitions:
  - type: mindfuel
    url: https://app.mindfuel.ai/demands/12
  - type: businessCase
    url: https://wiki.example.com/churn-business-case
customProperties:
  - property: sponsor
    value: Chief Marketing Officer
tags:
  - retention
dataProducts:
  - id: customers
  - id: customer-logins

The JSON schema is at /schemas/usecase.schema.json. Every listed team and data product must exist, and each data product may be listed only once.

Status

The status is free text, like a data product's. The form suggests three, and these are the ones Entropy Data acts on:

Any other status, and no status, is treated like active.

Who can maintain use cases

The owning team's USE_CASE_ADD, USE_CASE_EDIT, and USE_CASE_DELETE permissions decide who may add, edit, or delete its use cases. Assigning a data product to a use case is editing the use case. Use cases without a team are maintained by organization owners, and only they may remove a use case's team.

While use cases are switched off, their permissions are hidden in the role, API key, and agent settings. Roles, keys, and agents keep holding them.

Find use cases

In the Marketplace, use cases are read-only.

• Use Cases lists every use case with its value, status, owner, and assigned data products.
• A use case's page shows a Data Map of its assigned data products, with the data products they exchange data with shown faded, a list of the assigned data products, and an Audit Trail of its changes.
• The Data Products list and the Data Map have a Use Case filter. The list also has a Use Cases column when any listed product is assigned to one.
• A data product's page has a Use Cases card that lists the use cases it is assigned to and links to them.

Data products you cannot see are left out of every view, and the audit trail doesn't name them. The edit form says how many it leaves out, and saving it keeps them. The YAML editor and the API list every assigned data product by its ID.

Add a use case

1. In Governance, open Use Cases and click Add Use Case.
2. Enter a name. The ID is suggested from it.
3. Choose the owning team.
4. Choose the status and describe the purpose: the value the use case creates, and for whom. It takes Markdown.
5. Optionally assign data products, and add links and custom fields.
6. Click Add Use Case.

To write the YAML yourself, open an existing use case, click Edit, and choose Edit as YAML. The editor checks the YAML against the schema as you type.

Assign data products

A use case owns its data products, like a data product its output ports, so they change only where the use case changes: on its Edit page in Governance, in the Assigned Data Products section or in the YAML's dataProducts, and through the API. A data product's Use Cases card links to the use cases it is assigned to.

Deleting a data product removes it from every use case. Approving an access request that cites a use case also assigns the data product, see below.

Use cases in access requests

When you request access, you can pick one of the organization's use cases instead of making up a purpose. Proposed and retired use cases are not offered.

1. On the request form, open Use case and pick the use case.
2. The purpose is filled in from the use case's purpose. You can still change it, and a purpose you wrote yourself is not overwritten.
3. Submit the request as usual.

The access agreement keeps the use case, and its page shows it under the purpose. Once the agreement is approved, by a person or automatically, the provider's data product is assigned to the use case. An existing assignment stays as it is.

Through the access agreement API, a request cites a use case by its id in the optional info.useCase object, next to the purpose:

{
  "id": "access-churn",
  "info": {
    "purpose": "Churn analysis",
    "useCase": { "id": "churn-prediction" }
  },
  "provider": { "dataProductId": "invoices", "outputPortId": "snowflake" },
  "consumer": { "dataProductId": "customer-subscriptions" }
}

The field is never required. A PUT that leaves it out keeps the use case the agreement already cites, so clients that don't know the field change nothing. A new citation must name a use case that is neither proposed nor retired. While use cases are switched off, the field is not returned and is ignored.

API

The REST API manages use cases under /api/usecases, in the use case format as JSON or YAML. Every endpoint answers 404 while use cases are not enabled for the organization.

A PUT replaces the whole use case: a field left out is cleared, including status and dataProducts. Saving the use case above from a file:

curl -X PUT "https://api.entropy-data.com/api/usecases/churn-prediction" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @churn-prediction.yaml

To assign another data product, add it to dataProducts and send the whole use case again.

Every change, however it is made, appears in the event feed as UseCaseCreatedEvent, UseCaseUpdatedEvent, or UseCaseDeletedEvent.