The Relativity Short Message Format

When managing workflows containing short message data, like enterprise chats, SMS, or social media applications, the Relativity Short Message Format (RSMF) allows you to efficiently search, review and produce important short message data. A RSMF file is an RFC 5322 (Internet Message Format) standards compliant file that encapsulates normalized short message data. There are currently over 75 different chat applications that have been converted to RSMF within RelativityOne. Almost any data that resembles a chat or conversation can be converted into an RSMF.

To begin viewing short message data in Relativity, you must create an RSMF file from the database export of the chat platform. The chat data can be accessed directly from the application via an API or it can be received as an exported file such as a .json, xmls, etc. When using Relativity’s Collect for direct access, you can automatically convert chat data to an RSMF file and process it into Relativity. For cases where you receive raw export files from chat applications, you can convert the exports to an RSMF file for Slack in Relativity. To learn more about supported file types, visit Supported file types for processing.

Relativity provides developer tools to complete RSMF file creation. You may find partners on the Relativity App Hub that also offer RSMF creation services. To learn more, visit Creating an RSMF File.

Once you’ve generated the files, the recommended workflow is to use Processing to ensure attachments maintain the proper relationship. You can also import the attachments separately and overlay the relationship to ingest an RSMF file into Relativity in order for attachments to display in-line in our Short Message Viewer, and to ensure those attachments are associated with the correct messages. To learn more, visit RelativityOne Staging Explorer.

Finally, you will need to either use Processing or import the attachments separately and overlay the relationship to ingest an RSMF file into Relativity in order for attachments to display in-line in our Short Message Viewer, and to ensure those attachments are associated with the correct messages. To learn more, visit Processing an RSMF file.

See these related pages:

RSMF 2.0 functionality

The second version of RSMF incorporates changes from several chat applications. These updates are intended to continue to enrich the data captured within RSMF, as well as ensure that the Relativity Short Message Format continues support for key features of many chat platforms. RSMF 2.0 and RSMF 1.0 are compatible with Relativity. The following features are available in RSMF 2.0:

Support for read receipts.
Support for the direction of each message sent.
Support for history events, which in some chat platforms indicate if someone reviewed previous communication with the chat after a message was received.
Support for custom platform icons beyond what Relativity supports out of the box.

RSMF structure

The RSMF follows an email structure by containing a header, body, and attachment:

Header—contains metadata for the entire RSMF at a file level. For example, this might include the number of messages or applications within the file. This data can be mapped as fields and used in search, review, and production. It is generated at the time of file creation.
Body—contains all the extracted text. Other events in the Extracted Text Viewer, that are not messages, such as conversations and names of attachments, can be added here as well. This will be used for searching and available in the Extracted Text Viewer. This text is generated by the files and not Relativity.
Attachment—contains zipped attachments and metadata stored in a .json file called rsmf_manifest.json at the root level. The zipped attachments should include any file attachment included in the conversation. This may include avatars, images, videos, or Microsoft Office files. The rsmf_manifest.json will contain individual message metadata stored following the structure detailed below. You can see this metadata in the Viewer while hovering over specific messages. Attachments are collected and zipped at the time of file creation.

Note: Individual message metadata, such as time stamps per message or the sender of a specific message is stored in the rsmf_manifest.json and is not currently visible outside of the Viewer. This data is not processed and cannot be searched at this time.

The RSMF is essentially a .zip, which is wrapped in a traditional .eml file. The header has one required field, X-RSMF-Version, and the others are optional.

Note: There are five fields below were added to RSMF 2.0 and not supported in RSMF 1.0. These five fields are supported in processing, search, the Viewer, production, and export. These fields are not supported with RSMF Slicing.

Header	RSMF 1.0	RSMF 2.0	Description
X-RSMF-Version	√ Required	√ Required	The version of the RSMF specification that the file adheres to.
X-RSMF-Generator	√ Optional	√ Optional	Identifies the author of the RSMF file.
X-RSMF-BeginDate	√ Optional	√ Optional	The timestamp (ISO8601) of the earliest short message event within the file. If there is no Sent Date handler X-RSMF-BeginDate will map to that field. If Sent Date does exist, X-RSMF-BeginDate will overwrite the value in field.
X-RSMF-EndDate	√ Optional	√ Optional	The timestamp (ISO8601) of the latest short message event within the file. If there is no Last Modified header X-RSMF-EndDate will map to that field.
X-RSMF-EventCount	√ Optional	√ Optional	The number of short message events captured within the file.
X-RSMF-Application		√ Optional	This is used to identify source of the data, which is intended to be ambiguous. For example, it could be the application of the data contained in the RSMF file. The intent with this field is to allow for better sorting of messages in the document list through a long text field.
X-RSMF-Custodian		√ Optional	This field is used to identify from whom the data was collected from. The intent with this field is to allow for better sorting of messages in the document list through a long text field.
X-RSMF-Participants		√ Optional	This field can be used to identify a string of names that are present in the conversation in the RSMF file. The intent with this field is to allow for better sorting of messages in the document list through a long text field.
X-RSMF-AttachmentCount		√ Optional	This field should be a number that is a sum of all of the attachments present in the RSMF. The intent with this field is to allow for better sorting of messages in the document list through a long text field.
X-RSMF-EventCollectionID		√ Optional	This field should be a unique ID that is to be used to help keep many RSMFs from a single conversation together. The intent with this field is to allow for better sorting of RSMFs in a document list to group parent RSMFs to the same conversation, if conversations or RSMFs are broken up for review purposes prior to being put into Relativity.

Since the RSMF file type is an open format, custom headers are supported. You can add custom headers to an RSMF file and ingest them using Processing by following the X-RSMF-* naming format. For more information, see Processing an RSMF file.

Example RSMF file

The following code sample shows an RSMF file that includes all information required before it is ingested using Processing.

X-RSMF-Version: 2.0.0
			X-RSMF-Generator: Relativity
			X-RSMF-BeginDate: 2010-02-18T10:05:11.0000000Z
			X-RSMF-EndDate: 2011-01-26T13:33:20.0000000Z
			X-RSMF-EventCount: 4662
			To: Keith Kaminski, Karl Knoernschild, Jim Witte
			Content-Type: multipart/mixed; boundary="_RSMF_Boundary_Delimiter_"
			MIME-Version: 1.0
 
 
			--_RSMF_Boundary_Delimiter_
			Content-Type: text/plain; charset="us-ascii"
			Content-Transfer-Encoding: quoted-printable
 
			You there?
			Yeah.
 
 
 
			--_RSMF_Boundary_Delimiter_
			Content-Type: application/zip; name="rsmf.zip"
			Content-Disposition: attachment; filename="rsmf.zip"
			Content-Transfer-Encoding: base64
 
			BASE64 encoded RSMF.ZIP goes here
 
 
		--_RSMF_Boundary_Delimiter_--

rsmf_manifest.json file

The rsmf_manifest.json file is a .json file that describes short message activity. The root of a manifest file has a version, a list of participants, a list of conversations, and a list of events.

{  
			"version":"2.0.0",
			"participants":"...",
			"conversations":"...",
			"events":"..."
		}

Name	RSMF 1.0	RSMF 2.0	Type	Description
version	√ Required	√ Required	string	The version of the RSMF specification that the file adheres to.
participants	√ Required	√ Required	array	An array of participants. A participant is someone who has participated in at least one of the conversations described in the manifest. See Participants for more details.
conversations	√ Required	√ Required	array	An array of conversations. A conversation is a time-bound set of short message events that occur on a specific platform, such as Slack, Bloomberg, or SMS. See Conversations for more details.
events	√ Required	√ Required	array	An array of events. An event is any discrete activity that can happen within the confines a conversation. See Events for more details.
eventcollectionid		√ Optional	string	This field should be a unique ID that is used to help keep many RSMFs from a single conversation together. The intent with this field is to allow for better sorting of RSMFs in a document list to group parent RSMFs to the same conversation, if conversations, or RSMFs, are broken up for review purposes prior to being put into Relativity.

Participants

A participant is someone who has participated in at least one of the conversations described in the manifest file. At least one participant is required for an RSMF file to be valid.

[  
			{  
			"id":"P1",
			"display":"Keith Kaminski",
			"avatar":"kk.png",
			"email":"keith.kaminski@relativity.com",
			"custom":[  
			{  
			"name":"Employer",
			"value":"Relativity"
			},
			{  
			"name":"Department",
			"value":"Engineering"
			}
			]
			}
			]

Name	RSMF 1.0	RSMF 2.0	Type	Description
id	√ Required	√ Required	string	Uniquely identifies a participant within the manifest file.
display	√ Required	√ Optional	string	Display value for the participant.
avatar	√ Optional	√ Optional	string	The name of a file within the rsmf.zip, including any extension that contains an image to display for the avatar for the participant.
email	√ Optional	√ Optional	string	The primary email address of the participant.
account_id		√ Optional	string	The primary ID that distinguishes the participant in that application. For example, this could be a phone number for texts or handles for social media.
custom	√ Optional	√ Optional	object	An array of optional name/value objects that can be used to store additional metadata about the participant.

Conversations

A conversation is a time-bound set of short message events that occur on a specific platform, such as Slack, Bloomberg, or SMS. Conversations either have a fixed set of participants for their entire duration, such as with SMS messages, or can change over time, such as with a Slack channel or Bloomberg room. At least one conversation is required for an RSMF file to be valid.

[  
			{  
			"id":"C1",
			"display":"Keith and Karl",
			"platform":"SMS",
			"type":"direct",
			"participants":[  
			"P1",
			"P2"
			],
			"custom":[  
			{  
			"name":"Source",
			"value":"Keith's iPhone"
			}
			]
			}
			]

Name	RSMF 1.0	RSMF 2.0	Type	Description
id	√ Required	√ Required	string	Uniquely identifies a conversation within the manifest file.
display	√ Required	√ Optional	string	Display value for the conversation.
platform	√ Required	√ Required	string	The name of the messaging platform from which the conversation originated.
type	√ Required	√ Required	string	The type of the conversation. Valid values are: "direct" "channel" "direct": Indicates the participants are fixed for the duration of the conversation. "channel": Indicates that participants may enter and leave the conversation at various points in time.
participants	√ Required	√ Optional	array	The participants included in the conversation. Each participant must map back to the id of a participant defined in the root of the manifest. The participant list has different meanings depending the type of the conversation: When the type is "direct", this indicates all of the participants that took part in the conversation. When the type is "channel", this indicates only the participants who were in the conversation at the time of the earliest event for that conversation within the manifest file.
custodian		√ Optional	string	The ID of a participant who was the source of the conversation. This must map back to one of the participants in the conversation.
custom	√ Optional	√ Optional	object	An array of optional name/value objects that can be used to store additional metadata about the conversation.
icon		√ Optional	string	The name of a file within the rsmf.zip, including any extension, that contains an image to display for the icon for the conversation. We expect this icon to be the logo for the platform the data was pulled from. The recommended image size for an icon is no larger than 28 by 28 pixels, and it should be either a .png or .jpeg file.

Events

An event is a discrete activity that can happen within the confines a conversation, such as a message or a join/leave notification. At least one event is required for an RSMF file to be valid.

[
			{
			"id":"m2",
			"type":"message",
			"parent":"m1",
			"body":"Looks good!",
			"participant":"P1",
			"conversation":"C1",
			"deleted":false,
			"importance":"normal",
			"timestamp":"2018-09-11T09:55:00Z",
			"reactions":[
			{
			"value":"thumbs up",
			"count":2,
			"participants":[
			"P1",
			"P2"
			]
			}
			],
			"attachments":[
			{
			"id":"partyon.png",
			"display":"partyon.png",
			"size":4254
			}
			],
			"edits":[
			{
			"participant":"P1",
			"timestamp":"2018-09-12T12:53:00Z"
			}
			],
			"custom":[
			{
			"name":"GPS",
			"value":"41 24.2028, 2 10.4418"
			}
			]
			}
		]

Name	RSMF 1.0	RSMF 2.0	Type	Description
id	√ Optional	√ Optional	string	Uniquely identifies an event within the conversation. An event only needs to have an identifier if it is part of a thread.
type	√ Required	√ Required	string	Defines the type of event. Valid values are: "message" "disclaimer" "join" "leave"
parent	√ Optional	√ Optional	string	Identifies the parent event of the event. This needs to be set if the event is a message which is a part of a thread. Parent must map back to the id of another event.
body	√ Optional	√ Optional	string	Content associated with the event. Not all event types require a body. For a message type, this would be the text of the message. If not included, the default value is assumed to be an empty string.
participant	√ Required	√ Optional	string	The participant that is the source of the event. This must map to the ID of a participant defined in the root of the manifest.
timestamp	√ Required	√ Optional	string	The time stamp (ISO8601) of when the event occurred.
conversation	√ Required	√ Optional	string	Identifies the conversation in which the event occurred. This must map back to the ID of a conversation.
deleted	√ Optional	√ Optional	bool	Identifies whether a message has been deleted. If not included, the default value is assumed to be false.
importance	√ Optional	√ Optional	string	Sets an importance value for the message. Valid values are: "normal" "high" If not included, the default value is assumed to be "normal."
reactions	√ Optional	√ Optional	array	An array of reactions associated with the event. See the Reaction section for more information.
attachments	√ Optional	√ Optional	array	An array of attachments associated with the event. See the Attachment section for more information.
edits	√ Optional	√ Optional	array	An array of edits that have been made to the event. See the Edits section for more information.
custom	√ Optional	√ Optional	object	An array of optional name/value objects that can be used to store additional metadata about the event.
direction		√ Optional	string	Valid strings of incoming and outgoing, which helps reviewers understand whose device this information was collected from, relative to the custodian.
read_receipts		√ Optional	array	An array of read receipts associated with the event. See the Read_receipts section below for more details.

Reaction

[
			{
			"reactions":[
			{
			"value":"thumbs up",
			"count":2,
			"participants":[
			"P1",
			"P2"
			]
			}
			],
		]

Name	RSMF 1.0	RSMF 2.0	Type	Descriptions
value	√ Required	√ Required	string	Identifies the reaction. The maximum length for a reaction is 30 characters.
count	√ Required	√ Optional	whole number	The number of times this reaction was added to the event.
participants	√ Required	√ Optional	array	Identifies the participants that used the reaction. Each participant must map back to the ID of a participant defined in the root of the manifest.

Name

RSMF 1.0

RSMF 2.0

Type

Descriptions

value

√

Required

√

Required

string

Identifies the reaction. The maximum length for a reaction is 30 characters.

count

√

Required

√

Optional

whole number

The number of times this reaction was added to the event.

participants

√

Required

√

Optional

array

Identifies the participants that used the reaction. Each participant must map back to the ID of a participant defined in the root of the manifest.

Attachment

Name	RSMF 1.0	RSMF 2.0	Type	Descriptions
id	√ Required	√ Required	string	Identifies the attachment. The value should correspond to the name of a file within the rsmf.zip, including any extension.
display	√ Required	√ Optional	string	Display value for the attachment. Relativity renders attachments based on the extension of the display value of an attachment.
size	√ Required	√ Optional	whole number	The size of the file in bytes.

Name

RSMF 1.0

RSMF 2.0

Type

Descriptions

√

Required

√

Required

string

Identifies the attachment. The value should correspond to the name of a file within the rsmf.zip, including any extension.

display

√

Required

√

Optional

string

Display value for the attachment. Relativity renders attachments based on the extension of the display value of an attachment.

size

√

Required

√

Optional

whole number

The size of the file in bytes.

Edits

Name	RSMF 1.0	RSMF 2.0	Type	Description
participant	√ Required	√ Required	string	The participant that made the edit. This must map to the ID of a participant defined in the root of the manifest.
timestamp	√ Required	√ Optional	string	The time stamp (ISO8601) of when the edit occurred.
previous		√ Optional	string	The value of the previous body that was changed due to the edit.
new		√ Optional	string	The value of the new body once the edit was made.

Read_receipts

Name	RSMF 2.0	Type	Description
participant	√ Required	string	The participant that made the action. This must map to the ID of a participant defined in the root of the manifest.
timestamp	√ Optional	string	The time stamp (ISO8601) of when the edit occurred.
action	√ Optional	string	If the recipient was delivered the message, or read the message. Valid values include read, delivered. If participant is seen twice but has different action strings, we'll display the read icon, but that contains details when it was delivered to them. For example, in WhatsApp and Facebook Messenger, there is data to denote that a message was delivered to the recipient, and when it was read by the recipient. Because the message being read is more significant, in the Short Message Viewer we would only show the recipient’s read status.

Name

RSMF 1.0

RSMF 2.0

Type

Description

participant

√

Required

string

The participant that made the action. This must map to the ID of a participant defined in the root of the manifest.

timestamp

√

Optional

string

The time stamp (ISO8601) of when the edit occurred.

action

√

Optional

string

If the recipient was delivered the message, or read the message.

Valid values include read, delivered.

If participant is seen twice but has different action strings, we'll display the read icon, but that contains details when it was delivered to them.

For example, in WhatsApp and Facebook Messenger, there is data to denote that a message was delivered to the recipient, and when it was read by the recipient. Because the message being read is more significant, in the Short Message Viewer we would only show the recipient’s read status.

Viewing the RSMF in an email application

To see the content within an RSMF, you can use any email application to open an RSMF and view the contents by changing the extension to .eml.

Edit the RSMF file format from .rsmf to .eml.
Use an email application to open the file. It will load and look like an email because RSMF files are .eml files. Examples of each part of the RSMF file are provided below:
- Header - All of the RSMF headers noted with the prefix X-Rsmf-display in an email application.
- Body – The extracted text of the RSMF file.
- Attachments – contains a zipped file that includes both the rsmf_manifest.json and any attachments.

The Relativity Short Message Format

RSMF 2.0 functionality

RSMF structure

Header

Example RSMF file

rsmf_manifest.json file

Participants

Conversations

Events

Reaction

Attachment

Edits

Read_receipts

Viewing the RSMF in an email application