# Import Predefined Data via JSON

A newly installed 4ALLPORTAL comes with mostly empty modules. To create predefined data directly on startup, you can place a corresponding JSON file in a module's folder and start e.g. with default

users, roles, contacts, companies
tasks, collections, folders
dashboards, user tutorials
thesauri

Note that these records are created directly in the database. They are thus immediately available (in a demo or productive system) and do not have to be created manually/subsequently.

With JSON files, you can as well edit, relate or delete existing records directly in the database.

Database Access

To create most JSON files, access to the database is helpful or required, for example to find out about mandatory fields, IDs, or the name of a relation.

# JSON Options and File Storage

Storing a JSON file in a module's folder resembles a PATCH request to our REST API (full documentation (opens new window)). The defined objects are requested and created/edited/deleted with the given properties directly in the module's database table.

Thus, all options of our API can also be used in a JSON file to define an object's properties and to create, edit, or delete records in a given module. You can define values for all database fields of a module, including an ID if necessary (e.g. for relations).

# Storage and Naming Rules

For the system to recognize a JSON file at system start, it must be stored in custom folder predefined_data. Make sure to store your files module specific. For a predefined contact, store your JSON file in folder custom/modules/contact/predefined_data, and so on.

You can choose the name for the JSON file freely, considering the following rules:

the filename must be unique per module
the file extension must be .json
the maximal length of the filename is 255 characters (please take into account that the system automatically adds the module to your chosen filename like this: account/add_new_company)

# Limitations and Required Fields

Note that JSON cannot ignore the system's rules. If the system requires a mandatory field when creating a new object, it must be given in the JSON file, too. The defined properties must match the fields available in the database table.

If you are unsure about possible or mandatory fields, take a look at the database, or in the GUI compare a module's create pop-up or list of fields in admin snap-in Module configurations/{module}/Fields.

# File Execution and Status

At system start, or after clearing the configuration cache, the system checks for JSON files in all custom module folders. They are processed in alphabetical order. Each file is read once. If a file was executed successfully, it will not be executed again.

The status of a JSON file can be checked in admin snap-in Protocol overview/Update Management. All executed or skipped files are listed here.

If you want to execute a successfully executed file again, you need to rename it in the filesystem.

# Defective Files

If a file was defective, it will not be executed. Its status is "Skip". It will not be executed again. Now you can:

look for the error message in the process detail view.
check the JSON for any syntax problems and make corrections. Note that a JSON file must contain all mandatory fields a module's object requires.
set the process status to Initial via toolbox action Repeat.
reload your 4ALLPORTAL.

# IDs for Editing and Relations

If you want to edit an existing record or create a record relating to a second record from another module, you must give the corresponding ID of that record.

To edit an existing record, or to create a relation to an existing record, take the respective ID from the database/detail view's URL.
To create a relation to a record not yet existing (e.g. when predefining a dashlet together with a dashboard - example, generate and define an ID for the parent.
We recommend generating a version 4 UUID using a tool like UUID Generator (opens new window).

# Examples

# Create a New Record

To create a new user, place e.g. file new_user_tony.json in folder custom/modules/user/predefined_data:

[
  {
    "firstname": [
        {
            "value": "Tony"
        }
    ],
    "email": [
        {
            "value": "t.tester@example.com"
        }
    ],
    "role": [
        {
            "value": "b182b72e-f845-4a46-9da2-e991d50521e4"
        }
    ],
	"salutation": [
        {
            "value": "mr"
        }
    ],
    "username": [
        {
            "value": "Tony1"
        }
    ]
  }
]

# Create Multiple Records

To create multiple records in a module, place e.g. file multiple_new_folders.json with three new folders in folder custom/modules/folder/predefined_data. In this case, the new folders are created as subfolders in folder "data", defined via its pid:

[
  {
    "name": [
        {
            "value": "Folder 1"
        }
    ],
    "pid": [
        {
            "value": "141205c4-4887-45c1-9559-48be28212743"
        }
    ]
    },
    {  
    "name": [
        {
            "value": "Folder 2"
        }
    ],
    "pid": [
        {
            "value": "141205c4-4887-45c1-9559-48be28212743"
        }
    ]
    },
    {  
    "name": [
        {
            "value": "Folder 3"
        }
    ],
    "pid": [
        {
            "value": "141205c4-4887-45c1-9559-48be28212743"
        }
    ]
  }
]

# Edit an Existing Record

To edit an existing user, place e.g. file tony_edit1.json with Tony's ID in folder custom/modules/user/predefined_data:

[
  {
    "id": "86cbf165-1750-40f4-7b7c-0197ecd509bc",
    "lastname": [
        {
            "value": "Tester"
        }
    ]
  }
]

# Delete an Existing Record

To delete an existing user, place e.g. file tony_delete.json with Tony's ID in folder custom/modules/user/predefined_data:

[
  {
    "id": "86cbf165-1750-40f4-7b7c-0197ecd509bc",
    "deleted": [
        {
            "value": "1"
        }
    ]
  }
]

# Add a Relation to an Existing Record

To link an existing contact to an existing company, place e.g. file john_edit1.json with John's ID and the company's ID in folder custom/modules/contact/predefined_data:

[
  {
    "id": "86cbf165-1750-40f4-7b7c-0197ecd509bc",
    "account_contact": [
        {
            "value": "a46b078e-74be-4665-af2e-e92fbce29b74"
        }
    ]
  }
]

# Add Multiple Relations to an Existing Record

To link multiple existing contacts to an existing company, place e.g. file contacts_for_abc.json with the account's ID and the contacts' IDs in folder custom/modules/account/predefined_data:

[
  {
    "id": "a46b078e-74be-4665-af2e-e92fbce29b74",
    "account_contact": [
        {
            "value": [ "67727f8e-b7f2-40b0-934a-07f9caa99c22", "3f382cp5-4163-4c2d-97bb-18e608be7835", "16f30981-b44b-47ec-945a-695012a88ae9" ]
        }
    ]
  }
]

# Add a Relation Between New Records

To create a new dashlet together with a new dashboard (ID required), place e.g. files basic_dashboard.json with a generated ID in folder custom/modules/dashboard/predefined_data, and all_contacts.json in folder custom/modules/dashlet/predefined_data:

[
  {
    "id": "4144f7c4-cbd3-45db-b845-613541c56233",  
    "name": [
        {
            "value": "Basic Dashboard"
        }
    ]
  }
]

[
  {
    "name": [
        {
            "value": "all_contacts"
        }
    ],
    "dashboard": [
        {
            "value": "4144f7c4-cbd3-45db-b845-613541c56233"
        }
    ],
    "height": [
        {
            "value": "3"
        }
    ],
	"width": [
        {
            "value": "4"
        }
    ],
    "datalist_module_name": [
        {
            "value": "contact"
        }
    ],
    "type": [
        {
            "value": "data_list"
        }
    ],
    "title": [
        {
            "value": "All my contacts"
        }
    ]
  }
]

← Implement and Customize the HTML Text Editor Labels and Translations →