api – Polska Bibliografia Naukowa

Czy identyfikacja osób w publikacji przesyłanej przez API odbywa się tylko przy pomocy objectId tej osoby? Jak pozyskać ten identyfikator?

Przy przesyłaniu publikacji do systemu PBN przez API identyfikacja osób nie odbywa się wyłącznie według identyfikatora (objectId) tej osoby. Jeśli nie jest nam znany objectId osoby to przy przesyłaniu publikacji można podać orcidId lub naturalId (hash numeru PESEL lub hash numeru dokumentu, zawierający kod kraju+numer tego dokumentu) w tej publikacji (szerzej zostało to opisane w dokumencie opisującym walidacje w nadsyłanych publikacjach – kliknij tutaj).

Jeśli chcemy użyć objectId osoby w celu przesłania publikacji, do pozyskania tego identyfikatora możemy wykorzystać końcówkę /v1/person/natural/{id} umożliwiającą pobranie metadanych osoby na podstawie jej naturalnego identyfikatora (jest to hash numeru PESEL lub hash numeru dokumentu, zawierający kod kraju+nr tego dokumentu, funkcja hashująca SHA-512).

Jak uzyskać UUID z systemu POL-on dla pracownika przy pomocy API PBN?

UUID pracownika jest to unikatowy identyfikator uniwersalny pracownika w systemie POL-on 2.0. Kliknij tutaj, aby dowiedzieć się jak pobrać UUID pracownika w POL-on.

W API systemu PBN UUID z systemu POL-on jest zwracany w końcówce /v1/person/institution/{id}.

Przykładowa odpowiedź na powyższe żądanie:

[
  {
    "firstName": "string",
    "institutionId": "string",
    "institutionName": "string",
    "lastName": "string",
    "orcid": "string",
    "personId": "string",
    "polonUuid": "string",
    "title": "string"
  }
]

Jaki identyfikator podawać w przypadku doktorantów afiliujących pracę do instytucji?

Podawanie identyfikatora dla doktorantów wygląda analogicznie jak w przypadku pracowników (personId, orcidId albo naturalId).

Chciałbym użyć numeru ORCID w celu identyfikacji osoby w trakcie wysyłania publikacji przez API. W jaki sposób PBN pozyskuje numery ORCID?

Aby było możliwe zidentyfikowanie osoby przy pomocy ORCID, osoba musi mieć powiązane konto PBN z POL-on i ORCID. Należy jednak mieć na uwadze, że wersja testowa systemu PBN Alpha jest kopią bazy produkcyjnej sprzed paru miesięcy i jeśli ktoś w tym czasie powiązał swoje konto produkcyjne PBN z ORCID to nie będzie to widoczne na PBN Alpha.

Jeżeli osoba nie powiązała konta PBN z ORCID oraz POL-on, a jest pracownikiem to dodając publikację należy podać jej naturalId lub personId (objectId), Jeśli taka osoba nie jest pracownikiem wystarczy podawać jej imię i nazwisko.

Do czego używany jest adres zwrotny widoczny w liście tokenów aplikacji?

Jest to adres zwrotny utworzony podczas rejestracji aplikacji dla instytucji. Konieczny do uzyskania jednorazowego kodu (One Time Token), niezbędnego w kolejnym kroku do pozyskania właściwego tokenu uwierzytelniającego (tokenu użytkownika).

W jaki sposób odbywa się edycja publikacji przez API?

Edycja publikacji przy pomocy API odbywa się przede wszystkim w Profilu Instytucji. Identyfikacja publikacji w przypadku aktualizacji (edycji) odbywa się za pomocą objectId (id publikacji z bazy mongo) i DOI (jeśli DOI nie było pierwotne podane to może być null lub bez DOI) lub tylko DOI.

Edycja publikacji w PBN ma dwojaki charakter – wyróżniamy edycję danych podstawowych (metadanych publikacji) – takich jak tytuł, język, rok wydania itp. oraz edycję linków (czyli powiązań pomiędzy obiektami – w przypadku publikacji linkami są: czasopismo w przypadku artykułu, osoba w publikacji, wydawnictwo w książce, afiliacje itp.).

Edycja publikacji w PBN przy pomocy API, zarówno w Profilu Instytucji, jak i w repozytorium polega na modyfikacji wszystkich danych (metadanych oraz linków). W celu sprawdzenia poprawności danych w publikacjach, które mają być przekazane do ewaluacji należy zweryfikować je przede wszystkim w Profilu Instytucji.

Czy w trakcie wysyłania publikacji przez API należy dodać oświadczenie, o którym mowa w art. 265 ust. 13 Ustawy Prawo o szkolnictwie wyższym i nauce?

Tak, wysyłając publikacje za pomocą API konieczne jest podanie oświadczenia dla przynajmniej jednej osoby. Przesyłanie publikacji za pomocą API opiera się na dodawaniu publikacji do Profilu Instytucji, którego podstawą są oświadczenia (Profil Instytucji jako ekwiwalent techniczny dla oświadczenia o którym mowa w art. 265 ust. 13 Ustawy Prawo o Szkolnictwie Wyższym i Nauce).

Dodając publikacje za pomocą API trafiają one przede wszystkim do Profilu Instytucji, stąd konieczność wskazania oświadczeń. Dodawanie publikacji do ogólnodostępnego repozytorium jest kwestią wtórną (każda publikacja w Profilu Instytucji powinna mieć swój link do publikacji w repozytorium – dzięki temu dla innych użytkowników istnieje możliwość edytowania rekordu w repozytorium ręcznie; oczywiście taka edycja w repozytorium nie wpływa na stan publikacji w Państwa Profilu Instytucji).

Wyjątkami – jeśli chodzi o dodawanie publikacji za pomocą API – jest typ proceedings, czyli tom pokonferencyjny oraz książka pod redakcją (edited book)

Tom pokonferencyjny nie bierze udziału w ewaluacji (powstał w PBN jako byt czysto techniczny w celu sprawozdania materiałów konferencyjnych), dlatego nie ma możliwości dodania do niego oświadczenia.

Książkę pod redakcją można dodać opcjonalnie bez oświadczenia, ponieważ nie zawsze w instytucji wstępuje oświadczenie dla redakcji naukowej (a jednocześnie może istnieć oświadczenie dla autorstwa rozdziału z takiej książki – wówczas książka nie powinna znaleźć się w Profilu Instytucji, ale rozdział już tak).

Co oznaczają pola verified i verificationLevel we wszystkich rekordach?

W systemie każdy obiekt (a także link, czyli połączenie między obiektami) może zostać zweryfikowany (potwierdzony), określonym poziomem weryfikacji. Obecnie mamy 3 poziomy weryfikacji: NONE, USER, MODERATOR. NONE oznacza brak weryfikacji, USER wykorzystywany jest tylko do linków (dotyczy osób, a te nie podlegają edycji). Z kolei obiekty weryfikowane są z poziomem MODERATOR – wtedy, gdy osoba z rolą WORK_IMPORTER:
– doda obiekt, albo
– zmieni metadane obiektu, albo
– w przypadku publikacji – doda lub zmieni jakikolwiek link powiązany do tej publikacji, albo
– potwierdzi obiekt specjalnym przyciskiem „Potwierdź” na stronie szczegółów tego obiektu.

Pola verified i verificationLevel określają czy i na jakim poziomie obiekt został zweryfikowany.

Więcej informacji na ten temat znajduje się na stronach pomocy PBN:

Weryfikacja publikacji przez Importera Publikacji

Weryfikacja obiektów i linków w repozytorium PBN

Co z publikacjami (np. książkami), które nie mają DOI? Podobnie jest z rozdziałami z książek, często jest DOI książki, ale nie ma DOI rozdziału, jak wówczas je dodawać za pomocą API?

W przypadku książek wymagane jest wprowadzenie DOI albo linku do pełnego tekstu lub do strony z informacjami o publikacji (można zaraportować oba pola). Dlatego walidator pozwala na zapisanie do bazy książek bez DOI (wówczas musi być URL). W przypadku rozdziałów nie jest wymagane podawanie DOI/URL.

Opis walidacji został zamieszczony w sekcji Masowe Interfejsy Wymiany Danych w części poświęconej publikacjom (POST
/v1/publications): https://pbn.nauka.gov.pl/centrum-pomocy/baza-wiedzy/publikacje/.

Czy po pierwszym transferze rekordy publikacji mogą być aktualizowane? W jaki sposób są identyfikowane?

Tak, publikacje można edytować/aktualizować. Identyfikacja publikacji w przypadku aktualizacji publikacji odbywa się za pomocą objectId (id publikacji z mongo) i DOI (jeśli DOI nie było pierwotne podane to może być null lub bez doi) lub tylko DOI.

W jaki sposób identyfikować publikacje w fazie wstępnego dopasowania tego co jest obecnie w PBN, z tym co jest w naszym systemie?

Identyfikowanie publikacji w PBN 2.0 przez API zaczyna się od pola objectId. Jeśli go nie ma, identyfikacja następuje po DOI wraz z typem publikacji.

Czy należy wprowadzać/poprawiać dane przez interfejs aplikacji (GUI) jeśli planuje integracje przez API?

Jeśli możecie Państwo poczekać, to docelowo będzie można nanosić zmiany poprzez API. Jeśli zależy Państwu na poprawności danych już teraz, to pozostaje praca przez GUI.

Czy upoważnienia (oświadczenia) autorów do wykazania publikacji w dorobku jednostki będzie można importować do PBN razem z informacjami o publikacjach przez API?

Publikacje za pomocą API dodawane są do Profilu Instytucji (oraz jeśli publikacji nie ma w repozytorium to również do repozytorium), a Profil Instytucji jest technicznym ekwiwalentem oświadczenia, co oznacza, że publikację będzie można dodać tylko wtedy gdy wskazane będzie w niej oświadczenie autora. Innymi słowy dodawanie publikacji za pomocą API będzie możliwe tylko gdy publikacja będzie posiadała oświadczenie (informację oświadczeniu należy przesłać w importowanej publikacji).

Czy import prac do nowego PBN będzie możliwy tylko za pomocą API? Czy będzie jeszcze opcja „ręcznego” zrzutu publikacji (xml) dla instytucji, które do tej pory pracowały w ten sposób?

Import będzie się odbywał w pełni poprzez interfejsy programistyczne.

Tradycyjny import XML w nowym API nie będzie obsługiwany z racji zmiany podejścia do sposobu przetrzymywania metadanych.