Importing Basics

Coming from another platform and want to get started on Hedron quickly? The Importer is here to help!

In this guide, we'll go over the basics of importing content from files you may have from other platforms by walking through the process of importing 2 items.

To get started, head over to the Importer from the Navigation Menu > Rule Systems > Management Tools. You should see a page like this:

The Importer is Hedron's official tool for quickly bringing content into Hedron from other platforms. When you use it, you walk through a series of simple steps to import data from a file you upload.

Specifically, some of the steps in the Import Process are done by you, while others are done by Hedron. In short, you:

1. Upload a File
2. Partition or Split the File (if necessary)
3. Define the mapping of data
4. Look at the summary of your import

And any other steps are handled by Hedron.

NOTE: When importing Ruleset Entities, your Context Ruleset determines what Ruleset that Entities are imported into.

File Uploading & Supported File Types

All you need to get started is your data in any of the following forms:

• Comma-Separated Values (CSV)
• Microsoft Excel (XLSX)
• JSON
• Markdown (MD)

In general, we suggest you use CSV, XLSX, and JSON to import Entities like items, feats, spells, etc and you use Markdown to import Pages.

Spreadsheet Formats (CSV, XLSX)

For spreadsheet-type files, we expect each row to correspond to one entity of the same type on Hedron; for example, each row could be a spell or an item — but whichever it is, all rows must be that kind of entity.

At this time, we also only support importing from the 1st sheet of a spreadsheet, so please split multi-sheet spreadsheets into individual files.

We also assume the first row of the spreadsheet is the header row and thus, contains the labels for each value.

Thus, for example, this would be a valid spreadsheet:

In this example spreadsheet, we have 2 items: "My Item 1" and "My Item 2", along with some additional data for each.

JSON

For JSON files, we expect that the file could either be a singular entity, or a set of entities, depending on whether the contents are an array or not.

Otherwise, the key-value mappings are maintained as is and only first-level, non-nested elements will be accessible.

For example, this would be valid JSON data for the same entities as the spreadsheet example:

[
  {
    "name": "My Item 1",
    "description": "This is a sword",
    "weight": 6
  },
  {
    "name": "My Item 2",
    "description": "This is not a sword",
    "weight": 2
  }
]

That is, in this example, we have 2 items: "My Item 1" and "My Item 2", along with some additional data for each.

Markdown

For Markdown files, we expect that the file is a standard markdown file where each header denotes the separation of entities or specific values.

For example, the above data could be represented by the following markdown file:

# My Item 1
This is a sword

## Weight
6

# My Item 2
This is not a sword

## Weight
2

Due to the nature of Markdown Files, their data gets mapped to specific values, rather than the headings you specify. Specifically, based on your Partitioning (to be discussed next), you will have header values mapped to "Title", while their content is mapped to "Content", or alternatively, "Full Content" (which includes sub-headers).

For example, for "My Item 1", the "Title" would be "My Item 1", the content would be "This is a sword", and the full content would be "This is a sword \n## Weight \n6".

Partitioning

For Markdown Files, you will also be asked to perform a Partitioning Step:

You can skip this step if your file represents exactly 1 entity of your intended type.

However, in our example, our data represents 2 entities, so we should set the Partition Level to the Header level at which our entities are separated. In our case, that's "Header 1". When we make that change, you will notice the expected Imported entities changes:

This makes sense because if we split up our Markdown file by all the Header 1s, we'd get two different entities, as we expect.

In the future, this functionality may be extended to other file types as well.

Configuring Your Import

Once you have uploaded your file and performed any partitioning, you reach a tabbed page for you to specify the data mapping for your content.

Verifying Your Data

On the Data Stats tab, you can see how much and how often we found data of each type in your file. For example, when we upload our JSON file, we see:

In other words, there's 3 available fields for our 2 entities: "name", "description", and "weight". We also see that every entity has all 3 of these fields.

This is a good way to verify we uploaded the right file and everything was read correctly.

Mapping Your Data

Once you have confirmed that the right file has been uploaded and everything looks good, go back to the Data Mapping tab.

First, we select our Import Type from the list of available importable entity types. In this case, we'll use Items.

You'll see a new area appear for your mappings to be specified. Using the button to "Add Mapping", you should now create a mapping from each of your data's values to Hedron fields. On the left side, you will select fields from your data; on the right, you'll select where that data should be inserted into your Hedron entities.

For our example, we might do something like this:

This mapping specifies that "name" from our uploaded file is mapped to the Item's Name on Hedron. Similarly, we map "description" and "weight" from our uploaded data to the Item Description and Item Weight on Hedron, respectively.

Once you have finished mapping any relevant fields from your data (including at least one "Name" mapping), you should be able to press the "Begin Import" button to start your Import. Note: this is irreversible, so double check everything!

The Summary Page

After you start your import, you may wait a few moments before being presented a final summary screen:

Depending on how many entities are imported, you may see that your import was split up into multiple batches. In such cases, note that entities are imported in the order they appear in your uploaded file.

Otherwise, from this screen you can verify that the import was successful, and then start a new import or navigate to the relevant browser.

Why Did My Import Fail?

Most likely, your import could have failed because:

• You did not have enough quota for all entities. Check your profile page, delete entities you aren't using and try again.
• The data you gave did not confirm to Hedron standards. For example, maybe you tried to set the price of an item to something like "Cat".
• Something else. In this case, consider reaching out to us on any of our platforms, we'd love to help!

Otherwise, that covers the basics of importing content into Hedron!

In future articles, we'll try to also go over more advanced concepts in greater detail such as importing directly into a book you own or using "Multi-Values".