Collection hierarchy and subcollection requests¶

KCWorks supports parent/child relationships between collections (InvenioRDM subcommunities). A child collection can request to join under a parent, or a parent can invite an existing child. Both flows use the standard Requests inbox on the collection that is the request receiver.

Operations below assume you are in the KCWorks UI app container. See Starting an interactive shell.

Prerequisites¶

Enable a parent to accept children¶

A parent collection must have children.allow set to true before join requests succeed or the subcollection UI pages load. By default new collections have children.allow=false.

Collection owners can enable this with a community API update (authenticated as the owner):

curl -X PATCH "https://<site>/api/communities/<parent-uuid>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"children": {"allow": true}}'

Administrators can also use the set-parent CLI with --enable-children (see Direct parent assignment below).

Until children.allow is true on the parent:

POST /api/communities/<parent-id>/actions/join-request returns an error
/collections/<parent-slug>/subcommunities/new returns 404

Child requests to join a parent (`subcommunity`)¶

Use this when the child collection initiates the relationship.

Roles:

Request field	Community
`created_by`	Child (requester)
`receiver`	Parent (must have `children.allow=true`)
`topic`	Child

Where it appears: the parent’s Requests tab (/collections/<parent-slug>/requests).

API (existing child collection)¶

The caller must be an owner of the child collection.

curl -X POST "https://<site>/api/communities/<parent-uuid>/actions/join-request" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"community_id": "<child-uuid>"}'

API (create a new child as part of the request)¶

curl -X POST "https://<site>/api/communities/<parent-uuid>/actions/join-request" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "community": {
      "title": "My subcollection",
      "slug": "my-subcollection"
    }
  }'

UI¶

When the parent allows children, owners can open:

/collections/<parent-slug>/subcommunities/new

That form submits to the same join-request API.

Auto-accept when one user owns both collections¶

If the authenticated user is an owner of both the child and the parent, the join service accepts the request immediately and links the child under the parent without leaving it in the inbox.

This auto-accept applies only to subcommunity join-requests, not to subcommunity-invitation requests.

Parent invites a child (`subcommunity-invitation`)¶

Use this when the parent collection invites an existing child to join.

Roles:

Request field	Community
`created_by`	Parent
`receiver`	Child
`topic`	(none)

Where it appears: the child’s Requests tab (/collections/<child-slug>/requests).

There is no dedicated KCWorks UI page for creating this invitation today. Create it from a Flask shell in the UI container (replace IDs and use the parent owner’s identity):

from invenio_access.permissions import authenticated_user
from invenio_access.utils import get_identity
from invenio_accounts.proxies import current_accounts
from invenio_communities.proxies import current_communities

parent_owner = current_accounts.datastore.get_user(<parent-owner-user-id>)
identity = get_identity(parent_owner)
identity.provides.add(authenticated_user)

current_communities.subcommunity_service.create_subcommunity_invitation_request(
    identity=identity,
    parent_community_id="<parent-uuid>",
    child_community_id="<child-uuid>",
    data={"title": "Invitation to join parent collection"},
)

The child collection’s owners accept or decline from their Requests inbox.

Auto-accept: unlike join-requests, invitations are not auto-accepted when the same user owns both collections. A manager on the receiving (child) side must accept (or you can use direct assignment below).

Direct parent assignment (without a request)¶

For operational backfills or when both sides are under your control, use the set-parent CLI instead of the request workflow:

invenio kcworks-communities set-parent <child-slug> <parent-slug> --enable-children

See CLI Commands for --clear, --force, and other options. This uses system identity and does not create an inbox request.

Notifications¶

Email and chat notifications for subcollection requests link to the request in the receiver collection’s Requests inbox. KCWorks builds those URLs from RDM_REQUESTS_ROUTES["community-dashboard-request-details"] in invenio.cfg (currently /collections/<pid_value>/requests/<request_pid_value>).

Nested hierarchies¶

KCWorks allows more than one level of nesting (a child whose parent already has a parent). Upstream Invenio limits nesting to a single level; KCWorks replaces the parent validation component to allow deeper trees. Each parent in the chain still needs children.allow=true for request-based linking to that parent.