API

Att komma igång med Stratsys API:er

Denna instruktion syftar till att bistå utvecklare som vill skapa en klient som kan anropa något av Stratsys API:er.

Förberedelser 

Innan man kan skapa en API-klient så behöver behörigheterna eventuellt justeras för den användare som ska skapa upp klienter med rätt att konsumera Stratsys API:er. Detta utförs i Användaradministrationen i Stratsys plattform. För mer information kring användaradministrationen, läs mer här.

Den användare som ska ha rätt att skapa klienter för Stratsys API behöver ha behörighetsrollen Utvecklare, och man tilldelar en användare den behörigheten på följande sätt:

  • Öppna användarens profil i plattformen
  • I profilen som öppnas, expandera fliken "Roller"
  • Klicka i rollen "Utvecklare".

     

    Uppskapande av klient

    • Låt användaren med Utvecklar-behörighet navigera till https://developers.svc.stratsys.com/[TenantId
    • Eventuellt behöver användaren Logga in till Stratsys på ordinarie sätt. 
    • Klicka på Clients i menyn till vänster, sedan på ”Add Client” 

    Skapa en ny klient, döp den till något lämpligt som beskriver vad klienten används till (t.ex. Power BI API Client), välj ”Web application/server to server” och ”Client credentials” och klicka på ”Add”. Notera ”Client Id”-fältet 

    Klicka sedan på Secrets i ”Settings”-menyn. Under Shared secrets, skriv in något lämpligt i ”Description”-fältet (t.ex. secret) och klicka på ”Save”. Nu kommer du att se Client Secret för denna klient. 

     

    OBS! Denna secret visas bara denna enda gång, så var noga med att spara undan denna någonstans, den måste gå med i alla anrop till API:t och behöver kommuniceras till kunds utvecklare. 

    • För att ge tillgång till V1-API:t, klicka på ”API resources” i Settingsmenyn, välj Stratsys API v1 i dropdownen. 

    • Klicka på Save utan att göra något mer, så har vi tilldelat full access för denna klient till API v1. 
    • Nu är konfigurationen klar och det går att börja koda anrop mot Stratsys API v1. 

    Följande information behöver utvecklarna ha för att kunna anropa API:t (v1) 

    Adress för att få ut bearertoken 

    https://login.svc.stratsys.com/[TenantId]/connect/token 

    (där TenantId är Id:t för den aktuella Stratsys-kunden)

    ClientId 

    Id:t i Stratsys/Developers enligt beskrivning ovan 

    Secret 

    Secret enligt ovan 

    Scope 

    https://web.stratsys.se/auth/v1/full.access 

    Bas-URL för APIv1 

    https://www.stratsys.se/api/v1 

    Claims 

    Externkoder 

    För att använda sig av externkoder behöver detta definieras under Claims. Definierar man inget källsystem här så kommer Stratsys interna ID:n att användas. 

    Har man exempelvis ett källsystem som heter QlikView så behöver detta defineras som ett Claim av typen ”externalsource” med värdet exakt som källsystemet heter i Stratsys.

    Planeringsversion 

    För att klienten ska hantera planeringsversion korrekt i Stratsys v1 så behöver detta defineras som ett claim med namnet useplanningversion som ska vara satt till true om klienten ska gå mot planeringsversion istället för aktuell version. 

     

    Uppskapande av Galleriklient

    Vi har tagit fram ett antal galleriklienter för att förenkla skapandet av vissa klient-typer som alltid definieras på samma sätt. Följande galleriklienter är tillgängliga idag, men fler kan komma att tillkomma. Har du någon tanke på en galleriklient som du anser att vi borde ta fram, kontakta gärna din Stratsyskonsult/kundansvarig.

    Klientnamn Beskrivning
    Directory Sync Client Används för att synka en lokal katalogtjänst med Stratsys plattform
    2c8 API Client Används vid 2c8-integration för att skapa noder i Stratsys från 2c8. Uppgifterna härifrån ska delges 2c8 vid uppsättning
    2c8 Publishing Client Används vid 2c8-integration för att autentisering från publiceringsplatsen i 2c8 ska ske mot Stratsys IdP.
    Stratsys Published Gadgets Client Används för att tillåta publicering av gadgets från Stratsys på tredje-partssajter.
    Stratsys Reports Client Används för att sätta upp webbpublicering av Stratsys rapporter

    Directory Sync Client

    Directory Sync-klienten används av AD-synk-klienten för att synkronisera användare från en lokal LDAP-katalog (vanligtvis Active Directory) till Stratsys Plattform och en tillhörande Stratsys-databas.

    Börja gärna med att klicka på Readme för att få fram rätt struktur på clientSettings.json-filen (som är det som kan fyllas i då man följer denna guide). Alternativt om AD-synk-klienten redan är installerad på den tilltänkta servern så kan man med fördel fylla i uppgifterna direkt i clientSettings.json-filen direkt.

    Så här ser mallen för clientSettings.json ut

    {
    "TenantId": "",
    "CompanyCode": "",
    "Authentication": {
    "ClientCredentials": {
    "ClientId": "",
    "ClientSecret": ""
    }
    },
    "ExternalSource": ""
    }

    Följande fält ska nu alltså fyllas i med information som krävs för att klienten ska kunna läsa rätt information från Stratsys, samt uppdatera användarinformationen korrekt.

    TenantId: Fås enklast från Directory Sync-klientens vänstra vy, klicka på Kopiera-ikonen och fyll i på avsett ställe i clientSettings.json.

    CompanyCode: CompanyCode är namnet på den Stratsys-databas som användarna ska synkroniseras till. Rätt CompanyCode får man enklast fram genom inloggnings-URL:en till Stratsys som är på något av dessa två format, som båda alltid innehåller CompanyCode som en del av URL:en (se kursiverat). CompanyCode ska skrivas med gemener.

    https://www.stratsys.se/[CompanyCode]

    https://[CompanyCode].app.stratsys.com

    ClientId: Fås enklast från Directory Sync-klientens vänstra vy, klicka på Kopiera-ikonen och fyll i på avsett ställe i clientSettings.json.

    ClientSecret: Genereras på följande sätt:

    • Klicka på Secrets under Configuration
    • Fyll i något i Description-fältet (t.ex. Secret)
    • Klicka på Save

    Nu visas Client Secret, kopiera med Kopiera-ikonen och lägg in i clientSettings.json. Denna secret visas bara en gång, så missas det att kopiera den så behöver man upprepa stegen ovan.

    ExternalSource: Eventuellt källsystems namn som hämtas från aktuell Stratsys-databas. Detta återfinns i Stratsys, under Administration => Källsystem och externa koder

    Källsystemets namn måste skrivas på exakt samma sätt som källsystemet heter i Stratsys. Om namnet på källsystemet ändras i Stratsys behöver man göra motsvarande ändring i clientSettings.json-filen för att synkroniseringen ska fungera.

    2c8 API Client

    2c8 API Client används för publicering av noder (processer) från 2c8 till Stratsys och informationen här behöver delvis fyllas i i 2c8 Modeling Tool. Detta görs vanligtvis under grundkonfigurationen av en 2c8-integration och ska inte i normalfallet inte behöva ändras därefter.

    Client Id: Kopieras över till 2c8 Modeling Tool genom att klicka på Kopiera-ikonen.

    External source: Sätts som standard till 2c8 och används inifrån Stratsys som en koppling till källsystemets namn. Detta sätts upp av er Stratsys-konsult och ska i normalfallet aldrig behöva ändras.

    Secrets: Denna Secret ska fyllas i 2c8 Modeling Tool. Den genereras på följande sätt:

    • Klicka på Secrets under Configuration
    • Fyll i något i Description-fältet (t.ex. Secret)
    • Klicka på Save

    Nu visas Client Secret, kopiera med Kopiera-ikonen och lägg in i 2c8 Modeling Tool. Denna secret visas bara en gång, så missas det att kopiera den så behöver man upprepa stegen ovan.

    2c8 OAuth Publishing Client

    Denna klient används då 2c8 är uppsatt att använda sig av Stratsys autentisering för åtkomst till innehåll i 2c8. Detta sätts i normalfallet upp under genomförandeprojektet för en 2c8-integration och ska i normalfallet inte behöva ändras därefter.

    Client Id: Behöver meddelas 2c8 för konfiguration hos 2c8. Kopiera genom att klicka på Kopiera-ikonen och meddela 2c8-konsult.

    Redirect URIs: Behöver fyllas i för att tillåta att man navigerar till avsedd URL. Behöver i normalfallet aldrig ändras efter det är konfigurerat under projektets gång. Denna behöver ändras så att klienten pekar mot rätt server hos 2c8 (eller hos kund om det hostas av kunden själv). Stratsys behöver denna information från 2c8 för att kunna fylla i rätt information här.

    Secrets: Denna Secret ska meddelas konsult för 2c8 för konfiguration hos 2c8. Generera secret på följande sätt:

    • Klicka på Secrets under Configuration
    • Fyll i något i Description-fältet (t.ex. Secret)
    • Klicka på Save

    Nu visas Client Secret, kopiera med Kopiera-ikonen och meddela 2c8. Denna secret visas bara en gång, så missas det att kopiera den så behöver man upprepa stegen ovan.

    Stratsys Published Gadgets Client

    Denna klient används för att kunna bädda in gadgets från Stratsys på andra sajter, till exempel på en kunds intranät/SharePoint eller Teams eller motsvarande.

    Följande inställningar behöver göras vid skapande av en klient:

    Client Id: Detta ID behövs i den tillhörande HTML-koden för att veta vilken klient data ska hämtas för.

    CORS origins: Dessa behöver fyllas i för de sajter som ska tillåtas bädda in innehåll från Stratsys, både eventuella utvecklingsmiljöer, samt produktionsmiljöer.

    Tänk på att då CORS origins ska fyllas i så tillåts inte wildcards (*) eller att hostnamnet avslutas med /. Korrekt format är således till exempel: https://host.customername.se

    Stratsys Reports Client 

    Denna klient används för konfiguration av webbpublicerade rapporter som aktiveras från Stratsys. Med denna klient konfigurerad så kan rapporter från Stratsys bäddas in på andra sajter, exempelvis ett intranät eller en publik webbplats.

    Följande inställningar behöver göras vid skapande av denna typ av klient:

    Client Id: Detta ID behövs i de tillhörande HTML-taggarna för att innehållet ska kunna publiceras.

    CORS origins: Dessa behöver fyllas i för de sajter som ska tillåtas bädda in innehåll från Stratsys, både eventuella utvecklingsmiljöer, samt produktionsmiljöer.

    Tänk på att då CORS origins ska fyllas i så tillåts inte wildcards (*) eller att hostnamnet avslutas med /. Korrekt format är således till exempel: https://host.customername.se