← To the list of documents
Версия:

add

Creates a new record in the class table, clears the associated cache, and saves the history (see History Mechanism). Creation may be prohibited by profile settings (new_command|editable at the class/client object level).

Input Parameters. IAPIQueryParams Interface

The fields you want to populate during creation from the class field list.

Fields prohibited for addition in the profile (editable/server_editable/insertable/server_insertable) will be ignored.

Fields for each created class can be viewed:

These include not only physical fields but also virtual fields—those that are pulled from related tables via JOIN during a query or formed by various SQL functions, such as CONCAT.

Example classes/_structures/crm_user.ts:

/**
 * Automatically generated based on class_fields_profile when synchronizing a class with tables.json (from the interface).
 * Do not change this interface manually, as it will be overwritten during the next generation.
 */
export interface ICrm_userDataRow extends IAPIResponseDataRow {
    id: number;
    firstname?: string;
    lastname?: string;
    midname?: string;
    fio?: string;
    email?: string;
    phone?: string;
    city?: string;
    age?: number;
    gender_id?: number;
    gender_name?: string;
    last_action_datetime?: any;
    status_id?: number;
    status_name?: string;
    status_sysname?: string;
    crm_user_type_id?: number;
    crm_user_type_name?: string;
    crm_user_type_sysname?: string;
    avatar?: string;
    note?: string;
    organization_id?: number;
    organization?: string;
    subject?: string;
    agreement_personal_data?: string;
    is_sent_to_bitrix?: boolean;
    created?: any;
    updated?: any;
    deleted?: any;
    created_by_user_id?: number;
    created_by_user?: string;
    deleted_by_user_id?: number;
    deleted_by_user?: string;
    remove_comment?: string;
    last_edited_by_user_id?: number;
    last_edited_by_user?: string;
}

The ICrm_userDataRow structure doesn’t show which fields are virtual, but this is visible in tables.json (or tablesCore.json for classes that exist in the core out of the box).

"crm_user": {
    "profile": {
      "name": "crm_user",
      "name_ru": "Клиент",
      "ending": ""
    },
    "structure": {
      "id": {"type": "bigint","length": "20","notNull": true,"autoInc": true,"primary_key": true},
    
      "firstname": {"type": "varchar","length": "255"},
      "lastname": {"type": "varchar","length": "255"},
      "midname": {"type": "varchar","length": "255"},
      "fio" : {"type": "varchar", "length": "255", "concat_fields": "lastname, ,firstname, ,midname", "is_virtual": true, "name": "ФИО"},
    
      "email": {"type": "varchar","length": "255","name":"email/login"},
      "phone": {"type": "varchar","length": "255"},
      "city": {"type": "varchar","length": "255"},
      "subject": {"type": "varchar","length": "255"},
      "note": {"type": "text"},
    
      "age": {"type": "int","length": "3", "name":"Возраст"},
      "gender_id": {"type": "bigint","length": "20", "visible": false},
      "gender_name" : {"type": "varchar", "length": "255", "from_table": "gender", "keyword": "gender_id", "return_column": "sysname", "is_virtual": true, "name": "Gender"},
    
      "last_action_datetime" : {"type": "datetime"},
    
      "status_id": { "type": "bigint", "length": "20", "server_editable":false, "server_updatable":true, "visible": false},
      "status_name" : {"type": "varchar", "length": "255", "from_table": "crm_user_status", "keyword": "status_id", "return_column": "name", "is_virtual": true, "name": "Статус"},
      "status_sysname" : {"type": "varchar", "length": "255", "from_table": "crm_user_status", "keyword": "status_id", "return_column": "sysname", "is_virtual": true, "name": "Системное имя статуса", "visible": false},
    
      "crm_user_type_id": { "type": "bigint", "length": "20", "visible": false},
      "crm_user_type_name" : {"type": "varchar", "length": "255", "from_table": "crm_user_type", "keyword": "crm_user_type_id", "return_column": "name", "is_virtual": true, "name": "Тип пользователя сайта"},
      "crm_user_type_sysname" : {"type": "varchar", "length": "255", "from_table": "crm_user_type", "keyword": "crm_user_type_id", "return_column": "sysname", "is_virtual": true, "name": "Системное имя типа", "visible": false},
    
      "organization_id": {"type": "bigint", "length": "20"},
      "organization": {"type": "varchar", "length": "255", "from_table": "organization", "keyword": "organization_id", "return_column": "name", "is_virtual": true, "name": "Организация"},
    
      "agreement_personal_data": {"type": "text", "name": "Разрешение на обработку персональных данных"},
    
      "avatar": {"type": "text", "name": "Аватар"},
    
      "is_sent_to_bitrix": {"type": "tinyint", "length": "1", "default_value": 0, "name": "Отправлен в Битрикс"}
    }
},

You can also specify virtual fields, such as sysname. In this case, the system will automatically go to the corresponding lookup table, find the id for this value (usually from the cache), and insert it into the corresponding physical field.

This applies to virtual fields that reference lookups.

Some fields may have a default value specified in the profile settings. It will be used if no value is provided.

A value can be specified for a virtual field. For example, for an Order that has fields status_id, status, and status_sysname, a default value of status_sysname="CREATED" can be set. The system will find the value in the lookup and insert it into status_id (unless status_id or status_sysname are passed during creation).

The system will check records for uniqueness according to the class/client object profile settings.

If non-uniqueness is detected, the system will return a UserError recExist (code: 105).

Output Parameters. IAPIResponse/IError Interface

In case of an error, the method returns an error object—an instance of UserError/MyError.

In case of success, the method returns the id of the added record in the data object of the UserOk instance (res.data.id).

let res: IAPIResponse // Can be used multiple times

res = await r.api(Crm_user, 'add', {
    firstname: 'John',
    lastname: 'Doe',
    email: 'john.d@example.com'
})
if (res.code) return res
console.log('Added successfully. ID:', res.data.id)