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.

AsetusMuotoPakollinenKuvausEsimerkki
urlstringKylläRajapinnan osoite. Ainoastaan https-protokolla on tuettu, ja kohdejärjestelmällä pitää olla https:ää varten validi sertifikaatti.
url: 'https://jira.kansalliskirjasto.fi/omahienorajapinta'
usernamestringEiKäyttäjätunnus HTTP-autentikointia varten
username: 'tunnus'
passwordstringEiSalasana HTTP-autentikointia varten
password: 'huippusalainen'
authMethodstringEi'basic' (oletus) tai 'digest'
authMethod: 'digest'
headersarrayEiMahdolliset HTTP-otsikkotiedot, jotka pyynnössä halutaan lähettää normaalien lisäksi
headers:
  - 'X-Autentikointiavain: salaisuus'
successCodesarrayEiHTTP-paluukoodit, joiden perusteella voidaan päätellä, että palaute on kirjattu järjestelmään. Oletuksena kelvolliset paluukoodit ovat 200-299.
successCodes:
  - '200'
  - '204'

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
emailSubjectLomakkeen emailSubject-asetus
internalUserIdKäyttäjän ID Finnan tietokannassa
recordTietueen otsikko (tietuekohtaisessa lomakkeessa)
recordIdTietueen ID (tietuekohtaisessa lomakkeessa). Finnan indeksin tietueissa id:n etuliitteenä on 'Solr'.
recordInfoRivitetty tekstimuotoinen tietueen kuvaus (tietuekohtaisessa lomakkeessa)
recordMetadataTietueen metadataa (title, authors, publicationDates, formats, isbns, issns, openurl). Jos tieto puuttuu, voi kenttä olla tyhjä tai null.
referrerSivu, jolta lomakkeelle tultiin (vain, jos reportReferrer: true)
useragentKäyttäjän selaimen tunnistetieto (vain, jos reportUserAgent: true)
userCatIdKäyttäjän ID kirjastojärjestelmässä (vain, jos includePatronId: true)
userCatUsernameKäyttäjän kirjastokortin numero kirjastojärjestelmässä (vain, jos includeBarcode: true)
viewBaseUrlFinna-näkymän osoite (näkymä, josta lomake lähetettiin)

Esimerkkisanoma ylläolevan lomakemäärittelyn pohjalta:

{
  "email": "taavi.testaaja@helsinki.fi", 
  "emailSubject": "Varastokirjastotilaus (Turun kaupunginkirjasto): Solr|vaari.355334 - Dewey decimal classification and relative index. Vol. 2, Schedules", 
  "internalUserId": 7, 
  "lastdate": "", 
  "message": "", 
  "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: http://localhost:8080/finna2/Record/vaari.355334", 
  "recordMetadata": {
    "authors": [
      {
        "date": "", 
        "id": null, 
        "name": "Dewey, Melvil", 
        "name_alt": "", 
        "role": "", 
        "type": "Personal Name"
      }
    ], 
    "formats": [
      "Kirja"
    ], 
    "isbns": [
      "0-910608-11-3"
    ], 
    "issns": [], 
    "openurl": {
      "ctx_enc": "info:ofi/enc:UTF-8", 
      "ctx_ver": "Z39.88-2004", 
      "rfr_id": "info:sid/finna.fi:generator", 
      "rft_au": "Dewey, Melvil", 
      "rft_btitle": "Dewey decimal classification and relative index. Vol. 2, Schedules", 
      "rft_date": "1971", 
      "rft_edition": "18. ed", 
      "rft_genre": "book", 
      "rft_isbn": "0910608113", 
      "rft_pub": "Forest Press", 
      "rft_title": "Dewey decimal classification and relative index. Vol. 2, Schedules", 
      "rft_val_fmt": "info:ofi/fmt:kev:mtx:book", 
      "url_ver": "Z39.88-2004"
    }, 
    "title": "Dewey decimal classification and relative index. Vol. 2, Schedules",
    "publicationDates": [
      "1971"
    ] 
  }, 
  "userCatId": "123", 
  "userCatUsername": "taavi", 
  "viewBaseUrl": "https://www.finna.fi"

  • No labels