Migracja z SuiteCRM 7 do SuiteCRM 8 nie jest aktualizacją wersji. To przeniesienie instancji do nowej architektury: Symfony na backendzie, Angular na froncie i dotychczasowy kod 7.x zamknięty w warstwie legacy. Dla jednych firm oznacza to kilka tygodni pracy, dla innych przepisanie customizacji budowanych latami. Seria SuiteCRM 7.15 ESR daje czas na decyzję, ale z niej nie zwalnia. Poniżej opisujemy, kiedy migracja ma sens, co najczęściej przestaje działać i jak przygotować projekt.

Czym migracja do SuiteCRM 8 różni się od zwykłej aktualizacji?

Migracja do SuiteCRM 8 wymaga nowej instalacji docelowej i dedykowanej paczki migracyjnej. Nie da się jej przeprowadzić przez Upgrade Wizard na istniejącej instancji SuiteCRM 7. Dokumentacja SuiteCRM wprost rozdziela dwa pojęcia. Upgrade odbywa się w obrębie 7.x i jest łatką nakładaną na istniejącą instalację. Migracja to zmiana głównej wersji na nowej instancji. Różnica ma praktyczne konsekwencje: wycofanie migracji oznacza odtworzenie kopii zapasowej, a nie odinstalowanie paczki.

SuiteCRM 8 dodaje warstwę aplikacyjną Symfony i interfejs oparty na Angularze. Kod SuiteCRM 7 trafia do katalogu public/legacy i działa jako warstwa legacy wewnątrz nowej aplikacji. Dane i większość logiki biznesowej przechodzą bez zmian. Problem dotyczy wszystkiego, co zależało od sposobu renderowania widoków w SuiteCRM 7: własnych klas widoków, skryptów JavaScript i szablonów Smarty. Nowy frontend po prostu ich nie wywołuje.

Technicznie migracja SuiteCRM 7 do 8 przebiega według stałego schematu. Najpierw rozpakowuje się paczkę migracyjną (nazwa według wzorca SuiteCRM-8.x-7.x-migration). Następnie kopiuje się instancję SuiteCRM 7 do katalogu public/ i zmienia jej nazwę na legacy. Potem uruchamia się trzy komendy CLI:

• ./bin/console suitecrm:app:setup-legacy-migration
• ./bin/console suitecrm:app:upgrade -t <wersja>
• ./bin/console suitecrm:app:upgrade-finalize

Od wersji 8.7 (Symfony 6.4) przed uruchomieniem skryptów trzeba dodatkowo ręcznie podmienić katalogi vendor i include oraz plik deprecated.php wersjami z paczki.

Kiedy warto przejść na SuiteCRM 8, a kiedy zostać na SuiteCRM 7.15 ESR?

Pozostanie na SuiteCRM 7.15 ESR jest w 2026 roku decyzją racjonalną, a nie zaniedbaniem, pod warunkiem że to świadomy wybór z planowaną datą końcową. SalesAgility zapowiedziało, że wydanie 7.15 jako Extended Support Release wydłuża życie serii 7.x o co najmniej dwa lata i dodaje wsparcie PHP do wersji 8.4. Obie linie są aktywnie rozwijane: 31 lipca 2026 roku ukazały się równolegle SuiteCRM 7.15.2 i SuiteCRM 8.10.2.

Za migracją do SuiteCRM 8 przemawia kierunek rozwoju platformy. Nowe mechanizmy rozszerzeń (front-end extensions, Process API, save handlery, zadania asynchroniczne) istnieją wyłącznie w linii 8.x. Każda nowa customizacja budowana dziś w SuiteCRM 7 zwiększa przyszły koszt przejścia. Po drugiej stronie wagi leży cykl wydań. Wersje minor SuiteCRM 8 mają krótkie okna wsparcia: aktywne wsparcie dla 8.6 trwało od kwietnia do lipca 2024 roku. Przejście na 8.x oznacza więc regularne aktualizacje.

Jednego scenariusza nie rekomendujemy w żadnym wariancie: pozostawania na niewspieranych wersjach 7.10, 7.11 czy 7.12. Przykładem ryzyka jest podatność CVE-2024-36411 z oceną CVSS 9.6 (Critical, 2024), czyli SQL Injection w kontrolerze EmailUIAjax. Poprawiono ją dopiero w wersjach 7.14.4 i 8.6.1. Starsze wydania nie otrzymały poprawki.

Kryterium	Raczej migrować teraz	Raczej zostać na 7.15 ESR
Customizacje UI (widoki, JS, Smarty)	Nieliczne lub brak	Liczne i krytyczne dla procesu sprzedaży lub obsługi
Wtyczki firm trzecich	Dostawcy mają wersje dla 8.x	Kluczowe wtyczki nie mają wersji dla 8.x
Serwer	Linux, Apache 2.4, PHP 8.2+	Windows Server / IIS bez możliwości zmiany stosu
Zasoby IT	Zespół gotowy na regularne aktualizacje minor 8.x	Brak zasobów na częste aktualizacje
Plany rozwoju systemu	Nowe moduły i integracje w najbliższym roku	System stabilny, zmiany minimalne
Horyzont	Chęć uniknięcia migracji pod presją końca wsparcia 7.x	Planowana zmiana platformy CRM w ciągu 2 lat

Najdroższy scenariusz, jaki widzimy w projektach, to migracja odkładana do ostatnich miesięcy wsparcia SuiteCRM 7. Wtedy audyt, testy i przepisywanie customizacji odbywają się pod presją czasu, a decyzje o tym, co porzucić, zapadają bez analizy.

Co przestanie działać po migracji z SuiteCRM 7 do 8?

Najbardziej narażone są customizacje warstwy prezentacji. Chodzi o własne klasy widoków (view.detail.php, view.edit.php), modyfikacje JavaScript, szablony Smarty oraz logic hooki ingerujące w wyświetlanie, takie jak process_record. Logika backendowa, czyli hooki before_save i after_save, Workflow i vardefy, zwykle przechodzi, bo działa w warstwie legacy. Zgłoszenia na forum społeczności SuiteCRM potwierdzają ten wzorzec. Hook process_record wyświetla w SuiteCRM 8 surowy kod HTML, a view.detail.php przestaje być wywoływany.

Obszar	Ryzyko	Co sprawdzić przed migracją
Własne widoki (custom/modules/*/views)	Wysokie	Nowy interfejs ich nie renderuje. Opcje: tryb legacy modułu w module_routing.yaml albo przepisanie na front-end extension
Logic hooki UI (np. process_record)	Wysokie	Lista hooków ingerujących w listy i widoki. Do przepisania lub do trybu legacy
Logic hooki backendowe (before_save, after_save)	Niskie–średnie	Zgodność kodu z PHP 8.2+ (minimum w aktualnej matrycy SuiteCRM 8)
Metadane widoków (custom/modules/*/metadata)	Średnie	Wybór trybu scalania metadanych. Tryb nadpisania usuwa pliki customizacji
Pliki spoza core w public/legacy	Średnie	Inwentaryzacja plików dodanych poza custom/. Proces migracji może je usunąć
Wtyczki firm trzecich	Wysokie	Potwierdzenie u dostawcy, że istnieje wersja dla SuiteCRM 8
Modyfikacje motywu SuiteP i CSS	Wysokie	Zmiany w motywie SuiteCRM 7 nie przenoszą się na interfejs SuiteCRM 8
Integracje i adresy URL	Średnie	Nowa struktura katalogów, site_url i RewriteBase. Test wszystkich integracji na stagingu

Tryb legacy dla modułu to obejście, a nie rozwiązanie docelowe. Ustawienie modułu w module_routing.yaml sprawia, że wyświetla się on w starym interfejsie osadzonym w nowym. Pozwala to przeprowadzić migrację SuiteCRM 7 do 8 bez blokowania projektu przez kilka problematycznych modułów. Użytkownicy pracują jednak wtedy w dwóch interfejsach naraz, a dług techniczny tylko zmienia adres.

Jakie wymagania infrastrukturalne stawia SuiteCRM 8?

Aktualna matryca kompatybilności SuiteCRM 8 obejmuje PHP 8.2, 8.3 i 8.4, serwer Apache 2.4, MariaDB 10.6, 10.11, 11.4 i 11.8 oraz MySQL 8.0 i 8.4. Platformy to Linux, Unix i macOS. Od wersji 8.7 SuiteCRM nie działa na PHP 7.4. Najczęściej przeoczana zmiana dotyczy jednak Windows: matryca SuiteCRM 7.14 obejmowała Windows Server 2019+ i IIS 10, a aktualna matryca SuiteCRM 8 ich nie wymienia.

Element	SuiteCRM 7.14.x	SuiteCRM 8 (aktualna matryca)
Platforma	Linux, Unix, macOS, Windows Server 2019+	Linux, Unix, macOS
Serwer WWW	Apache 2.4, IIS 10	Apache 2.4
PHP	8.1, 8.2 (w 7.15 ESR do 8.4)	8.2, 8.3, 8.4
MariaDB	10.4, 10.5, 10.6, 10.10, 10.11	10.6, 10.11, 11.4, 11.8
MySQL	według matrycy 7.x	8.0, 8.4 (MySQL 5.7 był jeszcze wspierany w 8.8)
Node.js / Angular CLI	nie dotyczy	Tylko do budowy front-end extensions, niewymagane na produkcji

Dla instancji działających na Windows i IIS migracja do SuiteCRM 8 oznacza więc w praktyce dwa projekty: zmianę serwera i zmianę wersji CRM. Warto je rozdzielić w czasie. Najpierw przenosi się SuiteCRM 7.15 na Linux i Apache, potem przeprowadza migrację do SuiteCRM 8. Każdy problem da się wtedy przypisać do jednej zmiany.

Jak przygotować się do migracji SuiteCRM 7 do 8 krok po kroku?

Przygotowanie do migracji SuiteCRM 7 do 8 zaczyna się od inwentaryzacji, a nie od pobrania paczki. Poniższa sekwencja to schemat, który stosujemy w projektach migracyjnych. Kroki 1–3 można wykonać na długo przed decyzją o terminie migracji.

1. Inwentaryzacja customizacji. Należy spisać zawartość custom/, moduły z Module Buildera, wszystkie logic hooki, pliki dodane poza custom/ oraz zainstalowane wtyczki. Każdy element trzeba sklasyfikować: backend (zwykle przechodzi) czy UI (wymaga decyzji).
2. Aktualizacja SuiteCRM 7 do wymaganej wersji. Dokumentacja migracji wymaga najnowszego wydania 7.14.x. Dla linii 7.15 SuiteCRM udostępnia paczkę „8.10.2 Migrate from 7.15.x”. Po drodze trzeba wykonać manualne kroki z release notes każdej wersji.
3. Środowisko zgodne z matrycą. Obejmuje to PHP 8.2+, Apache 2.4 i wspieraną wersję bazy danych. Trzeba też sprawdzić, czy kod customizacji działa na minimalnej wersji PHP z matrycy.
4. Kopia zapasowa plików instancji i bazy danych.
5. Próbna migracja na stagingu. W pliku .env.local należy ustawić APP_ENV=prod. Komendy warto uruchamiać z flagą -vvv (pełne raportowanie błędów E_ALL). Trzeba też świadomie wybrać tryb scalania metadanych widoków.
6. Porządki po komendach. Należy przywrócić uprawnienia plików dla użytkownika serwera WWW. Przy błędzie „Invalid CSRF token” wystarczy wyczyścić ciasteczka przeglądarki.
7. Testy procesowe. Testować należy pełne scenariusze (lead → szansa → oferta, obsługa zgłoszenia), integracje, raporty, Workflow i harmonogramy. Logi znajdują się w public/legacy/upgradeWizard.log i public/legacy/suitecrm.log.
8. Decyzja per moduł i go-live. Każdy moduł trafia do jednej z trzech kategorii: natywny interfejs SuiteCRM 8, tymczasowy tryb legacy albo przepisanie. Ostatnim elementem jest plan regularnych aktualizacji minor 8.x po wdrożeniu.

Tryby scalania metadanych to decyzja, której nie warto zostawiać domyślnej konfiguracji bez zrozumienia. Tryb domyślny zachowuje istniejące customizacje metadanych i pomija scalanie. Tryb merge próbuje połączyć customizacje z nowymi metadanymi core i tworzy kopię zapasową. Tryb override zastępuje customizacje metadanymi core i usuwa pliki w public/legacy/custom/<Module>/metadata.

Jak może wyglądać migracja SuiteCRM 7 do 8 w praktyce?

Scenariusz hipotetyczny. Firma dystrybucyjna ma 60 użytkowników SuiteCRM 7.14 na Windows Server z IIS. Instancja zawiera 14 logic hooków (w tym 3 typu process_record), 2 moduły z Module Buildera, własny widok szczegółów szansy sprzedaży (Opportunities) oraz 3 wtyczki firm trzecich. Liczby i harmonogram w tej sekcji są ilustracyjne. Nie opisują konkretnego wdrożenia eVolpe.

Audyt w tym scenariuszu daje jasny podział:

• 11 hooków backendowych przechodzi do SuiteCRM 8 po weryfikacji zgodności z PHP 8.2.
• 3 hooki process_record i własny widok Opportunities trafiają na start do trybu legacy. Ich przepisanie na front-end extensions zaplanowano w drugiej fazie.
• Jedna z trzech wtyczek nie ma wersji dla SuiteCRM 8. Jej funkcję przejmuje natywny moduł Workflow.
• Infrastruktura: wymiana serwera na Linux z Apache to osobny etap, wykonany przed migracją.

Harmonogram fazy pierwszej w takim scenariuszu może wyglądać następująco:

Etap	Szacowany czas
Audyt	2 tygodnie
Zmiana serwera na SuiteCRM 7.15	2 tygodnie
Próbna migracja i poprawki	3 tygodnie
Testy akceptacyjne z użytkownikami	2 tygodnie

Kluczowy wniosek ze scenariusza: o koszcie migracji SuiteCRM 7 do 8 nie decyduje liczba użytkowników ani rekordów, tylko liczba customizacji warstwy UI i wtyczek bez wersji dla 8.x. Firma z 300 użytkownikami i czystą instancją może migrować szybciej niż firma z 30 użytkownikami i rozbudowanymi widokami.

Jakie błędy najczęściej popełnia się przy migracji SuiteCRM 7 do 8?

Najczęstszy błąd to potraktowanie migracji jak upgrade’u: bez audytu, bez stagingu, z założeniem, że „wszystko przejdzie”. Pozostałe błędy wynikają zwykle z pośpiechu lub niewiedzy o różnicach architektonicznych:

• Migracja z nieaktualnej wersji 7.x. Pominięcie kroku aktualizacji do wymaganej wersji 7.x i manualnych kroków z release notes.
• Zła paczka. Użycie paczki instalacyjnej SuiteCRM 8 zamiast migracyjnej. Objawem jest brak komendy suitecrm:app:setup-legacy-migration.
• Tryb override „żeby było czysto”. Wybór nadpisania metadanych bez kopii customizacji usuwa układy widoków budowane latami.
• Założenie, że wtyczki przejdą bez zmian. Przykładem jest wtyczka Security Suite, niekompatybilna z SuiteCRM 8.x. Bez wersji od dostawcy wtyczka to element do zastąpienia, nie do przeniesienia.
• Tryb legacy jako stan docelowy. Moduły „tymczasowo” w legacy po dwóch latach wciąż blokują korzyści z nowego interfejsu.
• Brak planu na cykl wydań SuiteCRM 8. API front-end extensions zmieniało się między wersjami: dokumentacja zawiera osobne przewodniki migracji rozszerzeń do 8.5+ i 8.8+. Każde rozszerzenie trzeba więc testować przy aktualizacjach minor.
• Komendy jako root bez przywrócenia uprawnień. Serwer WWW traci dostęp zapisu do nowo utworzonych plików.

Podsumowanie

Migracja z SuiteCRM 7 do 8 to projekt architektoniczny, którego koszt wyznacza liczba customizacji UI i wtyczek, a nie wielkość bazy. SuiteCRM 7.15 ESR daje czas, ale ten czas warto wykorzystać na inwentaryzację, nie na odkładanie decyzji. Audyt customizacji można przeprowadzić w tym kwartale, niezależnie od terminu migracji, i od niego zależy realny budżet całego przejścia.

Ile customizacji w Waszej instancji SuiteCRM 7 dotyka warstwy wyświetlania? Czy ktoś w zespole potrafi dziś odpowiedzieć na to pytanie bez otwierania katalogu custom/?

Jeśli zainteresował Cię ten temat, skontaktuj się z nami. Chętnie odpowiemy na twoje pytania.

Najczęściej zadawane pytania

Źródła

• SuiteCRM Documentation – Migration (Upgrading vs migrating): https://docs.suitecrm.com/admin/migration/
• SuiteCRM Documentation – Moving to SuiteCRM 8: https://docs.suitecrm.com/admin/migration/to-suitecrm-8/
• SuiteCRM Documentation – Running the Migration (8.7.0+): https://docs.suitecrm.com/8.x/admin/migration/running-the-migration/
• SuiteCRM Documentation – Compatibility Matrix 8.x: https://docs.suitecrm.com/8.x/admin/compatibility-matrix/
• SuiteCRM – Extended Support for SuiteCRM 7.x: https://suitecrm.com/extended-support-for-suitecrm-7-x/
• SuiteCRM – Releases: https://suitecrm.com/releases/
• OSV – CVE-2024-36411: https://osv.dev/vulnerability/CVE-2024-3641