improve docs

Author: Jens Kürten

docs/assets/connect_function.png

@@ -0,0 +1,99 @@
+Functions can be used to validate user input and thus ensure that fields on e.g. parts or documents are filled out correctly.
+
+
+### Required field based on Part category
+This example shows how you can enforce parts of category *"Single Part"* to have a material assigned to them.
+
+The example Function can be connected to the [PartCreateCheckEvent](../reference/events.md#partcreatecheckevent) and [PartModifyCheckEvent](../reference/events.md#partmodifycheckevent) and will return an [AbortAndShowErrorAction](../reference/actions.md#abortandshowerroraction) to abort the creation or modification of the part if the condition is not met.
+
+```python
+from csfunctions import MetaData, Service
+from csfunctions.actions import AbortAndShowErrorAction
+from csfunctions.events import (
+    PartCreateCheckEvent,
+    PartModifyCheckEvent,
+)
+
+
+def single_part_needs_material(
+    metadata: MetaData,
+    event: PartCreateCheckEvent | PartModifyCheckEvent,
+    service: Service,
+):
+    """
+    If a part of category ' Single Part' is created, a material has to be assigned.
+    This should be checked when the part is created or modified.
+    """
+
+    for part in event.data.parts:
+        # the event contains a list of parts that are about to be created
+        if part.t_kategorie_name_en == "Single Part" and not part.material_object_id:
+            return AbortAndShowErrorAction(
+                message="A material has to be assigned to a part of category 'Single Part'."
+            )
+
+```
+
+### Require parts to be classified before release
+
+Classification is a powerful tool for organizing your parts, however the best tool only works if users use it.
+With this example Function you can require parts to be classified before they can be released.
+
+This Function should be connected to the [PartReleaseCheckEvent](../reference/events.md#partreleasecheckevent) and will return an [AbortAndShowErrorAction](../reference/actions.md#abortandshowerroraction) to prevent the release, if classification data is missing.
+
+The example code shows you how to fetch classification data for parts from the [CIM Database Cloud GraphQL API](https://saas-docs.contact-cloud.com/latest-en/admin/admin-contact_cloud/saas_admin/webhooks_graphql){:target="_blank"}. The Function then checks if any classification data is present, however you can easily expand this to check for specific classes.
+
+```python
+from csfunctions import MetaData, Service
+from csfunctions.actions import AbortAndShowErrorAction
+from csfunctions.events import (
+
+    PartReleaseCheckEvent,
+)
+import requests
+
+
+def fetch_part_classification_property_codes(cdb_object_id: str, metadata: MetaData) -> list[str]:
+    """
+    Returns a list of classification property codes for a given object ID.
+    """
+
+    graphql_url = str(metadata.db_service_url).rstrip("/") + "/graphql/v1"
+    query = f"""{{
+        object_property_values(ref_object_id: "{cdb_object_id}") {{
+            property_code
+        }}
+    }}
+    """
+    response = requests.post(
+        graphql_url,
+        headers={"Authorization": f"Bearer {metadata.service_token}"},
+        json={"query": query},
+    )
+    response.raise_for_status()
+    data = response.json()
+    return [
+        item["property_code"]
+        for item in data["data"]["object_property_values"]
+    ]
+
+
+def parts_need_classification(
+    metadata: MetaData,
+    event: PartReleaseCheckEvent ,
+    service: Service,
+):
+    """
+    Parts need to be classified before they can be released.
+    """
+
+    for part in event.data.parts:
+        # the event contains a list of parts that are about to be released
+        # for each part fetch the classification property codes and check if they are empty
+        property_codes = fetch_part_classification_property_codes(part.cdb_object_id, metadata)
+        if not property_codes:
+            return AbortAndShowErrorAction(
+                message=f"The part '{part.eng_benennung or part.benennung}' is missing classification data."
+            )
+
+```

docs/assets/create_codespace.png

@@ -0,0 +1,107 @@
+# Field calculation
+
+The data sheet editor in CIM Database Cloud already allows you to define some basic [field calculations](https://saas-docs.contact-cloud.com/2025.13.1-en/admin/admin-contact_cloud/saas_admin/app_setup_data_edit_field_calc){:target="_blank"} to fill out fields automatically.
+
+However, the Python expressions available in the datasheet editor are limited. Functions allow for much more freedom in defining your field calculations, and allow you to do things like *"fetching external data"* or *"referencing other objects"*.
+
+Field calculations with Functions utilize the "<Object\>FieldCalulationEvent", e.g. [PartFieldCalculationEvent](../reference/events.md#partfieldcalculationevent), which expect the response to contain a `DataResponse` with a dictionary containing the fields that should be updated.
+
+```python
+return DataResponse(data={somefield="new value"})
+```
+
+
+## Custom part number for external parts
+
+This example shows you the basics of calculating fields with Functions and how to use the `service` parameter to generate a fresh number.
+
+The example Function checks if the part is an *"External"* part and generates a custom part number for it.
+
+```python
+from csfunctions import DataResponse
+from csfunctions.events import PartFieldCalculationEvent
+from csfunctions.metadata import MetaData
+from csfunctions.service import Service
+
+
+def calculate_part_number(metadata: MetaData, event: PartFieldCalculationEvent, service: Service):
+    """
+    Example Function.
+    This function is triggered when a part fields should be calculated.
+    For "External" parts we want to set the part number as "E-000123".
+    All other parts should keep the standard part number.
+
+    """
+    if event.data.action != "create":
+        # part number can only be set when the part is created
+        return
+
+    # match "External Single Part" or "External Assembly"
+    if event.data.part.t_kategorie_name_en.startswith("External"):
+
+        # generate a new number using the service
+        new_number = service.generator.get_number("external_part_number")
+
+        # new_number is an integer, so we need to convert it to a string
+        # and pad it with leading zeros to 6 digits
+        new_part_number = str(new_number).zfill(6)
+
+        # then add the prefix "E-" to the number
+        new_part_number = "E-" + new_part_number
+
+        # finally we return the new part number (teilenummer)
+        return DataResponse(data={"teilenummer": new_part_number})
+```
+
+!!! tip
+    You can check `event.data.action` to decide for which operations (*copy*,*create*,*index* and *modify*) you want your field calculation to return a new value.
+    Some fields, like part number (*teilenummer*) can only be set during the initial creation.
+
+## Translate a field with DeepL
+
+Inside Functions you can fetch data from external systems and fill out fields based on that data. This is something that would not be possible with the field calculations in the datasheet editor. You could use this for example to fetch new part numbers from an ERP system.
+
+This example uses the API from [DeepL](https://www.deepl.com) to translate a field from German to English. The example uses the additional attributes 1 and 2 on parts, but you can of course change that to any attributes that fit your use-case.
+
+```python
+import os
+from csfunctions import DataResponse
+from csfunctions.events import PartFieldCalculationEvent
+import requests
+
+# set the DEEPL_API_KEY during deployment like this:
+# cfc env deploy <environment name> --environment-variables "DEEPL_API_KEY=<your API key>"
+DEEPL_API_KEY = os.getenv("DEEPL_API_KEY")
+
+def part_field_calculation(metadata, event: PartFieldCalculationEvent, service):
+    if event.data.action != "create":
+        # only translate on creation
+        return
+
+    if event.data.part.cssaas_frame_add_attr_1:
+        translated_text = translate_text(
+            event.data.part.cssaas_frame_add_attr_1, "EN", "DE")
+        return DataResponse(data={"cssaas_frame_add_attr_2": translated_text})
+
+def translate_text(text, target_lang, source_lang=None):
+    url = "https://api-free.deepl.com/v2/translate"
+    data = {
+        "auth_key": DEEPL_API_KEY,
+        "text": text,
+        "target_lang": target_lang.upper()
+    }
+    if source_lang:
+        data["source_lang"] = source_lang.upper()
+
+    response = requests.post(url, data=data)
+    response.raise_for_status()
+    return response.json()["translations"][0]["text"]
+
+```
+
+!!! note
+    This example requires a DeepL API key to function. Adding secrets like API keys to your code is a bad practice, which is why the example fetches the API key from an environment variable.
+
+    You can set environment variables during deployment of your Function to the CIM Database Cloud Functions infrastructure like this:
+
+    `cfc env deploy <environment name> --environment-variables "DEEPL_API_KEY=<your API key>"`

docs/assets/display_function_credentials.png

@@ -0,0 +1,4 @@
+# Examples
+
+This section contains example Functions that you can copy and adapt to your specific use case.
+Remember to [register the Function](../getting_started.md#register-the-function) in the `environment.yaml` after copying it into your code base.

docs/assets/portal-user-menu.png

@@ -0,0 +1,75 @@
+# Working with workflows
+
+Functions can interact with workflows. You can trigger Functions from within workflows using the [Trigger Webhook](https://saas-docs.contact-cloud.com/latest-en/admin/admin-contact_cloud/saas_admin/webhooks_workflow){:target="_blank"} task and you can even start new workflows by using the [StartWorkflowAction](../reference/actions.md#startworkflowaction)!
+
+
+## Start workflow on EC status change
+
+This example shows you how to start a workflow template in response to an engineering change status change.
+
+!!! note
+    Starting workflows in response to engineering change status changes is already possible in CIM Database Cloud without the use of Functions. However Functions allow you to dynamically select different templates and fill out task parameters, based on the nature of the change.
+
+This example uses a very simple template, containing just an *information task*. If an engineering change contains external parts, users with the *External Part Manager* Role should be notified of the planned change during the evaluation phase.
+
+You can easily adapt this example to your use-case, by adding additional tasks to the template or changing the conditions under which the workflow should be started.
+
+
+```python
+from csfunctions.actions.start_workflow import (
+    StartWorkflowAction,
+    Subject,
+    TaskConfiguration,
+)
+from csfunctions.events import EngineeringChangeStatusChangedEvent
+from csfunctions import MetaData
+
+# change these to match your template and roles!!!
+TEMPLATE_ID = "PT00000002"
+INFORMATION_TASK_ID = "T00000008"
+INFORM_ROLE = "External Part Manager"
+
+
+def start_workflow_on_ec_status_change(
+    metadata: MetaData, event: EngineeringChangeStatusChangedEvent, service
+):
+    if event.data.engineering_change.status != 30:
+        # only start the workflow if the status changed to 30 (Evaluation)
+        return
+
+    # check if the ec contains external parts
+    if not any(
+        part.t_kategorie_name_en.startswith("External")
+        for part in event.data.engineering_change.planned_changes_parts
+    ):
+        # no external parts, so we don't need to start the workflow
+        return
+
+    return StartWorkflowAction(
+        template_id=TEMPLATE_ID,
+        title=f"Information about EC {event.data.engineering_change.cdb_ec_id}",
+        # attach the engineering change to the workflow
+        global_briefcase_object_ids=[
+            event.data.engineering_change.cdb_object_id],
+        task_configurations=[
+            TaskConfiguration(
+                task_id=INFORMATION_TASK_ID,
+                description="A an engineering change containing external parts moved to the evaluation phase.",
+                recipients=[
+                    Subject(
+                        subject_type="Common Role",
+                        subject_id=INFORM_ROLE,
+                    )
+                ],
+            )
+
+        ],
+    )
+```
+
+!!! note
+    To sucessfully execute this example you need to:
+
+    - Create a workflow template with an information task and adjust the `TEMPLATE_ID` and `INFORMATION_TASK_ID` to match them
+
+    - Create and assign an "External Part Manager" role to a user