Sharing

Sharing defines who can see or edit a record in tSM (Tickets, Orders, Documents, etc.).
It lets you grant access to people, groups, or roles, mark a record as public, and capture the purpose of sharing (owner, collaborator, reviewer, …).

Typical use cases:

• Collaboration — invite a teammate or group to co-work on a ticket or order
• Stakeholder access — give read-only visibility to Account or Compliance
• Publishing — expose a document or FAQ to all portal users (isPublic)
• DMS/Knowledge — maintain ACLs on files, folders, and knowledge items

Related concepts (covered in the overview): supporting entities link to a parent via ownerType and ownerId.
Sharing entries further reference a participant via refType/refId and classify the intent with sharingTypeCode.

---

Typical Flows

1) Make a record public (no specific participant)

@dms.sharing.create({
  "ownerType": "Document",
  "ownerId": #document.id,
  "isPublic": true,
  "sharingTypeCode": "Public",
  "description": "Published for all portal users"
})

2) Add a collaborator (user)

@dms.sharing.create({
  "ownerType": "Ticket",
  "ownerId": #ticket.id,
  "refType": "User",
  "refId": #assignee.id,
  "sharingTypeCode": "Collaborator",
  "isPublic": false,
  "description": "Primary engineer"
})

3) Grant a group read-only visibility

@dms.sharing.create({
  "ownerType": "Order",
  "ownerId": #order.id,
  "refType": "Group",
  "refId": "ACCOUNTING",
  "sharingTypeCode": "Viewer",
  "isPublic": false,
  "description": "Accounting visibility for invoicing"
})

4) List all sharing entries for a record

@dms.sharing.search({
  "ownerType": "Ticket",
  "ownerId": #ticket.id
})

---

Business & Governance

• Who vs. Why — refType/refId identify who gets access (user, group, role, external party), while sharingTypeCode captures why (owner, collaborator, reviewer, viewer).
• Public vs. targeted — set isPublic = true to publish broadly (e.g., customer portal). Otherwise, specify a refType/refId participant.
• Least privilege — prefer narrow sharingTypeCode semantics (e.g., Viewer vs. Collaborator) and align them with role-based permissions.
• Auditability — all sharing records carry audit info; use description for justification to support reviews.
• DMS alignment — use sharing to drive ACLs consistently across Tickets, Orders, and DMS items (documents/folders).

---

Reference

Sharing (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Unique identifier (not intended for end-user display).
ownerType	String	Yes	–	The record being shared (e.g., Ticket, Order, Document).
ownerId	String	Yes	–	ID of the record being shared.
refType	String	Yes*	–	Participant type (e.g., User, Group, Role, External). Required unless isPublic = true.
refId	String	–	–	Participant identifier (user ID, group code, role name, …). Optional for public shares.
sharingTypeCode	String	Yes	–	Purpose/role of the share (e.g., Owner, Collaborator, Viewer, Public).
description	String	–	–	Business rationale/context; useful for audits.
isPublic	Bool	Yes	–	true to make the owner entity visible to everyone (target audience defined by portal/tenant policy).
auditInfo	Object	–	–	Standard audit fields (created by/at, updated by/at).
data	Map	–	–	Custom metadata (e.g., expiration policy, scope hints).

• Rule of thumb: Provide refType/refId for targeted sharing; omit them for public shares.

---

Sharing Type (code table)

Defines allowed sharingTypeCode values and their semantics (owner, collaboration, viewer, reviewer, …). These codes are looked up by code and displayed by name.

Field	Type	Required	Read-only	Notes
code	String	Yes	–	Unique ASCII code (no spaces).
name	String	Yes	–	Display name shown to users.
description	String	–	–	Tooltip/longer description.
validityFrom/To	Date	–	–	Validity window controlling if the type is usable.
valid	Boolean	–	Yes	Computed from validity; not stored.
localizationData	Object	–	–	Translations for attributes.
config	Map	–	–	Additional configuration.
dataTags	List	–	–	Labels/tags for search/reporting.
auditInfo	Object	–	–	Standard audit fields.

---

Good Practices

• Define clear types — align sharingTypeCode with your permission model (Owner, Collaborator, Viewer, Reviewer, …).
• Target narrowly — prefer user/group/role shares over broad public sharing unless required by policy.
• Annotate intent — use description to explain why access was granted (helps periodic reviews).
• Automate revocation — store expiration or conditions in data (e.g., { "expiresAt": "2026-01-01" }) and enforce via jobs.
• Audit regularly — report on sharing by owner entity and participant to maintain least privilege.

---

See Also

• Supporting Entities – Overview (ownership & typing model)
• Attachment — DMS files that frequently rely on Sharing for ACLs
• Comment — collaboration notes (pair well with sharing rules)
• SpEL Clients — configuration & usage