ZenTao | Alephant Documentation

The ZenTao connector brings approved ZenTao requirements, tasks, bugs, and optional attachments into AIvis retrieval. It reads only the project IDs and product IDs explicitly entered by an administrator and does not scan the whole ZenTao instance.

Use cases

Scenario	Recommendation
Project-status Q&A	Index requirements and tasks by project ID.
Bug retrospectives	Index bugs by product ID, including status, description, and activity comments.
Requirement traceability	Configure both project IDs and product IDs when both views are needed.
Attachment retrieval	Enable attachments only when content is approved and volume is manageable.
Private ZenTao deployments	Explicitly enable private-network options after deployment review.

What it indexes

ZenTao data	Scope requirement	Indexing behavior
Requirements	Project IDs or product IDs	Indexes title, description, status, created/updated time, and action comments.
Tasks	At least one project ID	Reads project executions and then tasks under those executions.
Bugs	At least one product ID	Reads bug title, description, status, and action comments.
Attachments	Under enabled parent objects	Optional child documents under requirements, tasks, and bugs.

Project IDs and product IDs are separate lists. Each list can contain at most 100 unique positive integers. At least one of requirements, tasks, or bugs must be enabled. Tasks require project IDs; bugs require product IDs.

The connector does not index ZenTao users, team membership, time tracking, charts, test suites, releases, document libraries, or unlisted projects/products.

Prerequisites

Confirm the ZenTao instance URL. Public deployments should use HTTPS.
Prepare a dedicated account and password that can read the target projects, products, objects, and attachments.
Collect the target project IDs and product IDs.
If ZenTao is private-network only, confirm backend network access and whether HTTP is approved.
Decide the AIvis access group before indexing private content.

Allow insecure HTTP can only be used after Allow private network is enabled, and should only target approved private-network ZenTao deployments. Public ZenTao instances should use HTTPS.

Where to get configuration values

Configuration value	Where to get it
ZenTao site URL	Use the ZenTao instance root URL. Public deployments should use HTTPS; API routes are usually under `api.php`. See RESTful API v1 configuration and FAQ.
Account / password / token validation	Exchange a dedicated account and password for an API Token. See ZenTao developer manual: get Token.
Project ID	Confirm it from the ZenTao project URL or project list. You can also validate it with get projects (v2).
Product ID	Confirm it from the ZenTao product URL or product list. You can also validate it with get products (v2).
API version differences	ZenTao private deployments can differ by version; API routes and request-header casing may vary. Read API v2.0 tutorial before upgrading or switching API versions.

Configure in AIvis

In the Admin panel, open Connectors, select ZenTao, create or choose a ZenTao credential, and then enter instance URL, scope IDs, content switches, and network options.

Field	How to fill it	Notes
ZenTao site URL	For example `https://zentao.example.com`	The connector normalizes the root URL to the API base.
Account	Dedicated read-only account	Used to authenticate to ZenTao API.
Password	Account password	Stored as a protected secret.
Project IDs	One positive integer per line	Required when tasks are enabled.
Product IDs	One positive integer per line	Required when bugs are enabled.
Include requirements	Enabled by default	Reads project and/or product requirements.
Include tasks	Enabled by default	Reads tasks under project executions.
Include bugs	Enabled by default	Reads product bugs.
Include attachments	Disabled by default	Emits parseable attachments as child documents.
Allow private network	Disabled by default	Only for approved private deployments.
Allow insecure HTTP	Disabled by default	Available only with private-network access.

Sync behavior

The standard Admin-created ZenTao connector runs as a polling connector with checkpoint resume.

Stage	Behavior
Scope validation	Attempts to read the first page of target project or product data before indexing.
Requirements	Reads project and/or product requirement details.
Tasks	Reads project execution lists, then task details under those executions.
Bugs	Reads product bug details.
Attachments	Emits attachments as child documents and records item failures when parsing fails.

The connector guards against unstable pagination, duplicate objects, and oversized inventories.

Permissions

The ZenTao account determines what AIvis can ingest, but this connector does not synchronize ZenTao members, roles, product permissions, field permissions, or per-object access into AIvis.

AIvis access setting	Meaning
Private groups	Only selected AIvis groups can search documents produced by this connector. Recommended for project, customer, and engineering data.
Public	Every eligible AIvis user can search indexed content. Use only for projects that can be shared with that audience.
Auto permission sync	ZenTao is not supported for this mode.

Use AIvis Private groups for project, customer, and engineering data. Use Public only when every eligible AIvis user may search every indexed object. ZenTao is not available as an auto permission-sync source.

Verify

Create a connector with one test project ID or product ID.
Search known requirement, task, and bug titles, descriptions, and statuses.
If attachments are enabled, upload a small parseable attachment and confirm it is searchable.
Search unlisted projects or products and confirm they are absent.
Test assigned and outside AIvis users.
Modify one test object and confirm the next sync updates it.

Troubleshooting

Symptom	What to check
Site validation fails	Backend reachability, HTTPS for public instances, and private-network options.
Login fails	Account, password, API login ability, and password rotation.
Project or product not found	ID value and account access to the target scope.
Task indexing cannot be created	A project ID is required when tasks are enabled.
Bug indexing cannot be created	A product ID is required when bugs are enabled.
Attachments are missing	Attachment switch, download reachability, file type, and size.
Users can search content they should not see	Restrict AIvis groups or split connectors by project/product/audience.

Security and maintenance

Use a dedicated read-only account instead of an administrator account.
Enable private-network or insecure HTTP options only for controlled private deployments.
Review project IDs, product IDs, content switches, attachment settings, account owner, and AIvis groups regularly.
Rotate the password if it may have leaked.
Disable or narrow the connector when projects or products are retired.