Параметры локаций и посещений

В Календарном планировании локация — это точка, которую сотрудник должен посетить и обслужить. Также в планировании учитываются специальные локации, такие как начальная и конечная точки маршрута. Для одной локации может быть запланировано несколько посещений.

При планировании с помощью Excel характеристики локации указываются на листе locations, а параметры посещений — на листе visits. При планировании в API все параметры указываются в объекте locations.

Основные параметры

Идентификатор

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

Дополнительный идентификатор

Дополнительный числовой или строковый идентификатор локации вы можете указать в поле ref.

Название

Название локации можно указать в поле title.

Описание

Описание локации дается в поле description.

Комментарий

В поле comments можно указать комментарий к локации, например, особенности парковки или  ссылку на сайт.

Номер телефона

В поле phone можно передать номер телефона для связи с локацией.

Адрес и координаты

Координаты локации — широта и долгота — передаются в полях point.lat и point.lon. Координаты указываются в системе WGS84WGS84. Вы можете заранее произвести геокодирование (преобразование адреса в свободной форме в географические координаты).

Важно убедиться, что координаты не перепутаны местами и нет координат, которые по значениям сильно отличаются от остальных (как правило это признак ошибочного геокодирования — при планировании такой адрес может оказаться очень далеко от остальных, и такая локация не попадет ни в один из маршрутов).

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

Сервисное время

Сервисное время, выделяемое сотруднику на посещение локации, указывается в секундах в поле service_duration_s.

Тип локации

По умолчанию локации имеют тип check_in. В  планировании можно использовать специальные локации с type = base, чтобы обозначить локацию, где сотрудник начинает или заканчивает маршрут (дом, офис).

Количество и частота посещений локации

Посещение локации можно планировать на произвольный период. Предполагается, что график посещения локации одинаковый для каждого периода планирования.

Количество посещений локации за период планирования указывается в поле visit_count. За пропущенные или лишние посещения могут начисляться штрафы:

• penalty.drop — фиксированный штраф, если не было ни одного посещения локации;
• penalty.visit_count.fixed — фиксированный штраф, если пропущено хотя бы одно посещение локации или выполнено хотя бы одно лишнее посещение;
• penalty.visit_count.per_visit — штраф за каждое пропущенное или лишнее посещение локации.

Также штрафы могут начисляться за пропуск отдельных типов посещений.

Поля min_days_between_visits и max_days_between_visits задают минимальный и максимальный интервал между посещениями. При этом дни считаются включительно, то есть между посещениями в соседние дни проходит один день. Например, если значение интервала равно 1, посещения будут ежедневными, если 2 — через день.

В поле last_visit_date указывается дата последнего посещения локации перед началом планирования. Она должна быть раньше даты запуска планирования, которая указывается в поле options.date. Интервал между этой датой и датой первого посещения локации в периоде планирования должен соответствовать ограничениям min_days_between_visits и max_days_between_visits.

За нарушение ограничений могут быть назначены соответствующие штрафы:

• penalty.min_days_between_visits.fixed и penalty.min_days_between_visits.per_day
• penalty.max_days_between_visits.fixed и penalty.max_days_between_visits.per_day

Каждый штраф состоит из фиксированной части за факт нарушения ограничения и переменной части, которая рассчитывается за каждый день или каждое посещение, нарушающее ограничение. Значения штрафов по умолчанию равны 0.

Пример

Планируется посещение 17 локаций в течение 30 дней. Локации с 1 по 5 нужно посещать вечером, с 6 по 17 — утром. Каждую локацию нужно посетить 8 раз, максимальный интервал между посещениями 6 дней, минимальный — 3 дня. Посещения распределяются между двумя сотрудниками, один из которых работает в утреннее время, второй — в вечернее.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Дни посещений

Для локации можно указать дни посещений:

• allowed_days — дни, когда можно посещать локацию. Если значение не задано, то разрешены все рабочие дни. При этом учитывается параметр options.working_days_in_week, задающий количество рабочих дней в неделе — если options.working_days_in_week = 7, то локацию можно посещать в любой день.
• preferred_days — дни, когда желательно посещать локацию.
• mandatory_days — обязательные дни посещения. Если в поле указано больше дней, чем значение поля visit_count, то решение не может быть построено.
• denied_days — запрещенные для посещения дни. Они исключаются из дней, заданных остальными параметрами. Это поле удобно использовать, чтобы указать праздничные дни вне расписания.

Для обозначения дней поддерживаются форматы:

• полные английские названия дней с большой буквы "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday";
• 2- и 3-буквенные сокращения "Mo", "Mon", "Tu", "Tue", "We", "Wed", "Th", "Thu", "Fr", "Fri", "Sa", "Sat", "Su", "Sun";
• даты в формате YYYY-MM-DD;
• номера дней от начала планирования, начиная с 0.

За посещение локации в любой другой день, кроме указанных в preferred_days, может быть назначен штраф: фиксированный штраф за факт нарушения penalty.preferred_days.fixed или штраф за каждый день, запланированный с нарушением ограничения penalty.preferred_days.per_day.

{
  "locations": [
    {
      "id": "Location1",
      "allowed_days": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
      "preferred_days": ["Mo", "We", "Fr", "2023-06-10"],
      "mandatory_days": [0, 2, 5, "Monday"],
      "denied_days": ["2023-06-12"]
    }
  ]
}

Временные окна локаций

У локаций можно указать временное окно — интервал времени, когда сотрудник может посетить локацию. Рекомендуется указывать реалистичные, не слишком узкие временные окна.

Если временные окна не указаны, локацию можно посещать в любое время с 00:00 до 24:00.

Для определения временного окна используется поле time_window.

Временное окно определяется в одном из следующих форматов:

• 07:00:00 - 23:00:00 — временное окно начинается в 7 утра и заканчивается в 23 вечера текущего дня;
• 2019-10-10T07:00:00+03:00/2019-10-10T23:00:00+03:00 — временное окно на конкретную дату и часовой пояс (читается как YYYY-MM-DDThh:mm:ss±hh:mm).

Можно указать несколько временных окон (например, если в работе локации есть перерыв). В этом случае в Excel указываются несколько столбцов: time_window.0, time_window.1 и т.д. В запросах API вместо поля time_window указывается time_windows — массив элементов time_window. Посещение будет запланировано в одно из указанных окон.

Для каждого временного окна (одиночного или в массиве) можно задать внешнее жесткое окно hard_time_window.

В ответе API в полях used_time_window и used_hard_time_window будет содержаться информация об использованном временном окне.

За нарушение временных окон назначаются штрафы: penalty.out_of_time — за любое нарушение, penalty.early — за слишком раннее посещение, penalty.late — за опоздание. Каждый из этих штрафов может иметь фиксированную часть fixed за факт нарушения и переменную per_minute за каждую минуту нарушения.

По умолчанию сервисное время необязательно должно попадать во временное окно локации (то есть допустима ситуация, когда сотрудник посещает локацию в 17:59, хотя временное окно до 18:00).

При использовании параметра penalize_late_service = true (значение по умолчанию — false) штрафы начисляются при позднем завершении посещения локации (т.е. после окончания выбранного временного окна).

Теги локаций

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

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

Если локацию нужно закрепить за конкретным сотрудником, то можно задать уникальный тег для сотрудника и указать его в обязательных тегах локации. Подробнее см. в разделе Закрепление локации с помощью тегов.

Необязательные требования для локации указываются в поле optional_tags. При планировании эти требования могут быть проигнорированы, но если теги локации и сотрудника совпадают, это влияет на стоимость маршрута.

Для каждого опционального тега указываются значение optional_tags.N.tag и вес optional_tags.N.value. Вес может быть как положительным, так и отрицательным. Если опциональный тег локации совпал с тегом сотрудника из поля tags на листе employees (employees.tags в запросе API), то вес вычитается из стоимости маршрута; если опциональный тег локации совпал с тегом сотрудника из поля excluded_tags на листе employees (employees.excluded_tags в запросе API), то вес прибавляется к стоимости маршрута.

Также с помощью опциональных тегов можно задать приоритет посещения локации, подробнее см. в разделе Приоритеты с помощью тегов.

Пример

Нужно посетить 49 локаций. Некоторым локациям заданы опциональные теги:

• morning — 6 локаций с весом 500;
• VIP — 3 локации с весом 1000.

Сотрудник 1 начинает и заканчивает рабочий день рано, поэтому для него определен тег morning. У сотрудника 2 есть специальные навыки, поэтому для него определен тег VIP.

В результате планирования в большинстве случаев требования соблюдались: сотрудник 1 посещает 4 из 5 локаций, а сотрудник 2 посещает все VIP-локации.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API

Несовместимость локаций

Отдельные локации могут иметь особые условия для посещения. Условия для разных локаций могут оказаться взаимоисключающими, такие локации нельзя посещать в одном маршруте. Например, для посещения медицинской лаборатории и строительного склада сотруднику может потребоваться разная спецодежда. Характеристики локаций, по которым определяется их несовместимость, указываются в поле load_types. Например, для медицинской лаборатории можно указать load_types = clean.

Для одной локации можно перечислить несколько характеристик через запятую. Например, если при обслуживании локации необходима работа с продуктами в холодильной камере, можно указать load_types = food,cold.

Поле load_types нельзя заполнять для локаций с типом base.

Несовместимость локаций задается в поле incompatible_load_types: для всех маршрутов на листе options и для отдельных сотрудников на листе employees, подробнее см. Несовместимость локаций.

Несколько сотрудников, обслуживающих одну локацию

По умолчанию для одной локации назначается один обслуживающий ее сотрудник. Но можно разрешить нескольким сотрудникам посещать одну и ту же локацию в разные дни. Для этого в опциях укажите поле options.allow_multiple_visitors равным true.

Максимальное количество сотрудников, которые могут посещать локацию, можно ограничить параметром location.max_distinct_visitors. Штраф за нарушение этого ограничения может быть фиксированным penalty.max_distinct_visitors.fixed и за каждого посетителя сверх установленного значения penalty.max_distinct_visitors.per_visitor.

При расчете стоимости обслуживания локации можно задать фиксированную стоимость за посещение локации более чем одним сотрудником cost.additional_visitors.fixed и стоимость за каждого дополнительного сотрудника, начиная со второго, cost.additional_visitors.per_visitor.

Для оценки стоимость спланированного решения используйте метрики:

• additional_visitors_cost — суммарная стоимость за использование дополнительных сотрудников,

• total_locations_cost — общая стоимость обслуживания всех локаций,

• total_employee_cost — общая стоимость использования сотрудников, обслуживающих все локации.

{
  "options": {
    "allow_multiple_visitors": true
  },
  "locations": [
    {
        "penalty": {
            "max_distinct_visitors": {
                "fixed": 1000000,
                "per_visitor": 1000000
            }
        },
        "cost": {
            "additional_visitors": {
                "fixed": 10000,
                "per_visitor": 10000
            }
        },
        "max_distinct_visitors": 2
    }
  ]
}

Приоритеты

Вы можете задать приоритет посещения локации с помощью параметра priority на листе locations. Он может быть задан целым неотрицательным числом. Чем меньше значение параметра, тем выше приоритет посещения локации. У нескольких локаций может быть указан одинаковый приоритет.

Сотрудник может посетить локации с меньшим приоритетом только после того, как он посетит все локации с более высоким приоритетом в запланированном периоде.

Локации, для которых приоритет не указан, могут посещаться в любом порядке.

Пример использования приоритетов см. в разделе Назначение приоритетов.

Типы посещений

Для локации можно задавать разные типы посещений. Это необходимо, если в посещения планируются различные работы. Например, для магазина это могут быть «Выкладка товара» и «Инвентаризация». Также для локации можно устанавливать последовательность посещений разных типов. Например, инвентаризация проводится в каждое пятое посещение, в остальные посещения выполняется выкладка товара.

Типы посещений указываются в Excel на листе visits (в запросе API в массиве locations.visits).

Для каждого типа посещений можно устанавливать свои параметры и ограничения:

• location.id — идентификатор локации, к которой относится тип посещения;
• title — название типа посещения;
• service_duration_s — время обслуживания при посещении данного типа;
• drop — штраф за пропуск посещения данного типа. Если задан, то заменяет значение penalty.visit_count.per_visit для посещений данного типа, см. Количество и частота посещений локации;
• allowed_days — дни, в которые разрешены посещения данного типа;
• preferred_days — дни, предпочтительные для посещений данного типа;
• denied_days — дни, в которые запрещены посещения данного типа.

Для обозначения дней поддерживаются форматы:

• полные английские названия дней с большой буквы "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday";
• 2- и 3-буквенные сокращения "Mo", "Mon", "Tu", "Tue", "We", "Wed", "Th", "Thu", "Fr", "Fri", "Sa", "Sat", "Su", "Sun";
• даты в формате YYYY-MM-DD;
• номера дней от начала планирования, начиная с 0.

При планировании через Excel для каждого типа посещений на листе visits нужно обязательно указывать время обслуживания service_duration_s. При планировании через API если service_duration_s для типа посещений не указан, будет использован параметр, заданный для локации в целом.

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

Например, в период планирования нужно выполнить 10 посещений. Для локации указаны три типа посещений: первый "Инвентаризация" (И), второй и третий "Выкладка" (В). Тогда посещения будут запланированы в таком порядке: И, В, В, И, В, В, И, В, В, И.

{
  "locations": [
    {
      "service_duration_s": 1800,
      "allowed_days": [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ],
      "preferred_days": ["Mon", "Wed", "Fri"],
      "denied_days": [
        "2023-06-12"
      ],
      "visit_count": 10,
      "visits": [
        {
          "title": "Инвентаризация",
          "service_duration_s": 3600,
          "drop": 1000000,
          "allowed_days": [ "Mon", "Tue" ],
          "preferred_days": ["Mon"]
        },
        {
          "title": "Выкладка"
        },
        {
          "title": "Выкладка"
        }
      ],
      "penalty": {
        "drop": {
          "fixed": 100000,
          "per_visit": 10000
        },
        "preferred_days": {
          "fixed": 10000,
          "per_visit": 1000
        }
      }
    }
  ]
}

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