Page History
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.
...
Rajapinnan osoite. Ainoastaan https-protokolla on tuettu, ja kohdejärjestelmällä pitää olla https:ää varten validi sertifikaatti.
Osoitteeksi voi laittaa myös pelkän "test", jolloin kutsun sisältö tulostetaan vain näytölle testaamista varten.
...
url: "https://jira.kansalliskirjasto.fi/omahienorajapinta"...
username: "tunnus"...
password: "huippusalainen"...
authMethod: "digest"...
headers:
- "X-Autentikointiavain: salaisuus"
...
successCodes:
- "200"
- "204"
Esimerkki
| Code Block |
|---|
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):
...
Esimerkkisanoma ylläolevan lomakemäärittelyn pohjalta:
| Code Block |
|---|
{
"email": "[email protected]",
"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": [
"Book"
],
"formatsRaw": [
"0/Book/",
"1/Book/Book/"
],
"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"
]
},
"recordHoldingsSummary": [
"NRL VARASTO CD 20 002712 vaari"
],
"userCatId": "123",
"userCatUsername": "taavi",
"viewBaseUrl": "https://www.finna.fi"
|
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: |
| 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
| Code Block |
|---|
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.
...
| Code Block |
|---|
{
"email": "[email protected]",
"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"
]
},
"recordHoldingsSummary": [
"NRL VARASTO CD 20 002712 vaari" ],
"userCatId": "123",
"userCatUsername": "taavi",
"viewBaseUrl": "https://www.finna.fi"
|
Esimerkkikonversiot
- Microsoft Teams (PHP-skripti, lähinnä aihioksi)
