스터디 파일 형식 API에 대한 팁 및 모범 사례

이 페이지에는 스터디 파일 형식(SFF) API를 사용하기 위한 몇 가지 팁과 모범 사례가 나열되어 있습니다.

프로그래밍 방식 사용량 사용

SFF API는 파일을 수동으로 읽는 것이 아니라 프로그래밍 방식으로 접근하도록 설계되었습니다. SFF 패키지의 매니페스트 파일은 각 열에 대한 CSV 파일 및 메타데이터를 구성하며, 각 스터디 데이터 섹션에는 자체 블록이 있습니다.

스터디 디자인 섹션은 매니페스트 파일 내에서 별도로 구성됩니다. 아이템 정의 데이터는 각 아이템이 CSV 파일의 열이기 때문에 임상 데이터 섹션에 포함됩니다. 매니페스트는 SFF에 대한 메타데이터 및 스키마의 신뢰할 수 있는 소스로 취급되어야 합니다.

열 헤더

또한 SFF 열 헤더는 기계가 읽을 수 있도록 설계되었습니다. JSON 형식의 속성은 특정 순서로 유지되지 않으므로 프로그래밍 방식으로 열을 구문 분석하는 것이 중요합니다. 유일한 예외는 임상 데이터 섹션의 itemgroups 배열입니다. 이 배열은 각 아이템 정의가 아이템 그룹 내에 표시되는 순서를 유지합니다. 이에 따라 여러 아이템 그룹 정의에서 동일한 아이템 정의를 사용하는 경우가 방지됩니다.

효율적인 변경 사항 추적

SFF의 각 파일에는 각 행의 고유 식별자 역할을 하는 행 ID 열이 포함되어 있습니다. 이 열을 사용하여 행 레벨 변경 내용을 추적할 수 있습니다.

• 각 변경 사항을 업서트로 처리: 행이 증분 SFF 파일에 나타나면 해당 행에 대한 추가 또는 수정을 나타냅니다.
• Deletes CSV 파일은 가장 최근의 변경 증분에서 삭제된 모든 행을 나열합니다.

참조 데이터 매핑

전체 SFF 패키지에는 Labels 및 Override Labels라는 두 개의 CSV 파일이 포함되어 있습니다. 이러한 파일은 Veeva EDC에 구성된 레이블 및 표시 오버라이드 레이블에 대한 추가 데이터를 제공합니다.

Labels 파일

Labels CSV 파일에서 유형 열을 사용하여 레이블의 범주를 식별하고 오브젝트의 원래 이름에 매핑합니다.

예를 들어 유형 이 "Event"인 경우 event definition label을 참조합니다. The event definition name은 SFF 파일 내의 이벤트 이름(Event Name) 열입니다. 따라서 Labels 파일을 사용하여 이벤트 정의 이름과 이벤트 정의 레이블 사이를 매핑할 수 있습니다.

Override Labels 파일

Override Labels 파일을 사용하여 표시 오버라이드 레이블을 식별합니다(EDC Studio에서 특정 오브젝트 관계에 대해 구성된 경우).

오버라이드 레이블의 유형은 다섯 가지이며, 각 레이블은 스터디 정의 오브젝트에 연결됩니다.

• 이벤트 그룹
• 이벤트
• 폼(Form)
• 아이템 그룹(Item Group)
• 아이템

소스 정의(Source Definition) 열은 소스 정의 이름을 대상 정의(Target Definition) 열의 해당 대상 정의 이름에 매핑합니다.

예를 들면 다음과 같습니다.

소스 정의 값은 "form_A"이고 소스 레이블 유형은 "form"입니다. 대상 정의 이름은 "ig_A"이고 대상 레이블 유형은 "itemgroup"입니다.

즉, "ig_A"라는 아이템 그룹 정의는 "form_A"라는 폼 정의에 속하며, 표시 오버라이드 레이블이 설정되어 그 값이 대상 오버라이드 레이블 열에 있습니다.

생성일 활용

파일 이름에는 정의된 각 증분에 대해 게시된 시간(증분 추출의 경우 15분마다, 전체 추출의 경우 24시간마다)이 포함됩니다. API에서 반환된 created_date 순서대로 SFF ZIP 패키지를 사용하는 것이 가장 좋습니다. 특히 증분 SFF 사용량에 created_date를 사용하면 다운스트림 시스템에 변경 사항을 적용하여 동기화 상태를 유지하는 순서를 이해하는 데 도움이 됩니다. 예를 들어 created_date는 00:30(UTC)쯤일 수 있지만 게시된 시간은 00:45로 표시될 수 있습니다. 이는 시스템이 00:30에서 00:45 사이의 시간 간격을 캡처했기 때문입니다. 파일 이름에 대해 자세히 알아보십시오.

설정 및 새로 고침을 위해 전체 SFF 패키지 검색

처음 활성화할 때 전체 SFF 패키지를 검색해야 합니다. 증분 SFF도 활성화된 경우, 제3자 데이터가 필요하지 않은 한 처음에는 전체 패키지만 검색하면 됩니다. 제3자 데이터는 전체 패키지에서만 사용할 수 있습니다. 데이터가 동기화되지 않아 전체 새로 고침이 필요한 경우 전체 패키지를 다시 검색할 수 있습니다.

권장되는 파일 수집 방법

이러한 시나리오에서 SFF 패키지를 수집하는 데는 초기 활성화, 스터디 디자인 변경, 시스템 재설정, 제3자 데이터 사용과 같은 방법을 이용하는 것이 좋습니다.

초기 활성화

초기 SFF 활성화의 경우 오후 12:00(UTC)에 전체 패키지를 검색합니다. 여기에는 오전 6:00(UTC) 시점의 데이터가 포함됩니다. 증분 업데이트를 사용하는 경우 초기 SFF 활성화 후 오후 12:15(UTC)에 게시된 증분 패키지를 다운로드합니다. 증분 패키지가 생성되며 오후 12:15(UTC)부터 상시 데이터 업데이트에 사용할 수 있습니다.

디자인 변경 및 전체 필요

EDC 스터디 디자인을 변경하고 CDB로 수집할 때 API는 전체 추출 및 증분 추출 응답 모두에서 full_required를 "True"로 설정하여 전체 추출이 필요함을 나타냅니다. 이를 통해 모든 데이터가 최신 스터디 디자인을 반영할 수 있습니다.

full_required가 "True"로 설정된 상태로 다음 전체 추출을 사용하면, 후속 증분 추출에는 해당 전체 추출의 created_date 이후 발생한 모든 변경 사항이 포함됩니다. 이 created_date는 오전 6:00(UTC)경이며 패키지는 오후 12:00(UTC)쯤에 게시됩니다.

SFF 및 스터디 디자인 변경에 대해 자세히 알아보십시오.

시스템 재설정

대상 시스템에 문제가 발생하여 재설정해야 하는 경우 created_date 기반으로 가장 최근에 게시된 전체 추출을 사용합니다. 그런 다음 created_date 기반으로 생성된 증분 추출을 사용합니다.

제3자 데이터 사용

제3자 또는 비 Veeva EDC 데이터는 전체 패키지에서만 사용할 수 있으므로 시스템에 필요한 재처리량을 줄이는 것이 좋습니다.

시스템 재처리를 줄이기 위한 지침은 다음과 같습니다.

• 전체 패키지를 사용하되, 임상 폼 데이터를 사용할 때는 EDC 소스 데이터를 무시합니다. 매니페스트 파일의 임상 데이터 섹션 또는 블록에서 EDC 소스를 식별할 수 있습니다.
• EDC 데이터가 있는 운영 또는 참조 데이터 파일은 전체 추출의 생성과 게시 사이에 변경되었을 수 있습니다. 따라서 전체 추출의 created_date부터 시작하여 전체 추출이 게시될 때까지 증분 업데이트를 다시 적용해야 합니다. 여기에는 모든 시스템 파일, 즉 Queries, Query Messages, Local Lab Codelists, Local Lab Units 및 Deletes가 포함됩니다.