Build a Program with AI

The External Program Connector only needs a command-line program that follows a published protocol. The protocol specification is written to stand on its own, so you can give it to an AI assistant such as Claude, ChatGPT or GitHub Copilot and ask for a program for your data source. The assistant needs no knowledge of Data Sync.

The result is a connector for your own system, in a language you choose, without learning the protocol first.

1. Get the Specification

Download the External Program Connector Protocol, version 1

The specification is also available at this address, for assistants that can read web pages:

https://docs.simego.com/downloads/external-program-protocol-v1.md

How you use it depends on your assistant:

Type of assistant	Examples	How to work
Coding agent	Claude Code, GitHub Copilot agent mode	Save the specification in an empty project folder. The agent can write the program, run it, and fix what fails by itself.
Chat	Claude, ChatGPT	Attach the specification to the conversation. You run the program yourself and paste back any errors.

A coding agent is the better choice for anything beyond a simple read-only program, because it can run the tests in the specification.

2. Decide What to Ask For

The assistant takes the protocol from the specification. It needs you to describe your data:

Tell the assistant	Why it matters
The data source and how to reach it	Link to the API documentation, or include a sample response or a sample file.
The language and libraries	The language must be installed wherever the project runs, including on Ouvvi agents.
The datasources	Which tables, files or API resources should be listed in Data Sync.
The key of each datasource	It must be unique and stable. If you don't know it, ask the assistant to suggest one and explain why.
Read-only, or which of add, update and delete	Start read-only unless you need to write.
The parameters	For example a URL or folder, and which values are secret.
The time zone of dates	This decides which DateTimeHandling setting the connection needs.
The amount of data	Each read must finish within the timeout, 5 minutes by default, and all rows are held in memory.

3. Ask for the Program

Copy this prompt and fill in the parts in square brackets:

Build a command-line program that lets Data Synchronisation Studio connect to
[describe the data source] through its External Program Connector.

Implement the attached specification, external-program-protocol-v1.md, exactly.
It is the complete contract. Read all of it first, especially sections 1.1, 5, 7, 8 and 11.

Language: [for example Python 3.12, using only the requests library]
Datasources: [list them, or say how to discover them]
Key of each datasource: [column names, or ask for a suggestion]
Access: [read-only / add, update and delete]
Parameters: [for example BaseUrl (required), ApiKey (required, secret)]
Date and time values are in: [UTC / a named time zone / there are none]
Expected size: [for example about 50,000 rows]
Data source details: [link to documentation, a sample response or a sample file]

Requirements:
- Declare "stop": true in info and support --stop-file.
- read must return every row, or exit with code 1. Never exit 0 after a partial
  read, for example when one page of an API fails.
- Never put secrets in the code, the arguments or the log file.
- Declare each column with its correct data type, and write each value the same
  way on every run.

When it is built, run the tests in section 12 of the specification, using
[a test folder / a sandbox account] and report the result of each item in the checklist.
Tell me what to set for ProgramPath, ScriptPath, Parameters and DateTimeHandling.

Example

This is a filled-in prompt for a read-only connection to a REST API:

Build a command-line program that lets Data Synchronisation Studio connect to our
helpdesk system's REST API through its External Program Connector.

Implement the attached specification, external-program-protocol-v1.md, exactly.
It is the complete contract. Read all of it first, especially sections 1.1, 5, 7, 8 and 11.

Language: Python 3.12, using only the requests library
Datasources: Tickets and Agents
Key of each datasource: id
Access: read-only
Parameters: BaseUrl (required), ApiToken (required, secret)
Date and time values are in: UTC
Expected size: about 80,000 tickets, returned 500 per page
Data source details: see the attached openapi.yaml. Authenticate with an
"Authorization: Bearer" header. On HTTP 429, wait for the time in Retry-After.

Requirements:
- Declare "stop": true in info and support --stop-file.
- read must return every row, or exit with code 1. Never exit 0 after a partial
  read, for example when one page of an API fails.
- Never put secrets in the code, the arguments or the log file.
- Declare each column with its correct data type, and write each value the same
  way on every run.

When it is built, run the tests in section 12 of the specification against
https://sandbox.example.com, and report the result of each item in the checklist.
Tell me what to set for ProgramPath, ScriptPath, Parameters and DateTimeHandling.

To add writing later, continue the conversation: "Add write add and write update for Tickets, following section 5.5 of the specification, and test each rule in that section's table."

4. Review What It Built

warning

Data Sync runs the program with the same access as your account, or as the account of the Ouvvi agent. Treat generated code as you would code from any other source, and read it before you run it against real systems.

Before you connect the program:

• Check what it does. Ask the assistant to list each system, file and address the program touches, and what it changes.
• Keep secrets out of the conversation. Use placeholders, a sandbox account and sample data when working with an AI service. Enter real values only in the Parameters of the connection, where secret values are encrypted.
• Check how failures are handled. A read that fails part way must exit with code 1. If the program is the source and returns too few rows without an error, Data Sync treats the missing rows as deleted and removes them from the target.
• Check the write code closely. An add must never overwrite an existing row, and a failed change mustn't stop the others.

5. Test It in Data Sync

1. Add an External Program connection with the settings that the assistant gave you.
2. Enter the Parameters and choose a DataSource.
3. Open a Data Preview and check the rows, data types and dates.
4. If the program will be a target, connect it to a copy or test area of your data.
5. Run a Compare and check the results before you run a Sync.
6. Run a Compare again after the sync. It should find no changes. If it does, see below.

6. Fix Problems

Give the assistant the exact error message and the row or value involved. These are common problems and what to ask for:

What you see	What to ask the assistant
The same rows are updated on every sync	"Column X reads back as A after being written as B. Fix this following sections 1.1 and 7 of the specification."
Times are out by some hours	"Dates are stored in [time zone]. Which DateTimeHandling should I use, and does the program convert times as section 7 describes?"
A key is reported as duplicated, or an add says the row exists	"Rows aren't matching. Check that the key of [datasource] is unique and stable, as section 1.1 requires."
The read times out	"A read takes [time]. Make it faster, stream rows to the output as they arrive, and support --stop-file." Increase TimeoutSeconds if the read needs longer.
It works in a terminal but not in Data Sync	"It fails under Data Sync with [message]. It runs with --config, from the working directory [folder], as [account]. Don't rely on the current folder or on environment variables."
Non-English text is wrong	"Make every file UTF-8, as section 6.1 of the specification requires."

When the program works, keep the specification and your prompt with its source code, so that you or an assistant can change it later. See the Program Protocol page for a summary of how the program works, and the connector guide for each setting.