Dokumentacja Integracyjna SMPL
25.0.0 - STU1 Poland flag

Obsługa załączników

W systemie SMPL, w niektórych zasobach możliwe jest zapisanie załączników.

Poniższa instrukcja definiuje sposób integracji z systemem RPPL (Repozytorium plików programów lekowych), który dostarcza funkcjonalność obsługi załączników.

Informacje ogólne

Rozwiązanie obsługi załączników w systemie SMPL jest oparte na protokole TUS.

Zalecane jest korzystanie z jednego z dostępnych klientów TUS np.

Pełna lista klientów jest dostępna na stronie tus.io.

Rozwiązanie to wymusza użycie odpowiednich nagłówków oraz metod HTTP. Pełna dokumentacja jest dostępna na stronie tus.io.

Dodatkowo należy uzupełnić dodatkowe nagłówki HTTP, które umożliwią systemowi SMPL zapisanie załącznika w odpowiednim kontekście, opisane poniżej w odpowiednich operacjach.

Żadania realizowane są na serwer TUS dostępny w ramach systemu SMPL pod adresem https://{ADRES_SZYNY_USLUG}/tus/smpl/files, gdzie {ADRES_SZYNY_USLUG} to adres szyny usług np. isus.ezdrowie.gov.pl.

Zapisanie załącznika

Zalecany proces zapisu załącznika wygląda następująco:

  1. Pobranie tokena dostępowego zgodnie z dokumentacją uwierzytelnienia
  2. Ustalenie identyfikatora pacjenta, dla którego zapisywany jest załącznik (np. z referencji subject.reference zasobu QuestionnaireResponse)
  3. Przygotowanie żądania utworzenia załącznika (metoda POST) zgodnie z protokołem TUS, z uwzględnieniem dodatkowych nagłówków HTTP
  4. Przesłanie zawartości załącznika na jeden z dwóch sposobów:
    • przesłanie całej zawartości załącznika w jednym żądaniu (zalecane dla małych plików), wymaga przesłania całego linku w ramach tworzenia załącznika metodą POST na adres https://{ADRES_SZYNY_USLUG}/tus/smpl/files
    • przesłanie zawartości załącznika w częściach (‘chunkach’), zgodnie z protokołem TUS (zalecane dla dużych plików), po przesłaniu pierwszego żądania typu POST na adres https://{ADRES_SZYNY_USLUG}/tus/smpl/files, należy wykonać żądania PATCH dla każdej kolejnej części pliku na adres https://{ADRES_SZYNY_USLUG}/tus/smpl/files/{uuid pliku}, gdzie uuid pliku znajduje się w odpowiedzi żądania POST w nagłówku Location.
  5. Odczytanie identyfikatora załącznika z odpowiedzi na utworzenie załącznika (nagłówek Location)
  6. Zapisanie identyfikatora załącznika w zasobie FHIR, np. w zasobie QuestionnaireResponse w polu answer.valueAttachment zgodnie z dokumentacją obsługi formularzy
  7. Zapis zasobu z referencją do załącznika.

W celu zapisania załącznika konieczne jest przekazanie również dodatkowych nagłówków HTTP:

  • Authorization: Bearer {TOKEN DOSTĘPOWY} - zawierający token JWT do obsługi zasobów FHIR pozyskany zgodnie z dokumentacją uwierzytelnienia
  • Patient_reference: {IDENTYFIKATOR PACJENTA} - identyfikator zasobu Patient z ZM (Zdarzenia Medyczne) pacjenta, dla którego zapisywany jest załącznik, zgodny z referencją subject.reference np. https://ezdrowie.gov.pl/fhir/Patient/1

Usunięcie załącznika

Możliwe jest usunięcie załącznika, który nie jest używany w żadnym zasobie (np. po odpięciu go od zasobu lub przed zapisaniem wersji zasobu z załącznikiem). Załączniki nieużywane przez żaden zasób mogą być automatycznie usuwane po określonym czasie, jednak w celu natychmiastowego usunięcia danych, w celu ochrony danych osobowych lub ograniczenia zużycia zasobów, możliwe jest wykonanie operacji usunięcia.

Aby usunąć załącznik, należy wysłać żądanie DELETE na adres https://{ADRES_SZYNY_USLUG}/tus/smpl/files/{uuid pliku}, gdzie uuid pliku to identyfikator załącznika zapisany w zasobie FHIR. Uwaga, referencja pliku w zasobie fhir może posiadać relatywny adres np. /tus/smpl/files/{uuid pliku}, należy pobrać uuid poprzez odcięcie po ostatnim znaku /

Wymagane jest podanie dodatkowych nagłówków HTTP:

Odczyt załącznika

Aby odczytać załącznik, należy wykonać żądanie GET na adres https://{ADRES_SZYNY_USLUG}/tus/smpl/files/{uuid pliku}, gdzie uuid pliku to identyfikator załącznika zapisany w zasobie FHIR. Uwaga, referencja pliku w zasobie fhir może posiadać relatywny adres np. /tus/smpl/files/{uuid pliku}, należy pobrać uuid poprzez odcięcie po ostatnim znaku /

Wymagane jest podanie dodatkowych nagłówków HTTP: