In this article, we will cover:
- Introduction
- Custom Offline Activity File (required)
- Things to note
- Best practices
- Download Sample CSV
Introduction
Batch Mode Integration is a convenient way to award points for offline custom activities such as entering a store, running 10K etc. Please familiarise yourself with Batch Mode Integration before proceeding with this article.
To award points for any offline custom activity other than a purchase, you must upload the following custom file to the designated SFTP location in CSV format, or upload it manually in the admin console under General >> Settings >> Batch Mode.
This file is described in detail below.
Custom Offline Activity File (required)
This file contains details about each custom offline activity, other than purchases, for which points are to be awarded. If points are to be awarded for multiple custom activities, all such activities should be combined into this single file before uploading.
However, we highly recommend using separate files for each custom activity.
Note: If you intend to upload a single file for multiple custom activities, ensure to include the respective custom attributes linked to each activity.
Thus, this file may contain multiple activity IDs. A prerequisite is that a custom activity corresponding to each activity ID has been configured and made live in the TrueLoyal console. The activity ID will be used to associate the award transaction with an activity. Points are awarded based on the points_awarded value in the file, as custom activities don't have their own points value.
The naming convention for this file is ZN_ACTIVITY_YYYYMMDD.csv. For example, a file with activities for 26 April 2017 should be named ZN_ACTIVITY_20170426.csv.
Note: The CSV file name should not contain any special characters.
CSV Fields
The fields contained in this CSV file are described in the table below:
| Field | Description | Mandatory (Yes/ No)? |
|---|---|---|
| activity_timestamp | Date in YYYYMMDD format followed by time in HH:MM:SS format (24 hours) on which the activity took place. For example: 20231116/19:50:02 | Yes |
| points_expiration_date | Pass the date and time for point expiration. This will override the global settings of point expiration. Format: YYYYMMDD/HH:MM:SS (20241221/18:00:04). Passing the time is optional. | No |
| user_email | Email address of the member. | Yes (If member_id is passed in CSV, user_email address becomes optional.) |
| user_name | Name of the member (first name and the last name) | Yes |
| member_id | Unique Identifier (Member ID) for the member object in the client's system. | Yes (if this column is passed in CSV) |
| client_user_id | User ID assigned to the member by the admin, if one exists. | No |
| user_phone | The phone number of the buyer without country code. | No |
| activity_id | The unique activity ID stored with TrueLoyal. You can find this in the TrueLoyal admin console under the activity name. The ID has to match the TrueLoyal record exactly or the points will not be awarded. | Yes |
| points_awarded | Number of points to be awarded to the user for this activity. Points are awarded based on this value, as custom activities don't have their own points value. | Yes |
| activity_description | Description of the activity which was performed. Example: Visited the store. | No |
| approval_date | Date and time on which the transaction will be auto approved. Format: YYYYMMDD/HH:MM:SS (20231221/18:00:04) | No |
| activity_url | If you provide the URL, then the activity_description will be hyperlinked to the activity_url. So, it will show a link where or how the activity was performed. | No |
| {activity_id}.{client_internal_id} or {activity_id}@{client_internal_id} |
This is activity specific custom attributes. To know more, click here. You can pass in custom attributes that you want TrueLoyal to associate with the transaction. The types of attributes you can create:
|
No |
| {global}.{client_internal_id} or {global}@{client_internal_id} |
This is global attributes or activities global attributes. To know more, click here.
|
No |
Note: If your program does not utilise an email address as the primary identifier, the 'member_id' field will be included in the CSV. Otherwise, it will not appear in the CSV file.
Error messages
Here are all the error messages that you may receive:
| Error Message | Description |
| "Invalid numerical value" | The value provided is not a valid numerical value for the specified data type in custom attributes. |
| "Incorrect date format. Expected - YYYYMMDD/H:M:S or YYYYMMDD" | The provided date format is incorrect. It should adhere to either YYYYMMDD/H:M:S or YYYYMMDD. |
| "Invalid list value provided" | An invalid value has been passed in a list data type created for custom attributes. |
| "Order ID is mandatory for Purchase transaction." | The Order ID is essential for identifying transactions uniquely, particularly for purchase transactions. |
| "One of the rows related to this order is invalid" | This message indicates that a row related to the order contains incorrect data. |
| "Unable to determine if the row is Purchase or Return" | This message is displayed when crucial columns such as order_type, order_total, order_subtotal, product_price, and quantity are empty, making it impossible to identify the transaction type. |
| "Member ID is mandatory" | The Member ID field is required when provided in CSV. |
| "Mismatch in email in member Id" | The member_id column is missing from the file, or the value in it doesn't match the member. If your file includes a member_id column, it must contain the Member ID shown on the member's profile, not their email address. Keep all columns from the downloaded sample file. |
| "User Email is mandatory" | This field is obligatory for clients using the V1 store. |
| "Order Subtotal has to be positive." | The order subtotal must have a positive value; negative values are not accepted. |
| "Product price has to be of type float" | Product price should be of type float/ integer; other data types are not accepted. |
| "Product quantity has to be of type int" | Product quantity should be an integer; incorrect data types are not permitted. |
| "Order Subtotal has to be greater than Zero." | For purchase transactions, the subtotal or total must be greater than zero. This error occurs when these values are zero or when product prices and quantities multiply to zero. |
| "User not registered in TrueLoyal" | This message appears when a user is not found in the TrueLoyal database, particularly when auto-enrollment is disabled and only added to purchase orders. |
| "Error occured while creating user in TrueLoyal" | This error message indicates backend errors during user creation in TrueLoyal. |
| "Unable to register user in TrueLoyal as member_id is absent" | For V2 customers, the member_id field is mandatory, and this error occurs when it's not provided. |
| "Unable to register user in TrueLoyal as email/client_user_id are absent" | For V1 customers, the email field is mandatory, and this error occurs when email or user_id is not provided. |
| "Unable to calculate return amount" | Calculation of the return amount failed due to incorrect provided data. |
| "return_subtotal": "return amount should not be 0" | The return amount should not be zero. |
| "return_subtotal": "return amount should be passed" | To calculate return amount- product prices or quantity should be provided. If not then subtotal or total should be specified. |
| "return_subtotal": "return amount greater than available amount" | The return amount exceeds the available points. |
| "order_id": "no transaction present for order_id:{order_id}" | The provided order ID does not correspond to any transaction. |
| "quantity": "Product quantity exceeded" | The provided product quantity exceed or incorrect. |
| "returned_product_id": "returned product id is invalid" | The provided product ID for the returned product is invalid. |
| "user_deleted": "Returned transaction belongs to the deleted user." | The returned transaction details belong to a deleted user. |
| "user_blocked": "Returned transaction belongs to the blocked user." | The returned transaction details belong to a blocked user. |
| "not_enough_points_to_deduct": "User does not have enough points to deduct" | Insufficient points to deduct for return transaction. |
| "email_not_passed": " User email not passed or User email passed is incorrect or Client User ID is incorrect" | Email or user_id is mandatory for V1 store customers during return transactions. |
| "user_not_exists": "No user found for the given email/member_id." | Unable to identify the user as provided email address or member_id is incorrect. |
| "Unexpected error occured. Exception: {error}" | A generic exception occurred during daily transactions. |
| "Error in reading custom activity information from {file_name} for merchant {merchant_key} : {error}" | A generic exception occurred while reading custom attributes from a specified file. |
| missing parameters | This message indicates missing mandatory parameters. For more details, refer to this document. |
Things to note
- The CSV file should not exceed 5000 records. If you wish to upload a larger volume, please create a new CSV file with the additional records.
- Please ensure that you review the "numeric data" before adding it to any field. There is a possibility that it could be converted to a scientific data format when inserted into the CSV file.
- The downloaded CSV will contain only activity attributes as it specifically pertains to activities. Reward and reward global attributes will not be included.
- The CSV file must not have any rows that solely consist of white spaces.
- When uploading a CSV file through SFTP, it undergoes processing every 8 hours. However, for manual processing, the file is processed immediately.
- You can process a maximum of 50 files per day.
- CSV files should not contain double quotes.
- When a custom activity is paused, it won't appear for download in the dropdown menu. Additionally, if a custom activity is paused, TrueLoyal won't award points for that particular activity.
- The file must be encoded in UTF-8 format and saved as a CSV file.
Note: Our system records all date and time fields in UTC time. This applies to the system generated fields such as enrollment date as well as the date time fields passed through the batch files.
Best practices
There are a few things you can do to make sure your batch uploads go smoothly:
- Set up the custom activity first: Create the custom activity and set it to Active before you prepare your file. In the Settings tab, you might want to set "Show Activity in User Dashboard" to hidden if members shouldn't see it as something they can complete themselves.
- Check the text configuration: In the Text Configuration tab, set the "Display Name", as this is what members see in their points history. It's also worth checking the "Notification Text", which is used in the Points Earned email. Keep {{POINTS}} in it so members can see how many points they've earned.
- Use the sample CSV: Always download the sample CSV for the specific activity you're awarding points for, and keep all of its columns.
- Check the results email: Once the file has been processed, you will receive an email with the results, sent to the email address entered in Batch Mode and to the account's full-access admins. If every row was processed, the email confirms the file was processed successfully. If any rows have errors, the email tells you how many records were processed successfully and includes an error file (errors_[your file name].csv). The error_description column in that file explains why each row failed, so you can correct those rows and re-upload only them.
- Test with one member: Before you upload your full list, upload a file containing just one member first.
- Uploads can't be reversed: Please be aware that once a batch file has been processed, it can't be reversed. The system only blocks a file with the same file name, so if a processed file is renamed and uploaded again, the points will be awarded a second time. If some rows fail, only re-upload the failed rows using the error file you receive by email.
Download Sample CSV
Before you can download the sample file, a custom activity must be created and set to active. If there is no active custom activity, there will be nothing to select in the dropdown and the sample file can't be downloaded.
- Go to General >> Settings >> Batch Mode within the TrueLoyal admin console.
- Choose Custom Activity File as the file type.
- Select the desired custom activity type.
- Click on Download.
If you have any questions or concerns regarding batch mode integration, please don't hesitate to contact Technical Support at support@trueloyal.com.
Comments
Please sign in to leave a comment.