XML 형식으로 이슈 가져오기 및 내보내기

프로젝트 트래커는 XML 형식으로 이슈를 가져오고 내보낼 수 있습니다.

XML 가져오기에 관한 도움말

XML 이슈를 가져오려면 예전에 XML 파일로 내보낸 이슈의 내용을 추출해야 합니다. XML 파일을 가져올 때, 이슈 양식으로 존재하던 내용을 프로젝트로 가져오고 현재 구조에 따라 다시 배열합니다.

XML 이슈를 가져오려면 다음 작업을 수행하십시오.

  1. 프로젝트 탭 아래 프로젝트에서 왼쪽 네비게이션 창의 프로젝트 트래커 링크로 이동합니다.
  2. 관리 > XML로 이슈 가져오기 링크를 누릅니다.
  3. 찾아보기 버튼을 누르고 가져올 파일 이름을 선택합니다. 가져온 파일은 XML 형식(예: scarab-issues.xml)이어야 합니다. XML 파일을 찾지 못할 경우, "모든 파일" 드롭다운 상자를 눌러 표시되는 전체 파일 목록에서 검색하면 됩니다.
  4. 파일 가져오기 버튼을 눌러 이슈 내용을 프로젝트에 삽입합니다.

XML 내보내기에 관한 도움말

다른 응용 프로그램에서 이슈 내용을 사용할 수 있도록 XML 형식으로 이슈를 내보낼 수 있습니다. 쿼리 결과 페이지 또는 프로젝트 트래커의 XML 내보내기 페이지에서 이슈를 내보낼 수 있습니다. XML로 이슈를 내보낼 경우, 현재 프로젝트로만 제한됩니다. 프로젝트 간 쿼리에서 XML로 이슈를 내보낼 수 없습니다.

참고: 상태 속성에 대해 정의된 전이와 종속된 속성에 대해 정의된 규칙은 XML 가져오기가 수행되는 동안에는 이행되지 않습니다. 따라서 상태 전이에 앞서 생성된 이슈가 가져올 대상으로 정의되었을 수 있습니다.

쿼리 결과 페이지에서 XML 형식으로 이슈를 내보내려면

  1. 프로젝트 트래커를 사용하는 프로젝트에서 왼쪽 네비게이션 창의 프로젝트 트래커 > 검색 쿼리 이슈를 누릅니다.
  2. 신규 검색쿼리 생성 버튼을 누르거나 기존 쿼리 링크를 누릅니다.
  3. 새 쿼리를 만드는 중이라면 기준을 입력하고 제출을 누릅니다.
  4. 쿼리 결과 페이지의 쿼리 결과 섹션에서 '내보내기 형식 선택'이라고 표시된 드롭다운 목록을 누르고 XML(완전한 이슈)을 선택합니다.

참고: 날짜 속성이 연관된 이슈 유형의 이슈를 쿼리하는 경우 이슈를 "내보내기 형식 선택" 옵션에서 Excel(XLS) 형식으로 내보내고 Excel 편집기(예: Microsoft Excel)를 사용하여 엽니다. 이 때 "날짜" 등록 정보를 가지는 셀이 프로젝트 트래커에 사용되는 형식(즉, "YYYY-MM-DD")으로 날짜를 표시하지 않을 수도 있습니다. 이것은 Excel 편집기에서 사용되는 날짜 설정 때문에 발생하는 것으로 실제 날짜는 그대로 유지됩니다. 내보낸 Excel 파일의 날짜 표시를 변경하려면 Excel 편집기에서 다음을 수행하십시오.

  1. 연관된 날짜 등록 정보를 가지는 Excel 시트의 전체 열이나 행 또는 특정 셀을 선택합니다.
  2. 마우스 오른쪽 버튼을 누르고 형식 셀 옵션을 선택합니다.
  3. 숫자 탭 아래에서 커스텀 카테고리 옵션을 선택합니다.
  4. 오른쪽에 나타나는 하위 메뉴에 있는 유형 입력란에 다음을 입력합니다. "yyyy-mm-dd"(따옴표 없이)
  5. 확인 버튼을 눌러 변경사항을 저장합니다.

해당 운영 체제에서 사용하는 날짜 설정에 상관 없이 날짜가 "yyyy-mm-dd" 형식으로 나타나도록 합니다. 운영 체제의 날짜 설정을 변경하면 다른 어플리케이션에도 영향이 미칩니다.

내보내기 페이지에서 XML 형식으로 이슈를 내보내려면

  1. 프로젝트 트래커를 사용하는 프로젝트에서 왼쪽 네비게이션 창의 프로젝트 트래커 > XML로 이슈 내보내기를 누릅니다.
  2. 화면상의 지시에 따라 이슈 ID를 하나 이상 입력합니다.
  3. 파일 또는 브라우저 창으로 내보낼 것인지 선택합니다.
  4. 내보내기 버튼을 누릅니다.

내보내기 형식

두 가지 방식으로 내보내기가 수행될 수 있으며, 이 방식은 XML 파일의 <import-type> 요소에서 정의합니다.

create-same-db 혹은 create-different-db - 가져오기를 수행할 때, 가져오는 모든 이슈를 새 이슈로 간주하고 기존 데이터는 모두 무시하며 XML 파일의 모든 데이터는 새 데이터로서 가져옵니다.

이 가져오기 형식은 다음 용도로 사용됩니다.

update-same-db - 시스템은 <id> 요소를 기준으로 데이터베이스에서 기존 이슈를 찾으려 합니다. 기존 이슈를 나타내는 <issue>로 인해 기존 이슈가 수정됩니다. 동일한 XML에 <id> 요소가 기존 이슈와 일치하지 않는 <issue>가 포함될 수도 있습니다. 이 경우, 새로운 이슈로 가져옵니다.

다양한 외부 이슈 트래커 간에 이슈 데이터를 이동할 때 특정 클라이언트가 PT를 촉진자로 사용하도록 지원하는 경우에 기존 갱신 구현을 사용합니다. 이 사용법에 대한 자세한 내용은 현재 알려지지 않았습니다.

update-same-db의 주 용도가 확실하지 않으므로 개발 과정에서는 웹 서비스 API의 빈약한 대안으로 사용될 가능성도 있다고 가정했습니다. 단, CGI 매개 변수를 이용하여 스크립트를 작성하면 편리할 것입니다. 다음과 같은 경우는 현재 구현 환경에서 다양한 수준으로 적용될 수 있습니다.

선행 조건

현재 가져오기가 성공적으로 수행되기 위한 선행 조건은 XML 파일에서 참조하는 모든 프로젝트, 사용자 이름, 이슈 형식, 속성 및 속성 옵션이 시스템에 이미 존재해야 한다는 것입니다. 이미 존재하지 않으면 가져오기는 실패합니다.

사용자 인터페이스

"XML 가져오기"에 입력되는 것은 하나의 XML 파일이며, 그 상세 정보는 DTD에 의해 지정됩니다. DTD에는 일부 추가 설명이 포함되어 있지만 자세한 내용은 여기를 참조하십시오. 파일은 서비스 그룹과 운영 그룹 간에 합의된 절차에 따라 HTTP 파일 업로드를 통해 가져오거나 서버의 파일 시스템에 위치할 수 있습니다.

HTTP 파일 업로드

파일 업로드 옵션은 프로젝트 내부에 이슈를 입력할 권한이 있는 사용자가 이용할 수 있습니다. 그러나 관리 네비게이션 아이템으로 표시되는 기능에 액세스하는 링크는 프로젝트 이슈 트래킹 - 설정 또는 프로젝트 - 편집 권한이 있는 사용자(일반적으로 프로젝트 소유자 및 기타 관리 역할)에게만 표시됩니다.

가져오기 결과는 HTTP 응답을 통해 제시됩니다. 또는 시간이 미리 설정된 한도(현재는 30초)보다 길다면 그 결과는 이메일을 통해 사용자에게 전달됩니다. 오류 결과 역시 즉각적인 응답이나 이메일로 전달됩니다. 이메일의 경우, 성공 메시지에는 웹 인터페이스를 통해 결과를 볼 수 있는 링크가 포함되어 있습니다. 가져오기가 스크립트로 작성된 경우, 쿼리 매개변수 format=xml을 추가하여 XML 문서 형태로 결과를 반환할 수도 있습니다. 이 매개변수 값이 존재한다면 가져오기가 완료된 후에 응답이 이루어집니다. 이메일 전송 대기 시간 제한은 없지만, HTTP 클라이언트나 서버에서 최대 시간 제한을 둘 수 있습니다.

파일 첨부 요소는 XML 내부에서 허용되지만, 무시될 것입니다. update-same-db 형식의 경우, 경고가 표시될 수 있습니다.

명령줄(서버)

파일 시스템을 통한 XML 가져오기는 Issuezilla에서 PT로 프로젝트를 변환할 때 사용되며, 서비스를 통해 클라이언트에서도 이용할 수 있습니다. 파일 첨부 요소는 XML 내부에서 허용되지만, 서버에 존재하는 파일을 가리켜야 합니다. 서버에 존재하는 중요한 파일에 대한 액세스를 막기 위해 서비스는 가져오기에 앞서 XML을 제공한 클라이언트를 정리해야 합니다.

가져올 여러 XML 파일이 포함된 디렉토리를 지정할 수 있습니다. 이것은 편리한 방법으로서, 파일들을 독립적인 가져오기로 취급합니다.

경고 없이 가져오기가 성공하면 아무런 메시지도 표시되지 않습니다. 오류 및 경고는 표준 출력에 인쇄됩니다.

유효성 검사

유효성 검사에는 DTD를 기준으로 XML을 검사하는 것이 포함될 수 있습니다. XML 파일에 포함된 데이터는 응용프로그램 상태와도 비교됩니다.

XML 유효성 검사

XML 파일에 DOCTYPE 태그가 있는 경우 릴리스 3.0.1 이상에서는 <!DOCTYPE scarab-issues SYSTEM "PROTO://www.DOMAIN/dtd/pt.dtd"> (여기서 PROTO는 https 또는 http), 릴리스 3.0.0 및 2.6.x에서는 <!DOCTYPE scarab-issues SYSTEM "http://project.domain.com/dtd/scarab-0.16.29.dtd">로 지정되어야 합니다. 이 DOCTYPE 태그가 지정된 경우 해당 릴리스의 현재 DTD를 기준으로 XML 유효성이 검사됩니다.

의미 체계 유효성 검사

XML 파일에 포함된 데이터는 PT 데이터베이스 내부의 현재 메타 데이터를 기준으로 검사합니다. 이슈 형식, 속성과 같은 모든 메타 데이터는 선행 조건으로 마련되어야 합니다. XML에서 값이 지정된 속성은 비활성 상태이더라도 지정된 이슈의 이슈 형식과 연결되어야 합니다. XML의 속성 이름은 전역 속성 이름으로 매핑됩니다. 속성 옵션에서는 프로젝트 및 이슈 형식에서 사용되는 옵션에 대해 전역 이름 또는 별명을 사용할 수 있습니다.

종속성의 유효성 검사에서는 해당 형식 및 이슈가 존재하는지 검사합니다. 유효성을 검사하지 않는 정보에 대한 자세한 내용은 생성 형식 및 갱신 형식 비교를 참조하십시오.

XML에 지정된 날짜 문자열은 해당 날짜와 함께 제공된 형식 문자열에 따라 구문 분석되어야 합니다.

XML에서 사용되는 사용자 이름은 도메인 내부의 실제 사용자와 매핑되어야 합니다(호스트 사용자의 경우 호스트).

파일 첨부는 서버상의 파일에 대한 유효한 경로를 포함해야 합니다. 파일 첨부가 허용된 경우에만 유효성을 검사합니다.

모든 데이터는 가져오기가 시작되기 전에 유효성이 검사되며, 유효성 검사 단계와 가져오기 종료 사이에 메타 데이터를 변경하면 가져오기가 실패하고 이슈의 일부만 가져오게 됩니다.

참고: XML 가져오기 기능을 사용해 속성을 가져올 경우, 필수 속성은 무시됩니다. 즉 컬랩넷 사용자 인터페이스를 통해 새 이슈를 만들 경우, 모든 필수 속성("*"로 표시)에 대해 값을 제공해야 합니다. 그러나 필수 속성의 값이 누락되었더라도 XML 가져오기를 통해 새 이슈를 생성할 수는 있습니다.

속성 종속성

가져오기 쓰레드에서는 사용되지 않습니다. 전이 및 필수 속성에 대해서는 감사 정보가 제공되지 않으므로, 과거 어느 시점에서의 활동이 포함된 이슈를 가져오는 것이 합법적인지 여부를 알 수 없습니다. 프로젝트 트래커가 이 정보에 대한 감사를 관리했더라도 XML 가져오기 기능은 기존 이슈 트래커에서 데이터를 가져올 수 있으며, 이슈에 대한 활동은 프로젝트 트래커 내부에서 메타 데이터 변경보다 먼저 이루어질 수 있습니다. 해당 데이터가 과거 어느 시점에서의 상태에 대한 요구 사항을 충족시켰다고 가정합니다.

필수 속성 값 없이 이슈를 가져올 수 있습니다. 프로젝트 트래커에서 이슈가 맨 처음 편집될 때 필수 값이 이행됩니다.

이슈 종속성

동일한 XML 파일에 포함된 이슈간에 종속성을 지정할 수 있습니다. 가져오는 중인 서로 다른 XML 파일의 이슈 간에는 종속성을 선언할 수 없습니다. create-same-db 형식의 경우, XML의 이슈와 이미 PT에 입력된 이슈간에 종속성을 지정할 수 없습니다. 이미 입력된 이슈에 대해 update-same-db 형식을 사용하여 종속성을 지정할 수 있습니다.

활동 묶음

활동은 동시에 발생하는 것끼리 그룹화할 수 있지만, 일반적으로 다른 활동과 그룹화되지 않는 일부 활동은 하나의 활동을 포함하는 활동 묶음으로 지정됩니다.

  1. 이슈에 파일 첨부 추가하기
  2. 이슈에 코멘트 추가하기

속성 값 및 종속성을 변경하는 몇 가지 활동을 하나의 활동 묶음에 포함시킬 수 있습니다. 그러나 'Status changed from NEW to STARTED'와 같은 활동 항목과 'Status changed from NEW to FIXED'와 같은 항목을 동일한 활동 묶음에 두면 안 됩니다. 그러한 조합은 유효성 검사에서 파악되지 않습니다.

생성되었거나 수정된 날짜 정보는 코멘트/이유, URL 및 파일이 포함된 첨부 요소에 대해서는 무시됩니다. 웹을 통해 XML이 업로드될 경우, 파일 첨부가 무시됩니다. XML 내부에서 이전 첨부와 ID가 동일한 첨부를 사용하는 활동이 있으면 초기 첨부에 대해 또 다른 이력 기록이 만들어지지만, 원래 첨부가 수정되지는 않습니다. 따라서 XML 내부에서 첫 번째 첨부 참조는 최종 상태를 포함해야 합니다. 나머지 모든 참조는 일반적으로 동일하지만, 동일한 ID를 갖는 한 무시됩니다.

하나의 활동에서 기존 값 및 신규 값 요소는 속성 값을 추가하거나 수정할 때 사용합니다. 단일 값 속성은 기존 값과 신규 값을 모두 포함할 수 있는데, 이 경우 값을 변경하는 것으로 해석됩니다. 다중 값 속성은 둘 중 한 요소만 포함해야 합니다. 할당된 사용자가 'user1'에서 'user2'로 변경되지 않습니다. 할당된 사용자 'user1'이 제거되고, 'user2'가 할당된 사용자로 추가됩니다. 기존 값으로 옵션 또는 사용자 이름을 포함하고 신규 값으로는 아무 것도 포함하지 않으면 값을 제거하는 것으로 해석됩니다.

샘플 XML

보다 연관성 있는 XML 섹션을 보여 주는 몇 가지 수정 사례를 활동 서명 문서에서 확인할 수 있습니다. 그 외에도 몇 가지 예가 있습니다.

생성 및 갱신 형식 비교

유효성 검사

XML에서 종속성은 '갱신' 형식에 대해 시스템에 이미 입력된 이슈를 참조할 수 있습니다. '생성' 형식은 XML에서 발견되는 종속성과 이슈 간에 자체 일관성을 요구합니다.

새 이슈

'생성' 형식은 항상 XML의 각 이슈 요소에 대해 새로 저장된 이슈를 만듭니다. ID 요소는 '갱신' 형식을 사용할 경우 저장된 이슈와 비교됩니다. ID가 저장된 이슈와 일치하면 해당 이슈가 수정됩니다. 그렇지 않으면 '생성' 형식과 비슷하게 새 이슈가 만들어집니다. 새로 저장된 이슈에는 프로젝트에서 사용 중인 접두사 및 카운터에 따라 새 ID가 지정됩니다.

활동 묶음

'생성' 형식에서는 활동 묶음 날짜가 XML 입력에 지정된 대로 사용됩니다. update-same-db 가져오기의 경우 이슈가 갱신 중이면 활동 묶음에 대해 생성된 날짜가 이슈에 대해 마지막으로 수정된 날짜 및 현재 날짜와 비교됩니다. 마지막 수정 날짜 이전의 활동 묶음은 무시되고 경고가 제공됩니다. 미래 날짜는 가져오기가 수행 중인 시간으로 변화되고, DTD 제한사항 내에서 현재 시간을 사용하도록 갱신을 지정하는 방법을 제공합니다.

활동

종료 날짜가 널(null)인 활동은 두 형식 중 하나의 새 활동이 됩니다. 일반적으로 활동과 관련된 속성의 널(null) 종료 날짜는 활동이 속성에 대한 현재 값을 나타냄을 의미합니다. '갱신' 가져오기 형식의 경우 종료 날짜 값을 가지는 활동은 무시됩니다.

종속성

'갱신' 형식의 경우 이미 존재하는 종속성을 추가하거나 존재하지 않는 종속성을 삭제하는 시도는 자동으로 무시됩니다. '생성' 형식에 대해 동일한 시도를 수행하면 해당 종속성 및 이후 발생하는 종속성이 저장되지 않는 예외가 발생합니다. 모든 이슈는 계속 저장될 것입니다. 존재하지 않는 종속성 갱신은 두 형식 모두에 대해서 무시됩니다.