Unifaun Online integrasjon

Oppsett og konfigurasjon av Unifaun Online integrasjon med BxLogistics Pro

I denne manualen tar vi for det meste opp hvordan integrasjonen fungerer mot Visma Business, dog vil mye av de samme prinsippene fortsatt gjelde for andre ERP systemer. Typiske sky ERP slik som Visma.net har fordelen med at man kan hoppe over et par ekstra steg da man slipper legge opp ekstra databasekoblinger og SQL spørringer mot forskjellige databaser i BxAdmin, da både ERP og Unifaun benytter samme database for grunndata - BxEngine. 

21.07.2021: Dokumentasjonen er fortsatt under arbeid, vil bli oppdatert og endret fortløpende med mer informasjon etterhvert.  

1. Forberedelser

Printere

Sørg for at etikettprinter og eventuell A4 printer som står for Unifaun utskrifter er installert på server tilgjengelig for BxEngine tjenesten (med andre ord, printkø på samme server som BxEngine). 
Dersom det ikke er mulig å installere printkø på BxEngine serveren (pga. begrensninger i nettet eller hos ASP) kan man installere BxSmartPrintPro som en printproxy på f.eks. en lager-PC eller lokal server hvor det er lettere å få installert etikettprintere. 
Vi anbefaler å installere printkø lokalt på Bx server/PC, fremfor delt fra printserver etc., da det både er mer stabilt og utskrifter går raskere. 
Det vi mener med lokal printkø er at printkøen ligger under Control Panel -> Devices and Printers -> og heter noe som "Printer" fremfor "Printer on servername" eller "\\servername\Printer". Bør se ca. slik ut: 

Velger dere likevel å bruke en printer delt fra printserver eller lignende er det veldig viktig at printeren er tilgjengelig for BxEngine og/eller BxSmartPrintPro tjenestene våre. Local System som er standard servicebruker på disse to tjenestene har i de fleste tilfellene ikke tilgang til delte nettverksprintere.
I vårt oppsett i BxAdmin må også printernavnet legges inn med UNC stien, som f.eks. "\\servername\Printername". 

Printere som inneholder (Redirected) vil ikke fungere da dette er printere som er med over via en RDP eller Citrix sesjon, så fort sesjonen lukkes forsvinner også printkøen. 

Unifaun

Alt oppsett i Unifaun vedr. transportavtaler, fraktselskaper etc. i seg selv må også være ferdig satt opp, vi regner med at dere eller Unifaun sørger for at dette er i orden. BxSoftware tar ikke på seg ansvaret for å sette opp dette. 
For å integrere mot Unifaun Online krever det også at dere har pålogging til Unifaun Online https://www.unifaunonline.com/

ERP system

Alle leveringsmetoder må være lagt opp i ERP systemet. Det må legges opp én metode pr. leveringsprodukt i Unifaun dere ønsker å benytte fra håndterminalene. For å ta noen eksempler:
Bring Ekspress neste dag, Bring Pakke til bedrift, Bring Stykkgods til bedrift, Bring Pakke levert hjem, Bring Pakke til hentested, Schenker Stykkgods osv., alle disse må ha én leveringsmetode pr. produkt i ERPet. Vi anbefaler også å legge opp et "Henter selv" valg eller tilsvarende som kan benyttes for å sende ordren uten at det bestilles frakt via Unifaun.
Eksempel på hvordan leveringsmetoder legges opp under. 

Visma.net: Leveringsmetoder Visma.net
Visma Business: Link kommer
Visma Global: Link kommer
Uni Micro: Link kommer
Andre ERP: Link kommer

2. Unifaun

For å integrere mot Unifaun Online krever det at dere har pålogging til Unifaun Online https://www.unifaunonline.com/

  1. Logg inn på https://www.unifaunonline.com/ og åpne Maintenance -> API keys
  2. Trykk Search. Da får du opp et søkeresultat over forskjellige Ider/nøkler opprettet tidligere dersom det er opprettet API nøkkel før. Trykk deretter View for å se hele API nøkkelen som skal hentes ut og legges inn i oppsettet vårt. Det er den kombinerte IDen som skal kopieres ut. Sørg for/pass på at API nøkkelen er for Web Services (REST) APIet da vi har basert integrasjonen vår på REST APIet til Unifaun. Gå til punkt 3 dersom dere ikke har nøkkel fra før for å opprette en. Gå videre til BxAdmin delen av dokumentasjonen når API nøkkel er hentet ut.

  3. Om dere ikke har API nøkkel fra før eller ønsker å ha en separat nøkkel for BxSoftware, opprett en ny med "New API key". Pass på at status er Enabled, type er Web Services (REST) og at Developer-Id fylles ut - dette skal være bruker ID man logger inn med i Unifaun. Trykk deretter Save. Da skal du ha fått en API nøkkel du kan hente ut på samme måte som forklart i punkt 1 og 2 lenger opp.



3. BxAdmin

Installation

Under Installation i BxAdmin må man legge opp en ekstra Database connection, dette skal være BxEngine databasen da det er BxEngine databasen vi laster ned data til fra Unifaun. Dersom det settes opp mot Visma.net eller andre skybaserte ERPer trenger man ikke gjøre noe med dette da BxEngine mest sannsynlig eksisterer fra før. 

Imports from ERP

  1. Opprett ny importer for Unifaun under Imports from ERP. Import type = unifaun, Module = deliverymethods, Enabled = Ja.
  2. I Field mapping trykker du Add missing defaults for å legge til alle import parameterne.
  3. I Import config trykker du Add missing defaults for å legge til konfigurasjons parameterne.
    1. Her passer du også på å legge inn korrekt verdi i dbconnection, som i dette tilfellet er 2 - fra punkt 1. Installation, BxEngine er da den andre database tilkoblingen som er lagt opp etter Visma Business. Dersom det settes opp mot Visma.net eller andre sky ERP holder det i de aller fleste tilfellene å la det være dbconnection 1 (standard). 
    2. I serverkey legger du inn API nøkkelen hentet fra Unifaun.

Export to ERP

  1. Vi skal også legge opp en exporter for Unifaun under Export to ERP. Export type = unifaun, Module = unifaun, Action = create, Enabled = Ja
  2. I Field mapping trykker du Add missing defaults for å legge til alle export parameterne.


Configuration

  1. I Configuration -> Client profile -> Velg korrekt profil: Aktiver disse parameterne under Area: consignor 
    1. enabled = true
    2. serverkey = API nøkkel fra Unifaun
    3. shipmentlabelprinter = Navn på printkøen slik den ligger tilgjengelig for BxEngine
    4. unifaun = true
    5. url = https://api.unifaun.com/rs-extapi/v1/shipments?returnFile=true


  2. Under Area: pickinglist, aktiver disse parameterne
    1. deliverymethod = true
    2. shipment = true

Data

Åpne Data i BxAdmin og trykk Run Import for å laste ned leveringsmetodene fra Unifaun. Vent et par minutter før du prøver en refresh da det innimellom kan ta litt tid å hente ned alle. Når de er ferdig lastet ned burde listen se slik ut. 


Knytning mot leveringsmetoden gjøres ved å fylle "DeliveryMethod" kolonnen med verdien for leveringsmetoden i ERP systemet. I dette tilfellet mot Visma Business blir det da txtno fra txt tabellen hvor txttp = 5. Her har jeg lagt opp fire forskjellige Bring valg. 

Neste og siste oppsett-steg er å legge opp SQL spørringen korrekt slik at vi får knyttet sammen vår Data tabell og ERP systemets data. 

SQL Integration

Spørringen for leveringsmetoder ligger under SQL Integration -> Picking -> Delivery Methods, den bør se ca. slik ut for å få ut standard funksjonalitet. Her kan dere legge på flere where filtre etc. for å få frem språk og/eller kun de leveringsmetodene dere ønsker å få frem. Legg merke til at spørringen hovedsaklig går mot Visma Business databasen, hvor BxEngine er left joinet i spørringen. Legg også merke til at vi har gjort om 5 til 0 da det i våre data er et "Henter selv" valg, alle som konvertes til en 0 vil ikke bli sendt til Unifaun. Externalserviceid benyttes for å legge opp ekstra servicer som epost/sms varsler etc. - dette tar vi for oss senere i et eget punkt under 4. Ekstra oppsett.

Sjekk også Package Types spørringen og pass på at det er BxEngine databasen som er database knytningen her da denne spørringen er eksklusivt for BxEngine databasen. Pacakge Types benyttes for å sende med pakketype verdien, ikke alltid dette blir aktivert i oppsettet, beskrivelse på hva dette benyttes til blir lagt opp i et punkt under 4. Ekstra oppsett.


Da skal alt nødvendig grunnoppsett være ferdig satt opp for å få Unifaun integrasjonen til å fungere. Når alle punkter over er gjennomført trenger man kun å hente innstillinger og data til terminalene for å få frem oppsettet på terminalene. 
1. Hente innstillinger
2. Motta data

4. Ekstra oppsett

Pakkeinnhold

Ved noen tilfeller for spesifikke fraktleverandører kreves det at vi sender med ekstra informasjon som innhold i pakken på selve utskriften. I de aller fleste tilfellene holder det å sende med en statisk verdi på alle sendinger som forklarer innholdet i pakkene, f.eks. "Reservedeler bil".  Dersom dette er forskjellig fra gang til gang kan man hente ut nødvendig informasjon fra ERPet i SQL Integration -> Picking -> Pickinglist, gi det nye feltet/kolonnen i spørringen et fornuftig navn, f.eks. delcontents, deretter kopierer du koden fra kodefeltet under og limer inn (CTRL+V) i Export to ERP -> unifaun -> under Field mapping.
Dersom det holder med en fast verdi på hver pakke som sendes kan man kopiere ut koden fra Field mapping -> fast verdi

Field mapping -> variabel verdi

[{"export":11,"sourcefield":"delcontents","destination":"shipment.goodsDescription","static":"","ignorezero":false,"maxlength":null,"forceset":false,"ignorefailure":false,"enabled":true,"isprimarykey":false,"importoneline":false,"isforeignkeyto":"","sequence":null,"destinationrow":"","paddingcharacter":null,"readonly":false,"required":"","returnmapping":false,"destinationtype":"","comment":null,"id":124},{"export":11,"sourcefield":"delcontents","destination":"shipment.parcels[].contents","static":"","ignorezero":false,"maxlength":null,"forceset":false,"ignorefailure":false,"enabled":true,"isprimarykey":false,"importoneline":false,"isforeignkeyto":"","sequence":null,"destinationrow":"","paddingcharacter":null,"readonly":false,"required":"","returnmapping":false,"destinationtype":"","comment":null,"id":125}]

Da bør det se ca. slik ut

Field mapping -> fast verdi

[{"export":11,"sourcefield":"","destination":"shipment.goodsDescription","static":"eksempeltekst fast verdi","ignorezero":false,"maxlength":null,"forceset":false,"ignorefailure":false,"enabled":true,"isprimarykey":false,"importoneline":false,"isforeignkeyto":"","sequence":null,"destinationrow":"","paddingcharacter":null,"readonly":false,"required":"","returnmapping":false,"destinationtype":"","comment":null,"id":124},{"export":11,"sourcefield":"","destination":"shipment.parcels[].contents","static":"eksempeltekst fast verdi","ignorezero":false,"maxlength":null,"forceset":false,"ignorefailure":false,"enabled":true,"isprimarykey":false,"importoneline":false,"isforeignkeyto":"","sequence":null,"destinationrow":"","paddingcharacter":null,"readonly":false,"required":"","returnmapping":false,"destinationtype":"","comment":null,"id":125}]

Da bør det se ca. slik ut

Ekstra servicer

Denne vil bli oppdatert etterhvert - kun midlertidig informasjon under. 

Additional services og addons/Unifaun options
Unifaun options = cfg_shipmentoptions - Bruk Inf1 i Data - Eks mot DB Schenker:
[{"id": "ENOT", "from": "avsenderepost@mail.com", "to": "#delmail#"}] - 

Additional services = externalserviceid - Bruk Services i Data - Eks mot DB Schenker: 
[{"id": "NOT", "text4": "#delmail#"}]