Skip to content

Commit 3e711b9

Browse files
akoako
authored
Merge pull request #218 from dionesiusap/feature/213-catalog-search
feat: add mxcli catalog search and show commands
2 parents 8cd529f + 4c7649c commit 3e711b9

10 files changed

Lines changed: 1901 additions & 1 deletion

File tree

‎.claude/skills/mendix/browse-integrations.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Browse Integration Services and Contracts
22

3-
This skill covers discovering external services, browsing cached contracts, and querying integration assets via the catalog.
3+
This skill covers discovering external services, browsing cached contracts, and querying integration assets via the **MDL CATALOG** (local project metadata).
4+
5+
**⚠️ NOTE:** This covers the **MDL CATALOG keyword** (`SELECT ... FROM CATALOG.entities`), NOT the **Mendix Catalog CLI** (`mxcli catalog search`). See `.claude/skills/mendix/catalog-search.md` for the external service registry.
46

57
## When to Use This Skill
68

‎.claude/skills/mendix/catalog-search.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Catalog Search (Mendix Platform Service Registry)
2+
3+
Search and discover services registered in **Mendix Catalog** (catalog.mendix.com) programmatically.
4+
5+
**⚠️ NOTE:** This is the **external Mendix Catalog service** (CLI: `mxcli catalog search`), NOT the **MDL CATALOG keyword** which queries local project metadata tables (`SELECT ... FROM CATALOG.entities`). See `.claude/skills/mendix/browse-integrations.md` for MDL CATALOG queries.
6+
7+
## Authentication Required
8+
9+
Catalog search requires a Personal Access Token (PAT):
10+
11+
```bash
12+
# One-time setup
13+
mxcli auth login
14+
```
15+
16+
Create a PAT at: https://user-settings.mendix.com/ (Developer Settings → Personal Access Tokens)
17+
18+
## Basic Usage
19+
20+
```bash
21+
# Search for services
22+
mxcli catalog search "customer"
23+
24+
# Filter by service type
25+
mxcli catalog search "order" --service-type OData
26+
mxcli catalog search "api" --service-type REST
27+
28+
# Production endpoints only
29+
mxcli catalog search "inventory" --production-only
30+
31+
# Services you own
32+
mxcli catalog search "sales" --owned-only
33+
34+
# JSON output for scripting
35+
mxcli catalog search "data" --json | jq '.[] | {name, uuid, type}'
36+
```
37+
38+
## Output Formats
39+
40+
**Table (default):**
41+
```
42+
NAME TYPE VERSION APPLICATION ENVIRONMENT PROD UUID
43+
CustomerService OData 1.2.0 CRM Application Production Yes a7f3c2d1-4b5e-6c7f-8d9e-0a1b2c3d4e5f
44+
OrderAPI REST 2.0.1 E-commerce Platform Acceptance No b8e4d3e2-1a2b-3c4d-5e6f-7a8b9c0d1e2f
45+
InventorySync SOAP 1.0.0 Warehouse System Test No c9f5e4f3-2b3c-4d5e-6f7a-8b9c0d1e2f3a
46+
47+
Total: 42 results (showing 1-3)
48+
```
49+
50+
- **NAME**: Service name (truncated if > 22 chars)
51+
- **TYPE**: OData, REST, SOAP
52+
- **VERSION**: Service version
53+
- **APPLICATION**: Hosting application name
54+
- **ENVIRONMENT**: Production, Acceptance, Test
55+
- **PROD**: "Yes" if production, blank otherwise
56+
- **UUID**: Full UUID (36 chars) - copy this for use with `mxcli catalog show <uuid>`
57+
58+
**JSON mode:**
59+
```bash
60+
mxcli catalog search "customer" --json
61+
```
62+
63+
Returns full endpoint details including:
64+
- Complete UUIDs
65+
- Descriptions
66+
- Security classification
67+
- Last updated timestamp
68+
- Entity and action metadata (for OData)
69+
70+
## Pagination
71+
72+
```bash
73+
# First 10 results
74+
mxcli catalog search "api" --limit 10
75+
76+
# Next 10 results
77+
mxcli catalog search "api" --limit 10 --offset 10
78+
79+
# Maximum 100 per request
80+
mxcli catalog search "service" --limit 100
81+
```
82+
83+
## Common Use Cases
84+
85+
**Find production OData services:**
86+
```bash
87+
mxcli catalog search "customer" --service-type OData --production-only
88+
```
89+
90+
**Get UUIDs for automation:**
91+
```bash
92+
mxcli catalog search "order" --json | jq -r '.[] | .uuid'
93+
```
94+
95+
**Generate service inventory report:**
96+
```bash
97+
mxcli catalog search "api" --json | \
98+
jq -r '.[] | "\(.name) (\(.serviceType)) - \(.application.name)"'
99+
```
100+
101+
**Filter by multiple criteria:**
102+
```bash
103+
mxcli catalog search "data" \
104+
--service-type OData \
105+
--production-only \
106+
--limit 50
107+
```
108+
109+
## Flags
110+
111+
| Flag | Type | Default | Description |
112+
|------|------|---------|-------------|
113+
| `--profile` | string | "default" | Auth profile name |
114+
| `--service-type` | string | (all) | Filter by OData, REST, or SOAP |
115+
| `--production-only` | bool | false | Show only production endpoints |
116+
| `--owned-only` | bool | false | Show only owned services |
117+
| `--limit` | int | 20 | Results per page (max 100) |
118+
| `--offset` | int | 0 | Pagination offset |
119+
| `--json` | bool | false | Output as JSON array |
120+
121+
## Error Handling
122+
123+
**No credential:**
124+
```
125+
Error: no credential found. Run: mxcli auth login
126+
```
127+
128+
**Authentication failed:**
129+
```
130+
Error: authentication failed. Run: mxcli auth login
131+
```
132+
133+
Solution: Log in with a valid PAT.
134+
135+
**Network errors:**
136+
Catalog API requires internet connectivity. Check network connection and firewall settings.
137+
138+
## Future Features
139+
140+
Phase 2 (not yet implemented):
141+
- `mxcli catalog show <uuid>` - Display detailed endpoint metadata
142+
- `mxcli catalog create-odata-client <uuid>` - Generate OData client from Catalog entry
143+
- Interactive search UI with arrow-key navigation
144+
145+
See GitHub issue #213 for architecture discussion.
146+
147+
## Disambiguation: Two Different "Catalogs"
148+
149+
**Mendix Catalog** (this skill):
150+
- **What**: External service registry at catalog.mendix.com
151+
- **CLI**: `mxcli catalog search "customer"`, `mxcli catalog show <uuid>`
152+
- **Purpose**: Discover OData/REST/SOAP services across your organization
153+
- **Requires**: Platform authentication (PAT token)
154+
- **Data source**: Mendix cloud service
155+
156+
**MDL CATALOG keyword** (different concept):
157+
- **What**: Local project metadata tables in the mxcli SQLite database
158+
- **MDL syntax**: `SELECT ... FROM CATALOG.entities`, `SHOW CATALOG TABLES`
159+
- **Purpose**: Query project structure (entities, microflows, pages, etc.)
160+
- **Requires**: `REFRESH CATALOG` command (no auth needed)
161+
- **Data source**: Your local .mpr file
162+
163+
See `.claude/skills/mendix/browse-integrations.md` for MDL CATALOG usage.
164+
165+
## Related
166+
167+
- Platform authentication: `.claude/skills/mendix/platform-auth.md`
168+
- OData client creation: `.claude/skills/mendix/odata-data-sharing.md`
169+
- MDL CATALOG queries: `.claude/skills/mendix/browse-integrations.md`

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
88

99
### Added
1010

11+
- **mxcli catalog search** — Search Mendix Catalog for data sources and services with filters for service type, environment, and ownership (#213)
1112
- **Local file metadata for OData clients** — `CREATE ODATA CLIENT` now supports `file://` URLs and relative paths for `MetadataUrl`, enabling offline development, reproducible testing, and version-pinned contracts (#206)
1213
- **Path normalization** — Relative paths in `MetadataUrl` are automatically converted to absolute `file://` URLs for Studio Pro compatibility
1314
- **ServiceUrl validation** — `ServiceUrl` parameter must now be a constant reference (e.g., `@Module.ConstantName`) to enforce Mendix best practice

0 commit comments

Comments
 (0)