goalsmanagement.ratingitem.upsert

Scope: goalsmanagement

Кто может вызывать: Участник карточки оценки (сотрудник, руководитель, директор) или администратор. Права проверяются так же, как на странице карточки оценки: утверждённая карточка и карточка не запущенного (завершённого) процесса только для просмотра; сотрудник правит только «Черновик», руководитель — «Черновик» и «Согласование руководителем», функциональный руководитель и директор — свои этапы, администратор — любой неутверждённый этап. С версии 16.0.1. Подробнее: Права доступа

Сохранить/обновить оценки карточки (WAF-безопасное имя вместо *.save)

HTTP: POST

Побочные эффекты: сохраняет оценки; для количественных целей записывает в строку снимок формулы, по которой посчитан прогресс (позднейшая смена формулы цели старые строки не пересчитывает). Итоговый прогресс карточки (totalProgress) не опускается ниже 0

Параметры метода

Параметр Тип Обяз. Описание
cardId int да ID карточки оценки
rating array да Существующие строки оценок. Пустой массив / без id / чужой id — VALIDATION_ERROR. Новых строк метод не создаёт. RATING_TABLE перезаписывается только переданными строками

Поля элемента rating[]

Поле Тип Обяз. Описание
id int да HL-id строки оценки (из ratingitem.list). Должен принадлежать cardId
progress number нет Прогресс, %. Нет — 0. Для количественной цели пересчитывается по value и формуле цели (progressFormulaMode; по умолчанию факт / план), ограничивается maxPercent и округляется до percentStep. Отрицательным может быть только при включённой настройке модуля «Допускать отрицательный прогресс». Для качественной цели, у которой в каталоге заданы текстовые описания градаций %, значение должно быть одним из описанных, иначе INVALID_RATING_PROGRESS_LABEL; значение, равное сохранённому, принимается. Для количественных целей и родительских целей, считаемых по подцелям, не проверяется
value number нет Факт для количественной цели
result string нет Текст результата (не количественная)
commentEmployee string нет Комментарий сотрудника
commentHead string нет Комментарий руководителя
commentFuncHead string нет Комментарий функ. руководителя
commentDirector string нет Комментарий директора
commentAdmin string нет Комментарий администратора
userGoalId int нет ID строки цели (goalitem). Нужен, чтобы определить количественность и пересчитать progress/value
isSubgoal string нет "Y" / "N". Подцель не входит в USER_GOAL_TOTAL_PROGRESS
type_goal string нет Подпись типа для грида (value из enum, как в ratingitem.list). В HL не пишется
goal string нет Подпись цели для грида (имя). В HL не пишется
task string нет Подпись задачи для грида; если непусто, в гриде вместо goal
criterion string нет Критерий для грида
weight mixed нет Для грида и доли в USER_GOAL_TOTAL_PROGRESS. В HL оценки не пишется; без него вклад строки в итог = 0
userFields object нет Значения каталожных пользовательских полей: ключ — fieldId (int), формат значения — как в goalitem.upsert. Подробнее — «Пользовательские поля» ниже

Пользовательские поля

Принимаются только поля, включённые в карточку оценки (SHOW_IN_RATING_CARD=Y, поле активно). Остальные ключи userFields игнорируются.

  • Запись. Значение сохраняется, если поле можно заполнять в карточке оценки (fillInRatingCard) и allowEmployeeEdit=true. При allowEmployeeEdit=false поле недоступно для записи всем ролям (сотрудник карточки, руководитель, администратор) — значение из запроса молча игнорируется.
  • Обязательность. ratingitem.upsert — черновое сохранение: пустые обязательные поля не блокируют запись. Обязательные поля проверяются при переходе карточки на следующий статус — ratingcard.changeStatus.
  • Привязка к цели. Настройки поля для конкретной цели каталога (обязательность, allowEmployeeEdit и др.) определяются по строке оценки на сервере, а не по переданному userGoalId: для существующей строки используется цель, к которой она привязана в базе.

Возвращаемые данные

Ответ в конверте модуля: result.result — результат сохранения; result.error. Ключи total/next для не-list методов могут отсутствовать в сериализации, если не переданы.

Обработка ошибок

Справочник кодов: error-codes.md.

Код Описание
UNAUTHORIZED Пользователь не авторизован
VALIDATION_ERROR Некорректные или неполные параметры, в т.ч. невалидное значение каталожного поля (формат, длина, диапазон, список, расширение/размер файла)
ACCESS_DENIED Нет права править карточку оценки на текущем этапе: не участник, карточка утверждена, процесс не запущен или завершён, этап правит другая роль
INVALID_RATING_PROGRESS_LABEL rating[].progress не входит в описанные градации % выполнения цели каталога
INTERNAL_ERROR Внутренняя ошибка сервера

Пример запроса (POST)

curl -X POST "https://{портал}/rest/{user_id}/{webhook_code}/goalsmanagement.ratingitem.upsert.json" \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          --data '{
          "cardId": 701,
          "rating": [
            {
              "id": 9001,
              "progress": 65,
              "commentEmployee": "План выполнен на 65%",
              "commentHead": "Результат подтверждён",
              "userFields": {
                "12": "Значение UF"
              }
            }
          ]
        }'

Пример ответа

{
          "result": {
            "result": {
              "cardId": 701,
              "saved": true
            },
            "error": null
          }
        }

См. также

Предыдущая
goalsmanagement.ratingitem.list
Следующая
Обзор раздела