---
title: "Command line"
manual: "HIS Connector"
version: "main"
source: "CommandLine/Index.rst"
modified: "2026-09-15T12:04:13+00:00"
---

# Command line

Synchronizations are run with the console command `hisconnector:sync`. The
command reads a synchronization configuration file, fetches the configured
data from HIS and writes it into the mapped TYPO3 tables.

**Composer mode**

```bash
vendor/bin/typo3 hisconnector:sync \
    EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
```

**Classic mode**

```bash
typo3/sysext/core/bin/typo3 hisconnector:sync \
    EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
```

The command can also be executed regularly with the scheduler task
**Execute console commands** provided by the TYPO3 system extension
`typo3/cms-scheduler`.

-   [Synopsis](#synopsis)
-   [Arguments](#arguments)
-   [Options](#options)
-   [Example](#example)
-   [Output and exit code](#output-and-exit-code)

## Synopsis

```text
hisconnector:sync [options] [--] <config>
```

## Arguments

-   **config**

    -   *Type:* string
    -   *Required:* true

    Synchronization configuration file to process.

    > [!IMPORTANT]
    > The configuration file has to be passed using the extension syntax
    > `EXT:<extension_key>/Configuration/HisConnector/<file>.yaml`, for
    > example:
    >
    > ```text
    > EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
    > ```
    >
    > Absolute or relative file system paths are not accepted.

    Only `*.yaml` files located directly in the folder
    `Configuration/HisConnector/` of an active extension are
    available. Configuration files of project specific synchronizations are
    therefore placed in that folder of a site package or another custom
    extension.

    The command stops with the message
    `Specified configuration file does not exist.` if the passed value does
    not address such a file. A file which cannot be parsed or does not contain
    a valid configuration is reported with
    `Specified configuration file is invalid:` followed by the reason.

## Options

-   **--offset**

    -   *Type:* integer
    -   *Default:* 0

    Zero-based index of the first record to synchronize from the list of
    records fetched from HIS.

-   **--limit**

    -   *Type:* integer
    -   *Default:* all records

    Maximum number of records to synchronize, starting at
    [--offset](#confval-hisconnector-sync-offset).

    Together with [--offset](#confval-hisconnector-sync-offset) a large
    synchronization can be split into several smaller runs:

    ```bash
    vendor/bin/typo3 hisconnector:sync --offset=0 --limit=100 \
        EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
    vendor/bin/typo3 hisconnector:sync --offset=100 --limit=100 \
        EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
    ```

    If the configured data source returns a single record instead of a list,
    this record is only synchronized with an offset of `0` and a limit
    greater than `0`.

-   **--storagePage**

    -   *Type:* integer

    Uid of the page the synchronized records are stored on. Overrides the
    `storagePage` setting of the configuration file.

    A storage page is mandatory. It has to be set either in the configuration
    file or with this option, otherwise every record is reported with the
    error `Storage page not specified in sync configuration.`

-   **--fileStorageFolder**

    -   *Type:* string

    Folder the synchronized files are stored in, given as combined identifier
    of storage uid and folder path, for example `1:/user_upload/his_connector/`.
    Overrides the `fileStorageFolder` setting of the configuration file.

    A file storage folder is only required if the mapping contains fields
    with files, for example person pictures.

## Example

The example configuration
`EXT:his_connector/Configuration/HisConnector/academic_persons.yaml`
neither defines a storage page nor a file storage folder, both have to be
passed as options:

```bash
vendor/bin/typo3 hisconnector:sync \
    --storagePage=42 \
    --fileStorageFolder=1:/user_upload/his_connector/ \
    EXT:his_connector/Configuration/HisConnector/academic_persons.yaml
```

## Output and exit code

The command prints one line per record fetched from HIS, containing the
entity class, the HIS identifier and the number of synchronized TYPO3
records, followed by a summary:

```text
Processing 2 of total 2 records...

FGTCLB\HisClientFacade\Model\Person:person-1 (3 record(s) synchronized)
FGTCLB\HisClientFacade\Model\Person:person-2 (2 record(s) synchronized)

Processed: 2
```

An error while fetching the details of a record from HIS or while
synchronizing it is printed for that record and the command continues with
the next one. The summary then reports the number of records with errors.

> [!NOTE]
> The command only returns a non-zero exit code if the configuration file
> does not exist or is invalid. Errors of single records are reported in
> the output, but do not change the exit code.