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

  • Threaded discussions

  • Channels (public, private, and direct)

  • Users

  • Users’ team memberships

  • Users’ channel memberships

  • Users’ custom status

  • Direct message and group message channels

  • Direct message and group message channels’ read/unread status

  • 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 data 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.

Note

From Mattermost v6.0, this command has been deprecated in favor of mmctl export commands as the supported way to export data out of Mattermost.

The export command runs in the CLI. It has permissions to access all information in the Mattermost database.

To run the export command:

  1. Navigate to the directory where the Mattermost server is installed. On a default install of Mattermost, the directory is /opt/mattermost.

  2. Run the following command to extract data from all teams on the server. Note that you can change the file name and specify an absolute or relative path to dictate where the file is exported:

    sudo -u mattermost bin/mattermost export bulk file.json --all-teams

    sudo -u mattermost bin/mattermost export bulk /home/user/bulk_data.json --all-teams

  3. Retrieve your file from the location you specified.

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

  • Threaded discussions

  • Channels (public, private, and direct)

  • Users

  • Users’ team memberships

  • Users’ channel memberships

  • Users’ notification preferences

  • Posts (regular, non-reply messages)

  • Posts’ replies and threads in public or private channels

  • Posts’ reactions

  • Custom emoji

  • Direct message and group message channels

  • Direct message and group message channels’ read/unread status

  • Direct message posts

  • Roles

  • Permissions schemes

Note

Configuration for data types such as exporting specific areas of the server, exporting additional types of posts, 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)
"entra id" - Microsoft Entra ID 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.
mention_count int64 The mention preferences for this user in this channel as defined by the ChannelMentionCount object.
mention_count_root int64 The mention preferences for this user in this channel as defined by the ChannelMentionCountRoot object.
urgent_mention_count int64 The mention preferences for this user in this channel as defined by the UrgendMentionCount object.
msg_count int64 The mention preferences for this user in this channel as defined by the MsgCount object.
msg_count_root int64 The mention preferences for this user in this channel as defined by the MsgCountRoot object.
last_viewed_at int64 The mention preferences for this user in this channel as defined by the LastViewedAt object.

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.