# Import Report

When you set `includeReport` to `true` on the [Create Import Job](/apis/v4/knowledge/contentmgr/api-bundled#operation/createImportJob) request, the service generates a structured report once the job concludes. The report summarizes which resources were created, updated, deleted, or failed, and includes the eGain-assigned IDs for each — useful for post-import work that needs to map source paths to the resulting resource IDs.

## Locating the Report

Once the job concludes, the report's location is returned as `reportFolderLocation` on the [Get Job Status](/apis/v4/knowledge/contentmgr/api-bundled#operation/getImportStatus) response, alongside the job's `logFileLocation`:

```json
{
  "status": "Successful",
  "jobType": "Import",
  "progress": { "processed": 5000, "total": 5000, "percentage": 100 },
  "logFileLocation": "s3://mybucket/ingestion-execution/9B2E4C7A-1D3F-4A82-B5E6-7C8D9E0F1A2B_execution_log.json",
  "reportFolderLocation": "s3://mybucket/ingestion-execution/9B2E4C7A-1D3F-4A82-B5E6-7C8D9E0F1A2B_report/",
  "startTime": "2024-03-01T10:00:00.000Z",
  "completionTime": "2024-03-01T11:15:00.000Z",
  "results": { "successful": 4985, "warnings": 10, "errors": 5 }
}
```

`reportFolderLocation` is only present when the job was created with `includeReport: true`. The report is written to the same data source the content package was imported from, under an `ingestion-execution/{packageId}_report/` path:

- **Amazon S3**: `s3://<bucket>/ingestion-execution/{packageId}_report/`
- **SFTP**: `sftp://<host>/ingestion-execution/{packageId}_report/`


See [Checking the Status of an Import or Validation Job](/developer-portal/guides/ingestion/ingestion-get-status-job) for more on polling job status.

## Report Scope

The report reflects only the resource types that had changes in your import input. A resource type (folders, articles, topics, or portals) is counted in `manifest.json` and given its own file (`folders.json`, `articles.json`, `topics.json`, `portals.json`, `failed-resources.json`) only if the job attempted at least one resource of that type — if your `knowledgehub.json` doesn't include topic or portal changes, for example, they simply won't appear in the manifest counts or produce a file, the same way folders or articles wouldn't if your input omitted them.

The [Successful Import](#successful-import) example below includes all four resource types. The [Partial Import](#partial-import) and [Failed Import](#failed-import) examples only exercise folders and articles, so no `topics.json` or `portals.json` appears in those — not because those resource types are out of scope, but because those particular imports didn't include topic or portal changes. See the [Data Import Format Guide](/developer-portal/guides/ingestion/data-import-format-guide) for the full set of resources you can import via `knowledgehub.json`.

If a job fails before any content is processed, only `manifest.json` is produced — see [Failed Import](#failed-import) below.

## Key Fields

Most fields in the report are self-explanatory from their names and the examples below. A couple are worth calling out:

- **`statusCode`** *(failed resources only)*: Reflects the nature of the failure using standard HTTP status codes — for example, `423 Locked` is reported when an article is checked out by another user.
- **`firstFailedAt` / `lastFailedAt`** *(failed resources only)*: These track a resource's failure history across retries, not the timing of the run that produced the report. `firstFailedAt` is set the first time the resource enters the failure ledger and is never overwritten on subsequent retries; `lastFailedAt` is the most recent failure time, and `statusHistory[].occurrences` counts how many attempts have failed. Because `firstFailedAt` can come from an earlier retry attempt, it may fall before the report's own `startedAt`.
- **`externalIdStatus`** *(articles, folders, and failed resources)*: Indicates what happened to the `externalId` you supplied for the resource; the field is absent if you didn't supply one.
  - `unchanged`: your ID was already on the resource — nothing needed to change.
  - `set`: your ID was written onto the resource during this run.
  - `collision`: your ID is already recorded on a different eGain resource, so the write was refused; `collisionWith` names the conflicting resource.
  - `skip-error`: the assignment couldn't be completed due to a transient issue (throttling, a 5xx, a session problem) or a permissions gate — not a problem with your data.
  - `unset`: your ID isn't recorded on any resource in eGain, either because the resource was never created or the assignment itself failed; this value only appears in `failed-resources.json`.
- **`finalOutcome`** *(failed resources only)*: The service retries a failed operation before giving up on it. `finalOutcome` reflects the result after both the first and the last retry attempt failed — for example, `still-failed` means the resource failed on its first attempt and remained failed through its last retry.


The examples below show the report contents for a successful, partial, and failed import job.

## Successful Import

In this example, the import job completed successfully. Two folders were created, two articles were checked in as drafts (with warnings) because a review workflow applies to their destination folder, one topic was created, and one portal was created.

### manifest.json

```json
{
  "jobId": "10fd4b35-5b4b-4d21-abee-ba3f062214ce",
  "jobType": "import",
  "domain": "ai.egain.cloud",
  "department": {
    "departmentId": 1015,
    "name": "Purple Nile Retail",
    "statusCode": 200,
    "errorMessage": null
  },
  "startedAt": 1788337729496,
  "completedAt": 1788337740543,
  "outcome": "success",
  "counts": {
    "folders": {
      "attempted": 2,
      "created": 2,
      "updated": 0,
      "deleted": 0,
      "failed": 0,
      "warnings": 0
    },
    "articles": {
      "attempted": 2,
      "published": 0,
      "drafts": 2,
      "deleted": 0,
      "failed": 0,
      "warnings": 2
    },
    "topics": {
      "attempted": 1,
      "created": 1,
      "updated": 0,
      "failed": 0
    },
    "portals": {
      "attempted": 1,
      "created": 1,
      "updated": 0,
      "failed": 0
    }
  }
}
```

### articles.json

```json
[
  {
    "path": "Purple Nile Retail - Sample Data/Account Management/Password Recovery",
    "articleId": 203400000012806,
    "status": "draft",
    "sourceFilePath": "content/password-recovery.html",
    "languages": [
      "en-US"
    ],
    "lastModified": "2026-09-02T08:28:58.000Z",
    "externalId": "pnr-password-recovery",
    "externalIdStatus": "unchanged",
    "warnings": [
      "Checked in as a draft (en-US): a review workflow applies to this article, and the ingestion import user can move it to Review but not to Published. Publish it from the eGain Knowledge Console."
    ],
    "lastUpdatedEpoch": 1788337740237
  },
  {
    "path": "Purple Nile Retail - Sample Data/Account Management/Profile Settings",
    "articleId": 203400000012805,
    "status": "draft",
    "sourceFilePath": "content/profile-settings.html",
    "languages": [
      "en-US"
    ],
    "lastModified": "2026-09-02T08:28:59.000Z",
    "externalId": "pnr-profile-settings",
    "externalIdStatus": "unchanged",
    "warnings": [
      "Checked in as a draft (en-US): a review workflow applies to this article, and the ingestion import user can move it to Review but not to Published. Publish it from the eGain Knowledge Console."
    ],
    "lastUpdatedEpoch": 1788337740232
  }
]
```

### folders.json

```json
[
  {
    "path": "Purple Nile Retail - Sample Data",
    "folderId": 203400000012803,
    "status": "created",
    "lastModified": null,
    "externalId": "pnr-sample-data-root",
    "externalIdStatus": "unchanged",
    "warnings": [],
    "lastUpdatedEpoch": 1788337737757
  },
  {
    "path": "Purple Nile Retail - Sample Data/Account Management",
    "folderId": 203400000012804,
    "status": "created",
    "lastModified": null,
    "externalId": "pnr-account-management",
    "externalIdStatus": "unchanged",
    "warnings": [],
    "lastUpdatedEpoch": 1788337737815
  }
]
```

### topics.json

```json
[
  {
    "path": "Credit Card and Payments",
    "topicId": 654600000003540,
    "status": "created",
    "lastModified": "2026-09-02T08:29:00.000Z",
    "lastUpdatedEpoch": 1788337739100
  }
]
```

### portals.json

```json
[
  {
    "path": "Purple Nile Retail Support Portal",
    "portalId": 654600000002041,
    "status": "created",
    "lastModified": null,
    "lastUpdatedEpoch": 1788337740500
  }
]
```

## Partial Import

In this example, one folder was updated and two of three articles were published successfully. The third article failed because it was checked out by another user, so it is listed in `failed-resources.json` instead of `articles.json`.

### manifest.json

```json
{
  "jobId": "ff5c982f-c6b4-4a59-afef-41cd54b2635d",
  "jobType": "import",
  "domain": "ai.egain.cloud",
  "department": {
    "departmentId": 999,
    "name": "Purple Nile Retail",
    "statusCode": 200,
    "errorMessage": null
  },
  "startedAt": 1788340203227,
  "completedAt": 1788340208655,
  "outcome": "partial",
  "counts": {
    "folders": {
      "attempted": 1,
      "created": 0,
      "updated": 1,
      "deleted": 0,
      "failed": 0,
      "warnings": 0
    },
    "articles": {
      "attempted": 3,
      "published": 2,
      "drafts": 0,
      "deleted": 0,
      "failed": 1,
      "warnings": 0
    }
  }
}
```

### articles.json

```json
[
  {
    "path": "Purple Nile Retail - Sample Data/Credit Cards & Payments/E-Gift Cards",
    "articleId": 203400000003750,
    "status": "published",
    "sourceFilePath": "content/e-gift-cards.html",
    "languages": [
      "en-US"
    ],
    "lastModified": "2026-09-02T09:07:23.000Z",
    "externalId": "pnr-egift-cards",
    "externalIdStatus": "unchanged",
    "warnings": [],
    "lastUpdatedEpoch": 1788340205492
  },
  {
    "path": "Purple Nile Retail - Sample Data/Credit Cards & Payments/Online Payments",
    "articleId": 203400000003751,
    "status": "published",
    "sourceFilePath": "content/online-payments.html",
    "languages": [
      "en-US"
    ],
    "lastModified": "2026-09-02T09:07:23.000Z",
    "externalId": "pnr-online-payments",
    "externalIdStatus": "unchanged",
    "warnings": [],
    "lastUpdatedEpoch": 1788340205493
  }
]
```

### folders.json

```json
[
  {
    "path": "Purple Nile Retail - Sample Data/Credit Cards & Payments",
    "folderId": 203400000003743,
    "status": "updated",
    "lastModified": "2026-09-02T08:59:05.000Z",
    "externalId": "pnr-credit-cards-payments",
    "externalIdStatus": "unchanged",
    "warnings": [],
    "lastUpdatedEpoch": 1788340205740
  }
]
```

### failed-resources.json

```json
[
  {
    "domain": "ai.egain.cloud",
    "path": "Purple Nile Retail - Sample Data/Credit Cards & Payments/Cashback Rewards",
    "resourceType": "article",
    "resourceId": 203400000003745,
    "operation": "upsert",
    "status": "failed",
    "statusCode": 423,
    "errorMessage": "Article is locked/checked out by another user (id=1, name=Partition Administrator). Release the checkout in eGain and re-run the import.",
    "sourceFilePath": "content/cashback-rewards.html",
    "primaryLanguage": "en-US",
    "allLanguages": [
      "en-US"
    ],
    "externalId": "pnr-cashback-rewards",
    "externalIdStatus": "unset",
    "firstFailedAt": 1788340042294,
    "lastFailedAt": 1788340208329,
    "finalOutcome": "still-failed",
    "statusHistory": [
      {
        "firstAt": 1788340042294,
        "at": 1788340208329,
        "occurrences": 2,
        "status": "failed",
        "statusCode": 423,
        "errorMessage": "Article is locked/checked out by another user (id=1, name=Partition Administrator). Release the checkout in eGain and re-run the import."
      }
    ],
    "lastUpdatedEpoch": 1788340208329
  }
]
```

## Failed Import

In this example, the job failed outright because the target department does not exist, so no folders or articles were processed. Only `manifest.json` is generated for the report.

### manifest.json

```json
{
  "jobId": "5a695057-69f1-4223-991f-5beea9f2ae56",
  "jobType": "import",
  "domain": "ai.egain.cloud",
  "department": {
    "departmentId": null,
    "name": "Purple Nile Retail - APAC",
    "statusCode": null,
    "errorMessage": "Department 'Purple Nile Retail - APAC' does not exist"
  },
  "startedAt": 1788344167941,
  "completedAt": 1788344170193,
  "outcome": "failed",
  "counts": {}
}
```