SitterIT Mobigo REST API — driftguide

Installera, sätta upp, uppdatera och avinstallera. För den som driftar servern. Ska du integrera mot API:et, läs integratörsguiden i stället.

Förutsättningar

Mobigo-version: du väljer inte, produkten läser

Motorn binder mot Mobigo.Core, och den ser olika ut mellan serierna. Därför finns ett motorbygge per Mobigo-serie — i dag 7.9 och 7.10. API:et finns däremot i ett enda exemplar: det rör aldrig Mobigo.Core, det pratar JSON över localhost.

Utgåvan innehåller alla motorbyggen:

C:\SitterIT\MobigoApi  SitterIT.Mobigo.Api.exe        ett bygge, alla serier
  engine\mobigo-7.9\             motor för Mobigo 7.9
  engine\mobigo-7.10\            motor för Mobigo 7.10

Vilken som gäller frågar vi inte om. Kör:

SitterIT.Mobigo.Api.exe engine "C:\inetpub\Mobigo Server\Bin\Common"

Mobigo 7.10 → motorbygget i "engine\mobigo-7.10".
engine\mobigo-7.10

Versionen läses ur kundens egen Mobigo.Core.dll, ur filens metadata utan att ladda den. Sista raden är enbart mappen, så ett installationsskript kan läsa den rakt av. Peka tjänsten på den mappen.

Och skulle fel motor ändå startas vägrar den, med besked:

Mobigo 7.9 passar inte det här bygget, som är gjort för Mobigo 7.10.
Det finns ETT BYGGE PER MOBIGO-SERIE — hämta det som matchar installationen
i adminytan. Uppstarten i Mobigo.Core har olika signatur per serie, så det
här bygget skulle falla på en MissingMethodException i stället för här.
Hittad: 7.9.2.0 i C:\inetpub\Mobigo Server\Bin\Common

Adminytan visar dessutom vilken serie som körs, och uppdateringskontrollen erbjuder bara utgåvor som matchar installationen. Tre spärrar, alla automatiska.

Vad som faktiskt skiljer sig

Motorn refererar 463 medlemmar i Mobigo.Core. Mot 7.9 saknas 10 och 33 har annan signatur — mätt, inte uppskattat. Tyngst väger att statusenumarna (TaskStatus, UserStatus, PlanDateType och tio till) flyttade från Mobigo.Core till Mobigo.Common i 7.10, och att uppstarten har olika form:

7.7 och 7.8 har inget bygge ännu. De ligger nära 7.9 — samma motorbygge är bara nio medlemmar ifrån att passa dem också.

Installera

Två processer på samma server. API:et äger HTTP och autentisering; motorn äger Mobigo.Core och lyssnar bara på localhost.

1. Packa upp

C:\SitterIT\MobigoApi  SitterIT.Mobigo.Api.exe        ett bygge, alla Mobigo-serier
  engine\mobigo-7.9\             motorbygge för Mobigo 7.9
  engine\mobigo-7.10\            motorbygge för Mobigo 7.10

Packa upp hela utgåvan. Att bara ta med den serie kunden kör i dag är att göra nästa Mobigo-uppgradering till en nedladdning till.

2. Sätt upp bolaget — ett kommando

SitterIT.Mobigo.Api.exe setup --mobigo "C:\inetpub\Mobigo Server\Bin\Common" --tenant "Kundnamn"

Bolaget «Kundnamn» uppsatt mot Mobigo 7.10.
  motor      engine\current  (från engine\mobigo-7.10)
  port       5590
  mobigo     C:\inetpub\Mobigo Server\Bin\Common
  config     C:\inetpub\Mobigo Server

Kommandot gör allt som annars blir olika varje gång:

• Väljer motorbygge genom att läsa versionen ur kundens egen Mobigo.Core.dll och kopierar det till engine\current.
• Genererar motornyckeln: 43 slumpade tecken. Motorn har full åtkomst till kundens databas.
• Hittar mobigo.config ovanför Bin-mappen, så databasens lösenord läses av Mobigo själv och aldrig skrivs i vår konfiguration.
• Tar nästa lediga port. En motor per bolag betyder en port per bolag.
• Registrerar bolaget i API:et med samma nyckel och port.

Kör man om kommandot behålls nyckel och port.

3. Registrera tjänsterna

sc create SitterITMobigoApi    binPath= "C:\SitterIT\MobigoApi\SitterIT.Mobigo.Api.exe" start= auto
sc create SitterITMobigoEngine binPath= "C:\SitterIT\MobigoApi\engine\current\SitterIT.Mobigo.Engine.exe" start= auto
sc start SitterITMobigoEngine
sc start SitterITMobigoApi

Flera bolag

API:et är ett för hela installationen — en adress, en adminyta, en licens. Motorn är en per bolag: den är konfigurerad för ett bolags Bin-mapp, databas och port, och två bolag kräver därför två processer.

SitterIT.Mobigo.Api.exe setup --mobigo "…\Kund1\Bin\Common" --tenant "Kund1"
SitterIT.Mobigo.Api.exe setup --mobigo "…\Kund2\Bin\Common" --tenant "Kund2"

Varje körning lägger motorn i engine\current\<bolag> med egen port och egen motornyckel, och skriver ut vilken tjänst som ska registreras:

engine\current\Kund1\   port 5590   tjänst SitterITMobigoEngine-Kund1
engine\current\Kund2\   port 5591   tjänst SitterITMobigoEngine-Kund2

4. Licens och första nyckeln

Öppna /admin på servern, ange licensnyckeln, och skapa integrationen. Nyckeln visas en gång.

Adminytan

Allt löpande arbete görs i webbläsaren, på servern:

https://<serverns adress>/admin

Inloggningen sker med ett Mobigo-konto — API:et frågar Mobigo, inte en egen lösenordslista, och kontot måste vara systemadministratör i Mobigo. Det finns alltså inget extra lösenord att hålla reda på, och den som slutar och stängs av i Mobigo kommer inte in här heller.

Kommandoraden behövs inte

Installationsskriptet gör allt förstagångsarbete — bolaget, certifikatet, lyssningen och tjänsterna. Därefter räcker adminytan.

Kommandona finns kvar för två lägen där webbläsaren inte hjälper: innan något är uppsatt, och när tjänsten inte startar. De är listade under Kommandon.

HTTPS

Samma nät: inget nytt certifikat

Mobigo Server kör redan i IIS med kundens certifikat. Lägg API:et som ett program under samma site:

https://mobigo.kund.se/       → Mobigo Server   (befintlig)
https://mobigo.kund.se/api/   → SitterIT Mobigo REST API

Kräver ASP.NET Core Hosting Bundle samt URL Rewrite + ARR. Proxa till http://127.0.0.1:5080 och sätt:

{
  "Hosting": { "BehindReverseProxy": true },
  "Kestrel": { "Endpoints": { "Http": { "Url": "http://127.0.0.1:5080" } } }
}

Eget certifikat, direkt i API:et

Kör API:et fristående — utan IIS framför — sköts certifikatet i adminytan, under Så nås API:et → Certifikat.

Har kunden redan ett? Certifikat i maskinens lagring med privat nyckel listas där. Har kunden ett i IIS för Mobigo Server syns det, och då behövs inget nytt — välj det bara.

Let's Encrypt — publikt betrott, gratis, och förnyas av sig självt. Rutan finns i adminytan så snart win-acme är på plats. Saknas den finns en knapp som hämtar och installerar den — filen kontrolleras mot en känd kontrollsumma innan något packas upp, för den körs sedan som tjänstekontot med åtkomst till certifikatlagringen. Servern behöver nå github.com; går det inte, lägg wacs.exe i mappen win-acme bredvid API:et för hand.

Sedan: ange värdnamn och e-postadress, tryck Beställ certifikat.

Ni måste bevisa att ni äger värdnamnet. Det går på tre sätt, och bara det första kräver en öppen port 80:

DNS-vägen har färdiga kopplingar för Cloudflare, Azure, Route53, Loopia med flera — då sätter win-acme TXT-posten själv vid varje förnyelse. Kör wacs.exe utan argument på servern; den har en meny som går igenom valen.

E-postadressen används av Let's Encrypt för att varna om ett certifikat närmar sig utgång utan att ha förnyats.

win-acme registrerar ett schemalagt jobb som förnyar var sextionde dag. Ingenting behöver göras om.

Vill ni köra det för hand, eller förstå vad knappen gör, är kommandot detta:

wacs.exe --source manual --host mobigo-api.kund.se --emailaddress [email protected] ^
         --accepttos --validation selfhosting ^
         --store certificatestore --certificatestore My --installation none

--installation none för att win-acme inte ska binda certifikatet i IIS — det är API:et som använder det, och valet görs under Certifikat.

Går inte Let's Encrypt? Är servern inte nåbar utifrån, eller är port 80 upptagen, skapar adminytan i stället ett självsignerat. Ange värdnamnet, eventuella ytterligare namn och giltighetstid. Knappen gör tre saker:

1. Skapar ett självsignerat certifikat med 2048-bitars RSA-nyckel. Namnen hamnar i subjectAltName, inte bara i CN — ett certifikat med rätt CN men utan SAN avvisas av varje modern klient.
2. Lägger det i maskinens certifikatlagring, och i tillitslagringen på samma maskin så serverns egna verktyg slutar varna.
3. Ger tjänstekontot läsrätt på den privata nyckeln.

Vad självsignerat inte löser: en klient som inte känner igen utfärdaren varnar. För en integration på kundens eget nät spelar det sällan roll — den som skriver integrationen kan lägga in certifikatet i sin egen tillitslagring. Ska API:et nås av utomstående över internet behövs ett certifikat från en publik utfärdare.

Utifrån: oftast eget certifikat

Mobigos värdnamn är ofta internt och certifikatet utfärdat av kundens interna CA — det litar ingen utomstående anropare på. Då behövs ett publikt värdnamn och certifikat, eller ett befintligt wildcard. Publicera bara API:et, inte hela Mobigo-siten. Motorn berörs aldrig: den binder alltid 127.0.0.1.

Licens och internet

API:et är licensierat per maskin. Licensen kontrolleras mot tokens.sitterit.se vid uppstart och därefter högst en gång per dygn.

Bara /v1 spärras. Adminytan och guiderna svarar även när licensen är ogiltig, så det går att rätta felet på servern.

Aktiveringen är maskinbunden

Nyckeln förbrukar en plats per maskin vid första kontrollen. Flyttas installationen till en ny server, eller kopieras den, räknas det som en ny maskin — svaret blir då licensen är inte aktiverad för den här maskinen. Hör av dig så frigör vi platsen.

Kontrollera läget

SitterIT.Mobigo.Api license check

Giltig för maskin a3f19c7e. Går ut 2027-08-20.

Reservkoden

Vid uppsättningen frågar adminytan efter licensnyckeln. Går licensservern inte att nå just då finns en reservkod i setup-code.txt bredvid databasfilerna. Den släpper in dig i adminytan så att sökvägar och bolag kan sättas upp — men den ersätter inte licensen. Licensnyckeln måste registreras innan API:et börjar svara på /v1.

Integrationer och nycklar

Varje integration som ska anropa API:et behöver en egen nyckel. Den skapas här, på servern, och det är den enda platsen den går att skapa på.

SitterIT.Mobigo.Api keys create ^
    --name "Webshop" ^
    --tenant "Kundnamn" ^
    --sign "API" ^
    --scopes "tasks:read,tasks:write,customers:read"

Kommandot skriver ut två saker som integratören behöver:

Integration skapad.
  Id      : f287ea5c-...        ← clientId
  ...

API-nyckel (visas bara denna gång — spara den nu):

  mk_...                        ← clientSecret

Kör keys utan argument för listan över alla scopes.

Se och återkalla

SitterIT.Mobigo.Api keys list
SitterIT.Mobigo.Api keys revoke --id f287ea5c-...

Återkallning slår igenom direkt, både på nyckeln och på alla token som utfärdats med den.

Uppdatera

Kunden uppgraderar Mobigo

Till exempel 7.9 → 7.10. Motorn är byggd för en serie, så den måste bytas — men tjänsten ska inte röras.

sc stop SitterITMobigoEngine
SitterIT.Mobigo.Api.exe setup --mobigo "C:\inetpub\Mobigo Server\Bin\Common" --tenant "Kundnamn"

Bolaget «Kundnamn» uppsatt mot Mobigo 7.10.
  motor      engine\current  (från engine\mobigo-7.10)
  MOTORN BYTTES: 7.9 → 7.10. Starta om tjänsten SitterITMobigoEngine.

sc start SitterITMobigoEngine

Samma kommando som vid installation. Nyckel och port behålls och sökvägarna uppdateras. Raden MOTORN BYTTES visas bara när serien faktiskt ändrades.

Stoppa motorn först. En körande motor håller sina filer låsta; kommandot avbryter i så fall i stället för att lämna halva bytet gjort.

Ny version av API:et

Adminytan söker efter utgåvor och visar bara sådana som passar kundens Mobigo-serie. Ingen automatisk uppgradering: att byta ut en körande motor mitt i kundens arbetsdag ska inte hända av sig självt.

1. sc stop SitterITMobigoApi och sc stop SitterITMobigoEngine
2. Packa upp den nya utgåvan över den gamla. engine\current skrivs inte över av uppackningen.
3. Kör setup igen — det lägger den nya motorn i engine\current och behåller bolagets inställningar.
4. Starta tjänsterna.

Databaserna med nycklar, tokens, idempotens och revisionslogg ligger kvar och läses av den nya versionen. Kolumner som tillkommit läggs till vid start.

Kommandon

Hela referensen. Kör dem från installationsmappen. Behövs sällan — adminytan täcker allt löpande arbete — men finns för de två lägen där webbläsaren inte hjälper: innan något är uppsatt, och när tjänsten inte startar.

Alla utan argument skriver ut sin egen användning.

Uppsättning

Integrationer

Lyssning och certifikat

Licens

Avinstallera

1. Återkalla integrationerna i adminytan först. Då slutar nycklarna fungera direkt, även om någon sparat undan dem.
2. sc stop och sc delete för båda tjänsterna.
3. Ta bort IIS-programmet eller siten, om en sådan lagts upp.
4. Ta bort C:\SitterIT\MobigoApi\.
5. Släpp licensens maskinplats på tokens.sitterit.se/admin/licenses, annars är platsen upptagen av en server som inte finns längre.

Kundens data berörs inte. API:et skriver bara i Mobigos egen databas genom Mobigos egna regler. Det som tas bort här är våra egna filer: integrationsnycklar, idempotenssvar, granskningslogg och inställningar. Uppdrag, kunder och rader som skapats via API:et ligger kvar i Mobigo.

API 0.1.0.0 · Integratörsguide · Swagger · Administration