Задача [API66]: Доработка API создания и изменения работы (параметр "Период повторения")

Задача [API66]: Доработка API создания и изменения работы (параметр "Период повторения")
Пред.	Постановка задач на итерацию 3.3	След.

Формулировка проблемы: на момент итерации 3.2 включительно методы API создания и изменения работы не передают и никак не учитывают период повторения, который работам можно задавать.

Решение: необходимо доработать методы API создания работы (rest/api/workflow/work/create) и изменения работы (rest/api/workflow/work/save), добавив в их входные и выходные параметры новый параметр repeat.

Опишем эти методы полностью, отдельно остановившись на описании нового параметра repeat.

Создание работы

URL метода: rest/api/workflow/work/create.

Тип запроса: POST.

Метод принимает следующие параметры (FormParam):

name - формулировка работы (обяз.);
authorID - UUID автора работы (обяз.);
userID - UUID ответственного (обяз. при отсутствии хотя бы одного параметра resUserID);
resUserID - UUID исполнителя (обяз. при отсутствии параметра userID);
Примечание.
Параметр resUserID должен быть указан столько раз, сколько исполнителей есть у работы.
startDate - дата и время начала работы в формате yyyy-MM-dd HH:mm:ss (обяз.);
finishDate - дата и время завершения работы в формате yyyy-MM-dd HH:mm:ss (обяз.);
priority - UUID приоритета (обяз.);
completionFormID - UUID формы завершения (не обяз., по умолчанию "Нет");
repeat - данные о периоде повторения работы (не обяз., по умолчанию "Нет");
comment- комментарий, который будет добавлен к работе после ее создания (не обяз.);
path - список вложений, которые будут добавлены при создании работы (не обяз.);
Примечание.
Параметр path должен быть указан столько раз, сколько вложений нужно добавить. Строка path должна быть в формате ПУТЬ:ИМЯ, где ПУТЬ - путь до временного файла, созданого на серере при помощи метода rest/api/storage/start_upload, ИМЯ - имя добавляемого вложения.
force (true/false) - возможность создания работы исполнителю при отсутствии прав на это (не обяз., по умолчанию "false");
Примечание.
Этот параметр принимается в счет, только если одновременно передается параметр moduleID. Данное ограничение сделано с целью не допустить бесконтрольное создание работ в обход существующей системы прав.
moduleID - UUID внешнего модуля (не обяз.);
locale - локаль пользователя, ru/en/kz (не обяз., по умолчанию ru).

Параметр repeat должен представлять собой json со следующими полями:

type - тип период повторения (не обяз);
values - значение периода повторения в квадратных скобках (обяз. при наличии type).

Возможные значения параметра type:

day - по дням недели;
month - по дням месяца;
year - ежегодно.

Только при наличии параметра type необходимо передавать values - список значений через запятую выбранного типа периода повторения.

Для type = day возможные значения:
- MON - понедельник;
- TUE - вторник;
- WED - среда;
- THU - четверг;
- FRI - пятница;
- SAT - суббота;
- SUN - воскресенье.
Для type = month: числовые значения в формате «D», где D - это дни месяца.
Для type = year: числовые значения в формате «D.M», где D - это дни месяца, а M - номера месяца.

Отсутствие параметра repeat означает отсутствие периода повторения (значение "Нет").

В случае неуспешного выполнения вовзращается json с полями:

errorCode - код выполнения (число, отличное от 0);
errorMessage - сообщение об ошибке.

Альтернативные потоки событий для периода повторения.

Альтернативный поток №1. Параметр type не передан, но передан параметр values. Периоду повторения должно присвоиться значение "Нет", наличие параметра values необходимо игнорировать.

Альтернативный поток №2. Передан некорректный (несуществующий) параметр type. Сервер возвращает ошибку:

Передан некорректный параметр type

действие не осуществляется.

Альтернативный поток №3. Параметр type передан, но не передан параметр values. Сервер возвращает ошибку:

Не передан параметр values

действие не осуществляется.

Альтернативный поток №4. Передано некорректное (в т.ч. несуществующее для указанного type) значение параметра values. Сервер возвращает ошибку:

Передан некорректный параметр values

действие не осуществляется.

В случае успешного выполнения возвращается полная информация о работе ответственного пользователя:

Примечание.
Если работа создается без указания ответственного (только для исполнителей) информация о созданных работах не возвращается.

errorCode - код ошибки (0 - успешно);
workID - UUID созданной работы;
work - описание работы:
- actionID - UUID созданной работы;
- name - формулировка работы;
- start_date - дата и время начала работы в формате yyyy-MM-dd HH:mm:ss;
- finish_date - дата и время завершения работы в формате yyyy-MM-dd HH:mm:ss;
- stateID - статус работы;
- user:
  - id - UUID ответственного;
  - name - ФИО ответственного в формате "Фамилия И.О.";
- author:
  - id - UUID автора работы;
  - name - ФИО автора в формате "Фамилия И.О.";
- percent - текущий прогресс работы;
- has_attachments (true/false) - имеются ли вложения;
- remained - число, показывающее сколько рабочих дней осталось до завершения работы;
- remained_label - подпись для параметра remained;
- is_expired (true/false) - истек ли срок выполнения работы;
- is_soon_expired (true/false) - истекает ли скоро срок выполнения работы;
- priority - UUID приоритета;
- can_edit (true/false) - есть ли права на редактирование работы;
- can_change_state (true/false) - есть ли право на изменения статуса работы (отметить как завершено);
- can_delete (true/false) - есть ли право на удаление работы;
- can_send_acquaintance (true/false) - есть ли право отправить на ознакомление;
- can_send_agreement (true/false) - есть ли право отправить на согласование;
- can_send_approval (true/false) - есть ли право отправить на утверждение;
- can_be_resended (true/false) - есть ли право передать работу другому пользователю;
- can_reassign (true/false) - есть ли право перепоручить работу;
- can_send_by_route (true/false) - есть ли право отправить по маршруту;
- can_change_progress (true/false) - есть ли право изменить прогресс работы;
- can_manage_comments (true/false) - есть ли право добавлять комментарии к работе;
- can_take_on_control (true/false) - есть ли право взятия работы на контроль;
- is_new (true/false) - есть ли непросмотренные уведомления по данной работе;
- has_subprocesses (true/false) - есть ли дочерние работы;
- can_mark_as_seen (true/false) - есть ли право снять отметку о наличии непросмотренных уведомлений по работе;
- work_state_icon - идентификатор пиктограммы для представления текущего состояния работы;
- work_state_label - идентификатор подписи для описания текущего состояния работы;
- process_result - статус завершения процесса:
  - пустая строка - нет результата (еще в процессе либо работа была завершена или удалена);
  - true - завершено успешно;
  - false - отказано;
- parent_process - UUID родительского процесса;
- procInstID - UUID процесса;
- completionFormID - UUID формы завершения;
- completionResultID - UUID результата завершения;
- isResolution (true/false) - принята ли резолюция на документ, в котором эта работа находится;
- repeat:
  - type - тип период повторения;
  - values - значение периода повторения.

Во всех методах API, где возвращается объект work (описание работы), должен присутствовать параметр repeat. Например, в методах:

получение списка работ пользователя (rest/api/workflow/works/list/{userID});
получение списка дочерних работ для данной (rest/api/workflow/subworks/{workID});
получение информации о работе по UUID (rest/api/workflow/works_by_id);
создание работы (rest/api/workflow/work/create);
изменение работы (rest/api/workflow/work/save);
изменение прогресса работы (rest/api/workflow/work/set_progress);
изменение статуса работы (rest/api/workflow/work/set_state);
отправки работы по маршруту (rest/api/workflow/work/start_route);
задания результата завершения работы (rest/api/workflow/work/set_result);
подтверждения результата работы (rest/api/workflow/work/accept_result);
отклонения результата работы (rest/api/workflow/work/reject_result).

Изменение работы

URL метода: rest/api/workflow/work/save.

Тип запроса: POST.

Метод принимает следующие параметры (FormParam):

actionID - UUID изменяемой работы (обяз.);
name - формулировка работы (обяз.);
userID - UUID ответственного (не обяз.);
startDate - дата и время начала работы в формате yyyy-MM-dd HH:mm:ss (обяз.);
finishDate - дата и время завершения работы в формате yyyy-MM-dd HH:mm:ss (обяз.);
priority - UUID приоритета (обяз.);
completionFormID - UUID формы завершения (не обяз.);
repeat - данные о периоде повторения работы (не обяз.);
locale - локаль пользователя, ru/en/kz (не обяз.).

Новый параметр repeat аналогичен таковому в методе создания работы.

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

В случае неуспешного выполнения вовзращается json с полями:

errorCode - код выполнения (число, отличное от 0);
errorMessage - сообщение об ошибке.

Альтернативные потоки событий для периода повторения.

Альтернативный поток №2. Передан некорректный (несуществующий) параметр type. Сервер возвращает ошибку:

Передан некорректный параметр type

действие не осуществляется.

Альтернативный поток №3. Параметр type передан, но не передан параметр values. Сервер возвращает ошибку:

Не передан параметр values

действие не осуществляется.

Передан некорректный параметр values

действие не осуществляется.

В случае успешного выполнения возвращается полная информация об измененной работе. Данная информация полностью аналогична созданию работы.

Примеры передаваемых и получаемых массивов

Пример передачи периода повторения по дням недели

name=Work&
startDate=2015-11-13+09%3A00%3A00&
finishDate=2015-11-30+18%3A00%3A00&
authorID=7b953be8-bddb-4ce4-bbfd-ae9548f69c7f&
userID=7b953be8-bddb-4ce4-bbfd-ae9548f69c7f&
priority=2&
repeat=%7B%22type%22%3A%22day%22%2C%22values%22%3A%5B%22MON%22%2C%22WED%22%5B%7B

Пример возвращаемого массива

[
  {
  "errorCode": "0",
  "workID": "7ce1feff-a3f0-4f4e-8bf6-59e37caf553f",
  "work": {
    "actionID": "7ce1feff-a3f0-4f4e-8bf6-59e37caf553f",
    "name": "РаботАПИ",
    "start_date": "2015-11-13 09:00:00",
    "finish_date": "2015-11-30 18:00:00",
    "stateID": "0",
    "user": {
      "id": "7b953be8-bddb-4ce4-bbfd-ae9548f69c7f",
      "name": "Абдрешен Л.С."
    },
    "author": {
      "id": "7b953be8-bddb-4ce4-bbfd-ae9548f69c7f",
      "name": "Абдрешен Л.С."
    },
    "percent": "0",
    "has_attachments": "false",
    "remained": "11.745833333333334",
    "remained_label": "11 дн",
    "is_expired": "false",
    "is_soon_expired": "false",
    "priority": "2",
    "can_edit": "true",
    "can_change_state": "true",
    "can_delete": "true",
    "can_send_acquaintance": "true",
    "can_send_agreement": "true",
    "can_send_approval": "true",
    "can_be_resended": "false",
    "can_reassign": "true",
    "can_send_by_route": "true",
    "can_change_progress": "true",
    "can_manage_comments": "true",
    "can_take_on_control": "false",
    "is_new": "false",
    "has_subprocesses": "false",
    "can_mark_as_seen": "true",
    "work_state_icon": "progress_status_icon",
    "work_state_label": "progress",
    "process_result": "",
    "parent_process": "null",
    "procInstID": "4fbcfad1-fba8-4c4a-83fb-1badf6c9a963",
    "completionFormID": "",
    "completionResultID": "",
    "isResolution": "false",
    "repeat": {
      "type": "day",
      "values": ["MON", "WED"]
    }
  }
]

Пред.	Наверх	След.
Задача [DF17]: Доработка настройки отображения документов	Начало	Задача [API67]: API для экрана авторизации в мобильном клиенте