Feat: Add Role object (Common Roles only) (#53)

* Add Role object (Common Roles only)

Lets consumers represent a Common (global) Role, so services like
functions-db-service can expose which roles a Person has.
Organizational-Context roles are not represented by this object.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Rename Role to CommonRole

Per review feedback: naming it Role/"role" now would make it awkward to
add other role types (e.g. Org-Context roles) later without a breaking
API change, since the discriminator value is part of the wire format.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Jens Kürten <jens.kuerten@contact-software.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: 3 people

csfunctions/objects/__init__.py

@@ -5,6 +5,7 @@
 from .base import BaseObject
 from .briefcase import Briefcase
 from .classification import ObjectPropertyValue
+from .common_role import CommonRole
 from .document import CADDocument, Document
 from .engineering_change import Change, ChangeOrder, ChangeRequest, EngineeringChange
 from .file import File
@@ -26,7 +27,8 @@
     | Briefcase
     | Workflow
     | Person
-    | MaturityLevel,
+    | MaturityLevel
+    | CommonRole,
     Field(discriminator="object_type"),
 ]
 
@@ -48,4 +50,5 @@
     "BaseObject",
     "Person",
     "MaturityLevel",
+    "CommonRole",
 ]

csfunctions/objects/base.py

@@ -23,6 +23,7 @@ class ObjectType(str, Enum):
     BRIEFCASE = "briefcase"
     PERSON = "person"
     MATURITY_LEVEL = "maturity_level"
+    COMMON_ROLE = "common_role"
 
 
 class BaseObject(BaseModel):

csfunctions/objects/common_role.py

@@ -0,0 +1,20 @@
+from typing import Literal
+
+from pydantic import Field
+
+from csfunctions.objects.base import BaseObject, ObjectType
+
+
+class CommonRole(BaseObject):
+    """
+    A Common (global) Role that can be assigned to a Person.
+    """
+
+    object_type: Literal[ObjectType.COMMON_ROLE] = ObjectType.COMMON_ROLE
+
+    role_id: str = Field(..., description="Role ID")
+    name_de: str | None = Field(None, description="Name DE")
+    name_en: str | None = Field(None, description="Name EN")
+    name_ja: str | None = Field(None, description="Name JA")
+    name_zh: str | None = Field(None, description="Name ZH")
+    cdb_object_id: str | None = Field(None, description="Object ID")

docs/reference/objects.md

@@ -246,6 +246,20 @@ A change request of the ECM module. Shares all attributes of its base class `csf
 |cdb_mpersno|str|Last Modified by|
 |cdb_mdate|datetime \| None|Last Modified on|
 
+## CommonRole
+`csfunctions.objects.CommonRole`
+
+A Common (global) Role that can be assigned to a Person.
+
+|Attribute|Type|Description|
+|-|-|-|
+|role_id|str|Role ID|
+|name_de|str \| None|Name DE|
+|name_en|str \| None|Name EN|
+|name_ja|str \| None|Name JA|
+|name_zh|str \| None|Name ZH|
+|cdb_object_id|str \| None|Object ID|
+
 ## Document
 `csfunctions.objects.Document`
 

docs/release_notes.md

@@ -3,6 +3,9 @@ hide:
   - toc
 ---
 
+### Version next
+- Feat: Add CommonRole object
+
 ### Version 0.27.0
 - Feat: Add part_blocked and document_blocked events
 - Feat: Add reviewers field to PartReleaseCheckEvent and DocumentReleaseCheckEvent, populated for express releases