Bulk export tool

plans-img Available on all plans

deployment-img self-hosted deployments

Moving data from one Mattermost instance into another begins with exporting data to a JSONL file using the bulk loading feature. This tool is useful if you have created a server for a proof of concept, have created another server for production use, and now want to retain the history from the proof of concept instance.

You can export the following data types:

  • Teams

  • Channels (public, private, and direct)

  • Users

  • Users’ team memberships

  • Users’ channel memberships

  • Posts (messages in public or private channels and replies to those messages)

Bulk export data

  1. Create a full export file including attachments by running the mmctl export create – attachments command. See the Mattermost workspace migration documentation for details.

  2. While the job is running, you can check its status by running the mmctl export job show command.

  3. When the export job status is successful:

  1. Identify the name of the completed export file by running the mmctl export list command.

  2. Download the export file to your local machine by running the mmctl export download command.

At this time, the export supports attributes of the objects listed below. All Mattermost bulk export data files will begin with a Version object as the first line of the file. This indicates the version of the Mattermost bulk import file format with which the exported data is compatible.

You can export the following data types:

  • Teams

  • Channels (public, private, and direct)

  • Users

  • Users’ team memberships

  • Users’ channel memberships

  • Users’ notification preferences

  • Posts (regular, non-reply messages)

  • Posts’ replies and threads

  • Posts’ reactions

  • Custom emoji

  • Direct message channels

  • Direct message posts

Note

Configuration for data types such as exporting specific areas of the server, exporting additional types of posts, permissions schemes, file attachments, webhooks, and bot messages is not yet supported. Deleted objects are also not yet supported.

For requests to add additional attributes or objects to our exporter, please add a feature request on our feature idea forum.

Version object

Field name Type Description
type string The string "version"
version number The number 1.
info object Optional VersionInfo object

VersionInfo object

Field name Type Description
generator string The name of the tool this export was generated with. Well known tools are:
"mattermost-server" for the Mattermost Server.
"mmetl" for the Slack export converter "mmetl".
version string The version of the tool this export was generated with. This may contain multiple pieces of version info, separated by spaces. The first one should be a semantic version.
"7.6.0 (29bb1e53ef5a439c73065f47de2972f9bbcb09a4, enterprise: true)" is an example of such a version string.
created string The timestamp of the file creation. This should be formatted as an RFC 3339 timestamp. The nanosecond part is optional.
"2022-11-22T16:40:51.019582328+01:00"
additional any Any additional information the generator wants to include into the file header. May be omitted. Be aware that the size of each line is limited to a few MiB.

Team object

Field name Type Description
name string The team name.
display_name string The display name for the team.
type string The type of team. Will have one of the following values:
"O" for an open team
"I" for an invite-only team.
description string The team description.
allow_open_invite bool Whether to allow open invitations. Will have one of the following values:
"true"
"false"
scheme string The name of the permissions scheme that applies to this team.

Channel object

Field name Type Description
team string The name of the team this channel belongs to.
name string The name of the channel.
display_name string The display name for the channel.
type string The type of channel. Will have one the following values:
"O" for a public channel.
"P" for a private channel.
header string The channel header.
purpose string The channel purpose.
scheme string The name of the permissions scheme that applies to this team.

User object

Field name Type Description
username string The user’s username. This is the unique identifier for the user.
email string The user’s email address.
auth_service string The authentication service used for this user account. This field will be absent for user/password authentication.
"gitlab" - GitLab authentication.
"ldap" - LDAP authentication (Enterprise and Professional)
"saml" - Generic SAML based authentication (Enterprise)
"google" - Google OAuth authentication (Enterprise)
"office365" - Microsoft Office 365 OAuth Authentication (Enterprise)
auth_data string The authentication data if auth_service is used. The value depends on the auth_service that is specified.
The data comes from the following fields for the respective auth_services:
"gitlab" - The value of the Id attribute provided in the GitLab auth data.
"ldap" - The value of the LDAP attribute specified as the "ID Attribute" in the Mattermost LDAP configuration.
"saml" - The value of the SAML email address attribute.
"google" - The value of the OAuth Id attribute.
"office365" - The value of the OAuth Id attribute.
nickname string The user’s nickname.
first_name string The user’s first name.
last_name string The user’s last name.
position string The user’s position.
roles string The user’s roles.
locale string The user’s localization configuration.
use_markdown_preview bool "true" if the user has enabled markdown preview in the message input box.
use_formatting bool "true" if the user has enabled post formatting for links, emoji, text styles, and line breaks.
show_unread_section string "true" if the user has enabled showing unread messages at top of channel sidebar.
theme string The user’s theme. Formatted as a Mattermost theme string.
military_time string "true" if the user has enabled a 24-hour clock. "false" if using a 12-hour clock.
collapse_previews string "true" if user collapses link preview by default. "false" if user expands link previews by default.
message_display string The style the user prefers for displayed messages. Options are "clean" if the user uses the standard style or "compact" if the user uses compact style.
channel_display_mode string "full" if the users displays channel messages at the full width of the screen or "centered" if the user uses a fixed width, centered block.
tutorial_step string "1", "2", or "3" indicates which specified tutorial step to start with for the user. "999" skips the tutorial.
email_interval string Email batching interval to use during bulk import.
delete_at int64 Timestamp of when the user was deactivated.
teams array The teams which the user is member of. Is an array of UserTeamMembership objects.
notify_props object The user’s notify preferences, as defined by the UserNotifyProps object.

UserNotifyProps object

This object is a member of the User object.

Field name Type Description
desktop string Preference for sending desktop notifications. Will be one of the following values:
"all" - For all activity.
"mention" - Only for mentions.
"none" - Never.
desktop_sound string Preference for whether desktop notification sound is played. Will be one of the following values:
"true" - Sound is played.
"false" - Sound is not played.
email string Preference for email notifications. Will be one of the following values:
"true" - Email notifications are sent immediately.
"false" - Email notifications are not sent.
mobile string Preference for sending mobile push notifications. Will be one of the following values:
"all" - For all activity.
"mention" - Only for mentions.
"none" - Never.
mobile_push_status string Preference for when push notifications are triggered. Will be one of the following values:
"online" - When online, away or offline.
"away" - When away or offline.
"offline" - When offline.
channel string Preference for whether @all, @channel, and @here trigger mentions. Will be one of the following values:
"true" - Mentions are triggered.
"false" - Mentions are not triggered.
comments string Preference for reply mention notifications. Will be one of the following values:
"any" - Trigger notifications on messages in reply threads that the user starts or participates in.
"root" - Trigger notifications on messages in threads that the user starts.
"never" - Do not trigger notifications on messages in reply threads unless the user is mentioned.
mention_keys string Preference for custom non-case sensitive words that trigger mentions. Words are separated by commas.

UserTeamMembership object

Field name Type Description
name string The name of the team this user is a member of.
roles string The roles the user has within this team.
theme string The user’s theme for this team. Formatted as a Mattermost theme string.
channels array The channels within this team that the user is a member of. Listed as an array of UserChannelMembership objects.

UserChannelMembership object

Field name Type Description
name string The name of the channel in the parent team that this user is a member of.
roles string The roles the user has within this channel.
notify_props object The notify preferences for this user in this channel as defined by the ChannelNotifyProps object.
favorite boolean Whether the channel is marked as a favorite for this user. Will be one of the following values:
"true" - Yes.
"false" - No.

ChannelNotifyProps object

This object is a member of the ChannelMembership object.

Field name Type Description
desktop string Preference for sending desktop notifications. Will be one of the following values:
"default" - Global default.
"all" - For all activity.
"mention" - Only for mentions.
"none" - Never.
mobile string Preference for sending mobile notifications. Will be one of the following values:
"default" - Global default.
"all" - For all activity.
"mention" - Only for mentions.
"none" - Never.
mark_unread string Preference for marking channel as unread. Will be one of the following values:
"all" - For all unread messages.
"mention" - Only for mentions.

Post object

Field name Type Description
team string The name of the team that this post is in.
channel string The name of the channel that this post is in.
user string The username of the user for this post.
message string The message that the post contains.
props object The props for a post. Contains additional formatting information used by integrations and bot posts. For a more detailed explanation see the message attachments documentation.
create_at int The timestamp for the post, in milliseconds since the Unix epoch.
reactions array The emoji reactions to this post. Will be an array of Reaction objects.

Reply object

Field name Type Description
user string The username of the user for this reply.
message string The message that the reply contains.
create_at int The timestamp for the reply, in milliseconds since the Unix epoch.

Reaction object

This object is a member of the Post object.

Field name Type Description
user string The username of the user for this reply.
emoji_name string The emoji of the reaction.
create_at int The timestamp for the reply, in milliseconds since the Unix epoch.

Emoji object

Field name Type Description
name string The emoji name.
image string The path (either absolute or relative to the current working directory) to the image file for this emoji.

DirectChannel object

Field name Type Description
members array List of channel members.
favorited_by array List of channel members who have favorited the direct channel.
header string The channel header.

DirectPost object

Field name Type Description
user string The username of the user for this post.
message string The message that the post contains.
create_at int The timestamp for the post, in milliseconds since the Unix epoch.