Розробка інтерфейсу смарт-процесів на Vue.js для Бітрікс24

Розробка інтерфейсу смарт-процесів на Vue.js для Бітрікс24

Смарт-процеси у Бітрікс24 — це налаштовувані CRM-об'єкти, що з'явились у API з версії 21.800. На відміну від стандартних угод і лідів, смарт-процеси створюються під конкретний бізнес-процес: заявка на відпустку, погодження договору, технічний інцидент. Стандартний інтерфейс смарт-процесу — це та сама картка CRM. Коли потрібен специфічний UI: нестандартний порядок кроків, візуальний прогрес, залежні поля зі складною логікою — підключається Vue-застосунок через механізм placement.

REST API смарт-процесів

Смарт-процеси працюють через методи crm.item.* — єдине API для всіх користувацьких типів:

// Отримати список елементів смарт-процесу
const items = await callMethod('crm.item.list', {
  entityTypeId: 1040, // ID вашого смарт-процесу
  select: ['id', 'title', 'stageId', 'assignedById', 'ufCrm_custom_field'],
  filter: { stageId: 'DT1040_1:NEW' },
  order: { id: 'DESC' }
})

// Створити елемент
await callMethod('crm.item.add', {
  entityTypeId: 1040,
  fields: {
    title: 'Нова заявка',
    stageId: 'DT1040_1:NEW',
    ufCrm_1040_custom_date: '2024-01-15',
  }
})

// Оновити елемент
await callMethod('crm.item.update', {
  entityTypeId: 1040,
  id: itemId,
  fields: { stageId: 'DT1040_1:IN_PROCESS' }
})

entityTypeId — числовий ідентифікатор смарт-процесу. Отримати через crm.type.list.

Архітектура багатокрокового інтерфейсу

Типовий кейс — форма погодження з кількома кроками, де кожен крок відповідає стадії смарт-процесу:

<!-- SmartProcessWizard.vue -->
<template>
  <div class="wizard">
    <StepIndicator :steps="steps" :current="currentStep" />

    <Transition name="slide" mode="out-in">
      <component
        :is="currentStepComponent"
        :key="currentStep"
        :item="store.item"
        @next="handleNext"
        @back="handleBack"
        @save="handleSave"
      />
    </Transition>
  </div>
</template>

<script setup>
import { computed } from 'vue'
import { useSmartProcessStore } from '@/stores/smartProcess'

const store = useSmartProcessStore()

const steps = [
  { id: 'initial', label: 'Вихідні дані', component: StepInitial },
  { id: 'approval', label: 'Погодження', component: StepApproval },
  { id: 'documents', label: 'Документи', component: StepDocuments },
  { id: 'completion', label: 'Завершення', component: StepCompletion },
]

const currentStep = computed(() => store.currentStep)
const currentStepComponent = computed(
  () => steps.find(s => s.id === currentStep.value)?.component
)

async function handleNext(data) {
  await store.saveStepData(data)
  store.nextStep()
}
</script>

Робота зі стадіями

Отримання стадій смарт-процесу та їх відображення:

// composables/useStages.js
import { ref, onMounted } from 'vue'
import { useBx24 } from './useBx24'

export function useStages(entityTypeId) {
  const { callMethod } = useBx24()
  const stages = ref([])

  onMounted(async () => {
    const result = await callMethod('crm.status.list', {
      filter: { ENTITY_ID: `DYNAMIC_${entityTypeId}_STAGE` }
    })
    stages.value = result
  })

  function getStageColor(stageId) {
    const stage = stages.value.find(s => s.STATUS_ID === stageId)
    return stage?.COLOR || '#cccccc'
  }

  function getStageLabel(stageId) {
    const stage = stages.value.find(s => s.STATUS_ID === stageId)
    return stage?.NAME || stageId
  }

  return { stages, getStageColor, getStageLabel }
}

Користувацькі поля смарт-процесів

UF-поля смарт-процесів мають префікс ufCrm_{entityTypeId}_:

// Отримання значень UF-полів
const item = await callMethod('crm.item.get', {
  entityTypeId: 1040,
  id: itemId
})

// UF-поля в item.ufCrm_1040_*
const customDate = item.ufCrm_1040_1704067200   // тип date
const customSelect = item.ufCrm_1040_enumeration // тип enumeration

// Оновлення UF-поля
await callMethod('crm.item.update', {
  entityTypeId: 1040,
  id: itemId,
  fields: {
    ufCrm_1040_1704067200: '2024-02-01',
  }
})

Для роботи з переліченнями — userfield.enumvalues.get повертає можливі значення.

Погодження та права доступу

Смарт-процеси підтримують ролі та права. Перевірка дозволів перед дією:

async function checkPermission(entityTypeId, action) {
  const result = await callMethod('crm.type.get', { id: entityTypeId })
  const userRole = result.userPermissions?.[action]
  return userRole !== 'NONE'
}

// У компоненті
const canEdit = ref(false)
onMounted(async () => {
  canEdit.value = await checkPermission(1040, 'WRITE')
})

Бізнес-процеси та автоматизація

Запуск бізнес-процесу з Vue-інтерфейсу:

// Запуск BP для елемента смарт-процесу
await callMethod('bizproc.workflow.start', {
  TEMPLATE_ID: templateId,
  DOCUMENT_ID: ['crm', 'CCrmDocumentDynamic', `${entityTypeId}_${itemId}`],
  PARAMETERS: {
    approver_id: selectedApproverId,
    deadline: deadlineDate,
  }
})

Статус запущеного процесу — bizproc.workflow.instances.

Відображення історії змін

Історія стадій із crm.timeline.bindings.list та crm.activity.list:

<template>
  <div class="timeline">
    <div v-for="event in timeline" :key="event.id" class="timeline-item">
      <div class="timeline-date">{{ formatDateTime(event.created) }}</div>
      <div class="timeline-content">
        <span class="timeline-author">{{ event.authorName }}</span>
        {{ event.description }}
      </div>
    </div>
  </div>
</template>

Терміни виконання

Інтерфейс смарт-процесу з багатокроковою формою, відображенням стадій та історією — 4–6 робочих днів. Повноцінне рішення з кастомним погодженням, інтеграцією з BP та зовнішніми системами — 2–4 тижні.