From e57df8b2967e0747d1ec2bb895738d22d819e5fe Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 16:39:10 +0000 Subject: [PATCH] Align English API docs with actual CLI implementation Generated-By: mintlify-agent --- en/architecture/tech-stack.mdx | 56 +++++++- en/features/connector.mdx | 182 +++++++++++++++---------- en/features/data-management.mdx | 234 +++++++++++++++++--------------- en/features/skills.mdx | 198 +++++++++++++++++---------- 4 files changed, 424 insertions(+), 246 deletions(-) diff --git a/en/architecture/tech-stack.mdx b/en/architecture/tech-stack.mdx index 74e936a..dae3048 100644 --- a/en/architecture/tech-stack.mdx +++ b/en/architecture/tech-stack.mdx @@ -182,7 +182,61 @@ Exit with Code --- -## Design Principles +## Yida API calls + +### Base configuration + +```javascript +const BASE_URL = 'https://www.aliwork.com'; + +// Request headers +const headers = { + 'Content-Type': 'application/json', + 'X-Csrf-Token': csrfToken, + 'Cookie': cookies, +}; +``` + +### Core APIs + +| Endpoint | Purpose | +|----------|---------| +| `/dingtalk/web/APP_xxx/xxx` | App internal API | +| `/dingtalk/web/APP_xxx/v1/form/searchFormDatas.json` | Form data query | +| `/dingtalk/web/APP_xxx/v1/form/saveFormData.json` | Save form data | +| `/dingtalk/web/APP_xxx/v1/form/getFormDataById.json` | Get form data by ID | +| `/dingtalk/web/APP_xxx/v1/form/updateFormData.json` | Update form data | +| `/dingtalk/web/APP_xxx/v1/process/getInstances.json` | Process instance query | +| `/dingtalk/web/APP_xxx/v1/process/getInstanceById.json` | Get process instance by ID | +| `/dingtalk/web/APP_xxx/v1/process/startInstance.json` | Start process instance | +| `/dingtalk/web/APP_xxx/v1/task/executeTask.json` | Execute task | +| `/dingtalk/web/APP_xxx/v1/task/getTasks.json` | List tasks | +| `/query/newconnector/listConnector.json` | List connectors | +| `/query/newconnector/createOrUpdateConnector.json` | Create or update connector | +| `/query/newconnector/getConnectorDetail.json` | Get connector detail | +| `/query/newconnector/testConnector.json` | Test connector action | + +--- + +## Security design + +1. **Cookie encrypted storage** - Local cache is stored encrypted +2. **CSRF token verification** - Every request includes a token +3. **No hardcoded credentials** - All credentials are dynamically obtained +4. **Environment isolation** - Independent across different AI tool environments + +--- + +## Performance optimization + +1. **Lazy-load translation files** - Language packs loaded on demand +2. **Local schema caching** - Reduces API calls +3. **Concurrent request control** - Prevents rate limiting from excessive requests +4. **Incremental updates** - Form updates use merge instead of overwrite + +--- + +## Design principles ### 1. Single Responsibility diff --git a/en/features/connector.mdx b/en/features/connector.mdx index bad8c29..5c63fbd 100644 --- a/en/features/connector.mdx +++ b/en/features/connector.mdx @@ -1,5 +1,5 @@ --- -title: "Connectors (HTTP Integration)" +title: "Connectors (HTTP integration)" description: "Integrate Yida applications with external APIs through HTTP connectors." icon: "plug" --- @@ -8,26 +8,26 @@ OpenYida provides powerful HTTP connector management, supporting intelligent con --- -## Feature Overview +## Feature overview - + Automatically parse and create connectors from curl commands, with auth extraction. - + Full connector lifecycle: create, update, test, delete. - + Supports Bearer Token, API Key, OAuth2, and more. - + Add, test, and manage connector execution actions. --- -## Smart Connector Creation +## Smart connector creation Create connectors from curl commands with one click: @@ -40,88 +40,124 @@ openyida connector smart-create \ Smart creation process: -1. **Parse API Info** - Extract protocol, host, method, path, auth type -2. **Match Existing** - Find existing connectors with same host and auth -3. **Generate Config** - Auto-build OpenAPI format connector definition -4. **Create or Update** - Create new connector or add actions to existing +1. **Parse API info** - Extract protocol, host, method, path, auth type +2. **Match existing** - Find existing connectors with same host and auth +3. **Generate config** - Auto-build OpenAPI format connector definition +4. **Create or update** - Create new connector or add actions to existing --- -## Connector Management Commands +## Connector management commands -### List Connectors +### List connectors ```bash -# List all connectors openyida connector list - -# List with pagination openyida connector list --page 1 --size 20 - -# Filter by app -openyida connector list --app ``` -### Get Connector Details +### Create connector ```bash -openyida connector get --id +openyida connector create "Connector Name" "api.example.com" \ + --operations ./operations.json \ + --protocol https \ + --desc "Connector description" ``` -### Update Connector + +The `method` field in the operations JSON file is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). If `method` is not specified, it defaults to `"get"`. + + +### Get connector details ```bash -openyida connector update \ - --id \ - --name "New Name" \ - --desc "Updated description" +openyida connector detail ``` -### Delete Connector +### Delete connector ```bash -openyida connector delete --id [--force] +openyida connector delete --force ``` --- -## Action Management +## Action management -### Add Action +### Add execution action ```bash -openyida connector action add \ - --connector \ - --name "Get Users" \ - --method GET \ - --path "/v1/users" \ - --params '[{"name":"page","type":"number"}]' +openyida connector add-action \ + --connector-id \ + --operations ./new-action.json \ + --confirm ``` -The `method` field is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). You can specify the method in any case. If omitted, it defaults to `"get"`. +The `method` field in the operations config is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). You can specify the method in any case. If omitted, it defaults to `"get"`. -### Test Action +### List existing actions ```bash -openyida connector action test \ - --connector \ +openyida connector list-actions +``` + +### Test action + +```bash +openyida connector test \ + --connector-id \ --action \ - --data '{"page": 1}' + --body '{"key": "value"}' +``` + +### Delete action + +```bash +openyida connector delete-action --force +``` + +--- + +## Auth account management + +### List auth accounts + +```bash +openyida connector list-connections ``` -### List Actions +### Create auth account ```bash -openyida connector action list --connector +openyida connector create-connection "Production Account" \ + --token "Bearer xxx" \ + --type bearer ``` --- -## Authentication Types +## Helper tools + +### Parse API info + +```bash +openyida connector parse-api --curl "curl command" --output ./api-info.json +``` + +### Generate API doc template -| Type | Description | Use Case | +```bash +openyida connector gen-template ./my-api-template.json +``` + +--- + +## Authentication types + +| Type | Description | Use case | |------|-------------|----------| | **None** | No authentication | Public APIs | | **Bearer Token** | Token in Authorization header | JWT-based APIs | @@ -131,42 +167,52 @@ openyida connector action list --connector --- -## Common Use Cases +## Best practices -### REST API Integration +### 1. Use environment variables for sensitive info ```bash -# Create connector for REST API -openyida connector smart-create \ - --curl "curl https://api.example.com/items -H 'Authorization: Bearer token'" \ - --name "Item Service" +export API_TOKEN="your-secret-token" +openyida connector smart-create --curl "curl -H 'Authorization: Bearer $API_TOKEN' ..." ``` -### Webhook Handler +### 2. Create complex connectors in stages ```bash -# Create webhook connector -openyida connector create \ - --name "Webhook Handler" \ - --type webhook \ - --url "https://hooks.example.com/webhook" +# Step 1: Create base connector +openyida connector create "DingTalk API" "oapi.dingtalk.com" + +# Step 2: Add actions one by one +openyida connector add-action --connector-id --operations ./action1.json +openyida connector add-action --connector-id --operations ./action2.json ``` -### Database Proxy +### 3. Test before enabling ```bash -# Create database connector via HTTP proxy -openyida connector smart-create \ - --curl "curl -X POST https://db-proxy.example.com/query" \ - --name "Database Proxy" +# Create without confirming +openyida connector add-action --connector-id --operations ./action.json + +# Test the action +openyida connector test --connector-id --action + +# Confirm in the Yida admin console ``` --- -## Best Practices +## FAQ + + + + Make sure the curl command is correctly formatted with a complete URL and necessary headers. If there are special characters, wrap the command in quotes. + + + + Use the `connector add-action` command. If the action ID already exists, the system prompts you to update it. + -1. **Reuse Connectors** - Use same connector for same host/auth combination -2. **Naming Convention** - Use descriptive names: `{Service}-{Purpose}` -3. **Documentation** - Add clear descriptions for each action -4. **Testing** - Always test connectors before production use -5. **Security** - Never commit credentials; use environment variables + + Currently supports Bearer Token, API Key, Basic Auth, and OAuth2. Auth info in curl commands is automatically detected. + + diff --git a/en/features/data-management.mdx b/en/features/data-management.mdx index 3bff216..05d260d 100644 --- a/en/features/data-management.mdx +++ b/en/features/data-management.mdx @@ -1,5 +1,5 @@ --- -title: "Data Management" +title: "Data management" description: "Unified data management interface supporting forms, processes, tasks, and subform operations." icon: "database" --- @@ -8,16 +8,16 @@ OpenYida provides a unified data management CLI supporting complete CRUD operati --- -## Feature Overview +## Feature overview - + Query, create, update, and delete form instance data. - + Manage process instances, approval records, and process status. - + Query todo, done, initiated, and CC'd tasks. @@ -27,192 +27,210 @@ OpenYida provides a unified data management CLI supporting complete CRUD operati --- -## Command Format +## Command format ```bash openyida data [args] ``` - **action**: `query` | `get` | `create` | `update` | `execute` -- **resource**: `form` | `process` | `task` | `subform` | `operation-records` +- **resource**: `form` | `process` | `task` | `tasks` | `subform` | `operation-records` --- -## Form Data Operations +## Form data operations -### Query Data +### Query data ```bash -# Query all data -openyida data query form --form +# Basic query +openyida data query form -# With conditions -openyida data query form --form --where '{"status": "active"}' +# Paginated query +openyida data query form --page 1 --size 50 -# Pagination -openyida data query form --form --page 1 --size 50 +# Query with conditions +openyida data query form \ + --search-json '{"field_xxx": "value"}' -# Sort -openyida data query form --form --sort '{"createdAt": "desc"}' +# Query specific instance +openyida data query form --inst-id ``` -### Get Single Record +### Get single record ```bash -openyida data get form --form --id +openyida data get form --inst-id ``` -### Create Record +### Create record ```bash -openyida data create form \ - --form \ - --data '{"name": "John", "email": "john@example.com"}' +openyida data create form \ + --data '{"field_xxx": "value", "field_yyy": 123}' \ + --dept-id ``` -### Update Record +### Update record ```bash -openyida data update form \ - --form \ - --id \ - --data '{"status": "completed"}' -``` - -### Delete Record - -```bash -openyida data delete form --form --id +openyida data update form \ + --inst-id \ + --data '{"field_xxx": "new value"}' \ + --use-latest-version y ``` --- -## Process Data Operations +## Process data operations -### Query Process Instances +### Query process instances ```bash -# All instances -openyida data query process --process +# Query process list +openyida data query process \ + --page 1 --size 20 \ + --instance-status RUNNING -# By status -openyida data query process --process --status RUNNING +# Status options: RUNNING, COMPLETED, TERMINATED ``` -### Get Process Detail +### Get process detail ```bash -openyida data get process --process --id +openyida data get process --process-inst-id ``` -### Execute Process Action +### Create process instance ```bash -# Approve -openyida data execute process \ - --process \ - --id \ - --action AGREE \ - --comment "Approved" - -# Reject -openyida data execute process \ - --process \ - --id \ - --action REJECT \ - --comment "Need more info" +openyida data create process \ + --process-code \ + --data '{"field_xxx": "value"}' \ + --dept-id +``` + +### Query approval records + +```bash +openyida data query operation-records \ + --process-inst-id ``` --- -## Task Management +## Task management -### Query Tasks +### Query tasks ```bash # Todo tasks -openyida data query task --type todo +openyida data query tasks --type todo # Done tasks -openyida data query task --type done +openyida data query tasks --type done # Initiated by me -openyida data query task --type initiated +openyida data query tasks --type submitted # CC'd to me -openyida data query task --type cc +openyida data query tasks --type cc ``` -### Get Task Detail +### Execute task ```bash -openyida data get task --id +openyida data execute task \ + --task-id \ + --process-inst-id \ + --out-result AGREE \ + --remark "Approved, please proceed" \ + --data '{"comment": "Approved"}' ``` +**out-result options:** +- `AGREE` - Approve +- `DISAGREE` - Reject + --- -## Subform Operations +## Subform operations -### Query Subform Data +### Query subform data ```bash -openyida data query subform \ - --form \ - --subform \ - --parent -``` - -### Create Subform Record - -```bash -openyida data create subform \ - --form \ - --subform \ - --parent \ - --data '{"item": "Product A", "quantity": 10}' +openyida data query subform \ + --inst-id \ + --table-field-id \ + --page 1 --size 20 ``` --- -## Operation Records +## Advanced usage -### Query Operation History +### Complex query conditions ```bash -# Form operations -openyida data query operation-records --form --instance +# Multi-field conditional query +openyida data query form \ + --search-json '{ + "field_status": "approved", + "field_amount": { "$gte": 1000 }, + "field_created_at": { "$gte": "2024-01-01" } + }' +``` -# Process operations -openyida data query operation-records --process --instance +### Batch operation script example + +```bash +#!/bin/bash +# Batch export form data + +APP_TYPE="APP_XXXXXXXX" +FORM_UUID="FORM-XXXX-XXXX" +PAGE=1 + +while true; do + RESULT=$(openyida data query form $APP_TYPE $FORM_UUID --page $PAGE --size 100) + + # Process current page data + echo "$RESULT" >> ./export.json + + # Check if there are more pages + HAS_MORE=$(echo "$RESULT" | jq '.hasMore') + if [ "$HAS_MORE" != "true" ]; then + break + fi + + PAGE=$((PAGE + 1)) +done ``` --- -## Data Export - -### Export to File +## Data export example ```bash -# CSV format -openyida data export form --form --format csv --output data.csv - -# Excel format -openyida data export form --form --format excel --output data.xlsx - -# JSON format -openyida data export form --form --format json --output data.json +# Export data within a time range +openyida data query form \ + --search-json '{ + "field_created_at": { + "$gte": "2024-01-01T00:00:00", + "$lte": "2024-12-31T23:59:59" + } + }' \ + --size 100 > ./data-export.json ``` --- -## Common Options - -| Option | Description | -|--------|-------------| -| `--form ` | Target form UUID | -| `--process ` | Target process code | -| `--where ` | Filter conditions | -| `--page ` | Page number | -| `--size ` | Page size | -| `--sort ` | Sort configuration | -| `--format ` | Export format | +## Important notes + + + Data operations are permanent. Delete and update operations cannot be undone. Always test with a small dataset before running batch operations. + + + + Paginated queries default to 20 records per page, with a maximum of 100. For large data exports, use a loop with pagination. + diff --git a/en/features/skills.mdx b/en/features/skills.mdx index f346706..da0a4be 100644 --- a/en/features/skills.mdx +++ b/en/features/skills.mdx @@ -1,5 +1,5 @@ --- -title: "CLI Reference" +title: "CLI reference" description: "Complete reference for all OpenYida CLI commands." icon: "terminal" --- @@ -8,7 +8,7 @@ OpenYida provides rich CLI commands for full application lifecycle management. --- -## Environment & Authentication +## Environment and authentication ```bash # Environment check @@ -42,144 +42,204 @@ openyida doctor --report # Generate report (json|markdown|html) --- -## Application Management +## Application management ```bash # Create application openyida create-app "" [desc] [icon] [color] [themeColor] -# List applications -openyida list-apps +# Export application +openyida export [output] # Generate migration package -# Import/Export -openyida import --file # Import from JSON -openyida export --app # Export to JSON - -# Deploy -openyida deploy --env # Deploy to environment +# Import application +openyida import [name] # Rebuild app from migration package ``` --- -## Form Management +## Form management ```bash # Create form -openyida create-form "" [--app ] [--folder ] +openyida create-form create "
" \ + [--layout ] \ + [--theme ] \ + [--label-align ] -# Create process form -openyida create-form "" --process [--app ] +# Update form +openyida create-form update # Get form schema -openyida get-form-schema --form +openyida get-schema -# Update form -openyida update-form --form --schema +# Update form config +openyida update-form-config ``` --- -## Page Management +## Page management ```bash # Create custom page -openyida create-page <appType> "<name>" [--datasource <jsonOrFile>] +openyida create-page <appType> "<page name>" [--datasource <jsonOrFile>] -# Publish page -openyida publish --page <id> [--env <env>] +# Compile and publish page +openyida publish <sourceFilePath> <appType> <formUuid> -# Share page -openyida share --page <id> [--public] [--password <pwd>] +# Compile only (no publish, output to pages/dist/) +openyida compile <sourceFilePath> + +# Page share configuration +openyida save-share-config <appType> <formUuid> <url> <isOpen> [openAuth] +openyida get-page-config <appType> <formUuid> +openyida verify-short-url <appType> <formUuid> <url> ``` --- -## Data Management +## Data management ```bash -# Query form data -openyida data query --form <formUuid> [--where <conditions>] [--limit <n>] +# Unified data management +openyida data <action> <resource> [args] + +# Form data +openyida data query form <appType> <formUuid> [--page N] [--size N] [--search-json JSON] +openyida data get form <appType> --inst-id <id> +openyida data create form <appType> <formUuid> --data <JSON> +openyida data update form <appType> --inst-id <id> --data <JSON> + +# Process data +openyida data query process <appType> <formUuid> [--instance-status STATUS] +openyida data get process <appType> --process-inst-id <id> +openyida data create process <appType> <formUuid> --process-code <code> --data <JSON> + +# Task management +openyida data query tasks <appType> --type <todo|done|submitted|cc> +openyida data execute task <appType> --task-id <id> --process-inst-id <id> --out-result <AGREE|DISAGREE> + +# Subform +openyida data query subform <appType> <formUuid> --inst-id <id> --table-field-id <fieldId> +``` -# Create data entry -openyida data create --form <formUuid> --data '<json>' +--- -# Update data -openyida data update --form <formUuid> --id <id> --data '<json>' +## Process management -# Delete data -openyida data delete --form <formUuid> --id <id> +```bash +# Create process form +openyida create-process <appType> "<form name>" <fieldsJSON> --process-code <code> -# Export data -openyida data export --form <formUuid> --format <csv|json|excel> +# Configure process rules +openyida configure-process <appType> <formUuid> --rules <rulesJSON> ``` --- -## Connector Management +## Permission management ```bash -# Create HTTP connector -openyida create-connector "<name>" --url <url> [--method <method>] +# Query form permissions +openyida get-permission <appType> <formUuid> -# Import from curl -openyida create-connector --curl '<curl-command>' +# Save form permissions +openyida save-permission <appType> <formUuid> \ + [--data-permission <json>] \ + [--action-permission <json>] +``` -# Test connector -openyida test-connector --id <connectorId> +--- +## Connector management + +```bash # List connectors -openyida list-connectors [--app <appId>] +openyida connector list [--page N] [--size N] + +# Create connector +openyida connector create "<name>" "<domain>" --operations <file> [options] + +# Get connector details +openyida connector detail <connector-id> + +# Delete connector +openyida connector delete <connector-id> [--force] + +# Action management +openyida connector add-action --connector-id <id> --operations <file> [--confirm] +openyida connector list-actions <connector-id> +openyida connector delete-action <connector-id> <operation-id> [--force] +openyida connector test --connector-id <id> --action <actionId> [options] + +# Auth account management +openyida connector list-connections <connector-id> +openyida connector create-connection <connector-id> "<name>" [options] + +# Smart creation +openyida connector smart-create --curl "<curl command>" [--name <name>] [--desc <desc>] + +# Helper tools +openyida connector parse-api --curl "<curl command>" --output <file> +openyida connector gen-template [output path] ``` --- -## Report & Charts +## Report management ```bash # Create report -openyida create-report "<name>" [--app <appId>] [--type <type>] - -# Add chart -openyida add-chart --report <id> --chart '<config>' +openyida create-report <appType> "<report name>" <chartDefinitionJSONOrFilePath> -# Export report -openyida export-report --id <id> --format <pdf|png> +# Append chart +openyida append-chart <appType> <reportId> <chartDefinitionJSONOrFilePath> ``` --- -## CDN & Assets +## CDN management ```bash +# Configure CDN +openyida cdn-config + # Upload image -openyida upload-image --file <path> [--app <appId>] +openyida cdn-upload <filePath> # Refresh cache -openyida cdn refresh --urls <urls> - -# List assets -openyida list-assets [--app <appId>] [--type <type>] +openyida cdn-refresh <path> ``` --- -## Global Options +## Global options | Option | Description | |--------|-------------| -| `--app <appId>` | Specify target application | -| `--env <env>` | Target environment (dev/prod) | -| `--format <format>` | Output format (json/table) | -| `--verbose` | Show detailed logs | -| `--dry-run` | Preview changes without executing | +| `--help`, `-h` | Show help information | +| `--version`, `-v` | Show version number | +| `--qr` | Use terminal QR code login | +| `--force` | Force operation, skip confirmation | + +--- + +## Environment variables + +| Variable | Description | Example | +|----------|-------------|---------| +| `OPENYIDA_LANG` | Set language | `zh`, `en`, `ja` | +| `LANG` / `LC_ALL` | System language | `zh_CN.UTF-8` | --- -## Environment Variables +## Exit codes -| Variable | Description | -|----------|-------------| -| `OPENYIDA_APP_KEY` | App key for API authentication | -| `OPENYIDA_APP_SECRET` | App secret for API authentication | -| `OPENYIDA_ACCESS_TOKEN` | Access token (optional) | -| `OPENYIDA_DEFAULT_ORG` | Default organization ID | +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | General error | +| 2 | Argument error | +| 3 | Login failure / not logged in | +| 4 | Network error | +| 5 | API error |