Atesen Customer Import for Jira Service Management documentation

Requirements

• Jira Cloud with Jira Service Management, and a site administrator who can install apps. If Atlassian asks for approval of app permissions, an administrator must complete it.
• The Jira Administrators global permission for the person who runs imports. Being a service project administrator, agent or portal customer alone is not enough.
• An active app licence or trial. Running imports requires one.
• The app is an administration page under Jira Settings, Apps. It is not part of the customer portal or help centre.

Prepare the CSV

Save a plain-text UTF-8 CSV with a header row, using a comma or a semicolon as the column delimiter. A UTF-8 byte order mark is supported and blank lines are skipped. Use at most 10,000 data rows per job and split larger files.

• email (required): one address per row, at most 254 characters. Spaces around it are trimmed and addresses are lowercased. Empty or invalid addresses are reported in Preview and excluded.
• name (optional): used as the display name of a new customer. If it is blank, the part of the email before the @ is used.
• organizations (optional): several names in one cell are separated with ; or |. Each name can have at most 200 characters. Organization names cannot themselves contain ; or |.
• Header names need not be exact: the app suggests the columns and you can pick them by hand. Extra columns are not imported, and there is no CSV field for a project key or service space.
• Wrap a field in double quotes when it contains the delimiter, a line break or a double quote, and double any quote inside it. Malformed quoting and rows with too many columns are rejected before the import.

Run an import

• Open Jira Settings, Apps, and select the app. It opens on Upload, followed by Map, Preview, Run and Results; History lists recent imports.
• Upload: choose your CSV file.
• Map: select the email column and the optional name and organizations columns, tick the service spaces that should get the customers and decide whether missing organizations should be created.
• Preview: check valid rows, invalid and empty emails, duplicates, matched organizations and organizations to create. Download the errors CSV if there are problems, correct your file and upload it again. Only the first occurrence of an email in a file is used.
• Start import: this writes to Jira. It creates missing customers, optionally creates organizations and adds the requested memberships and service-space access. Run a small file first.
• The job runs in the background. You can close the tab and return to History, pause it, and resume paused or stalled jobs.

Check every result

After the run, download the results CSV from Results or from History. Its columns are row, email, status, accountId, organizations_added, organizations_failed, service_spaces_added, error_code and error_message. Service spaces appear as IDs.

• created or existing: a customer was created or reused. Also check the organization and service-space columns.
• created_partial or existing_partial: the customer is ready but some organization or service-space work is incomplete. Read organizations_failed and the error columns.
• failed: read the error code and message and correct the input or permissions before importing again.
• failed_retryable: a temporary error remains. Resume the paused job to retry those rows while keeping the work that is done.

Limits

• Jira Service Management Cloud only. Customer Service Management profiles are not managed.
• At most 10,000 data rows per job, and at most 500 validation problems are kept per job; preview again after correcting to find the rest.
• No undo. The app does not delete customers or organizations, remove memberships or merge duplicate organizations, so review existing duplicate organization names in Jira first.
• No invitation emails are sent by the app.
• Job rows and results are kept in Atlassian Forge storage and scheduled for cleanup 30 days after the job was created. Download reports before then.

Troubleshooting

• The app is missing from Apps: check that it is installed on the right site and that you have the Jira Administrators global permission.
• API_403_ADMIN_REQUIRED: check the Jira Administrators global permission and that the app permissions were approved.
• EXISTING_NOT_LINKED: the customer already exists but Jira did not return the account, so its memberships were not added. Inspect them before retrying.
• A job is paused: temporary Jira errors and rate limits can pause a job. Resume the same job instead of starting an overlapping import.
• The file is rejected: repair the quoting or column problem named in the message and choose the file again.

Data handling summary

The app runs on Atlassian Forge and has no servers of its own. The rows of a job and its results are stored in Forge storage for 30 days and then deleted. The application privacy page has the full statement.

User guide for Atesen Customer Import

Atesen Software security policy