Summary: Learn the basic structure for coding a BrynQ interface with TaskScheduler and the brynq_sdk libraries.

Requirements: - You need developer access to the interface code repository. - You need access to Developer settings for the interface in BrynQ. - The source and target app authorizations must already be available or planned.

Coding an Interface

An interface script moves data from a source app to a target app. In BrynQ, the script usually runs as a TaskScheduler task and uses one or more brynq_sdk libraries to read, transform, and write data.

Understand the main parts

• TaskScheduler is the base class for a runnable interface task. It starts the run, writes logs, handles errors, and finishes the run with the correct result.
• brynq_sdk libraries are Python packages for specific apps or shared services. For example, a source app can use brynq_sdk_bob, while a target app can use brynq_sdk_zoho.
• Source SDK is the SDK used to read data from the source app.
• Target SDK is the SDK used to write or update data in the target app.
• Run file path tells BrynQ which Python file should be started for the interface.
• Docker Image tells BrynQ which runtime image should run the code.

Use a simple task structure

Start with one class that extends TaskScheduler. Keep the main flow inside run() so the interface is easy to read and test.

from brynq_sdk_task_scheduler import TaskScheduler
from brynq_sdk_bob import Bob


class SyncEmployees(TaskScheduler):
    def __init__(self, data_interface_id: int | None = None):
        super().__init__(data_interface_id=data_interface_id, loglevel="INFO")
        self.source = Bob(system_type="source", test_environment=False)

    def run(self):
        try:
            self.write_execution_log("Starting employee sync")
            employees, invalid_employees = self.source.people.get(
                field_selection=[
                    "root.id",
                    "work.employeeIdInCompany",
                    "root.email",
                    "root.firstName",
                    "root.surname",
                ]
            )

            self.write_execution_log(f"Read {len(employees)} employees from Bob")
            if len(invalid_employees) > 0:
                self.write_execution_log(
                    f"Skipped {len(invalid_employees)} invalid employees",
                    loglevel="ERROR",
                )

            for employee in employees.to_dict("records"):
                payload = {
                    "external_id": employee["work.employeeIdInCompany"],
                    "first_name": employee["root.firstName"],
                    "last_name": employee["root.surname"],
                    "email": employee["root.email"],
                }
                # Replace this with the target app SDK call for your interface.
                # Example: self.target.upsert_employee(payload)
                self.write_to_target(payload)

            self.write_execution_log(f"Synced {len(employees)} employees")
            self.finish_task()
        except Exception as error:
            self.error_handling(error)

    def write_to_target(self, payload: dict):
        pass


if __name__ == "__main__":
    SyncEmployees(data_interface_id=13).run()

This example shows the basic pattern only. The exact SDK class names and methods depend on the apps used by the interface.

Keep the run flow clear

• Read source data first, such as employees, contracts, or absence records.
• Transform the data into the format expected by the target app.
• Write the transformed data to the target app.
• Use write_execution_log for important progress messages that users should see in the run logs.
• Use error_handling in the exception block so BrynQ marks a failed run correctly.
• Use finish_task after the work is complete so BrynQ can mark the run as finished.

Configure Developer Settings

Developer settings connect the code to the interface setup in BrynQ.

Fill in the SDK fields

• In the left navigation, open Interfaces and select the interface.
• In the interface step navigation, open Developer settings.
• Under Source SDK, fill in SDK name with the source package name, for example brynq_sdk_bob.
• Under Source SDK, fill in SDK version with a version such as 1.2.3, or local during local development when that is allowed.
• Under Target SDK, fill in SDK name with the target package name, for example brynq_sdk_zoho.
• Under Target SDK, fill in SDK version with the version that should be installed for the interface.

Fill in the run settings

• In Docker Image, enter the image that contains the Python runtime and dependencies for the interface.
• In Run file path, enter the path to the Python file that contains the if __name__ == "__main__" block.
• Use Stop is allowed only when it is safe for a user to stop the interface during a run. Leave it off when stopping halfway could leave data in an unclear state.
• Use Interface is in development while the code is still being built or tested. Turn it off only when the interface is ready for normal use.

Basic Coding Rules

Keep the first version small and predictable.

Log what matters

• Log the start of the run.
• Log counts, such as how many records were read and how many were written.
• Log skipped records with a clear reason, for example missing email address or missing employee number.
• Do not log secrets, access tokens, passwords, or full personal data payloads.

Handle records safely

• Use a stable unique value, such as employee number or external ID, to match source records to target records.
• Validate required fields before sending data to the target app.
• Skip or log records that cannot be processed safely instead of guessing missing values.
• Keep transformations simple. For example, map Active from the source app to Employed in the target app only when that rule is agreed.

Test before scheduling

• Run the script locally with a small test set first.
• Check the run logs in BrynQ after a test run.
• Confirm that the target app received the expected values.
• Enable the schedule only after the code, authorization, mapping, and variables are complete.

More Information

Example: an employee interface reads Employee number, First name, Last name, and Email from the source app. The code uses Employee number as the unique key, formats the name and email for the target app, then writes the employee to the target app. If Email is missing, the script logs the skipped record and continues with the next employee. This keeps the run understandable and prevents one bad record from hiding the rest of the result.