Importing People

Importing People is the process of transferring People’s data from an external file source into Jomablue. Our import tool is designed to handle complex data import tasks, making the process as quick and easy as possible.

Prepare data for Import

Before importing your data into Jomablue, it’s crucial to ensure that the data is clean and accurate. This section can help you in preparing your data.

Quick data formatting tips:

• Emails must be formatted in accordance with RFC 5322
• Mobile numbers must adhere to the e.164 format.  Please see below under Formatting Mobile Numbers for Data Imports.
• Ensure that all required fields are populated

Simple Import sample

This import includes basic fields such as first name, last name, company, email, and mobile number. The default Category will be applied to all records.

Download Simple Sample csv

Advanced Import sample

Advanced Import contains the basic fields mentioned above along with Category assignments. This sample demonstrates how different values can be represented for each single Category across different Records. The import process allows for specific text identification (e.g., “Yes”) or for identifying “not blank” entries  (e.g., varying values in the Delegate column).

This sample also contains:

• Custom Fields - such as State and Industry, which can be pre-defined in Settings or imported as new custom fields during the import process.
• Session Entitlements - for restricted Sessions like day passes or workshops, indicated by "Y" in the Session name columns. These can be mapped to Session Entitlements during the import process.
• Item Entitlements - for collections such as water bottles or satchels, which can also be mapped to Item Entitlement during the import process.
• SMS OPT Out - where only People to be "Opted out" are marked in the CSV. This can be mapped to the Opt-out feature during import.

Download Advanced Sample csv

Notes:

• Ensure that all the correct Categories have been entered into the Portal and are active
• Make sure that all Sessions have been created in the Portal, and any Sessions intended to be restricted (thus requiring Session Entitlements) are set to restricted
• Verify that any Items needed are created in the Portal
• Adding a "Source" custom field is a useful way to trace the data origin if you encounter any issues

Applying an Organisation UID column to your data

We recommend including an Organisation UID (Unique IDentifier) column for each Person. Ideally, this UID should be system-generated, like one from your CRM software.

If unsure what to use, you could create a UID using a date and reference number (e.g., 18Jun-001, 18Jun-002). Alternatively, you can export your People records from Jomablue and use the existing Jomablue UID. For more information, refer to the guide on the Exporting People Data section below.

If there have been multiple events in your instance, consider the following regarding the re-use of Organisation UIDs:

• If you want an attendee’s Personal Record to persist across Events, you can reuse the Organisation UID from previous Events. This will associate their original Person Record with the new Event.
• To maintain separate Person records for attendees across different Events, you need to provide a new Organisation UID that has not been used before in any Event in your instance. This ensures Record updates for one Event do not affect another.

Important: Do not use an email address or mobile number as the Organisation UID. This column must contain unique values. Email addresses and mobile numbers might not be unique in registration lists. Avoid simple numeric counters (e.g., 1, 2, 3) as these could have been used in previous or future events.

Notes:

• Email addresses are sometimes exported from third-party registration products with extra spaces; these must be removed before importing. Also, check for typos in the domain extension (e.g., xyz.con).
• The First Name and Last Name fields are mandatory. Make sure every row in your file contains both fields.
• The simplest way to add Category information to your file is to create a separate column for each Category. This allows you to use the Import tool once for all Categories.
• After saving your file in CSV format, avoid reopening it in Excel or Google Sheets, as these applications will interpret the + symbols in mobile numbers as operators and remove them. Resaving the file may cause errors during the validation step of the import.

Mobile Number Format for Data Imports

When importing People into Jomablue, it is required to use the e.164 mobile number format. Note that if you are using Jomablue registration, the formatting will be applied automatically.

What is e.164 Format?

The e.164 format is a globally recognised standard for phone number formatting. It maximises the chances of successful SMS delivery within Jomablue. The format consists of:

• A plus symbol (+)
• The International Country Calling Code
• The Service number
• No Spaces

Conversion to e.164 Examples:

• Australian number: 0421 221 001 ➔ +61421221001
• US Number: (415) 555-2671 ➔ +14155552671
• UK number: 020 7183 8750  ➔ +442071838750

Notes:

• Wikipedia provides a comprehensive list of all country codes here
• Generally, when using a country code, the leading 0 of the phone number is dropped. For instance, 0499 999 999 becomes +61 499 999 999.
• For technical users, the following sample Regular Expression (regex) can be used to validate numbers. Note that this will not match numbers containing a '0' after the '+': /\+[1-9][\d+]{4,19}/.

Import People using Jomablue’s Import Tool

Once you have prepared your import file, you can start the process of importing your data.

Navigate to Import Tool

To access the Import Tool, go to the People section in the Jomablue Portal and click on Import in the top right of the screen.

You will be guided through all the steps needed to map, validate, and upload your file into the Portal.

Step 1: Upload CSV File

Next, Upload your CSV file. Select the appropriate character encoding scheme for your file. By default, this is set to UTF-8, so typically, you won’t need to make any changes.However, if you created your CSV file in Excel for Mac, choose the Mac OS Roman character encoding option or select CSV (UTF-8) as the file type when saving your file in Excel.

After selecting the correct encoding, upload your file using the Choose File button.

Step 2:  Assign Columns

After your file has been uploaded, a list of detected columns in the CSV will appear, showing the values in the first row of each column (if column headers were created, these will be displayed; if not, the values will be the first records in your file).

Map each column header to a Jomablue field type. This is done via the drop-down menus in the Column Type section. By default, each column is set to Ignore, but you will need to assign all columns to their relevant types. You can leave columns as Ignore if the data is not relevant to the import.

For most columns, this process is straightforward. The following column types should be matched to the corresponding first row values in your file:

• Organisation UID
• First Name
• Last Name
• Job Title
• Company
• Email
• Mobile

Select the appropriate option from the drop-down menu that corresponds to the first row value in that column.

Mapping a column to a Category

If your registration file contains Categories, there are additional steps. For each column corresponding to a Category, do the following

1. Select Category from the drop-down menu, and additional fields will display
2. Choose the corresponding category from the Select Category drop-down menu (you must have your Categories enabled in Portal before this step)
3. From the Person belongs to this category if value drop-down menu, select is anything other than empty
4. In the Person does not belong to this category if value menu, select is empty

This configuration will assign a Person to the chosen Category if the value in the selected column is anything other than empty. Repeat this process for each column and each category. An example of a completed column mapping can be seen below:









Advanced users can apply any of the other options that suit the conditions of the import.

Mapping column to an Item Entitlement or Session Entitlement

The process of mapping columns to Item Entitlements or Session Entitlements is identical to mapping Categories. Here are the steps to follow:

1. Select Item Entitlement or Session Entitlement from the Column Type drop-down menu
2. Choose the Item or Session you wish to apply the entitlement to
3. Set the Person belongs to this category if value drop-down menu to is anything other than empty, and set the Person does not belong to this category if value menu to is empty, just as you would do for Categories

Advanced users can apply any of the other options that suit the conditions of the import.

Finalising your Column Assignment

Once all columns are mapped, check the box labelled first row of my CSV is a header row if the first row of your CSV contains headers (which is recommended). This allows the import tool to skip the first row of the CSV. Once set, you can proceed to the next step!

Step 3: Validate Rows

The Import Tool will scan your file and column mappings to ensure the content of the file is valid. If it detects any issues, it will alert you in Step 4. If there are no issues, it will proceed to Step 5.

Examples of validation testing:

• Missing data from mandatory fields (e.g., First Name or Last Name are blank)
• Incorrectly formatted Email address (e.g., invalid special characters, missing @ symbol, invalid domain, multiple email addresses in one field)
• Mobile numbers include spaces, special characters or are missing the +
• Organisation UID contains duplicate entries
• Blank rows

Note: While users can manually edit Organisation UIDs before correcting errors, it is not recommended because this field is typically used as a key for system imports. If errors related to Organisation UIDs are detected, it is advisable to check the import file and make the necessary changes before attempting to re-import.

Step 4: Fix Errors

In this step, any errors flagged in your import file will be highlighted. Each error will appear as a row along with an explanation of the issue. You can edit these fields directly within the Import Tool (note that changes made here will not alter the original file you uploaded). Then you can save your changes or remove the row from the import entirely.
An example of a row with errors can be seen below:

This feature is beneficial for correcting small errors that may have occurred during your import. If the number of errors is large, you will have the option to review them in the Portal or restart the import and review your CSV file. Repeat this process until your import is free from errors and ready for review.

Step 5: Review and Submit

Once your import file is error-free, you're ready to run the import! This step will display the number of Records detected and set to be uploaded. We recommend comparing this number with the expected count of your Records before proceeding.

Step 6: Run Import

The Portal will upload the data to the Jomablue platform. Please ensure that you do not close your browser window until the import is complete. Upon completion, you'll be presented with the results of your import, as per Step 8 below.

Step 7: Results

Here, you'll see the results of your import formatted as "Records have been imported (X of Y imported),” where Y is the expected number of records to be imported (from Step 6), and X is the actual number of records imported.
If you need any assistance while using the Import Tool, feel free to get in touch with us via support@jomablue.com

Custom fields

A Custom field allows you to include additional important data specific to each attendee of your event. For example, you might want to include fields like State, Industry, or Products relevant to your organisation’s attendees.
This data can help you view Insights and filter Campaigns targeted at specific attendee groups. It is also automatically included when you export People, making sorting and filtering easier without needing to integrate Jomablue export with your external data.

Map Custom fields using the Import tool

When mapping to Custom fields using the Import Tool, these fields will be grouped in the dropdown menu as follows:

• Pre-defined Fields: Those defined under Settings, then Custom Fields
• Existing but not pre-defined fields: Results from a previous Import

You can create a new Custom Field key during the import process (using letters, numbers and underscores only). These new fields will appear as “Existing but not pre-defined.” You have the option to define these later, but it is not mandatory.

Delete a Custom field

When processing an Import to update existing registration data, you can include Custom fields. For example, you might want to update the Product used by the Attendee. However, if a field is blank in the import file, it will not remove the existing data; the system perceives this as “no change required.”

To completely remove a custom field from a Person’s Record, populate the Import file for that Custom field key with #N/A. After processing the Import, the Custom field will no longer exist.

Example: To remove an incorrect State from John Smith, you would:

1. Add #N/A in the State column in John Smith’s row of your CSV file
2. Map the State column in your CSV to the Custom Field labelled State in the Import Tool

Skip Category assignments for Data Imports

When mapping Category assignments during the registration import process, you have the option to check the box labelled "Skip over this category assignment for rows that don't match above."

Selecting this option means that any row that doesn't adhere to the specified rules will have that particular Category assignment skipped during the import process. If all Category rules are skipped when adding new people records, the Default Category will be assigned.

Conversely, if this option is NOT checked, and your CSV file contains data that doesn’t conform to the rules, an error will occur during the import. You will need to resolve this by updating the data to one of the values specified in the rules before proceeding with the import.While the import tool allows you to correct errors on the fly, we recommend cancelling the import if there are a large number of errors. In such cases, it’s best to correct the errors first and then restart the import process.

Apply bulk updates to People Data

You may need to make a number of changes to People in Jomablue. For example, you can use this process to change the Category of People, add Entitlements, or edit Custom fields. The process is relatively straightforward, allowing you to manipulate existing data and re-import it to override the data currently in Jomablue.

Export your People records from Jomablue or alternatively export a file from your original registration system (including the Organisation UID originally provided). Use Excel, Google Sheets or a Text Editor to edit your People data and save your file in CSV format.

Important:

• Please exercise caution with this process, as it can remove or override previously provided data. For example, if an individual registered as "Acme Ltd," this is what they will see on their badge or in the Community. 

Edit People Data

1. Open exported data file in Excel or a similar application
2. Make the necessary edits. You may delete any columns or rows that you don't want to update as part of this process.

Important:

• Keep the Jomablue UID intact – do not edit this column at all.
• You are unable to add new records to this file. 
  
  

Change Person Categories

1. In the Category columns, remove the “Y” where applicable (e.g., leave blank if a Category no longer applies)
2. Define your Category mapping as follows:

Note: the above mapping specifies:

• Person belongs to this Category if value is Y
• Person does not belong to this Category if value is empty

Important:

• Keep the Jomablue UID intact – do not edit this column at all. You are unable to add new records to this file.

Import your updated People records

To apply the new edits to Jomablue:

1. Navigate to People > Import
2. Select your edited File
3. Jomablue will detect the Jomablue UID column and confirm whether you're attempting to process an update or make a regular import. Select OK.
   Note: If importing a file that wasn’t exported from Jomablue, map the Organisation UID.
   
   

       4. Map the fields as you would with a regular import and proceed through the validation steps

Note: You only need to map the fields containing updated data. Any data in other existing fields within the records will be retained.

      5. Once completed, the updates contained within the CSV will be applied to the People in Jomablue.

Notes:

• You cannot update the Organisation UID as part of the bulk update process.
• Upon completion of the import, Jomablue will overwrite existing data in the Records based on the file, and the original data is not recoverable so be careful!

Process Bulk cancellations of People Records

You may start receiving cancellations to your event. Export your People records from Jomablue or alternatively export a file from your original registration system (including the Organisation UID originally provided and a column for Status) for import to Jomablue.

1. Check your CSV, ensuring that each Record contains a Jomablue UID or Organisation UID. The file should look similar to this where column K shows the Status of “Cancelled”:
   
   
   
2. You can now import this file directly into Jomablue without any filtering before the import. To map the file, follow these steps:

               a.  Navigate to People > Import and select the file

               b.  Map the Jomablue UID/Organisation UID and Status columns to fields

This action will update every record in Jomablue that is contained within the file as follows:

• Existing records will remain as "Registered"
• People records identified as “Cancelled” will be transitioned to Cancelled status

Note:

Cancelled People are automatically excluded from any Campaigns. This can be verified when previewing the Campaign. The recipient list won’t display any cancelled People. If any People are cancelled after the campaign is scheduled, they will be excluded at the time of sending.