Batch File Requirements

There are two methods for importing batch file data into Nitro:

• Import via API - import batch files from outside Nitro Studio.

• Data import - import batch files using a drag-and-drop interface within Nitro Studio.

Imported files will appear in Nitro Studio on the Data Import view's Uploads tab where you can view status and address any errors that may have occurred during processing.

General Requirements

The following requirements apply to all batch processing.

• The data file should represent net-new data. Only new data, or data that has changed between uploads, should be included in the file. Bunchball will not process full file loads.
• The file must be encoded in UTF-8.
• The file must be 25MB or smaller. Larger files should be split into smaller or multiple transmissions.
• The file must have a .csv extension. The batch load process supports comma ( , ) and pipe delimited ( | ) formats. If you have .txt pipe-delimited files, you must rename the file to have a .csv extension.

Requirements for Actions

The following requirements apply to user and group actions such as user activity, skills obtained, etc.

• Files must be restricted to one file per action type and should be restricted to one action name. Multiple action names/tags per file are supported only when you use all the same (or no) metadata columns and when all actions are of the same type (user or group). Values can be null.
• When sending group actions, the file can include either the group ID or the group name.
• The file format must:
  • Include a header row.
    The header row does not need to follow any particular case-sensitivity or naming convention, but it must contain the correct number of commas or pipes between each column with no trailing comma or pipe.
  • Contain fixed columns in the following order: 
    • 1 - UserId (for user actions) OR GroupId or {Group Name} (for group actions) (required)
    • 2 - ActionName ("tag") (required)
    • 3 - Value (optional)
    • 4 - ActionTime (optional) ISO 8601 in format 2017-10-05T18:21:19+08:00
    • 5 - 0 to 10 additional columns for the metadata key/value pairs

Show me an example with one file per user action type

USERID,ACTIONNAME,VALUE,ACTIONTIME,SKILLNAME,CERT_REQUIRED

123,SKILL_OBTAINED,0,2017-10-05T18:21:19+08:00,Training Supervisor,Yes

456,SKILL_OBTAINED,77,2017-10-05T18:22:45+08:00,Mentor,No

Show me an example with one file per group action type

In this example, the file uses the group ID

GROUPID,ACTIONNAME,VALUE,ACTIONTIME

45,TRAINING_COMPLETED,1,2019-02-11T18:21:19+08:00

47,TRAINING_COMPLETED,1,2019-02-13T18:22:45+08:00

In this example, the file uses the group name

GROUPNAME,ACTIONNAME,VALUE,ACTIONTIME

TECHNICIANS,TRAINING_COMPLETED,1,2019-02-11T18:21:19+08:00

Show me an example with multiple action names per file

In this example there are three actions from an LMS:

LMS_LOGIN (no metadata)

LMS_COURSE_COMPLETE (metadata COURSE_ID: 636)

LMS_WATCH_VIDEO (metadata VIDEO_ID: 444)

To send the three actions within one file:

USERID,ACTIONNAME,VALUE,ACTIONTIME,COURSE_ID,VIDEO_ID

123,LMS_LOGIN,,2017-10-05T18:21:19+08:00,,

123,LMS_COURSE_COMPLETE,,2017-10-05T18:21:19+08:00,636,

123,LMS_WATCH_VIDEO,,2017-10-05T18:21:19+08:00,,444

Requirements for Users

The following requirements apply to loading specific user preferences, group enrollment, and award account enrollment in a single file. To load additional user preferences or group enrollments, see the Requirements for Preferences and/or Requirements for Group Enrollment sections.

Note: This process uses the PUT /users/{userId} method. Therefore, all non-required fields are optional, but when used, they must match the expected API parameter.

The file format must:

• Include a header row. The header row represents the preference name, award account attribute, and group class.

• Contain userId as the first column.
• Use columns 2+ for user preferences, award account enrollment, and group classes. Columns are not fixed.

• Columns 2+ must meet the following requirements:
  • firstName, lastName, and iconUrl are the only supported user preferences. To send additional preferences, you must use a separate preferences file. Note: To remove a user's first or last name, send __DELETE__ as the name value.
  • A country code must be set if any award account enrollment attributes exist.
    • Setting the country code enrolls the user in the award account.
    • If your program does not have an award account and you set a country code, the upload will fail.
  • A maximum of 10 group classes are supported.
  • The group and group class must exist before upload. They will not be created for you.
  • The group class must be a segment. The group class operation is switchGroup. Therefore, if a user is already in a group within the group class, they will be moved to the group specified in the file. If they are not in the group class, they will be added.
    • If a group is blank for a particular row, the user record will be created without group information.
  • Group class names cannot be the same name as user and award account enrollment attributes. For example, you cannot use "state" as a group class as that is an award account attribute name. Show me the attributes that cannot be used as a group class
    

address, address2, bankCharacteristic1, bankCharacteristic2, city, countryCode, emailAddress, firstName, iconUrl, lastName, phoneNumber, postalCode, state

Show me an example

userId,firstName,lastName,countryCode,emailAddress,Region,Branch,Department

A001234,Joe,Smith,USA,jsmith@email.com,Southwest,Phoenix,Sales

Requirements for Preferences

The following requirements apply to user attributes (preferences) such as name, role, or user icon etc.

The file format must:

• Include a header row. The header row represents the preference name.
• Use rows 2+ for the preference values.
• Contain userId as the first column, and the name of the column is ignored. Subsequent columns are one per preference. For standard preferences (such as firstName, lastName, etc.), capitalization doesn't matter. Non-standard preferences will be created with the capitalization defined in the header column.

Show me an example

USERID,FIRSTNAME,LASTNAME,NICKNAME,JOBCODE,TITLE,CUSTOM06

A12345,Mia,Lopez,Mia,Job2,Title1,custom val1

B98765,Kumar,Singh,Kumar,Job2,Title2,custom val2

Show me an example using standard preferences

userId,firstName,lastName,additionalName,role,userPhotoUrl

1063,Joe,Smith,,Engineer,https://s3.amazonaws.com/bunchball_images/76ff24611/userpng16186.png

1064,Bethany,Jones,Beth,Manager,https://s3.amazonaws.com/bunchball_images/76ft64611/userpng18346.png

Requirements for Group Enrollment

The following requirements apply to adding users to groups. The group enrollment file will create a new group class (column header) and group (row value) if the group class or group doesn't already exist.

The file format must:

• Include a header row.
• Contain fixed columns in the following order:
  • 1 - Operation (required). Allows Add, Remove, and Transfer.
    • When the operation is Transfer, a user will switch groups within a particular column. For example, if the column header is “Facility” (a group class) and the column value is "MPL" (a group), then the user would move from their existing group within the Facility group class to the MPL group. If the user is not currently in a group within that group class, a Transfer acts like an Add.
  • 2 - UserId (required)
  • 3 - {Group Class Name} (required).
    • If a group is blank for a particular row, the user will not have that group updated. This is useful when there are multiple group columns in a file but a user should only be affected in one column
  • 4 - Use columns 4+ for additional group classes (optional). Maximum of 10 columns.

Show me an example

Operation|UserId|Region|Branch|Role

Add|123|Southwest|Phoenix|Technician

Transfer|234|Northeast|Rochester

Remove|456|Northeast|Rochester|Manager

Requirements for Points Load

The following requirements apply to debiting or crediting users' points within a point category. Processing results in the user's points budget being added to or replaced with the new amount. This adjusts the current points balance in the point category and goes into effect immediately upon processing.

The points file can support multiple point categories. However, each row only supports one point category and it must be a 1:1 relationship with the user ID, point value, and point category.

The file format must:

• Include a header row.
• Contain fixed columns in the following order:
  • 1 - Operation (required). Allows Add or Replace.
  • 2 - UserId (required)
  • 3 - Points (required)
  • 4 - Point Category (required). The point category name configured in Nitro Studio.
  • 5 - Description (optional)
  • 6 - Use columns 6+ for bill codes (optional). Maximum of 10 bill code columns and the name of the column is ignored. Note: Bill codes only apply when using the Add operation. They do not log when using Replace.
    • You must have bill codes configured in the Award Account before uploading a file with bill codes. If bill codes are not set up, you will see errors in the upload.

Show me an example

Operation,UserId,Points,Point Category,Description,BillCode1,BillCode2

Add,A123,100,Points,May training incentive,,Training

Add,A234,100,Points,May training incentive,,Training

Add,A345,100,Points,May training incentive,,Training

Replace,A678,500,Recognition,Monthly budget allocation

See also

Data import

Actions