Pull external data into your register with OpenConnector

Click Add Source. The Create Source dialog asks for a name, a type, an optional description, and an isEnabled toggle (on by default). Name it Swagger Pet Store (Academy), set the type to api (the type tells OpenConnector's CallService which adapter to dispatch at runtime — api is plain HTTP), add a short description, and leave it enabled. Click Create.

Now give the source its location — the base URL it talks to. Open the source from the list (its Actions → View) and set the location to https://petstore.swagger.io/v2. This public API needs no authentication, so there are no credentials to add. The detail page shows the source's full record: location, type, isEnabled, and the auth, rate-limit and retention fields you would fill in for a real, secured source.

Use the source's Actions → Test connection to confirm OpenConnector can reach the host. OpenConnector pings the source's base location and records the response. For the Swagger Pet Store the bare base path returns a server response (the host is reachable; the root simply has no resource of its own) — the real end-to-end check is running the synchronisation in Step 4, which calls an actual endpoint.

Host http://localhost:8080, basic auth admin:admin, and the header OCS-APIRequest: true on every call. Create the source with its location and type, then test connectivity with its id:

curl -u admin:admin -X POST "http://localhost:8080/index.php/apps/openconnector/api/sources" \
  -H "OCS-APIRequest: true" -H "Content-Type: application/json" \
  -d '{ "name": "Swagger Pet Store (Academy)", "type": "api",
        "location": "https://petstore.swagger.io/v2", "auth": "none", "isEnabled": true }'

curl -u admin:admin -X POST "http://localhost:8080/index.php/apps/openconnector/api/sources/test/<SOURCE_ID>" \
  -H "OCS-APIRequest: true"

The create response includes the source's id and uuid; keep them — the synchronisation references the source by its uuid.

A source, mapping and synchronisation are all OpenRegister objects in the openconnector register, so you create them with OpenRegister's ObjectService and test reachability with OpenConnector's CallService:

use OCA\OpenRegister\Service\ObjectService;
use OCA\OpenConnector\Service\CallService;

$objects = \OCP\Server::get(ObjectService::class);

$source = $objects->saveObject(
    object: [
        'name'      => 'Swagger Pet Store (Academy)',
        'type'      => 'api',
        'location'  => 'https://petstore.swagger.io/v2',
        'auth'      => 'none',
        'isEnabled' => true,
    ],
    register: 'openconnector',
    schema:   'source',
);

// Confirm OpenConnector can reach it by calling a real endpoint.
$call     = \OCP\Server::get(CallService::class);
$response = $call->call($source, '/pet/findByStatus?status=available');

Open Automation → Mappings → Add Mapping. OpenConnector creates the mapping and drops you straight into its editor. The editor has a General section (name, description, and a Pass through toggle), a Transformation rules section with Mapping rules, Cast rules and Unset rules tabs, and a Live preview that re-renders as you work.

On the Mapping rules tab click Add mapping rule. A dialog asks for a Target property and a Twig template. Add the three rows from the table above — name → {{ name }}, then species → {{ category.name }}, then status → {{ status }}.

Now the important toggle: turn Pass through off. With pass-through on, every field of the source record (its id, photoUrls, raw tags) is copied through alongside your three derived fields — handy sometimes, but here it would pollute your clean pet-academy object with source plumbing. Off, the output is exactly the three fields you mapped.

Paste a sample pet into the Sample input (JSON) box and watch the Output re-render live. With pass-through off and the three rules in place, the output is precisely what pet-academy expects:

{ "name": "doggie", "species": "Dogs", "status": "available" }

Give the mapping a name — Pet to pet — and a description from the editor's General section (or rename it later from the mappings list). It now reads cleanly as the thing it is: a Swagger pet, reshaped into one of your pets.

Before you wire it into a synchronisation, run the mapping's Test mapping action. It opens a dialog where you paste an input object, optionally pick a schema to validate the output against, and click Run test — the Result panel shows the reshaped object, so you confirm the mapping does what you expect against a real record, not a guess.

A mapping is a name plus a mapping object of target field → Twig template. Turn passThrough off so only the mapped fields reach the target. Create it, then test it against a sample record:

curl -u admin:admin -X POST "http://localhost:8080/index.php/apps/openconnector/api/mappings" \
  -H "OCS-APIRequest: true" -H "Content-Type: application/json" \
  -d '{ "name": "Pet to pet", "passThrough": false, "mapping": {
        "name": "{{ name }}", "species": "{{ category.name }}", "status": "{{ status }}" } }'

curl -u admin:admin -X POST "http://localhost:8080/index.php/apps/openconnector/api/mappings/test" \
  -H "OCS-APIRequest: true" -H "Content-Type: application/json" \
  -d '{ "mapping": { "name": "{{ name }}", "species": "{{ category.name }}", "status": "{{ status }}" },
        "inputObject": { "name": "doggie", "status": "available", "category": { "name": "Dogs" } } }'

The test response is the reshaped object: { "name": "doggie", "species": "Dogs", "status": "available" }.

use OCA\OpenConnector\Service\MappingService;

$mapping = $objects->saveObject(
    object: [
        'name'        => 'Pet to pet',
        'passThrough' => false,
        'mapping'     => [
            'name'    => '{{ name }}',
            'species' => '{{ category.name }}',
            'status'  => '{{ status }}',
        ],
    ],
    register: 'openconnector',
    schema:   'mapping',
);

// Reshape one sample record to verify the mapping before wiring it up.
$mapper = \OCP\Server::get(MappingService::class);
$result = $mapper->executeMapping(
    $mapping,
    ['name' => 'doggie', 'status' => 'available', 'category' => ['name' => 'Dogs']]
);
// $result === ['name' => 'doggie', 'species' => 'Dogs', 'status' => 'available']

Open Automation → Synchronizations → Add Synchronization. The Create Synchronization dialog asks for a name, a sourceType and a targetType. Name it Pets to Pet Store register, set sourceType to api and targetType to register/schema, and click Create.

Open the new synchronisation's Actions → Open editor. The editor is laid out in panels: Source (source type, the source record, endpoint, id position, results position), Target (target type, register, schema, an optional object filter), and Mapping (the source → target mapping, plus optional reverse and hash mappings). Fill them from the dropdowns and fields:

• In Source, pick Swagger Pet Store (Academy), set Endpoint to /pet/findByStatus?status=available, ID position to id, and Results position to _root.
• In Target, pick the Pet Store register and the Pet schema.
• In Mapping, pick Pet to pet as the Source → Target mapping.

Then Save changes.

Reference the source by its uuid, the mapping by its uuid, and the target as <REGISTER_ID>/<SCHEMA_ID> (here petstore-academy is id 2414 and pet-academy is id 4318):

curl -u admin:admin -X POST "http://localhost:8080/index.php/apps/openconnector/api/synchronizations" \
  -H "OCS-APIRequest: true" -H "Content-Type: application/json" \
  -d '{ "name": "Pets to Pet Store register",
        "sourceId": "<SOURCE_UUID>", "sourceType": "api",
        "sourceTargetMapping": "<MAPPING_UUID>",
        "sourceConfig": { "endpoint": "/pet/findByStatus?status=available",
                          "resultsPosition": "_root", "idPosition": "id" },
        "targetType": "register/schema", "targetId": "2414/4318" }'

$sync = $objects->saveObject(
    object: [
        'name'                => 'Pets to Pet Store register',
        'sourceId'            => $source->getUuid(),
        'sourceType'          => 'api',
        'sourceTargetMapping' => $mapping->getUuid(),
        'sourceConfig'        => [
            'endpoint'        => '/pet/findByStatus?status=available',
            'resultsPosition' => '_root',
            'idPosition'      => 'id',
        ],
        'targetType'          => 'register/schema',
        'targetId'            => '2414/4318', // petstore-academy / pet-academy
    ],
    register: 'openconnector',
    schema:   'synchronization',
);

Run it with Run now. The run reports a result — how many records it read (found), and how many it created, updated and skipped. On a first run against your empty target, every found record is created. On our run the register went from the six pets you typed in Part 1 to ten: four new pets created from the Swagger source, no duplicates of the six you already had.

curl -u admin:admin -X POST \
  "http://localhost:8080/index.php/apps/openconnector/api/synchronizations/<SYNC_ID>/run" \
  -H "OCS-APIRequest: true"

The run returns a log shaped like { "result": { "objects": { "found": 4, "created": 4, "updated": 0, "skipped": 0 } } }.

use OCA\OpenConnector\Service\SynchronizationService;

$syncService = \OCP\Server::get(SynchronizationService::class);
$log = $syncService->synchronize($sync);
// $log['result']['objects'] === ['found' => 4, 'created' => 4, 'updated' => 0, 'skipped' => 0]