Palautelomakkeen lähettäminen Finnan ulkopuoliseen rajapintaan

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ämän sivun liitetiedostoissa on myös yksinkertainen PHP-skripti esimerkiksi siitä, miten Finnan JSON voidaan muuttaa Microsoft Teams:n webhookille sopivaksi viestiksi. Esimerkki on kuitenkin täysin testaamaton, ja siitä puuttuu järkevät kenttien mappaukset.

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: - 'X-Autentikointiavain: salaisuus'
successCodes	array	Ei	HTTP-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
emailSubject	Lomakkeen emailSubject-asetus
fields	Lomakekenttien laajennetut tiedot: type - kentän tyyppi label - kentän label kääntämättömänä labelTranslated - kentän label käännettynä käyttäjän kielellä value - kentän arvo valueLabel - kentän arvon label kääntämättömänä (vain checkbox, radio ja select) valueLabelTranslated - kentän arvon label käännettynä käyttäjän kielellä (vain checkbox, radio ja select)
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)
recordMetadata	Tietueen metadataa (title, authors, publicationDates, formats, isbns, issns, openurl). Jos tieto puuttuu, voi kenttä olla tyhjä tai null.
recordHoldingsSummary	Tietueen perus-varastotiedot, jos saatavissa
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:

{
    "pickup": "2\/Vaski\/1\/1\/",
    "lastdate": "2022-03-08",
    "name": "Lib Rarian",
    "email": "[email protected]",
    "userCatId": "1",
    "userCatUsername": "taavi",
    "message": "testitilaus, ei toimiteta",
    "fields": {
        "pickup": {
            "type": "select",
            "label": "preferred_pickup_location",
            "labelTranslated": "Ensisijainen noutopaikka",
            "value": "2\/Vaski\/1\/1\/",
            "valueLabel": "2\/Vaski\/1\/1\/",
            "valueLabelTranslated": "Turun kaupunginkirjasto"
        },
        "lastdate": {
            "type": "date",
            "label": "Mihin menness\u00e4 aineisto tarvitaan",
            "labelTranslated": "Mihin menness\u00e4 aineisto tarvitaan",
            "value": "2022-03-08"
        },
        "name": {
            "type": "text",
            "label": "feedback_name",
            "labelTranslated": "Nimi",
            "value": "Lib Rarian"
        },
        "email": {
            "type": "email",
            "label": "feedback_email",
            "labelTranslated": "S\u00e4hk\u00f6posti",
            "value": "[email protected]"
        },
        "userCatId": {
            "type": "text",
            "label": "Asiakkaan yksil\u00f6iv\u00e4 tunniste",
            "labelTranslated": "Asiakkaan yksil\u00f6iv\u00e4 tunniste",
            "value": "taavi"
        },
        "userCatUsername": {
            "type": "text",
            "label": "Kirjastokortin tunnus",
            "labelTranslated": "Kirjastokortin tunnus",
            "value": "taavi"
        },
        "message": {
            "type": "textarea",
            "label": "feedback_message",
            "labelTranslated": "Viesti",
            "value": "testitilaus, ei toimiteta"
        }
    },
    "recordId": "Solr|vaari.2541981",
    "recordInfo": "\r\nOtsikko: The Principia\r\nTekij\u00e4: Newton, Isaac\r\nOrganisaatio: Varastokirjasto\r\nJulkaistu: 1995\r\nISBN: 978-0-87975-980-3 nidottu\r\nKirja    \r\nN\u00e4yt\u00e4 koko tietue: http:\/\/localhost\/finna2\/Record\/vaari.2541981",
    "emailSubject": "Varastokirjastotilaus (Turun kaupunginkirjasto): Solr|vaari.2541981 - The Principia",
    "internalUserId": 1,
    "viewBaseUrl": "https://www.finna.fi",
    "recordMetadata": {
        "title": "The Principia",
        "authors": [
            {
                "name": "Newton, Isaac",
                "name_alt": "",
                "date": "",
                "role": "",
                "id": null,
                "type": "Personal Name"
            },
            {
                "name": "Motte, Andrew",
                "name_alt": "",
                "date": "",
                "role": "",
                "id": null,
                "type": "Personal Name"
            }
        ],
        "publicationDates": [
            "1995"
        ],
        "formats": [
            "Book"
        ],
        "formatsRaw": [
            "0\/Book\/",
            "1\/Book\/Book\/"
        ],
        "isbns": [
            "978-0-87975-980-3 nidottu"
        ],
        "issns": [],
        "openurl": {
            "url_ver": "Z39.88-2004",
            "ctx_ver": "Z39.88-2004",
            "ctx_enc": "info:ofi\/enc:UTF-8",
            "rfr_id": "info:sid\/finna.fi:generator",
            "rft_title": "The Principia",
            "rft_date": "1995",
            "rft_val_fmt": "info:ofi\/fmt:kev:mtx:book",
            "rft_genre": "book",
            "rft_btitle": "The Principia",
            "rft_series": "Great minds series",
            "rft_au": "Newton, Isaac",
            "rft_pub": "Prometheus",
            "rft_edition": "",
            "rft_isbn": "0879759801"
        }
    },
    "recordHoldingsSummary": [
        "NRL VARASTO N1 21 027923 vaari"
    ]
}

Esimerkkikonversiot

Microsoft Teams Webhook (PHP-skripti, lähinnä aihioksi)

Content

Space Tools

Asetukset

Esimerkki

JSON-sanoman muoto

Esimerkkikonversiot