Loading

Data Loader를 사용하여 ContentNote 개체로 노트 가져오기

게시 일자: Apr 3, 2026
상세 설명

API 버전 32.0 이상에는 향상된/서식이 있는 텍스트 'Notes(노트)' 기능을 사용해 생성된 레코드를 포함하는 새로운 'ContentNote' 개체에 대한 API 지원이 추가되었습니다. 서식이 있는 텍스트 'Notes' 기능은 Summer '15 릴리스 노트에서 설명된 대로 Salesforce 사용자 인터페이스에서 정식으로 사용할 수 있습니다.


서식이 있는 노트는 Salesforce 사용자 인터페이스에서 작성할 수 있습니다. 그러나 로컬 파일 시스템에 저장해 둔 기존 노트를 Salesforce 조직의 'ContentNote'에 가져오기를 원하는 경우도 있을 것입니다. 


아래의 프로세스를 따라 Apex Data Loader를 사용해 기존 노트 가져오기를 진행하세요.


참고: 노트를 'ContentNote'로 가져오려면 Salesforce 조직에서 Chatter와 새로운 서식이 있는 텍스트 'Notes' 기능을 모두 활성화해 두어야 합니다. 새 'Note' 기능을 조직에서 활성화 및 설정하는 법은 노트 필기 도구 'Notes' 및 'Files' 기능 사용 시 고려 사항에서 확인하세요.

 
솔루션


1단계. CSV 파일 준비하기


아래와 같이 삽입하려는 각 행의 값을 매핑하는 두 개의 열로 구성된 CSV 파일을 준비해야 합니다.
 
  • Title - 노트의 제목이며 필수 사항입니다.
  • Content - 노트의 본문을 포함하는 .txt 또는 .html 파일의 로컬 시스템상 경로입니다.  해당 파일의 'Properties(속성)'에서 확인할 수 있습니다.
  • OwnerId - 노트 소유자의 사용자 ID입니다. 파일에 ID가 포함되어 있지 않은 경우 소유자는 기본적으로 데이터 로드를 수행하는 사용자로 설정됩니다.

선택 필드: 아래의 각 필드에 대해 지원되는 호출 및 값에 대한 세부 사항, 각 필드에 액세스하기 위한 Data Loader(API)의 최소 버전은 SOAP API 개발자 가이드의 ContentNote에서 확인할 수 있습니다.
 
  • SharingPrivacy - 파일의 공유 정책을 관리합니다.
  • CreatedById - 해당 레코드를 생성한 사용자의 사용자 ID입니다. 'Create Audit Fields(감사 필드 만들기)' 활성화가 필요하며 레코드 삽입 시에만 설정하거나 지정할 수 있습니다.
  • CreatedDate - 노트 생성 일자/시간입니다. Data Loader가 지원하는 데이터 형식에서 적합한 형식을 확인하세요.  'Enable Create Audit Fields(감사 필드 만들기 활성화)'가 필요하며 레코드 삽입 시에만 설정하거나 지정할 수 있습니다.
  • LastModifiedById - 노트를 마지막으로 수정한 사용자의 사용자 ID입니다.  'Enable Create Audit Fields(감사 필드 만들기 활성화)'가 필요하며 레코드 삽입 시에만 설정하거나 지정할 수 있습니다.
  • LastModifiedDate - 노트가 마지막으로 수정된 날짜/시간입니다.  'Enable Create Audit Fields(감사 필드 만들기 활성화)'가 필요하며 레코드 삽입 시에만 설정하거나 지정할 수 있습니다.
 
 
샘플 테이블:
 
 Title
Content
 Test Note 1
C:\notes\test_note_01.txt
 Test Note 2
C:\notes\test_note_02.html
 Test Note 3
C:\test_note3.txt

참고: MAC의 경우 구문이 약간 다릅니다. 예시: /Applications/Data Loader.app/test_note_01.txt
 

샘플 CSV:
Title,Content
Test Note 1,C:\notes\test_note_01.txt
Test Note 2,C:\notes\test_note_02.html
Test Note 3,C:\test_note3.txt
 
참고: 'ContentNote'는 Salesforce CRM Content 기능에 기반하므로 'Content' 열은 로컬 파일로의 경로를 반드시 포함해야 합니다. 노트의 본문은 CSV 파일에 포함되지 않을 수 있습니다.
 

참고: Excel .CSV 파일에 파일 경로를 대량으로 복사해서 붙여넣는 방법은 다음과 같습니다.

Windows:

  1. 파일 위치로 이동해서 노트로 가져올 파일을 모두 선택합니다.
  2. 파일들을 선택한 다음 Shift 키를 누른 상태로 마우스 오른쪽 버튼을 클릭합니다.
  3. Copy as Path(경로로 복사)를 선택합니다(확장된 홈 탭에도 복사 경로를 확인할 수 있습니다).
  4. CTRL + V를 눌러 복사한 항목을 Excel에 붙여 넣습니다.

MAC:

  1. 파일 위치로 이동해서 노트로 가져올 파일을 모두 선택합니다.
  2. 마우스 오른쪽 클릭 시 나타나는 메뉴에서 OPTION 키를 누른 상태로 유지하여 'Copy(item name) as Pathname((경로 이름으로 (항목 이름) 복사)' 옵션을 표시하거나 Cmd-Opt-C를 누릅니다.
  3. 파일 경로를 .csv 파일에 붙여 넣습니다.

 

2단계. 'Notes' 본문 파일을 로컬 하드 드라이브에 준비하기

 
하드 드라이브에는 삽입하려는 각 노트의 본문 내용을 포함하는 .txt 또는 .html 파일이 존재해야 합니다. 해당 파일들은 1단계에서 만든 CSV 파일에 매핑된 파일입니다.
 
.txt 및 .html 파일을 'ContentNote' 개체의 'Content' 필드로 가져올 때 일부 특수 HTML 문자는 지원되지 않습니다. 파일을 성공적으로 가져오려면 사전에 이러한 특수 문자를 그에 대응하는 지원되는 HTML 문자 코드로 변환해야 합니다.
 
지원되지 않는 문자와 이를 대체할 수 있는 HTML 문자 코드의 일부는 다음과 같습니다.
특수 문자
교체 문자 코드...
&
&
<
&lt;
>
&gt;
"
&quot;
'
&#39;
 
 

3단계. Data Loader로 'Note' 삽입하기

 
위 과정에 따라 CSV 파일과 가져올 파일을 준비했다면 기존의 노트를 가져올 준비가 완료된 것입니다.
 
  1. Apex Data Loader를 설치하고 실행합니다. 자세한 내용은 Data Loader 설치 시 고려 사항을 확인하세요.
  2. Insert(삽입)을 클릭합니다.
  3. 로그인 자격 증명을 입력합니다.
  4. Next(다음)을 클릭합니다.
  5. Show all Salesforce objects(모든 Salesforce 개체 표시) 옆의 상자를 체크합니다.
  6. 사용 가능한 개체 목록에서 Note(ContentNote)를 선택합니다.
  7. Browse...(찾아보기)를 클릭하고 1단계에서 준비해 둔 CSV 파일을 선택합니다.
  8. Next(다음)을 클릭합니다.
  9. 'Data Selection(데이터 선택)' 초기화 대화 상자가 나타나면 레코드 개수가 정확한지 확인한 다음 OK(확인)을 클릭합니다.
  10. 다음 화면에서 Create or Edit a Map(맵 만들기 또는 편집)을 클릭합니다.
  11. Auto-Match Fields to Columns(필드를 열에 자동 맞춤)를 클릭하거나 'Title'과 'Content' 필드를 CSV 파일에서 각각에 대응하는 열에 직접 일치시킵니다.  자세한 내용은 Data Loader 필드 매핑 정의에서 확인하세요.
  12. OK(확인)을 클릭해 진행합니다.
  13. 매핑이 올바른지 확인하고 Next(다음)을 클릭합니다.
  14. Browse...(찾아보기)를 클릭한 다음 성공 및 오류 파일의 위치를 지정합니다.
  15. Finish(완료)를 클릭합니다.
  16. 경고를 확인하고 진행할 준비가 되었다면 Yes(예)를 클릭합니다.
     
 

4단계. Data Loader로 삽입된 노트를 상위 레코드에 연결하기

 
노트 삽입을 마친 후에는 노트를 상위 레코드와 연결해야 합니다. 노트는 'Content'에 저장되어 있으므로 레코드를 'Content Document Link' 테이블에 삽입해야 합니다.
 
  1. 다음 열로 구성된 새로운 CSV 파일을 만듭니다. ContentDocumentId, LinkedEntityId, ShareType, Visibility.
  2. 노트 가져오기(3단계)의 성공 로그를 찾아서 새로운 파일의 ContentDocumentId 열을, 레코드를 연결하려는 노트에 대한 성공 파일의 ID 값으로 채웁니다.
  3. LinkedEntityId 열을 노트를 연결하려는 레코드의 ID로 채웁니다.
  4. ShareType과 Visibility 필드를 원하는 대로 채웁니다. 필요한 경우 다른 레코드에 대해서도 같은 과정을 반복한 다음 파일을 저장합니다. 참고: 'C' 유형은 지원되지 않으므로 표준 개체에 대해서는 'I' 또는 'V' 값만 지정할 수 있습니다. 이 기사에 삽입 파일의 예시가 첨부되어 있습니다. 이러한 필드와 그 함수에 입력할 수 있는 유효한 값에 대해서는 SOAP API 개발자 가이드의 자세한 내용은 ContentDocumentLink 섹션에서 확인하세요.
  5. Apex Data Loader를 실행합니다.
  6. Insert(삽입)을 클릭합니다.
  7. 로그인 자격 증명을 입력합니다.
  8. Next(다음)을 클릭합니다.
  9. Show all Salesforce objects(모든 Salesforce 개체 표시) 옆의 상자를 선택합니다.
  10. 사용 가능한 개체의 목록에서 Content Document Link(ContentDocumentLink)(컨텐츠 문서 링크)를 선택합니다.
  11. Browse...(찾아보기)를 클릭하고 이전 단계에서 만들어 둔 CSV 파일을 선택합니다.
  12. Next(다음)을 클릭합니다.
  13. 'Data Selection(데이터 선택)' 초기화 대화 상자가 나타나면 레코드 개수가 정확한지 확인한 다음 OK(확인)을 클릭합니다.
  14. 다음 화면에서 Create or Edit a Map(맵 만들기 또는 편집)을 클릭합니다.
  15. Auto-Match Fields to Columns(필드를 열에 자동 맞춤)를 클릭하거나 필드를 CSV 파일의 해당 열에 직접 일치시킬 수 있습니다.
  16. OK(확인)을 클릭해 진행합니다.
  17. 매핑이 정확한지 확인하고 Next(다음)을 클릭합니다.
  18. Browse...(찾아보기)를 클릭한 다음 성공 및 오류 파일의 위치를 지정합니다.
  19. Finish(완료)를 클릭합니다.
  20. 경고를 확인하고 진행할 준비가 되었다면 Yes(예)를 클릭합니다. 이제 상위 레코드 아래의 노트 관련 목록에 노트가 나타날 것입니다.
 

ContentNote 삽입 오류 문제 해결 팁


ContentNote 개체는 Upsert 호출을 허용하거나 승인하지 않으며 예컨대 다음과 같은 오류를 발생시킵니다.

웹 서비스 작업을 호출하는 동안 오류가 발생했습니다. upsert, 오류는 다음과 같습니다. UnexpectedErrorFault ApiFault exceptionCode='UNKNOWN_EXCEPTION'('165958568'로 끝날 수 있는 ErrorId 포함)

현재 ContentNote는 노트 파일 그 자체를 구문 분석하는 동안 문제가 발생할 경우 '노트를 저장하지 못했습니다'와 같은 일반적인 오류를 표시합니다. 이는 텍스트 본문(콘텐츠) 파일의 내용에 적절하게 이스케이프 처리되지 않은 특수 문자 등의 문제가 있음을 나타내는 경우가 많습니다.

또한 '노트를 저장할 수 없음: INVALID_CONTENT_TYPE' 오류의 경우 Sandbox 환경에서 2,500개 이상의 ContentNote 레코드를 삽입할 때 'Max number of Content Versions published per day(일일 게시 가능한 Content Versions의 최대 개수)' 한도를 초과할 경우에 발생할 수 있습니다.

Sandbox 조직의 한도 기본값은 2,500으로, 한도 기본값이 200,000개인 대부분의 프로덕션 조직에 비해 그 크기가 작습니다. .txt 또는 .html 파일에 대한 삽입 콘텐츠를 확인한 후 Sandbox에서 이 오류가 발생하는 경우, Salesforce 지원팀에 문의하여 한도 상향을 요청하세요
.
오류를 해결하려면 2단계에서 설명한 대로 영향을 받는 파일을 찾아 해당 특수 문자를 그에 대응하는 HTML 문자 코드로 바꿔야 합니다. 
 
Data Loader가 모든 삽입 대상 파일에 대해 오류를 보고하지만, 검사를 기반으로 일부 파일에 특수 문자가 없음을 확인할 수 있는 경우 다음 지침에 따라 영향을 받는 파일을 정확하게 파악하세요.
 
  1. Data Loader 배치 크기를 1로 설정합니다. 자세한 내용은 Data Loader 구성에서 확인하세요.
  2. 위 3단계를 따라 가져오기를 재시도합니다. 일부 파일은 성공적으로 가져올 수 있을 것입니다.
  3. 이 과정에서 오류가 발생한다면 가져오기에서의 오류 파일을 확인해 CSV 파일의 어떤 행에서 오류가 발생했는지 확인합니다.
  4. 오류 파일에서 어떤 행에 대해 '노트를 저장할 수 없습니다' 오류를 발생하는 경우, 그 행과 연결된 .txt 또는 .html 파일을 검토한 후 2단계에 설명된 대로 해당 파일의 특수 문자를 그에 대응하는 HTML 문자 코드로 바꿉니다.
  5. 다른 종류의 오류 메시지가 발생하는 경우 해당 메시지도 검토하고 해결합니다.
'Salesforce 도움말 문서를 검색하여 답변할 수 없는 오류를 해결하기 위해 도움이 필요하면 Salesforce 지원팀에 사례를 기록해 주세요.'
 
이제 위의 3단계에 따라 이전의 가져오기에서의 오류 파일을 CSV 가져오기 파일로 사용해서 가져오기를 재시도할 수 있습니다. 자세한 내용은 HTML 태그 또는 이스케이프 처리되지 않은 문자를 포함하는 노트 저장 시 오류 발생'에서 확인하세요.
 
최종 사용자가 'ContentNote' 개체에 레코드를 삽입하면 하위 'ContentVersion' 레코드가 자동으로 생성됩니다. 자세한 내용은 SOAP API 개발자 가이드의 ContentNote 개체 섹션을 확인하세요.
 
'ContentNotes'를 삽입할 때 최종 사용자가 CreatedById, CreatedDate 및/또는 LastModifiedDate와 같은 감사 필드를 설정하는 경우, 시스템에서는 올바른 감사 필드 데이터를 사용해 그에 대응하는 'ContentVersion' 레코드를 자동으로 생성해야 합니다. 그러나 Lightning Experience에서는 'ContentVersion'의 'Last Modified Date(마지막 수정 날짜)'가 'Last Modified Date(마지막 수정 날짜)'가 아닌 'Created Date(생성 날짜)'를 표시합니다. 향후 릴리스에서는 Lightning Experience의 이러한 동작을 변경하여 'Created Date(생성 날짜)' 대신 'Last Modified Date(마지막 수정 날짜)'를 올바르게 표시될 예정입니다.

'ContentNote' 삽입을 수행하지 않는 사용자에게 'OwnerId'를 설정할 경우, '사용자의 개인 라이브러리에 존재하는 문서는 항상 해당 사용자가 소유해야 합니다' 오류가 발생할 수 있습니다. 이 문제를 해결하려면 최신 버전의 Data Loader를 사용해서 Salesforce에 연결하세요.
 


참고 항목:
노트 작성 도구 'Notes' 및 'Files' 기능 사용시 고려 사항
일일 게시 가능한 'Content Versions'의 최대 개수 늘리기
Salesforce Classic에서 파일 액세스 권한 변경

Youtube 지원 동영상:
Data Loader로 노트 삽입하기
로컬 하드 드라이브의 노트 본문 파일 준비하기
Data Loader를 통해 삽입된 노트를 상위 레코드에 연결하기
 
Knowledge 기사 번호

000387816

 
로드 중
Salesforce Help | Article