EaserixDocs
DevelopersAPI referenceTasksImports

Upload a file that names several teams, one import per team

Step 1 of 3 for a file that holds several teams. Administrators only (`org.settings.manage`). multipart/form-data with the CSV in `file`, the `teamMap`, and optionally `column`, `source` and `namespace` as on `createImport`. The file is cut by team and each team's rows become an ordinary import in that team, so what an import promises (one team, a preview before it runs, a ledger that makes a re-run harmless, an undo) is unchanged. The imports of one upload share a `batchId`, and each is then previewed and committed with the routes of a single import. A part is a file of its own, so its rows are numbered within it, and a part that is the same as one imported before is recognised by `previousImport`. `teamMap` is a JSON object with one entry for every team the file names: the name as written in the file (case and spacing do not matter), and the id of the team its rows go to, or null to leave them out. A name the map does not mention is refused (`team_not_mapped`), because dropping rows by leaving them out of the map is how work is lost unnoticed. Several names may go to one team, and their rows are then one import, in file order. Teams are never created: a team the file names that the workspace does not have is left out until it exists in Accounts. A team the caller cannot reach is a 404. Everything is stored or nothing is. At most 50 teams, and a team holds at most 10 unfinished imports (409 with the `teamId`). A file that cannot be cut without changing it is refused with `not_splittable`.

View as Markdown
POST
/v1/imports/batches

Authorization

bearer
AuthorizationBearer <token>

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/imports/batches" \  -F file="string" \  -F teamMap="{\"Engineering\": \"5f0c0e0a-1c1b-4c55-9a0e-0d9f3c2a7b11\", \"Operations\": null}"
{  "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",  "teamColumn": "string",  "jobs": [    {      "import": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "teamId": "a4ede8ba-7c0a-4485-8763-cbd9b282fbec",        "source": "csv",        "namespace": "string",        "status": "uploaded",        "fileName": "string",        "fileSize": 0,        "totalRows": 0,        "createdCount": 0,        "skippedCount": 0,        "failedCount": 0,        "cancelRequested": true,        "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",        "createdAt": "2019-08-24T14:15:22Z",        "startedAt": "2019-08-24T14:15:22Z",        "finishedAt": "2019-08-24T14:15:22Z",        "retryAfter": "2019-08-24T14:15:22Z",        "undoneAt": "2019-08-24T14:15:22Z",        "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",        "undoableUntil": "2019-08-24T14:15:22Z",        "commentCount": 0,        "mapping": {          "v": 1,          "columns": {            "property1": "string",            "property2": "string"          },          "idColumn": "string",          "idAlias": "string",          "people": {            "property1": "string",            "property2": "string"          },          "strict": true,          "sprintDates": {            "property1": {              "start": "2019-08-24",              "end": "2019-08-24"            },            "property2": {              "start": "2019-08-24",              "end": "2019-08-24"            }          },          "linkColumns": [            "string"          ],          "markup": "none",          "commentFormat": "plain",          "completedFallback": "string",          "dateFormat": "iso",          "timezone": "Asia/Kolkata",          "labelSeparator": "str",          "status": {            "property1": {              "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",              "create": true,              "type": "backlog"            },            "property2": {              "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",              "create": true,              "type": "backlog"            }          },          "priority": {            "property1": 0,            "property2": 0          }        }      },      "file": {        "headers": [          "string"        ],        "rowCount": 0,        "sampleRows": [          [            "string"          ]        ],        "delimiter": "string",        "encoding": "utf-8",        "warnings": [          "string"        ]      },      "suggestedMapping": {        "v": 1,        "columns": {          "property1": "string",          "property2": "string"        },        "idColumn": "string",        "idAlias": "string",        "people": {          "property1": "string",          "property2": "string"        },        "strict": true,        "sprintDates": {          "property1": {            "start": "2019-08-24",            "end": "2019-08-24"          },          "property2": {            "start": "2019-08-24",            "end": "2019-08-24"          }        },        "linkColumns": [          "string"        ],        "markup": "none",        "commentFormat": "plain",        "completedFallback": "string",        "dateFormat": "iso",        "timezone": "Asia/Kolkata",        "labelSeparator": "str",        "status": {          "property1": {            "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",            "create": true,            "type": "backlog"          },          "property2": {            "stateId": "871bb69c-5872-42b2-88b0-72e9da663aaa",            "create": true,            "type": "backlog"          }        },        "priority": {          "property1": 0,          "property2": 0        }      },      "previousImport": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "finishedAt": "2019-08-24T14:15:22Z",        "createdCount": 0,        "namespace": "string"      },      "detected": {        "source": "linear",        "namespace": "string",        "notes": [          "string"        ]      }    }  ],  "leftOut": [    {      "team": "string",      "rows": 0,      "reason": "left_out"    }  ],  "warnings": [    "string"  ]}

Say which teams a file names

Before an upload, for a file that holds several teams (a Linear export of a whole workspace). Administrators only (`org.settings.manage`). multipart/form-data with the CSV in `file` and, optionally, `column`, the header of the column that names the team. Without `column` it is the `Team` column, and `teamColumn` is null when the file has none (a Jira file has none, but its Project column can be named). Nothing is stored. Each name in the file comes back with how many rows it has and `match`, the team of the workspace it most likely means: by team name, then by team key, ignoring case and spacing. `match` is null when nothing fits or when two teams fit, because Accounts allows two teams to share a name and a guess would put issues in a team nobody chose. Only teams the caller can reach are matched. Rows with no team are counted in `noTeamRows`.

Get an import's status and its row errors

Administrators only. Poll this while an import runs: the counts move as rows are written. `errors` holds the first 100 rows that could not be written (in row order) and `errorCount` the true total. An import in another workspace is a 404. `errors` also holds the rows the plan left out, which the worker saves when it starts (the upload is deleted when the job ends, so this is the only record of which rows and why). Notes, such as a value that was dropped from an issue that was still imported, are not rows left out and are not kept. At most 500 are saved, and when the plan had more, a last entry with code `more_problems` says how many are not listed. `errors=all` returns up to 10,000 instead of 100, for downloading them. `pendingPeople` lists the people the file named as assignee who were not members of the workspace, most issues first, with how many of this import's issues are still waiting for each. Those issues were created unassigned and are handed to the person when they are added to the workspace, so a person who has since joined is no longer listed. It is empty until the import has ended, and at most 50 are listed. `pendingPeopleTotal` and `pendingIssuesTotal` count everyone and every issue still waiting, however many are listed.