Pull from TrueLoyal¶

TrueLoyal, formerly named Zinrelo, is a loyalty platform. Brands use it to run loyalty programs that enroll members, track points that members earn and redeem, and assign members to tiers.

TrueLoyal can send loyalty members, point transactions, tiers, rewards, and activities to Amperity using the TrueLoyal Loyalty API. Choose which data types to pull. Amperity lands one NDJSON file for each data type that you select.

Members are the loyalty profiles in your program, including members whose status is active, blocked, or opted out.
Transactions are the point transactions in your program: points that are awarded, redeemed, and deducted.
Tiers, Rewards, and Activities describe how your loyalty program is configured. Member and transaction records refer to tiers, rewards, and activities by tier_info.loyalty_tier_id, reward_id, and activity_id, and these data types give those identifiers something to join to.

Members and transactions can be pulled for a specific time period or in full. Tiers, rewards, and activities are pulled in full on every run.

The Amperity connector for TrueLoyal is named True Loyal.

Beta

The True Loyal connector is in beta. Contact your Amperity representative to learn more.

The steps that are required to pull loyalty members, point transactions, tiers, rewards, and activities to Amperity from TrueLoyal:

Get details
Add courier
Get sample files
Add feeds
Add load operations
Run courier
Add to courier group

Get details¶

TrueLoyal requires the following configuration details:

The Partner ID for your TrueLoyal loyalty program and an API Key for that program.

Both values come from the TrueLoyal Admin Console for the loyalty program that Amperity pulls from. Find the partner ID under General > Settings. Create an API key under General > API Keys. Only an administrator with full access to the Admin Console can see the API Keys section. TrueLoyal recommends a separate API key for each integration.

The partner ID and the API key must belong to the same loyalty program.

Important

TrueLoyal does not document a way to limit an API key to read-only access. The API key that Amperity uses to read loyalty data can also be used to award, deduct, and redeem points. Amperity only reads data from TrueLoyal. Share the API key only through a secure channel.
The Data types to pull. Select any combination of Activities, Members, Rewards, Tiers, and Transactions. Select at least one.

Tip

Use SnapPass to securely share configuration details for TrueLoyal between your company and your Amperity representative.

Add courier¶

A courier brings data from an external system to Amperity.

To add a courier

From the Sources page, click Add Courier. The Add Courier page opens.
Find, and then click the icon for True Loyal. The Add Courier page opens.
Enter the name of the courier. For example: “TrueLoyal”.

From the Credential field, select an existing credential or select Create a new credential.

To add a credential, enter the name of the credential, a description, and the TrueLoyal Partner ID and API Key. Click Save.

When finished click Continue.
Under Data types, select the data types to pull.
Leave Load Operations empty. Add load operations after the feeds for this courier are configured.
Click Save.

Note

Every courier run begins by reading the first page of each data type that you selected, without a date filter. This verifies that the credential can read every data type, rather than verifying only that the credential is accepted. A data type that the credential cannot read fails the run at the start instead of partway through. This check does not use date filters or paging, so a run can still fail partway through a data type.

TrueLoyal refuses to list members for a loyalty program that is not active, but continues to return transactions, tiers, rewards, and activities for that program. A courier that does not pull members can run successfully against an inactive program, so a successful run for other data types does not show that the loyalty program is active.

Get sample files¶

Newline-delimited JSON (NDJSON) is a data format for structured data that defines the structure of JSON data using lines as separators. Each line in a NDJSON file is a valid JSON value.

Every TrueLoyal file that is pulled to Amperity must be configured as a feed. Before you can configure each feed you need to know the schema of that file. Run the courier without load operations to bring sample files from TrueLoyal to Amperity, and then use each of those files to configure a feed.

Amperity names each file after its data type.

Data type	File name	Name in load operations
Activities	`activities.ndjson`	`activities`
Members	`members.ndjson`	`members`
Rewards	`rewards.ndjson`	`rewards`
Tiers	`tiers.ndjson`	`tiers`
Transactions	`transactions.ndjson`	`transactions`

To get sample files

From the Sources tab, open the menu for a courier configured for TrueLoyal with empty load operations, and then select Run. The Run Courier dialog box opens.
Select Load all data.

A run for a specific time period returns only the members and transactions that changed during that time period. A sample file for members or transactions can be empty if nothing changed, and an empty file cannot be used to configure a feed.
Click Run.

The files that the courier pulls are available for selection as an existing source from the Add Feed dialog box.

Add feeds¶

A feed defines how to load data into a domain table, including specifying required columns and columns with semantic tags for customer profile (PII) or transactions data.

Note

A feed must be added for each file that is pulled from TrueLoyal, including all files that contain customer records and interaction records, along with any other files that is used to support downstream workflows.

Each file contains the records that TrueLoyal returns, with the fields that TrueLoyal returns for them. Fields vary between loyalty programs, and the field lists in the TrueLoyal API documentation do not include every field that the API returns. Use the sample file for each data type, rather than the TrueLoyal documentation, to configure its feed.

A top-level field whose value is null is omitted from the record rather than landed as an empty value. Nested objects and arrays, such as the custom attributes on a member, the tier information on a member, and the transaction attributes on a transaction, are landed as they are returned, including any null values inside them. Their contents vary between loyalty programs.

Select a primary key for each feed: member_id for members, and id for transactions, tiers, rewards, and activities. TrueLoyal documents an id field on each record, which is the identifier that TrueLoyal generates for that record. A record that Amperity pulls again, which happens on the boundary days of runs for a specific time period, updates the existing record in the domain table when the feed has a primary key.

The id field is not the identifier that other records use to refer to a tier, reward, or activity. Member and transaction records refer to them by tier_info.loyalty_tier_id, reward_id, and activity_id, which match the tier_id, reward_id, and activity_id fields on tier, reward, and activity records. Use those fields, not id, to join them.

Member records have two identifiers. id is generated by TrueLoyal. member_id is the identifier that your brand supplies when a member enrolls, such as a customer ID or an email address. Transaction records refer to members by member_id. Confirm what your brand stores in member_id before you decide which field to use for identity resolution.

To add a feed

From the Sources tab, click Add Feed. This opens the Add Feed dialog box.
Under Data Source, select Create new source, and then enter “TrueLoyal”.
Enter the name of the feed in Feed Name. For example: “Members”.

Tip

The name of the domain table will be “<data-source-name>:<feed-name>”. For example: “TrueLoyal:Members”.
Under Sample File, select Select existing file, and then choose from the list of files. For example: “members.ndjson”.

Tip

The list of files that is available from this dropdown menu is sorted from newest to oldest.
Select Load sample file on feed activation.
Click Continue. This opens the Feed Editor page.
Select the primary key.
Apply semantic tags to customer records and interaction records, as appropriate.
Under Last updated field, specify which field best describes when records in the table were last updated.

Tip

Choose Generate an “updated” field to have Amperity generate this field. This is the recommended option unless there is a field already in the table that reliably provides this data.
For feeds with customer records (PII data), select Make available to Stitch.
Click Activate. Wait for the feed to finish loading data to the domain table, and then review the sample data for that domain table from the Data Explorer.

Add load operations¶

After the feeds are activated and domain tables are available, add the load operations to the courier used for TrueLoyal.

Example load operations

Load operations must specify each file that is pulled to Amperity from TrueLoyal.

Refer to each file by the name of its data type, without the .ndjson extension, as shown in the table in Get sample files. Add a load operation for each data type that the courier pulls.

Tiers, rewards, and activities are pulled in full on every run. Pair the load for each of them with a truncate operation, so that each run replaces the contents of the domain table and a record that was removed from TrueLoyal is removed from Amperity.

Do not truncate the domain tables for members or transactions. A run for a specific time period, including every scheduled run, pulls only the members and transactions that changed during that time period. A truncate operation would replace every member or transaction in the domain table with only those changes.

Each scheduled run pulls the time period since the schedule’s previous run time, whether or not that run succeeded. Members and transactions that changed during the time period of a failed or missed run are not pulled until you run the courier for that time period.

For example:

{
  "df-A1B2C3": [
    {
      "type": "load",
      "file": "members"
    }
  ],
  "df-D4E5F6": [
    {
      "type": "load",
      "file": "transactions"
    }
  ],
  "df-G7H8I9": [
    {
      "type": "truncate"
    },
    {
      "type": "load",
      "file": "tiers"
    }
  ]
}

To add load operations

From the Sources tab, open the menu for the courier that was configured for TrueLoyal, and then select Edit. The Edit Courier dialog box opens.
Edit the load operations for each of the feeds that were configured for TrueLoyal so they have the correct feed ID.
Click Save.

To pull another data type later, edit the courier to select it under Data types, run the courier to get a sample file, add a feed for that file, and then add a load operation for it.

Run courier manually¶

Run the courier again. This time, because the load operations are present and the feeds are configured, the courier will pull data from TrueLoyal.

Important

Select Load all data for the first run. A run for a specific time period pulls only the members and transactions that changed during that time period, so a first run for a specific time period loads only part of your loyalty program.

To run the courier manually

From the Sources tab, open the menu for the courier with updated load operations that is configured for TrueLoyal, and then select Run. The Run Courier dialog box opens.
Select the load option, either for a specific time period or all available data. Actual data will be loaded to a domain table because the feed is configured.
Click Run.

This time the notification will return a message similar to:
```
Completed in 5 minutes 12 seconds
```

Add to courier group¶

A courier group is a list of one or more couriers that run as a group. A courier group can act as a constraint on downstream workflows and can run automatically as part of a scheduled workflow.

To add the courier to a courier group

From the Sources tab, click Add Courier Group. This opens the Create Courier Group dialog box.
Enter the name of the courier. For example: “TrueLoyal”.
Add a cron string to the Schedule field to define a schedule for the orchestration group.

A schedule defines the frequency at which a courier group runs. All couriers in the same courier group run as a unit and all tasks must complete before a downstream process starts. Define a schedule using cron.

Cron syntax specifies the fixed time, date, or interval at which cron runs. Each line represents a job. 30 8 * * * represents “run at 8:30 AM every day” and 30 8 * * 0 represents “run at 8:30 AM every Sunday”.

For example:
```
┌───────── minute (0 - 59)
│ ┌─────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌────────────── month (1 - 12)
│ │ │ │ ┌─────────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * * command to execute
```
Amperity validates the cron syntax and shows you the results. You may also use crontab guru to validate cron syntax.
Set Status to Enabled.
Specify a time zone.

A courier group schedule is associated with a time zone. The time zone determines the point at which a courier group’s scheduled start time begins. A time zone should be aligned with the time zone of system from which the data is being pulled.

Use the Use this time zone for file date ranges checkbox to use the selected time zone to look for files. If unchecked, the courier group uses the current time in UTC to look for files to pick up.

Note

The time zone that is chosen for an courier group schedule should consider every downstream business processes that requires the data and also the time zones in which the consumers of that data will operate.
Add at least one courier to the courier group. Select the name of the courier from the Courier dropdown. Click + Add Courier to add more couriers.
Click Add a courier group constraint, and then select a courier group from the dropdown list.

A wait time is a constraint placed on a courier group that defines an extended time window for data to be made available at the source location.

Important

A wait time is not required for a bridge.

A courier group typically runs on an automated schedule that expects customer data to be available at the source location within a defined time window. However, in some cases, the customer data may be delayed and is not made available within that time window.
For each courier group constraint, apply any offsets.

A courier can be configured to look for files within range of time that is older than the scheduled time. The scheduled time is in Coordinated Universal Time (UTC), unless the “Use this time zone for file date ranges” checkbox is enabled for the courier group.

This range is typically 24 hours, but may be configured for longer ranges. For example, it is possible for a data file to be generated with a correct file name and datestamp appended to it, but for that datestamp to represent the previous day because of how an upstream workflow is configured. A wait time helps ensure that the data at the source location is recognized correctly by the courier.

Warning

This range of time may affect couriers in a courier group whether or not they run on a schedule. A manually run courier group may not take its schedule into consideration when determining the date range. Only the provided input days to load data from are used as inputs.
Click Save.

Important

Leave Only retrieve files dropped in the past day? cleared unless the courier group runs daily. A scheduled courier group calculates the start of its time period from the schedule, not from the last successful run, so members and transactions that changed during a failed run’s time period are not pulled again.

The courier group settings do not offer a look-back period longer than one day. Contact your Amperity representative to set a look-back period that is at least twice the schedule interval. Pulling the same time period twice updates members and transactions rather than duplicating them, because their feeds have primary keys.

How data is pulled¶

Each run pulls the data types that you selected one at a time, in sequence.

Data type	Run for a specific time period	Notes
Activities	Pulled in full.	TrueLoyal does not filter activities by date.
Members	Filtered on `last_modified_date`.	Includes members whose status is active, blocked, or opted out.
Rewards	Pulled in full.	TrueLoyal does not filter rewards by date.
Tiers	Pulled in full.	TrueLoyal does not filter tiers by date.
Transactions	Filtered on `last_modified_date`.	Transactions refer to members by `member_id`.

Members of every status are pulled. TrueLoyal returns only active members unless a request names another status. Amperity requests active, blocked, and opted out members separately and lands all of them in the same file. Use the member_status field to tell them apart. Blocked and opted out members are often the records that suppression workflows depend on.

Date filters cover whole days. TrueLoyal filters members and transactions by date, not by time, and treats dates as UTC. A run for a specific time period pulls every member or transaction whose last_modified_date falls on any day in that time period, including the whole of the first day and the last day. A time period that ends at exactly midnight UTC also includes the following day. Consecutive runs can pull the same records again, and a feed with a primary key updates those records rather than duplicating them.

Requests are paced. Amperity reads up to 1,000 records in each request and paces its requests to stay below the rate limit of 100 requests per minute that TrueLoyal documents for its standard plan. TrueLoyal documents this limit for the whole loyalty program, so Amperity shares it with your other TrueLoyal integrations.

Troubleshoot errors¶

The following errors may occur when a courier runs. Errors that occur at the start of a run begin with “Failed to connect:”. Most errors that occur while reading a data type name that data type.

Error	Resolution
TrueLoyal rejected the API key.	The API key is incorrect, or was deactivated or deleted in the TrueLoyal Admin Console. TrueLoyal returns the same response when the partner ID is incorrect, so check both values. Reactivate the API key under General > API Keys, or create a new one if the key was deleted.
The TrueLoyal loyalty program is not active.	TrueLoyal refuses to list members for a loyalty program that is not active. Confirm that the partner ID and API key belong to your live loyalty program. Contact TrueLoyal to confirm whether the loyalty program is active.
TrueLoyal returned Not Found.	Contact your Amperity representative.
TrueLoyal is rate limiting this program.	Amperity retries these automatically. Contact your Amperity representative if the error recurs.
TrueLoyal returned a server error.	A problem on the TrueLoyal side. Amperity retries these automatically.
Amperity could not reach TrueLoyal, or the run was interrupted while reading a data type or writing its file.	A temporary interruption. Amperity retries these automatically.
TrueLoyal rejected the request as invalid, rejected a request parameter, or reported a failed request.	Retrying does not resolve this. If the error occurs when the run starts, check that the partner ID and the API key belong to the same loyalty program. If it occurs while a data type is being read, contact your Amperity representative.
TrueLoyal rejected the paging cursor.	Amperity does not retry this. The data type must be pulled again from the start. Run the courier again with the same settings, either Load all data or the same time period, because the next scheduled run does not cover it.
TrueLoyal returned a response that Amperity does not expect, or paging did not advance.	The run stopped rather than loading an incomplete or repeated set of records. Contact your Amperity representative.

If one data type fails, the entire courier run fails.

Choose topic collections

Pull from TrueLoyal¶

Get details¶

Add courier¶

Get sample files¶

Add feeds¶

Add load operations¶

Run courier manually¶

Add to courier group¶

How data is pulled¶

Troubleshoot errors¶