Visma Nova Webservice Versio 1.1 / 31.10.2018
pidättää itsellään oikeuden mahdollisiin parannuksiin ja/tai muutoksiin tässä oppaassa ja/tai ohjelmassa ilman eri ilmoitusta. Oppaan ja siihen liittyvän muun materiaalin kopiointi on kielletty ilman :n kirjallista lupaa. Microsoft, MS, SQL Server, Microsoft Word ja Windows ovat Microsoft Corporationin rekisteröityjä tavaramerkkejä., 2017
Sisällysluettelo 1 Johdanto...2 1.1 Nova WebService ja Nova ympäristön kuvaus... 2 1.2 Yleistä integraatio projektista... 3 2 Yleiset vaatimukset...4 3 Toimenpiteet ennen asennusta...4 3.1 Nova WS rajapinnan käyttäminen... 7 3.2 Testi Boomerang:lla... 9 3.2.1 Execute... 9 3.2.2 Execute2... 10 sivu 1
1 Johdanto Tämä dokumentti sisältää Visma Nova Webservicen asennusohjeen ja käyttöohjeen. XML -sanomakuvaukset löytyvät erillisestä dokumentista. Tukisähköposti: novasdksupport@visma.com 1.1 Nova WebService ja Nova ympäristön kuvaus Nova webservice asennetaan Nova asiakkaan ympäristöön Windows palvelimelle, jossa on IIS (Internet Information Services) palvelut asennettuna ja tältä palvelimelta tulee olla yhteys Novan tietokantapalvelimelle (SQL server). Webservicen asennuksen aikana muodostetaan yksilöllinen avain, jonka avulla 3. osapuoli ottaa yhteyden haluttuun asiakkaan Novan yritystietokantaan. Asiakas myöskin kertoo 3. Osapuolelle, mistä osoitteesta webservice vastaa (esimerkiksi: https://asiakkaandomain.fi/novawebservice/novawebsdk.asmx?). Webservicen käytetään välittämällä xml sanoma execute metodin avulla ja webservice palauttaa paluuviestin xml muodossa. 3. Osapuolen tehtäväksi jää sovelluksen toteuttaminen, joka sitten käyttää Visma Nova webservice rajapintaa. HUOM! Asiakas on vastuussa IIS asetuksista. sivu 2
1.2 Yleistä integraatio projektista Kaikki ohjelmien integraatioprojektit lähtevät liikkeelle määrittelystä, jossa integraation toteutuksen tilaaja ja integraation toteuttaja yhdessä määrittelevät toteutettavan integraation sisällön toiminnallisuuksineen sekä rajauksineen ja varmistuvat siitä, että tarjolla olevat rajapinnat integraation toteutukseen mahdollistavat halutunlaisen integraation toteutuksen. Määrittely kannattaa aina tehdä kirjallisesti. Integraation toteutusvaiheen testausta varten on hyvä olla mahdollisimman hyvin tuotantoympäristöä vastaava testiympäristö, jolloin pystytään jo toteutusvaiheessa testaamaan mahdollisimman hyvin erilaiset käyttötapavariaatiot. Tuotantoympäristössä integraatio otetaan käyttöön vasta, kun kaikki erilaiset määritetyt käyttötapavariaatiot on testattu ja todettu toimivaksi suunnitellusti tuotantoympäristöä vastaavassa testiympäristössä. Määrittelyvaiheeseen osallistumisesta voidaan tarvittaessa pyytää tarjous myös Visma Software Oy:ltä oman vastuumyyjän kautta. sivu 3
2 Yleiset vaatimukset 1. Windows palvelin: Windows Server 2008 R2-2016 2..Net 4.5 full 3. IIS asennettuna palvelimelle 4. Palvelimella julkinen IP 5. Palomuuri avaukset sovittava integraattorin ja asiakkaan välillä. Webservice käyttää porttia 80 (http) tai 443 (https). Suosittelemme käyttämään HTTPS protokollaa 6. Admin tasoinen asennustunnus 3 Toimenpiteet ennen asennusta Novasta pitää olla asennettu viimeisin versio. IIS pitää olla valmiiksi asennettuna ympäristössä ennen webservicen asennusta. IIS:ssä pitää olla oletusten lisäksi valittuna myös - Application Development o.net Extensibility 3.5 o.net Extensibility 4.5: o ASP.NET 3.5 HTTP Activation o ASP.NET 4.5 WCF Services HTTP Activation - Management Tools o IIS Management Scripts and Tools sivu 4
sivu 5
- ISAPI and CGI restrictions: pitää olla sallittu asp.net 4.0 versiolle HUOM! Huolehdi, että sinulla on riittävät oikeudet asennuksen suorittamiseen, koska suurin osa asennuksen aikana tapahtuvista virheistä johtuu yleensä puutteellisista käyttäjäoikeuksista. sivu 6
3.1 Nova WS rajapinnan käyttäminen Visma Nova Webservice on SOAP-mallin mukainen ja sisältää seuraavat webmetodit: Execute Execute2 ExecuteEx HelloWorld SDKVersion WebServiceVersion Pääasiallinen metodi, jonka avulla XML sanomat lähetetään webservicelle. Palauttaa XML sanoman. Tämä ottaa sisään string. Muuten sama kuin Execute metodi. Ero on siinä, että se ottaa sisään XML:n Ei käytössä Testi metodi Palauttaa Webservicen käytttämän NovaSDK:n versionumeron Palauttaa Webservicen versionumeron Execute -metodin avulla lähetetään webservicelle XML sanoma, joka koostuu kahdesta osasta: Login osa ja metodi osa. Logon osassa kerrotaan aina mitä yhteyttä halutaan käyttää. Login osiossa vaadittavat avaimen saat Webservicen asennuksen tehneeltä osapuolelta. Esimerkissä <Login> tagien sisällä <hash> elementti kertoo avaimen, jota käyttää. <?xml version="1.0" encoding="utf-8"?> <xml> <login> <hash dsn="nova">73685dbea3290215b74a3a2e9c1c3ecc</hash> </login> <ReadArticle> <ArticleCode>tuote1</ArticleCode> </ReadArticle> </xml> Varsinainen toiminto jota halutaan execute -metodin avulla tehdä on edellä mainitussa esimerkissä: <ReadArticle> <ArticleCode>tuote1</ArticleCode> </ReadArticle> Execute metodi palauttaa paluuviestinä xml sanoman. Esimerkkejä näistä toiminnoista sekä niiden kuvaukset löytyvät erillisestä dokumentista. Tässä esimerkki vb.net kielellä, jossa muodostetaan tilaus Novan webservicen avulla: Dim xmltext As String = "<?xml version=""1.0"" encoding=""utf-8""?> <xml> <login> <hash dsn=""nova"">73685dbea3290215b74a3a2e9c1c3ecc</hash> sivu 7
</login> <SalesOrder task=""insert""> <Number></Number> <CustomerNumber>99</CustomerNumber> <DeliveryNumber>100</DeliveryNumber> <DeliveryName>Toimitusasiakas</DeliveryName> <TermsOfPaymentId>1</TermsOfPaymentId> <OrderType>0</OrderType> <Rows> <Row> <Position>1</Position> <ArticleCode>akra</ArticleCode> <Amount>1</Amount> </Row> <Row> <Position>2</Position> <ArticleCode>mivv</ArticleCode> <Amount>2</Amount> </Row> <Row> <Position>3</Position> <ArticleCode>KOKO</ArticleCode> <Warehouse>2</Warehouse> <Amount>7</Amount> </Row> </Rows> </SalesOrder> </xml>" 'Huom! Olen lisännyt projektille servicereferensen, joka viittaa Novan Webserviceen. Dim client As ServiceReference1.NovaWebSDKSoapClient = New ServiceReference1.NovaWebSDKSoapClient Dim xmlresponse As XElement = New XElement("Empty") Dim xmlrequest As XElement = XElement.Parse(xmltext) Try xmlresponse = client.execute(xmlrequest.tostring) MsgBox(xmlResponse.ToString) Catch ex As Exception MsgBox(ex.Message) End Try Lisäksi asennuspaketista löytyy Sample -kansiosta esimerkki ohjelma. sivu 8
3.2 Testi Boomerang:lla Alla pari esimerkkiä miten webservistä voi testata Bomerangilla (plugin Chromeen) 3.2.1 Execute tai sivu 9
3.2.2 Execute2 Response HUOM! Muista prefixit. Esimerkki seuraavalla sivulla. sivu 10
Esimerkki: <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:nov="http://novawebservice.visma.com/" > <soap:header/> <soap:body> <nov:execute2> <nov:inputxml> <xml> <login> <hash dsn="nova">73685dbea3290215b74a3a2e9c1c3ecc</hash> </login> <FetchArticlesLike> <ChangedAfter>01-06-2018</ChangedAfter> </FetchArticlesLike> </xml> </nov:inputxml> </nov:execute2> </soap:body> </soap:envelope> sivu 11