Data export and import tool for EspoCRM

A tool for exporting & importing data in EspoCRM

Usage

Export data

bin/command export-import export

Import data

bin/command export-import import

Erase imported data (not yet implemented)

bin/command export-import erase

Command examples

Export

bin/command export-import export --format=json --export-path="build/ExportImport/Export" --pretty-print

Import

bin/command export-import import --format=json --import-path="build/ExportImport/Import" --import-type=createAndUpdate --user-password="pass"

Parameters

Export Path

Define an export path.

• Attribute: exportPath
• CLI attribute: --export-path="PATH"
• Possible values:
  • any string
• Default: build/ExportImport/Export

Import Path

Define an import path.

• Attribute: importPath
• CLI attribute: --import-path="PATH"
• Possible values:
  • any string
• Default: build/ExportImport/Import

The export / import process can be configured in custom/Espo/Custom/Resources/metadata/app/exportImport.json or by cli command.

Entity Type List

The needed Entity type list can be defined. If empty, then gets all Entity types.

• Attribute: entityTypeList
• CLI attribute: --entity-type-list="ENTITY_TYPE1, ENTITY_TYPE2"
• Possible values:
  • a string, e.g. "Account"
  • a string which is separated by a comma, e.g. "Account, Contact"
  • merge with a default list, e.g. "__APPEND__, Account"
• Default: all available entities

Import Type

The type of importing data.

• Attribute: importType
• CLI attribute: --import-type="TYPE"
• Possible values:
  • create
  • createAndUpdate
  • update
• Default: createAndUpdate

Pretty Print

Store data in pretty print format.

• Attribute: prettyPrint
• CLI attribute: --pretty-print
• Possible values:
  • true
  • false
• Default: false

User Active Status

Default user status for imported users. This applies to all user except admin user with ID 1.

• Attribute: userActive
• CLI attribute: --user-active
• Possible values:
  • true
  • false
• Default: false

User Password

User password for imported users. If empty then generates random values. For resetting the password use bin/command set-password [username].

• Attribute: userPassword
• CLI attribute: --user-password="PASSWORD"
• Possible values:
  • any string
• Default: null

Update Currency

Update all currency fields. This option is depends on currency. If currency option is not defined, the default currency will be used instead.

• Attribute: updateCurrency
• CLI attribute: --update-currency
• Possible values:
  • true
  • false
• Default: false

Currency

Currency symbol, ex. USD. If not defined, the default currency will be used instead.

• Attribute: currency
• CLI attribute: --currency=""
• Possible values:
  • USD
  • other currency symbols
• Default: default currency

Customization

Export / import all customization made for the instance.

• Attribute: customization
• CLI attribute: --customization
• Possible values:
  • true
  • false
• Default: false

Config

Enable export / import configuration data.

• Attribute: config
• CLI attribute: --config
• Possible values:
  • true
  • false
• Default: false

Update createAt

The current time will be defined for the createAt field.

• Attribute: updateCreatedAt
• CLI attribute: --update-created-at
• Possible values:
  • true
  • false
• Default: false

Hard Export Entities

This option enables export feature for an entity which is disabled in exportImportDefs.

• Attribute: hardExportList
• CLI attribute: --hard-export-list="ENTITY_TYPE"
• Possible values:
  • a string, e.g. "Account"
  • a string which is separated by a comma, e.g. "Account, Contact"
• Default: null

Hard Import Entities

This option enables import feature for an entity which is disabled in exportImportDefs.

• Attribute: hardImportList
• CLI attribute: --hard-import-list="ENTITY_TYPE"
• Possible values:
  • a string, e.g. "Account"
  • a string which is separated by a comma, e.g. "Account, Contact"
• Default: null

Config: ignore list

Additional ignore list for the config.

• Attribute: configIgnoreList
• CLI attribute: --config-ignore-list="option"
• Possible values:
  • a string, e.g. "version"
  • a string which is separated by a comma, e.g. "version, useCache"
  • merge with a default list, e.g. "__APPEND__, useCache"
• Default: see at application/Espo/Modules/ExportImport/Resources/metadata/app/exportImport.json

Export Import Defs

In the metadata defs can be configured some additional features. The path is custom/Espo/Custom/Resources/metadata/exportImportDefs.

Export additional fields

If need to export additional fields that out of the standard functionality.

exportAdditionalFieldList

Example for Quotes: custom/Espo/Custom/Resources/metadata/exportImportDefs/Quote.json

{
    "exportAdditionalFieldList": [
        "itemList"
    ]
}

Skip export list

If need to skip some records like system user or others.

exportSkipLists

Example for User: custom/Espo/Custom/Resources/metadata/exportImportDefs/User.json

{
    "exportSkipLists" : {
        "id": [
            "system"
        ],
        "userName": [
            "tester"
        ]
    }
}

Placeholders

Edit the file: custom/Espo/Custom/Resources/metadata/exportImportDefs/ENTITY.json.

Config

Get

{
    "fields": {
        "amountCurrency": {
            "placeholderAction": "Config\\Get",
            "placeholderData": {
                "key": "defaultCurrency",
                "default": null
            }
        }
    }
}

User

Password

{
    "fields": {
        "password": {
            "placeholderAction": "User\\Password",
            "placeholderData": {
                "value": "1"
            }
        }
    }
}

Active

{
    "fields": {
        "isActive": {
            "placeholderAction": "User\\Active"
        }
    }
}

Datetime

Now

{
    "fields": {
        "dateStart": {
            "placeholderAction": "DateTime\\Now"
        }
    }
}

ExportDifference

The difference between the record date and the export date. E.g. record date = 2022-05-01, export date = 2022-08-01. When import data at 2022-12-01, the record data will be 2022-09-01.

{
    "fields": {
        "dateStart": {
            "placeholderAction": "DateTime\\ExportDifference"
        }
    }
}

ExportDifferenceField

The same logic as ExportDifference, but the initial value gets from another field.

{
    "fields": {
        "createdAt": {
            "placeholderAction": "DateTime\\ExportDifferenceField",
            "placeholderData": {
                "field": "dateStart"
            }
        }
    }
}

To get the initial value from a couple fields. The value will be obtained from the first defined field.

{
    "fields": {
        "createdAt": {
            "placeholderAction": "DateTime\\ExportDifferenceField",
            "placeholderData": {
                "fieldList": [
                    "dateStart",
                    "dateEnd",
                    "dateCompleted"
                ]
            }
        }
    }
}

CurrentMonth

{
    "fields": {
        "dateStart": {
            "placeholderAction": "DateTime\\CurrentMonth"
        }
    }
}

CurrentYear

{
    "fields": {
        "dateStart": {
            "placeholderAction": "DateTime\\CurrentYear"
        }
    }
}

Run by the code

Import

The ExportImport service can be injected as a constructor parameter.

namespace Espo\Custom\Tools;

use Espo\Modules\ExportImport\Tools\ExportImport;

class MyImportTest
{
    public function __construct(private ExportImport $exportImportTool)
    {}

    public function runImport()
    {
        $this->exportImportTool->runImport([
            'importPath' => 'custom/Espo/Custom/MyData',
            'customization' => true,
            'config' => true,
            'userPassword' => 'password',
            'userActive' => true,
            'updateCurrency' => true,
            'updateCreatedAt' => true,
            'hardImportList' => [
                'ScheduledJob'
            ],
        ]);
    }
}

Development

Mode information about configuring the extension for development purposes, read the https://github.com/espocrm/ext-template#readme.

License

This extension is published under GNU AGPLv3 license.