Реестр формы

Скрипты позволяют использовать в вычислениях реестры задачи текущей или сторонней формы. Для этого в глобальном объекте form есть методы fetchSelfRegister и fetchRegister.

interface form {
    fetchSelfRegister(
        filterFn?: (filter: RegisterFilter) => RegisterFilter,
        fieldNames?: string[],
        options?: RegisterFormOptions,
    ): Promise<RegisterResponse>;

    fetchRegister(
        formId: number,
        filterFn?: (filter: RegisterFilter) => RegisterFilter,
        fieldNames?: string[],
        options?: RegisterFormOptions,
    ): Promise<RegisterResponse>;
}

interface RegisterFilter {
    fieldEquals(fieldName: string, value: FieldValue): RegisterFilter;
    fieldLessThen(fieldName: string, value: FieldValue): RegisterFilter;
    fieldGreaterThen(fieldName: string, value: FieldValue): RegisterFilter;
}

interface RegisterFormOptions {
    activeOnly?: boolean;
    archivedOnly?: boolean;
    taskIds?: number[];
}

interface RegisterResponse {
    tasks: RegisterForm[];
}

interface RegisterForm {
    task_id: number;
    fields: FieldValue[];
}

Аргументы метода fetchSelfRegister:

• filterFn — необязательная функция фильтрации реестра, получающая и возвращающая объект RegisterFilter. Функция определяет названия и значения (диапазоны значений) полей формы, по которым необходимо отфильтровать реестр;
• fieldNames — необязательный список названий полей запрашиваемой формы, значения которых необходимо получить в ответе;
• options — дополнительные параметры фильтрации реестра, позволяющие исключать открытые/закрытые задачи, а также ограничивать реестр фиксированным списком номеров задач.

Аргументы метода fetchRegister отличаются тем, что сперва идет обязательный параметр formId с id формы запрашиваемого реестра.

Методы возвращают Promise с объектом, включающим список задач. Для каждой задачи доступен её номер task_id, а также набор значений полей fields, которые были перечислены в аргументе fieldNames.

Рассмотрим пример. Есть форма «Публикация приказа» с полями «Год», «Номер» и «Документ» (файл с приказом). С помощью запроса реестра из скрипта можно убедиться, что приказ за тот же год и с тем же номером еще не был опубликован:

form.onChange(['Год', 'Номер'])
  .validateAsync('Номер', async state => {
    const [year, num] = state.changes;

    if (!year || !year.text || !num || !num.text)
      return null;

    const duplicates = await form.fetchSelfRegister(f => f
      .fieldEquals('Год', year)
      .fieldEquals('Номер', num), []
    );

    if (!duplicates || !duplicates.tasks)
      return null;

    const firstDuplicate = duplicates.tasks[0];
    if (firstDuplicate)
      return {
        errorMessage: `Приказ <a href="#id${firstDuplicate.task_id}">уже опубликован</a>`
      };

    return null;
  });

Теперь при попытке повторно заполнить форму теми же данными пользователь увидит ошибку со ссылкой на уже существующий приказ:

По умолчанию запрос вернёт все включенные в реестр задачи — как открытые, так и закрытые. Чтобы получить из реестра только активные задачи, используйте запрос вида:

const duplicates = await form.fetchSelfRegister(f => f
    .fieldEquals('Год', year)
    .fieldEquals('Номер', num), [], {
      activeOnly: true,
    }
  );

А чтобы отфильтровать и выгрузить из реестра только завершенные задачи, используйте запрос вида:

const duplicates = await form.fetchSelfRegister(f => f
    .fieldEquals('Год', year)
    .fieldEquals('Номер', num), [], {
      archivedOnly: true
    }
  );

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

С помощью скрипта можно из одной формы обращаться к реестру другой. Для этого используйте запрос вида:

const duplicates = await form.fetchRegister(id_form, f => f
  .fieldEquals('Номер', num), [] );

где в id_form следует указать id формы, реестр которой нужно получить.

В параметр fieldNames необходимо передавать все поля, которые нужны для дальнейших операций. Таблицы и табличные поля не поддерживаются. Если поле пустое, то всегда возвращается null в качестве значения, формат заполненных полей описан здесь

Для некоторых типов полей (как число, деньги, дата, срок) можно использовать не просто оператор равенства (fieldEquals), а операторы меньше чем (fieldLessThen) и больше чем (fieldGreaterThen).

const duplicates = await form.fetchSelfRegister(f => f
    .fieldGreaterThen('Год', year), ['Год', 'Описание']
  );

Кроме названия полей, можно также использовать их коды, если они известны:

const duplicates = await form.fetchSelfRegister(f => f
    .fieldGreaterThen('payment_date', year), []
  );

Если необходимо получить результат только по заранее известным задач, используется запрос вида:

const duplicates = await form.fetchSelfRegister(f => f
    .fieldGreaterThen('payment_date', year), [], {
      taskIds: [123, 456]
    }
  );