add

Создаст новую запись в таблице класса, сбросит связанный кэш, сохранит историю (см. Механизм истории). Создание может быть запрещено настройками профайла (new_command|editable на уровне класса/клиентского объекта).

Входные параметры. Интерфейс IAPIQueryParams

Те поля которые вы хотите заполнить при создании из списка полей класса.

Поля запрещенные для добавления в профайле (editable/server_editable/insertable/server_insertable) будут проигнорированы.

Поля каждого созданного класса можно посмотреть

• в tables.json (не считая тех, что создаются автоматически)
• в classes/structures/<имя_класса>.ts
• в интерфейсе (меню System->Classes)

Там будут не только физические поля, но и виртуальные, то есть такие, которые при запросе подтягиваются из связанных таблиц с помощью JOIN, или сформированные различными функциями SQL, например CONCAT.

Пример 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;
}

В структуре ICrm_userDataRow не видно, какие поля виртуальные, но это видно в tables.json (или в tablesCore.json, для классов существующих в ядре из коробки).

"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": "Отправлен в Битрикс"}
    }
},

Вы можете указывать и виртуальные поля, такие как sysname, тогда система сама отправится в соответствующий справочник, найдет id этого значения (чаще всего из кэша), подставит его в соответствующее физическое поле.

Применимо для виртуальных полей ссылающихся на справочники.

Для некоторых полей может быть указано значение по умолчанию в настройках профайла. Оно будет подставлено, если само значение не передано.

Значение может быть указано для виртуального поля. Например, для Заказа, у которого есть поля status_id, status и status_sysname, может быть указано значение по умолчанию для поля status_sysname=”CREATED”. Система найдет значение в справочнике и подставит его в status_id (конечно если status_id или status_sysname не переданы при создании).

Система проверит записи на уникальность, согласно настройкам профайла класса/клиентского объекта.

В случае обнаружения не уникальности система вернет ошибку (UserError) recExist (code:105).

Выходные параметры. Интерфейс IAPIResponse/IError

В случае ошибки метод вернет объект ошибки - инстанс UserError/MyError.

В случае успеха метод вернет id добавленной записи в объекте data инстанса UserOk (res.data.id).

let res: IAPIResponse // Может быть использована многократно

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)