1С: Синхронизация статусов расписания – настройка интеграции
UnSpot Schedule Status Adapter — внешняя обработка 1С, которая переносит рабочие статусы сотрудников из «ЗУП» в расписание UnSpot: больничные, отпуска, командировки, отсутствия и удалённую работу. В статье — что подготовить до подключения, где взять адрес и токен, как установить обработку в 1С, что означает каждое поле формы настроек, как включить регулярный запуск и что делать при ошибках. Как устроен обмен, что именно уходит в UnSpot и где хранятся токен и кэш — в статье 1С: Синхронизация статусов расписания – как устроен обработчик.
Кратко
- Обработка UnSpot Schedule Status Adapter переносит из ЗУП в расписание UnSpot больничные, отпуска, командировки, отсутствия и удалённую работу.
- Понадобятся: файл обработки, токен карточки «Импорт расписания сотрудника» (это External API, не SCIM) и пользователи UnSpot с теми же email, что в 1С.
- Каждый запуск охватывает период от 45 дней назад до 45 дней вперёд и отправляет только то, что изменилось с прошлого раза.
- «Сохранить и проверить» отправляет один настоящий статус на сегодня — это проверка с изменением данных.
- Незнакомое слово — загляните в раздел Термины статьи-обзора.
Важно до включения
- Рабочий день снимает брони столов. Для обычных рабочих дней обработка отправляет сброс статуса, а UnSpot при сбросе, как и при установке статуса, освобождает личные брони столов сотрудника на этот день. Первый запуск затронет рабочие дни на 45 дней вперёд.
- 1С перезаписывает ручные статусы. В периоде ±45 дней статус из 1С заменяет поставленный в UnSpot вручную — при первой отправке и каждый раз, когда значение в 1С меняется.
- Первый запуск долгий: статусы уходят по одному в секунду, для 100 сотрудников это часы.
- Токен лежит в базе 1С в открытом виде, скрипт выполняется без безопасного режима. Доступ к форме настроек — только администраторам. Подробности — в статье 1С: Синхронизация статусов расписания – как устроен обработчик.
Требования
- 1С 8.3 (работа проверена на версии 8.3.27.1688) с Библиотекой стандартных подсистем (БСП, проверено на 3.1.9.89).
- Конфигурация «Зарплата и управление персоналом» 3.1 ПРОФ или КОРП (проверено на 3.1.27.51 ПРОФ и 3.1.28.84 КОРП) — для неё выбор данных встроен. Другие конфигурации подключаются в режиме «Нестандартная конфигурация» с собственным скриптом — см. 1С: Собственный скрипт – настройка интеграции.
- Файл внешней обработки
1s-schedule-status-adapter.epf— его предоставляет команда UnSpot. - У сотрудников в 1С заполнены email, и пользователи с теми же email существуют в UnSpot. Если пользователей ещё нет, сначала настройте синхронизацию пользователей — например, по статье 1С: Синхронизация пользователей – настройка интеграции.
- Исходящий доступ с сервера 1С к домену вашего рабочего пространства UnSpot по TCP/443. Входящие правила не нужны — обработка только отправляет запросы.
Шаг 1. Подключение в UnSpot
Обработке нужны адрес API и токен доступа. Их выдаёт карточка «Импорт расписания сотрудника».
- В UnSpot откройте Настройка → Интеграции → Настройки API.
- В блоке «Предоставление информации» найдите карточку «Импорт расписания сотрудника» и нажмите «Подключить». При подключении можно задать срок действия токена.
- Скопируйте URL и токен — они понадобятся в настройках обработки. Токен показывается при подключении: сохраните его в надёжном месте.
Подключать карточку может Владелец или Администратор интеграций.
Что учитывать. Это отдельный токен External API. Токен SCIM 2.0 от синхронизации пользователей здесь не подойдёт.
Шаг 2. Установка обработки в 1С
- Запустите 1С:Предприятие (не Конфигуратор).
- Откройте Администрирование → Печатные формы, отчеты и обработки → Дополнительные отчеты и обработки. Если ссылки нет, включите флажок «Дополнительные отчеты и обработки» на той же странице.
- Нажмите «Добавить из файла…» и выберите файл
1s-schedule-status-adapter.epf.
В списке появится обработка UnSpot Schedule Status Adapter с двумя командами: UnSpot Schedule Status Adapter Settings — форма настроек и UnSpot Schedule Status Adapter Sync — запуск синхронизации.
Обработка регистрируется с отключённым безопасным режимом, поэтому для установки и запуска нужны соответствующие права в 1С — полные права или права на дополнительные обработки. Полный перечень прав — в разделе «Требования к сети и правам в 1С» статьи 1С: Синхронизация статусов расписания – как устроен обработчик.
Шаг 3. Настройки обработки
Откройте команду UnSpot Schedule Status Adapter Settings — появится форма настроек синхронизации статусов сотрудников. Настройки сохраняются внутри информационной базы, поэтому вводятся один раз. Обязательны адрес, токен и конфигурация, а для «Нестандартной конфигурации» — ещё и код выбора данных. Если чего-то нет, при сохранении появится подсказка («Введите UnSpot API URL», «Введите токен доступа», «Конфигурация 1С должна быть выбрана»).
UnSpot API URL
Полный адрес эндпоинта из карточки «Импорт расписания сотрудника» — вида https://<домен>/api/external/v1/user-schedule. Обработка отправляет запросы ровно по этому адресу: ничего дописывать или сокращать не нужно. Схему https менять нельзя — именно она включает защищённое соединение; номер порта в адресе не указывается. Формат адреса проверяется не при сохранении, а при проверке или запуске: адрес без протокола или с протоколом, написанным заглавными буквами, остановит работу ошибкой «Неверный формат URL: …».
Токен доступа
Токен из той же карточки. Передаётся в каждом запросе в заголовке Authorization (Bearer). Поле обычное текстовое, значение видно на экране — вводите его так, чтобы монитор не просматривался со стороны. Если при подключении карточки задан срок действия, по его истечении запросы начнут отклоняться с ошибкой 401 «API token has expired» — переподключите карточку и обновите токен в настройках обработки.
Конфигурация 1С
Определяет, каким скриптом обработка выбирает данные из информационной базы. Два значения:
- «ЗУП 3.1 (ПРОФ/КОРП)» — используется встроенный скрипт. Поле «Код выбора данных для синхронизации» показывает его в режиме «только просмотр»; при обновлении обработки встроенный скрипт обновляется вместе с ней.
- «Нестандартная конфигурация» — поле «Код выбора данных для синхронизации» становится редактируемым: укажите собственный скрипт — за основу можно взять копию встроенного (см. 1С: Собственный скрипт – настройка интеграции). Скрипт сохраняется в настройках и выполняется вместо встроенного. Если поле пустое, при сохранении появится сообщение «Код выбора данных для синхронизации не может быть пуст». Заготовка из комментариев, которую поле показывает до первого сохранения, скриптом не считается и не сохраняется: сохраняется только текст, который вы ввели или вставили. Если сохранить настройки, не изменив заготовку, запуск остановится с ошибкой о неопределённой переменной.
Код выбора данных для синхронизации
Скрипт на встроенном языке 1С. Его контракт: заполнить переменную СотрудникиДляUnSpot — соответствие «идентификатор физлица → структура с полями email и name» — и переменную СтатусыСостоянийДляUnSpot — соответствие «дата → идентификатор физлица → код статуса». Как устроен встроенный скрипт — в статье 1С: Синхронизация статусов расписания – как устроен скрипт, как написать свой — в статье 1С: Собственный скрипт – настройка интеграции.
Что учитывать. Собственный скрипт выполняется в информационной базе без безопасного режима и с правами пользователя, под которым идёт синхронизация. Относитесь к правке этого поля как к правке кода конфигурации.
Кнопки формы
- Сохранить — сохраняет настройки. Любое сохранение сбрасывает кэш отправленных статусов: следующий запуск пройдёт полностью. Что лежит в кэше — в разделе «Что кэшируется и где» статьи 1С: Синхронизация статусов расписания – как устроен обработчик.
- Сохранить и проверить — сохраняет настройки и выполняет пробный запуск за текущий день: показывает, сколько выбрано сотрудников с email и дат со статусами (у встроенного скрипта в проверке 0 или 1), отправляет статус в UnSpot и выводит сообщение сервера. Проверка отправляет реальный запрос и меняет расписание: выбранный сотрудник получит статус (или сброс статуса) на сегодня. Кэш при проверке не используется.
- Сохранить и запустить — сохраняет настройки и запускает полную синхронизацию фоновым заданием. Ход выполнения пишется в журнал регистрации.
Шаг 4. Проверка и регулярный запуск
Заполните настройки и нажмите «Сохранить и проверить». Успешная проверка выглядит так: «Настройки сохранены» → «Проверка синхронизации..» → «Выбрано сотрудников с email: N» → «Выбрано статусов сотрудников на текущую дату: N» → «Синхронизация статуса сотрудника … на дату …: …» → «OK» → «Синхронизация статуса успешна, проверка завершается» → «Проверка завершена». Во втором сообщении N — число дат, по которым есть статусы: у встроенного скрипта в проверочном запуске это 0 или 1.
Для регулярной синхронизации настройте регламентное задание: на странице обработки в строке команды UnSpot Schedule Status Adapter Sync включите расписание (флажок в колонке с часами) либо запускайте команду вручную кнопкой «Выполнить». Достаточно одного запуска в сутки — например, ночью. Повторный запуск при уже идущей синхронизации не стартует: обработка сообщит «Синхронизация уже выполняется, подождите завершения».
Что учитывать. Первый запуск и первый запуск после любого сохранения настроек может занять заметное время: статусы отправляются по одному в секунду, за период от −45 до +45 дней — это до 91 дня на сотрудника, то есть для 100 сотрудников порядка двух с половиной часов и больше. В следующие запуски статус, не изменившийся с прошлой успешной отправки, пропускается по кэшу.
Что учитывать. Паузу в секунду между статусами обработка делает вызовом процедуры ВызватьПаузу, которой в самой обработке нет: её должна предоставлять конфигурация. Если в вашей конфигурации такой процедуры нет, модуль обработки не скомпилируется и она не запустится вовсе — это сразу покажет кнопка «Сохранить и проверить».
Что учитывать. В периоде от −45 до +45 дней 1С считается источником статусов: отправленный статус заменяет значение в расписании UnSpot на этот день, в том числе поставленное вручную, а «Рабочее время» из 1С сбрасывает ручной статус. Отправка происходит при первой передаче за дату и каждый раз, когда значение в 1С изменилось; без изменения в 1С или сброса кэша ручная правка расписания не перезаписывается.
Что учитывать. Для рабочих дней обработка отправляет сброс статуса. По текущему коду UnSpot сброс, как и установка статуса, освобождает личные брони столов сотрудника, начинающиеся в эту дату. Поэтому при первом запуске и при запуске после сохранения настроек (кэш сброшен) будут сняты ещё не завершённые личные брони столов, начинающиеся в рабочие дни периода от сегодня до +45 дней. Учитывайте это при выборе времени первого запуска.
Что изменится в UnSpot: примеры
Как события в 1С отражаются в расписании UnSpot после ближайшего запуска.
| Что произошло в 1С | Что будет в расписании UnSpot |
|---|---|
| Оформили отпуск на ближайшие две недели | На эти дни встанет статус «Отпуск». Личные брони столов сотрудника на эти дни будут сняты |
| Отпуск отменили или перенесли | На освободившиеся рабочие дни уйдёт сброс: отметка «Отпуск» исчезнет. Брони стола, оформленные сотрудником на эти дни до запуска, тоже снимутся |
| Больничный оформили задним числом | Статус встанет и на прошедшие дни, если они не старше 45 дней |
| Отпуск запланирован через два месяца | Появится в расписании, когда до него останется 45 дней |
| Администратор вручную поставил статус в UnSpot | Ручной статус останется, пока значение в 1С на этот день не изменится. Первый запуск и запуск после сохранения настроек его перезапишут |
| Сотрудника ещё нет в UnSpot | Статусы не встанут (в журнале — «User not found»). Когда пользователь появится, они уйдут при следующем запуске |
Возможные ошибки
| Сообщение | Причина | Что делать |
|---|---|---|
401 Invalid API token | Токен не подходит: опечатка или использован токен другой карточки (например, SCIM 2.0) | Скопируйте токен из карточки «Импорт расписания сотрудника» заново |
401 API token has expired | Истёк срок действия токена | Переподключите карточку и обновите токен в настройках обработки |
400 User not found | В UnSpot нет активного пользователя с таким email | Проверьте email сотрудника в 1С и наличие пользователя в UnSpot; настройте синхронизацию пользователей |
429 Too Many Requests | Превышен лимит 1 запрос в секунду — например, запросы к API идут параллельно из другой системы с тем же токеном | Не используйте один токен в нескольких интеграциях одновременно |
| «Синхронизация уже выполняется» | Предыдущее фоновое задание ещё не завершилось | Дождитесь завершения — ход виден в журнале регистрации |
| «Не найдено сотрудников с заполненным email» | У сотрудников в 1С не заполнены email | Заполните email в карточках сотрудников |
| «Неверный формат URL» | Адрес в поле «UnSpot API URL» указан без протокола или протокол написан заглавными буквами | Введите адрес целиком, начиная с https:// |
| «Настройки не установлены» | Синхронизация запущена до первого сохранения настроек | Откройте форму настроек и сохраните их |
Подробный журнал каждого запуска — в 1С: Администрирование → Обслуживание → Журнал регистрации, источник вида UnSpotScheduleStatus#дата. Дата в имени — день первого сохранения настроек. В журнале видны выборка, каждая отправка с ответом сервера, пропуски и итог. Полный состав записей — в разделе «Что пишется в журнал регистрации» статьи 1С: Синхронизация статусов расписания – как устроен обработчик.
Связанные статьи
- 1С: Синхронизация статусов расписания – как устроен обработчик — протокол, передаваемые данные, кэш и журнал.
- 1С: Синхронизация статусов расписания – как устроен скрипт — разбор встроенного скрипта по блокам.
- 1С: Собственный скрипт – настройка интеграции — как написать скрипт для нестандартной конфигурации.
- 1С: Обзор интеграции — какие бывают интеграции с 1С и с чего начать.
- 1С: Синхронизация пользователей – настройка интеграции — пользователи должны существовать в UnSpot до передачи статусов.
- External API: обновление статуса в расписании — описание эндпоинта.
- Управление рабочими статусами в расписании — настройка статусов в UnSpot.
