Jos palautteiden käsittelyyn käytetään Finnan ulkopuolista järjestelmää, voidaan palautteet lähettää suoraan järjestelmään. Tällöin ko. järjestelmän pitää pystyä ottamaan vastaan lomakkeen tiedot JSON-muodossa POST-pyynnöllä lähetettynä.
Tällä sivulla on kuvattu tähän lähetystapaan liittyvät asetukset ja JSON-muotoisen tietueen sisältö. Katso myös yleinen ohje sivulla Palautelomakkeen ja omien lomakkeiden muokkaus.
Asetukset
Nämä asetukset vaikuttavat vain, jos lomakkeen sendMethod on 'api'. Asetukset ovat lomakkeen asetuksissa apiSettings-kohdan alla.
Asetus | Muoto | Pakollinen | Kuvaus | Esimerkki |
---|---|---|---|---|
url | string | Kyllä | Rajapinnan osoite. Ainoastaan https-protokolla on tuettu, ja kohdejärjestelmällä pitää olla https:ää varten validi sertifikaatti. | url: 'https://jira.kansalliskirjasto.fi/omahienorajapinta' |
username | string | Ei | Käyttäjätunnus HTTP-autentikointia varten | username: 'tunnus' |
password | string | Ei | Salasana HTTP-autentikointia varten | password: 'huippusalainen' |
authMethod | string | Ei | 'basic' (oletus) tai 'digest' | authMethod: 'digest' |
headers | array | Ei | Mahdolliset HTTP-otsikkotiedot, jotka pyynnössä halutaan lähettää normaalien lisäksi | headers: |
successCodes | array | Ei | HTTP-paluukoodit, joiden perusteella voidaan päätellä, että palaute on kirjattu järjestelmään. Oletuksena kelvolliset paluukoodit ovat 200-299. | successCodes: |
Esimerkki
forms: RepositoryLibraryRequest: title: repository_library_request enabled: true useCaptcha: false sendMethod: api apiSettings: url: https://somewhere successCodes: - 200 - 204 includeBarcode: true includePatronId: true onlyForLoggedUsers: true emailSubject: "Varastokirjastotilaus (%%pickup%%): %%record_id%% - %%record%%" response: repository_library_request_response senderInfoRequired: true hideSenderInfo: true hideRecipientInfo: false help: pre: repository_library_request_info_html fields: - name: pickup type: select options: - 2/Vaski/1/1/ - 2/Vaski/5/100/ - 2/Vaski/6/110/ label: preferred_pickup_location - name: lastdate type: date label: Mihin mennessä aineisto tarvitaan minValue: now format: Y-m-d required: false - name: name type: text label: feedback_name required: true - name: email type: email label: feedback_email required: true - name: message type: textarea label: feedback_message settings: - [placeholder, repository_library_request_message] - [rows, 3]
JSON-sanoman muoto
JSON-sanoma koostuu käyttäjän ja tietueen tiedoista sekä käyttäjän täyttämistä kentistä. Vastaanottava järjestelmä vastaa sanoman tulkitsemisesta. Finnan puolella on mahdollista vaikuttaa vain lomakkeen kenttien nimiin ja sisältöön.
Kenttien kuvaukset lukuunottamatta niitä, jotka tulevat suoraan lomakkeen kentistä (fields-kohta, esim. email):
Kenttä | Kuvaus |
---|---|
emailSubject | Lomakkeen emailSubject-asetus |
internalUserId | Käyttäjän ID Finnan tietokannassa |
record | Tietueen otsikko (tietuekohtaisessa lomakkeessa) |
recordId | Tietueen ID (tietuekohtaisessa lomakkeessa). Finnan indeksin tietueissa id:n etuliitteenä on 'Solr'. |
recordInfo | Rivitetty tekstimuotoinen tietueen kuvaus (tietuekohtaisessa lomakkeessa) |
referrer | Sivu, jolta lomakkeelle tultiin (vain, jos reportReferrer: true ) |
useragent | Käyttäjän selaimen tunnistetieto (vain, jos reportUserAgent: true ) |
userCatId | Käyttäjän ID kirjastojärjestelmässä (vain, jos includePatronId: true ) |
userCatUsername | Käyttäjän kirjastokortin numero kirjastojärjestelmässä (vain, jos includeBarcode: true ) |
viewBaseUrl | Finna-näkymän osoite (näkymä, josta lomake lähetettiin) |
Esimerkkisanoma ylläolevan lomakemäärittelyn pohjalta:
{ "email": "[email protected]", "emailSubject": "Varastokirjastotilaus (Turun kaupunginkirjasto): Solr|vaari.355334 - Dewey decimal classification and relative index. Vol. 2, Schedules", "internalUserId": 1, "lastdate": "2021-12-01", "message": "Voisitteko ilmoittaa mahdollisimman pian, mik\u00e4li aineistoa ei saa noudettavaksi kuukauden sis\u00e4ll\u00e4? Kiitos!", "name": "Taavi Testaaja", "pickup": "Turun kaupunginkirjasto", "record": "Dewey decimal classification and relative index. Vol. 2, Schedules", "recordId": "Solr|vaari.355334", "recordInfo": "\r\nOtsikko: Dewey decimal classification and relative index. Vol. 2, Schedules\r\nTekij\u00e4: Dewey, Melvil\r\nOrganisaatio: Varastokirjasto\r\nJulkaistu: 1971\r\nISBN: 0-910608-11-3\r\nKirja \r\nN\u00e4yt\u00e4 koko tietue: https://www.finna.fi/Record/vaari.355334", "userCatId": "123", "userCatUsername": "taavi", "viewBaseUrl": "https://www.finna.fi" }