Bulk Export Tool

Data from one Mattermost instance into another can be exported in the 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)
  • Users
  • Users’ Team memberships
  • Users’ Channel memberships
  • Posts (Posts in the Public/Private channels and also replies to those posts)

Bulk export data

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)
  • Users
  • Users’ Team memberships
  • Users’ Channel memberships
  • Users’ notification preferences
  • Posts (regular, non-reply posts)
  • Posts’ Replies
  • Posts’ Reactions
  • Custom Emoji
  • Direct Message Channels
  • Direct Message Posts

Configuration for exporting specific areas of the server, exporting additional types of posts, permissions schemes, file attachments, webhooks and bot messages are 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.

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 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 (E10 and E20)
"saml" - Generic SAML based authentication (E20)
"google" - Google OAuth authentication (E20)
"office365" - Microsoft Office 365 OAuth Authentication (E20)
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" is 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.

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 channelas 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.
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.
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.

Running the bulk export command

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/bin.
  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 ./mattermost export bulk file.json --all-teams

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

  1. Retrieve your file from the location you specified.