ITFin Community Apps

У цьому репозиторії описані інструкції по створенню додатків для розширення функціоналу ITFin.

Створення додатку

Для створення додатку необхідно виконати наступні кроки:

1. Перейти у розділ https://app.itfin.io/apps
2. Натиснути кнопку "Створити"
3. Вказати назву додатку та його ідентифікатор (для ідентифікатора допускаються тільки латинські літери, цифри та тире)
4. Натиснути кнопку "Зберегти"

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

Розробка додатку

Розробка ведеться на мові Javascript. За основу додатку можна взяти шаблон, який знаходиться у репозиторії: https://github.com/itfin-io/community-app-boilerplate

Додаток запускається у віртуальному середовищі, яке має обмежені можливості та обмеження по часу - 10хв. По суті своїй це функція, яка обробляє вхідні дані з системи чи зовні. Виклики формують чергу і виконуються послідовно. Відповідно обробка події відбувається з затримкою, а не в момент її виникнення.

Наприклад, коли створюється користувач у системі, то відбувається подія employees:created. Якщо у додатку вказано обробляти цей тип подій, то буде викликана функція onEvent першим параметром якої буде передано назву функції, другим аргументом буде обʼєкт з деталями.

Для тестування додатку ITFin може надати тестове середовище по запиту на пошту [e-mail].

Структура додатку

Обовʼязковими елементами додатку є файл manifest.json та власне сам файл з функцією, який вказується у файлі маніфесту параметром main і зазвичай є dist/index.js.

Приклад файлу manifest.json:

{
  "name": "app-name",
  "version": "0.0.1",
  "title": "Application Name",
  "description": "Description for your application",
  "main": "dist/index.js",
  "events": [
    "employees:created",
    "periodically:hourly"
  ],
  "image": "assets/icon.png"
}

Параметри

• name - ідентифікатор додатку, який вказується при створенні додатку
• version - версія додатку
• title - назва додатку
• description - опис додатку
• main - файл з функцією, яка викликається при виконанні додатку
• events - масив з назвами подій, які будуть оброблятись додатком
• image - іконка додатку

Приклад файлу index.js:

const manifest = require('../manifest.json');
const app = ITFinApp.createCommunityApp(); // створємо обʼєкт для доступу до АПІ

// функцію не потрібно експортувати, вона буде викликана автоматично
async function onEvent(name, params) {
  const config = await app.getAppConfig(); // отримуємо налаштування для додатку
  switch (name) {
    // при створенні користувача викликається подія employees:created 
    // і функція createNewUser створює нового користувача у Google Workspace
    case 'employees:created':
      return createNewUser(config, params);
  }
}

async function createNewUser(config, { Email, FirstName, LastName }) {
  const user = {
    primaryEmail: Email,
    name: {
      givenName: FirstName,
      familyName: LastName
    },
    // спрощено
  };
  return ITFinRequest.post('https://admin.googleapis.com/admin/directory/v1/users', user, {
    headers: {
      Authorization: `Bearer ${config.token}`
    }
  });
}

Конфігурація додатку

Якщо додатку потрібні вхідні параметри від користувача, то їх можна прописати у маніфесті в параметрі config:

{
  "config": [
    {
      "id": "sync_entities",
      "title": "What do you want to sync?",
      "field_type": "checkbox",
      "options": {
        "options": {
          "one_on_one": "Sync 1:1's meetings",
          "appraisals": "Sync performance appraisals"
        }
      }
    }
  ]
}

Публікація додатку

Завантажити додаток можливо на сторінці самого додатку у ITFin або ж використовуючи Deploy token (доступний на сторінці додатку) з CI/CD серверу. Завантажується zip-архів в корні повинен бути файл manifest.json. Також відбувається контроль версійності, система не дасть завантажити ту ж версію, яка вже існує, якщо вона не буде відмічена як dev версія.