Business solutions

Business solution (zestaw) to gotowy scenariusz dla firmy przygotowany przez Orbito: lista opublikowanych modułów, każdy z opisaną rolą w scenariuszu, oraz szablony automatyzacji, które je łączą. Przykład: „Sklep B2B z wysyłką” — zamówienia z PrestaShop, faktury w wFirmie, etykiety InPost i automatyzacje, które przenoszą zamówienie między nimi.

Zestaw instaluje się w firmie jednym kliknięciem: rdzeń instaluje brakujące moduły i zakłada automatyzacje jako wyłączone szkice do przejrzenia.

Strona ma dwie części: dla firm (instalacja zestawu) i dla Orbito (publikacja zestawów przez omm).

Dla firm

Gdzie znaleźć zestawy

Zestawy są w sklepie modułów: modules.orbito.pl/solutions. Strona zestawu (/solutions/<slug>) pokazuje opis scenariusza, moduły (wymagane i opcjonalne, z rolą każdego) i listę automatyzacji (nazwa i opis każdej).

Instalacja

1. Na stronie zestawu kliknij „Zainstaluj w Orbito”. Otworzy się panel Orbito na stronie instalacji zestawu: https://my.orbi.do/#/solutions/install/<slug>. Ten sam adres możesz wpisać w panelu ręcznie.
2. Zaloguj się (jeśli trzeba) i upewnij się, że w panelu jest wybrana firma, w której chcesz zainstalować zestaw — instalacja trafia do bieżącej firmy. Wystarczy członkostwo w firmie, tak jak przy instalacji pojedynczego modułu.
3. Podgląd. Panel sprawdza, co firma już ma, i przy każdym module pokazuje stan: masz już (moduł zostanie pominięty), zainstaluje albo pominięty. Moduły opcjonalne możesz odznaczyć (pole „dodaj”). Poniżej lista automatyzacji, które powstaną jako szkice.
4. Kliknij przycisk instalacji. Moduły startują i rejestrują się w Orbito — to może potrwać kilka minut; nie zamykaj strony.
5. Wynik: listy „Zainstalowane”, „Pominięte” (już aktywny / pominięty przez Ciebie), „Błędy modułów” i „Automatyzacje” ze stanem każdego szkicu i przyciskiem „Otwórz w edytorze”.

Zależności modułów zestawu (moduły wymagane przez moduły z listy) instalują się same, jak przy instalacji pojedynczego modułu. Podgląd ich nie wymienia — zobaczysz je w module po instalacji.

Co powstaje w firmie

• Moduły — po jednej instancji każdego modułu, którego firma nie ma aktywnego. Moduły już aktywne zostają bez zmian. Błąd jednego modułu nie przerywa instalacji reszty (trafia do „Błędy modułów”); możesz go doinstalować później ze sklepu w panelu.
• Automatyzacje — każdy szablon zestawu jako wyłączona automatyzacja w Ustawienia → Automatyzacje V2. Kroki modułów dostają instancję modułu automatycznie, gdy firma ma dokładnie jedną aktywną instancję tego modułu. Szablon nie zawiera danych Twojej firmy (statusów, kont, adresów) — przejrzyj parametry kroków, zanim włączysz automatyzację.

Stany szkiców w wyniku instalacji:

Problem SOLUTION_AUTOMATION_UNVERIFIED

Rdzeń może sprawdzić szkic dopiero wtedy, gdy moduły zestawu zarejestrują się i zgłoszą swoje wyzwalacze i akcje. Czeka na to najwyżej 60 sekund. Szkic powstaje bez sprawdzenia, a w Ustawienia → Problemy pojawia się wpis SOLUTION_AUTOMATION_UNVERIFIED (z nazwą automatyzacji i linkiem do edytora), gdy:

• moduły nie zgłosiły swoich elementów na czas (np. długi start kontenera), albo
• firma ma kilka instancji modułu użytego w automatyzacji — rdzeń nie zgaduje, którą wybrać.

Co zrobić:

1. Otwórz automatyzację z linku w problemie (albo „Otwórz w edytorze” w wyniku instalacji).
2. Przy kilku instancjach wybierz instancję w każdym kroku tego modułu. Sprawdź parametry kroków.
3. Włącz automatyzację. Rdzeń sprawdza ją przy włączaniu tak samo jak zwykłą; po udanym włączeniu problem znika sam.

Jeśli edytor pokazuje element jako niedostępny, sprawdź w Ustawienia → Moduły, czy moduł działa.

Ponowna instalacja i usuwanie

• Zestaw możesz zainstalować ponownie, np. po odznaczeniu modułu opcjonalnego za pierwszym razem. Moduły już aktywne zostaną pominięte, ale automatyzacje powstaną drugi raz — rdzeń nie pamięta, które szkice już założył. Usuń zbędne duplikaty w edytorze automatyzacji.
• Zestaw nie jest osobnym bytem w firmie. Nie ma „odinstalowania zestawu”: moduły wyłączasz i odinstalowujesz w Ustawienia → Moduły, automatyzacje usuwasz w edytorze, każdy osobno.

Dla Orbito: publikacja zestawów

Katalog zestawu

sklep-b2b/
├── solution.yaml                  # manifest (wymagany)
├── README.md                      # opis na stronie zestawu, markdown, do 20 000 znaków (opcjonalny)
├── cover.png                      # okładka: cover.png, cover.jpg albo cover.webp, do 2 MB (opcjonalna, jedna)
└── automations/
    ├── etykieta-po-oplaceniu.json # grafy automatyzacji — format `omm automation create -f`
    └── mail-o-wysylce.json

solution.yaml

slug: sklep-b2b                        # a-z, 0-9 i -, 3–60 znaków; adres /solutions/sklep-b2b
name: Sklep B2B z wysyłką              # do 80 znaków
summary: Zamówienia z PrestaShop, faktury w wFirmie i etykiety InPost bez przepisywania   # do 200 znaków
tags: [b2b, wysyłka, faktury]          # opcjonalne, filtr na liście zestawów

modules:                               # co najmniej jeden; kolejność = kolejność na stronie zestawu
  - code: core/orders                  # pełny kod "namespace/nazwa", bez powtórzeń
    role: Wspólna lista zamówień ze wszystkich kanałów   # wymagana, do 120 znaków
  - code: core/prestashop
    role: Import zamówień ze sklepu
  - code: core/inpost
    role: Etykiety i Paczkomaty
  - code: core/wfirma
    role: Faktury po opłaceniu zamówienia
    required: false                    # domyślnie true; false = firma może go pominąć przy instalacji

automations:                           # opcjonalne; ścieżki względem katalogu zestawu
  - automations/etykieta-po-oplaceniu.json
  - automations/mail-o-wysylce.json

Pliki automatyzacji

Każdy plik ma dokładnie format pliku omm automation create -f (patrz Automatyzacje firmy): { name, desc, triggers, actions, startActionId }, bez isEnabled.

{
    "name": "Etykieta po opłaceniu",
    "desc": "Opłacone zamówienie dostaje etykietę InPost i status „Do wysyłki”",
    "triggers": [
        { "type": "core/orders:order_paid", "params": {} }
    ],
    "startActionId": "label",
    "actions": {
        "label": {
            "type": "core/inpost:create_label",
            "params": {},
            "branches": { "next": "set_status" }
        },
        "set_status": {
            "type": "core/orders:set_status",
            "params": { "status": "to_ship" },
            "branches": { "next": null }
        }
    }
}

• Typy elementów modułów to pełne klucze <kod modułu>:<kod elementu>, jak w omm automation.
• Nie wpisuj params.__instanceId. To id instancji w Twojej firmie testowej — w firmie klienta nie istnieje. Rdzeń przy instalacji wstawia instancję modułu sam.
• Najwygodniej zbudować i przetestować automatyzację w firmie testowej, a potem przenieść ją do zestawu:

omm automation get <id> --json > automations/etykieta-po-oplaceniu.json
# usuń z pliku "isEnabled" i każde "__instanceId" w params; pola tylko do odczytu (_id, validation …) omm pomija sam

• name do 80 znaków, desc do 300 znaków. Opisz w desc, co automatyzacja robi — firma widzi to w podglądzie przed instalacją.

Komendy

omm solution publish ./sklep-b2b   # publikacja albo aktualizacja (ten sam slug) z katalogu zestawu
omm solution publish               # bieżący katalog
omm solution list                  # SLUG, NAME, MODULES, AUTOMATIONS, INSTALLS, PUBLISHED (także cofnięte)
omm solution unpublish sklep-b2b   # cofnięcie publikacji

• Każda publikacja zastępuje cały zestaw. Brak README.md albo okładki w katalogu czyści opis albo okładkę; listy modułów i automatyzacji są zastępowane w całości. Zostają licznik instalacji i data publikacji.
• Ten sam slug to ten sam zestaw. Slugu zajętego przez zestaw innego namespace'u nie da się użyć (409).
• Licznik instalacji liczy firmy — ta sama firma instalująca zestaw kilka razy liczy się raz.
• Gdy moduł zestawu przestanie być opublikowany, zestaw znika ze sklepu i z Orbito, aż moduł wróci.

Co sprawdza omm, a co repozytorium

omm czyta solution.yaml i wszystkie pliki, a przed wysłaniem zgłasza wszystkie błędy naraz:

• slug zgodny z ^[a-z0-9-]{3,60}$, name i summary niepuste,
• modules to niepusta lista, automations (jeśli jest) to lista ścieżek do istniejących plików,
• każdy plik automatyzacji to poprawny JSON bez isEnabled,
• najwyżej jedna okładka (cover.png, cover.jpg albo cover.webp).

Resztę sprawdza repozytorium, a omm przekazuje jego komunikaty bez zmian (z polem, którego dotyczą, np. modules[0].code):

• długości pól (name, summary, role, nazwa i opis automatyzacji, README.md), wymagana role przy module,
• kody modułów w postaci namespace/nazwa, bez powtórzeń, istniejące i opublikowane,
• okładka to obraz PNG, JPG albo WebP (rozpoznawany po zawartości pliku) do 2 MB,
• kształt grafów: triggers to lista, actions to obiekt, startActionId jest wymagany.

Ani omm, ani repozytorium nie sprawdzają, czy elementy, parametry i gałęzie automatyzacji są poprawne — to robi rdzeń dopiero przy instalacji zestawu w firmie. Dlatego publikuj tylko grafy sprawdzone wcześniej w firmie testowej (omm automation create waliduje cały graf).