Confluence Data Center의 공간을 매뉴얼웍스로 가져옵니다. Confluence REST API로 페이지 트리와 본문, 첨부 파일을 읽어 공간은 프로젝트로, 페이지는 문서와 장으로 만듭니다.

모든 내용을 그대로 옮기는 것이 아니라 대부분의 페이지를 손대지 않고 옮기고, 옮기지 못한 내용은 문서별 오류로 정확히 알려 주는 것을 목표로 합니다. 가져오기 전에 분석 단계에서 매크로마다 어떻게 옮겨지는지 먼저 보여 주므로, 이관 범위를 미리 판단할 수 있습니다.

지원 범위

Confluence Data Center 7.9 이상을 지원합니다. 개인 액세스 토큰으로 연결하기 때문에 개인 액세스 토큰을 지원하지 않는 이전 버전에서는 가져올 수 없습니다. Confluence Cloud는 지원하지 않습니다.

가져오는 내용과 가져오지 않는 내용은 다음과 같습니다.

가져오기 전에 준비할 것

개인 액세스 토큰 만들기

Confluence에서 프로필 사진을 클릭한 후 설정의 개인 액세스 토큰 화면에서 토큰을 만듭니다.

• 매뉴얼웍스는 토큰 사용자가 볼 수 있는 페이지만 가져옵니다. 가져올 공간의 모든 페이지를 볼 수 있는 계정으로 토큰을 만듭니다. Confluence 관리자 계정일 필요는 없습니다.

• 제한을 걸어 토큰 사용자가 볼 수 없는 페이지는 목록에도 나오지 않으므로 몇 개가 빠졌는지 알 수 없습니다. 빠진 페이지 확인하기를 참고합니다.

• 가져오기가 끝나면 토큰을 지우거나 만료해도 됩니다.

네트워크와 파일 크기 확인하기

• 매뉴얼웍스 서버에서 Confluence 서버로 HTTP 또는 HTTPS로 연결할 수 있어야 합니다. 웹 브라우저가 아니라 매뉴얼웍스 서버가 Confluence에 요청합니다.

• 업로드 파일 최대 크기(UPLOAD_FILE_MAX_SIZE)보다 큰 첨부 파일은 가져오지 않고 그 문서의 오류에 빠진 첨부 파일로 남깁니다.

요청 간격 정하기

매뉴얼웍스는 운영 중인 Confluence에 부담을 주지 않도록 요청 사이에 간격을 둡니다. 기본 값은 200밀리초입니다. 페이지가 많아 가져오기가 너무 오래 걸리거나, 반대로 Confluence가 바쁜 시간에 가져와야 한다면 콘솔에서 다음 명령어로 바꿉니다. 0이면 간격을 두지 않습니다.

set-preference -name CONFLUENCE_REQUEST_INTERVAL -value 500

Confluence가 속도 제한이나 과부하로 요청을 거절하면(429, 503 응답) Confluence가 알려 준 시간만큼, 최대 60초까지 기다렸다가 세 번까지 다시 보냅니다. 그래도 거절하면 그 페이지는 실패로 남습니다.

권한과 라이선스 확인하기

• 글 쓰기 권한이 있는 사용자가 가져올 수 있습니다.

• 만들 문서 수가 라이선스로 만들 수 있는 문서 수를 넘으면 가져올 수 없습니다. 페이지와 옵션 단계에서 미리 알려 줍니다.

공간 가져오기

<대시보드 | 가져오기 | Confluence에서 가져오기> 메뉴에서 가져옵니다. 다섯 단계로 진행합니다.

1. 연결

Confluence 주소와 개인 액세스 토큰을 입력하고 다음 버튼을 클릭합니다. 매뉴얼웍스가 Confluence에 연결해 공간 목록을 불러옵니다.

• Confluence 주소는 컨텍스트 경로까지 입력합니다. 예를 들어 Confluence를 /confluence 경로에 설치했다면 https://wiki.example.com/confluence 처럼 입력합니다.

2. 공간

가져올 공간을 선택하고 다음 버튼을 클릭합니다. 매뉴얼웍스가 공간의 페이지 트리를 읽고 페이지마다 본문을 받아 매크로를 셉니다. 페이지가 많으면 시간이 걸립니다.

3. 분석 결과

가져올 수 있는 페이지 수와 보기 제한이 걸린 페이지 수, 공간에서 쓰는 매크로의 종류와 건수, 그리고 옮기는 방식을 보여 줍니다. Confluence가 보기 제한 정보를 주지 않은 페이지가 있으면 그 수도 보여 줍니다. 옮기는 방식은 매크로 변환에서 설명합니다. 확인한 후 다음 버튼을 클릭합니다.

4. 페이지와 옵션

옵션을 정하고 가져올 페이지를 선택한 후 가져오기 버튼을 클릭합니다.

문서 수준

몇 번째 단계의 페이지부터 문서로 만들지 정합니다. 0이면 공간 전체를 책 하나로 만듭니다. 1이면 최상위 페이지마다 문서를 하나씩 만듭니다. 문서 수준보다 위에 있는 페이지는 프로젝트가 됩니다. 기본 값은 1입니다.

더 깊은 페이지

장보다 깊은 페이지를 어떻게 옮길지 정합니다. “장으로 펼치기”를 선택하면 같은 문서의 장으로 만들고, “부모 장 안에 합치기”를 선택하면 부모 장 안에 절로 넣습니다.

페이지 트리에는 페이지마다 프로젝트, 책, 짧은 문서, 부, 장, 절 중 무엇이 될지 표시합니다. 보기 제한이 걸린 페이지와 그 자손 페이지에는 “보기 제한” 표시를 붙입니다. 체크를 해제한 페이지는 가져오지 않습니다. 부모 페이지를 해제하면 자손 페이지도 함께 해제됩니다.

5. 결과

가져오기를 시작하면 만들 문서를 프로젝트 경로별로 묶어 보여 주고, 문서마다 진행 상태를 보여 줍니다. 경로는 공간부터 하위 프로젝트까지 / 로 나눠 보여 줍니다. 가져오는 중인 문서는 처리한 장의 비율을 진행 막대로 보여 줍니다. 가져오기가 끝나면 경로의 마지막 프로젝트 이름을 클릭해 새 창에서 그 프로젝트의 문서 목록을 열 수 있고, 만든 문서는 제목을 클릭해 새 창에서 열 수 있습니다. 오류가 있는 문서는 오류 열에 건수가 나옵니다. 오류 확인하기를 참고합니다.

문서의 진행 상태는 다음과 같습니다.

페이지 구조 변환

Confluence 페이지 트리는 다음과 같이 매뉴얼웍스 프로젝트, 문서, 장으로 바꿉니다.

다음을 참고합니다.

• 본문이 비어 있는 “개요” 장은 만들지 않습니다. 자식 페이지 목록만 두는 부모 페이지가 많기 때문입니다.

• 부모 페이지를 선택하지 않고 자식 페이지만 선택하면 가장 가까운 선택된 조상 아래에 둡니다. 선택된 조상이 없으면 공간 프로젝트 바로 아래에 둡니다.

• Confluence 페이지는 제목 2부터 쓰는 경우가 많습니다. 페이지에서 가장 높은 제목을 제목 1로 맞춰 차례에 빈 단계가 생기지 않게 합니다. 부모 장 안에 합친 페이지는 페이지 제목을 제목 단락으로 넣고 본문 제목을 그 아래 단계로 맞춥니다.

• 그림 첨부 파일은 문서 그림으로 올립니다. 그 밖의 첨부 파일은 공간 이름으로 만든 파일 디렉터리에 올리고 본문에서 링크합니다.

• 페이지 링크와 앵커 링크는 장과 단락 참조로 바꿉니다. 다른 문서의 장을 가리키는 링크도 참조로 바꿉니다.

매크로 변환

매크로는 다음 네 가지 방식으로 옮깁니다. 분석 결과의 “옮기는 방식”이 이 방식을 가리킵니다.

표, 목록, 할 일 목록, 인용, 그림, 링크, 사용자 언급, 이모티콘은 매크로가 아니므로 해당하는 매뉴얼웍스 단락과 글자로 바꿉니다.

렌더링에 실패하거나 결과가 비어 있으면 매크로 안의 글만 남기고 그 문서의 오류에 “옮기지 못함”으로 남깁니다.

오류 확인하기

가져오기 화면의 오류 열에 문서마다 오류 건수를 보여 줍니다. 건수를 클릭하면 오른쪽에 열리는 창에서 오류마다 유형, 페이지, 자세한 내용을 볼 수 있습니다. 오류 유형은 다음과 같습니다.

빠진 페이지 확인하기

토큰 사용자가 볼 수 없는 페이지는 Confluence가 응답에서 아예 빼고 보냅니다. 따라서 매뉴얼웍스는 이런 페이지의 제목과 개수를 알 수 없고, 문서의 오류에도 남지 않습니다. 보기 제한은 자식 페이지에도 이어지므로 제한된 페이지 아래의 페이지도 함께 빠집니다.

빠진 페이지가 없도록 다음 순서로 준비하고 확인합니다.

1. 가져올 공간의 모든 페이지를 볼 수 있는 계정으로 개인 액세스 토큰을 만듭니다. 공간 관리자라도 페이지 제한에 걸린 페이지는 보지 못할 수 있습니다. 이런 페이지는 가져오기 전에 제한을 풀거나, 그 페이지를 볼 수 있는 계정으로 토큰을 만듭니다.

2. 가져온 뒤 문서의 오류에서 끊긴 링크를 확인합니다. 볼 수 있는 페이지 본문에 빠진 페이지를 가리키는 링크가 있으면 그 링크 글자가 끊긴 링크로 나옵니다. Confluence에는 있는 페이지인데 가져온 결과에 없다면 권한 때문에 빠졌을 가능성이 큽니다.

3. Confluence 공간의 페이지 트리와 가져온 프로젝트의 문서와 장을 비교합니다.

다시 가져오기

같은 Confluence 주소에서 같은 사용자가 같은 공간을 다시 가져오면 이미 만든 프로젝트, 문서, 장, 첨부 파일을 다시 만들지 않고 문서 상태를 “이미 가져옴”으로 표시합니다. 새로 추가된 페이지와 앞서 실패한 페이지만 가져옵니다.

• 앞서 실패한 페이지를 다시 가져오면 그 페이지를 가리키던 끊긴 링크도 참조로 바뀝니다.

• 이미 가져온 장은 Confluence에서 수정되었어도 바꾸지 않습니다. 다시 받으려면 매뉴얼웍스에서 해당 장을 지운 후 다시 가져옵니다.

• 다른 사용자가 가져오면 새 프로젝트로 만듭니다. 가져오기를 실행한 사람이 프로젝트 리더나 문서 소유자가 아니게 된 경우에도 해당 프로젝트나 문서를 다시 쓰지 않고 새로 만듭니다.

예전 Confluence 주소 이어 주기

가져온 장과 부에는 Confluence 페이지 아이디를 사용자 정의 아이디로 붙입니다. 페이지 아이디가 123456이면 사용자 정의 아이디도 123456입니다. 부모 장 안에 합친 페이지는 장이 없으므로 그 절의 제목 단락에 붙입니다.

매뉴얼웍스는 서버 주소 바로 뒤에 사용자 정의 아이디를 붙인 주소로 들어오면 그 장이 있는 문서를 웹 뷰어로 엽니다. 예를 들어 https://manualworks.example.com/123456 으로 들어오면 페이지 아이디가 123456인 Confluence 페이지에서 가져온 장이 열립니다.

메일, Jira, 다른 문서에 남은 예전 Confluence 주소를 이어 주려면, 예전 Confluence 주소로 들어온 요청을 이 주소로 보내도록 웹 서버를 설정합니다. 다음은 Confluence를 /confluence 경로에 설치했던 경우의 Nginx 설정 예입니다.

location = /confluence/pages/viewpage.action {
    if ($arg_pageId ~ "^[0-9]+$") {
        return 301 https://manualworks.example.com/$arg_pageId;
    }
}

다음을 참고합니다.

• 페이지 아이디가 들어 있는 주소만 이어 줄 수 있습니다. 공간 키와 제목으로 된 주소(/display/공간키/페이지제목)나 짧은 링크(/x/로 시작하는 주소)는 페이지 아이디를 알 수 없어 이어 줄 수 없습니다.

• 사용자 정의 아이디는 문서 안에서만 겹치지 않으면 됩니다. 같은 문서에서 이미 쓰는 사용자 정의 아이디면 붙이지 않고, 그 문서의 오류에 “사용자 정의 아이디 중복”으로 남깁니다.

• 같은 공간을 다른 사용자가 다시 가져오는 등으로 여러 문서에 같은 사용자 정의 아이디가 있으면, 서버 주소 바로 뒤에 붙인 주소는 그 가운데 먼저 찾은 문서로 갑니다. 예전 주소를 이어 줄 문서 하나만 남기고 나머지 문서의 사용자 정의 아이디는 지우거나 바꿉니다.

• 부의 첫 장 “개요”처럼 한 페이지에서 장이 둘 만들어지면 먼저 만든 쪽(부)에만 붙입니다.

• 가져온 뒤 사용자 정의 아이디를 바꾸면 그 페이지의 예전 주소는 더 이상 이어지지 않습니다.

문제 해결

연결이나 가져오기에 실패하면 다음 메시지를 보여 줍니다.