Ми розпочинаємо нову серію для ERP Acumatica розробників. І перша стаття буде найбільш корисною для новачків, оскільки вона спрямовує нас до самих основ роботи з Acumatica.
Створення користувацьких полів
Однією з головних і водночас неймовірно корисних функцій кастомізації проекту для Acumatica ERP це можливість створювати власні поля. Спеціальні поля додаються до існуючих у стандартних таблицях бази даних. Для їх додавання зручно використовувати створення скриптів в інтерфейсі налаштувань. Скрипти баз даних Додати Користувацький стовпець до таблиці
Вам також потрібно буде створити необхідний код для взаємодії полів у PXCacheExtension для класу вихідного ЦАП. На цьому етапі не повинно виникнути жодних труднощів. Виконавши цей крок, розробник має право використовувати власні поля. За допомогою спеціальних полів можна зберігати нові важливі значення в базі даних, виводити інформацію з бази даних на екран користувача, залучати дані з цих полів до запиту API або записувати дані з об'єкта-відповіді, за яким слідує певний API-запит. Крім того, цей тип полів можна легко використовувати для побудови нової, унікальної та гнучкої бізнес-логіки під конкретну задачу. Ця функція є надзвичайно важливою і надає безпрецедентну гнучкість для розширення базового функціоналу Acumatica ERP.
При створенні полів таких користувачів або роботі з ними необхідно дотримуватися певних правил. Особливо важливо пам'ятати, що всі поля користувачів повинні починатися з префікса Usr в базі даних, і мають абстрактний клас, також з префіксом Usrоскільки це одна з передумов сертифікації програмного забезпечення ISV, яку необхідно виконати, отже, це ще одна вагома причина дотримуватися цього правила. Ви можете знайти додаткову інформацію про це за посиланням "Посібник із сертифікації програмного забезпечення Acumatica ISV". Назви нових об'єктів у ваших розв'язках повинні відповідати назвам, наданим їм згідно з цими правилами.
Виконання вимог
Однією з основних проблем, пов'язаних з недотриманням вимог цього правила, є видалення полів користувачів з подальшим оновленням системи. Такий сценарій призводить до втрати функціональності програмного рішення, а також до втрати даних, що зберігаються в певних полях. Приклад:public abstract class usrFieldName: BqlType .Field {}.
На перший погляд, все просто, але що робити, якщо проект вже існує, а поля користувачів названі без префікса? Причин може бути декілька, найпоширеніші з них: 1. Кастомізація розроблялася в той момент, коли таким вимогам не було приділено достатньо уваги.2. Реалізація специфічних вимог проводилася під час розробки розширеного функціоналу.
Виправити таку, здавалося б, просту помилку нелегко. Однією з причин є те, що дані для цих полів вже існують і зберігаються в існуючій базі даних без Usr префікс.
Зараз я хочу поділитися з вами одним із способів, як успішно виправити цей недолік. Дотримуючись описаних нижче кроків, сам код і налаштування будуть повністю відповідати вимогам щодо створення та використання спеціальних полів. Для початку ми визначимо і сформуємо план робіт і змін, які повинні будуть відбутися:
1. По-перше, в базі даних потрібно створити ідентичні до існуючих поля, однак, цього разу з Usr префікс.
2. Необхідно забезпечити перенесення даних зі старих полів до нових у новостворені поля, а також видалення старих полів для оптимізації бази даних.
3. Коректно встановіть поля класу в PXCacheExtension для початкового класу ЦАП.
4. Потім видаліть зі сторінок сайту поля, які не мають потрібного префікса, і замініть їх на еквівалентні, але тепер на Usr префікс.
На малюнках нижче ви можете знайти більш детальний опис цих кроків.
Крок 1
Почніть зі створення еквівалентних полів у вікні налаштувань. Створіть власні поля за допомогою інтерфейсу налаштувань.
Наступним кроком буде створення власних полів за допомогою інтерфейсу налаштувань кастомізації (наступний крок створення). Для цього перейдіть до налаштувань на екрані Проекти кастомізації (SM204505)потім перейдіть до пункту меню Скрипти баз даних Додати Користувацький стовпець до таблиці. У діалоговому вікні вставте всі необхідні параметри, еквівалентні полям без префікса.
Крок 2
Потім створіть, передайте нові дані та видаліть старі поля за допомогою SQL.
Додавання нового SQL-скрипта:
Наступним кроком буде написання SQL-скрипту в проекті кастомізації.
Наведений нижче SQL-скрипт легко масштабується і адаптується до різних скриптів для зміни полів на поля з Usr префікси:
IF NOT EXISTS (SELECT * FROM information_schema.COLUMNS WHERE TABLE_NAME = 'назва_таблиці_в_БД' AND COLUMN_NAME = 'UsrFieldName')
ПОЧАТОК
ALTER TABLE назва_таблиці_в_БД ADD UsrFieldName біт NULL;
КІНЕЦЬ;
IF EXISTS (SELECT * FROM information_schema.COLUMNS WHERE TABLE_NAME = 'назва_таблиці_в_БД' AND COLUMN_NAME = 'UsrFieldName')
ПОЧАТОК
IF EXISTS (SELECT * FROM information_schema.COLUMNS WHERE TABLE_NAME = 'назва_таблиці_в_БД' AND COLUMN_NAME = 'назва_поля')
ПОЧАТОК
exec('UPDATE table_name_in_DB SET UsrFieldName = FieldName');
IF EXISTS (SELECT * FROM information_schema.COLUMNS WHERE TABLE_NAME = 'назва_таблиці_в_БД' AND COLUMN_NAME = 'UsrFieldName')
ПОЧАТОК
ALTER TABLE назва_таблиці_в_БД ДОПУСТИТИ стовпець Назва поля;
КІНЕЦЬ;
КІНЕЦЬ;
КІНЕЦЬ;
ВПЕРЕД!
Спочатку ми перевіряємо, чи потрібно запускати новий скрипт, оскільки він не може виконуватися при повторних публікаціях налаштувань проекту, а потім перевіряємо, чи існує поле у відповідній таблиці БД. Якщо поле вже є, ми не виконуємо скрипт, однак, якщо поля не існує, скрипт переходить до наступного кроку. Далі ми створюємо необхідне поле в таблиці з префіксом Usr.
Наступним кроком буде перевірка, чи поле вже існує, і якщо так, то потрібно перенести дані зі старого поля до нового. Після перенесення даних починається процес видалення старих полів.
Тепер ми розглянемо, як правильно задавати класи полів у класах ЦАП.
Якщо ви використовуєте кодовий підхід, вам потрібно буде встановити клас поля в PXCacheExtension на початковий клас DAC. Для цього достатньо змінити ім'я абстрактного класу і передати аналогічний параметр до вставленої конструкції BqlType:загальнодоступний абстрактний клас usrTrackHours: BqlType .Field {}
Крім того, на цьому етапі важливо уважно стежити за тим, де в коді використовується це конкретне поле, і змінювати посилання на нього в усіх необхідних місцях, оскільки саме так можна створювати власні поля для існуючих таблиць.
Якщо ви використовуєте підхід додавання через налаштування інтерфейсу проекту, то буде зручно відкрити Проекти кастомізації (SM204505) а потім перейти до пункту меню ДОСТУП ДО ДАНИХ Додати новий записі там у діалогових вікнах будуть встановлені необхідні параметри для поля.
Однак не забудьте написати назву поля з Usr префікс, наприклад, UsrFieldName.
На малюнку нижче показано, як додається новий запис для доступу до даних за допомогою налаштувань інтерфейсу проекту:
А також встановлення необхідних параметрів для налаштування полів користувацького інтерфейсу проекту:
Далі ми розглянемо видалення полів без потрібного префікса і зміну їх на поля з префіксом Usr префікс.
Редагування XML-проекту в налаштуваннях проекту:
Далі ми розглянемо збереження XML-проекту в налаштуваннях проекту. Для цього буде зручно відкрити Проекти кастомізації (SM204505) а потім перейдіть до пункту меню Файл Редагування XML проекту і замініть необхідні поля у вікні на XML-код.
Для цього потрібно змінюватися: в
Виконавши всі необхідні зміни, натисніть на кнопку "Зберегти в базі даних". Крім того, вам потрібно опублікувати проект кастомізації, після чого внести вищезгадані зміни.
Висновок
Сподіваюся, прочитавши цю статтю, ви зрозумієте, що не варто боятися вдосконалювати існуючий код, оскільки, виділивши на це достатньо часу і ресурсів, ви зрештою будете впевнені, що подальша робота з ним не викличе неприємних сюрпризів і зайвих проблем.
Ще однією суттєвою перевагою виконання всіх вищезазначених змін є відповідність критеріям сертифікації програмного забезпечення ISV, які застосовуються до полів користувачів, визначених для класів ЦАП від Acumatica ERP.
P.S. Я хотів би висловити свою подяку команді Acumatica за Sprinterra за готовність завжди прийти на допомогу в будь-яких складних або нетривіальних ситуаціях під час розробки з використанням Acumatica Framework.
Юрій Музичин
Серпень 2021 року
Ukrainian 
English