Getting Started

Understanding Data Entities & Relationships

Before uploading data, it's crucial to understand the supported entities, their relationships, and how Zluri processes different data types.

Supported Entities

Entity Type	Description	Common Use Case
Users	Employee or user profile details	Sync employee roster from HR system
User Roles	Mapping of roles to their users	Track access of users
User Licenses	Mapping of licenses to their users	Track license assignment of users
User Activity	Login or activity events from apps	Track application usage patterns
Groups	Organizational or functional groupings	Manage teams, departments, and roles
Group Users	Mapping of users to their groups	Assign users to teams/departments
Transactions	SaaS payments and subscription spend	Track software spending history
Contracts	Vendor contract metadata	Manage vendor agreements
Contracts Licenses	Mapping of licenses to their contracts	Manage contract license assignments

Data Models: Snapshot vs. Incremental

Zluri processes entities using two different data models. Understanding this is critical for successful data management.

Snapshot Data (Current State Model)

What it is: Represents the current state of an entity at a point in time.

How it works: Each upload replaces the previous state entirely. If an entity is missing from the new upload, it's considered removed or inactive.

Snapshot Entities:

Users - Current employee roster
Groups - Current organizational structure
Group Users - Current group memberships
- Example:
  
  Upload 1: John Doe is "Active" in Engineering
  Upload 2: John Doe is "Active" in Marketing → Engineering assignment is replaced
  Upload 3: John Doe is missing → John is marked "Inactive"

Key Behaviour:

Upload reflects the complete current state
Missing records = inactive/removed
Latest upload wins
No historical record preservation

Incremental Data (Historical Event Model)

What it is: Represents time-based, historical events or transactions.

How it works: Each upload appends new records to existing history. Previous records are never overwritten or removed.

Incremental Entities:

Contracts - Contract creation and amendments
Transactions - Payment and renewal history
User Activity - Login events and usage logs

Example:

Upload 1: Payment of $1000 on Jan 1
Upload 2: Payment of $500 on Jan 15 → Both payments preserved
Upload 3: Login event at 2 PM → Added to activity history

Key Behaviour:

All events are preserved
Builds a historical timeline
Can upload partial data
Cannot delete or modify past events

Key Differences: Snapshot vs. Incremental

Aspect	Snapshot Data	Incremental Data
Nature	Current state	Historical events
Time Reference	Point-in-time	Time-series
Update Behaviour	Replaces the previous state	Adds to history
Example	"John is currently active"	"John logged in at 2 PM on Jan 15"
Use Case	Employee management	Activity tracking
Processing	Latest sync wins	All events preserved
Missing Records	Marked inactive/removed	No impact on history

Cross-Entity Dependencies

Some entities depend on others. You must upload foundational entities before dependent ones.

Dependency Requirements:

Entity	Depends On	Validation Requirement
Users	–	Can be uploaded independently
User Roles	Users	Each role record must reference a valid user - user entity must be present in the same sync upload
User Licenses	Users	Each license record must reference a valid user - user entity must be present in the same sync upload
User Activity	Users	Each activity record must reference a valid user - user entity must be present in the same sync upload
Groups		Can be uploaded independently
Group Users	Groups & Users	Must reference a valid user and group — both entities must be present in the same sync upload
Transactions	-	Can be uploaded independently
Contracts	-	Can be uploaded independently
Contracts Licenses	Contracts	Each contract license record must reference a valid contract - contract entity must be present in the same sync upload

📘
Important: "Must be present in the sync" means the referenced entity must be included in the same upload batch. If you're uploading User Activity, the corresponding Users must be in the same upload.

Sync Behavior & Data Replacement

Understanding how Zluri processes your uploads is critical to avoid data loss.

Full Sync Mode (Default for Snapshot Entities)

Behaviour:

Every upload is treated as the complete current state
Any entity not in the upload is marked as inactive/removed
All previous data for that entity type is replaced

Examples:

Users (Snapshot):

Week 1 Upload: 100 users Week 2 Upload: 95 users → 5 missing users marked INACTIVE
Week 3 Upload: 100 users (original 100) → 5 users marked ACTIVE again

What this means:

You must upload the full list of active users each time
Omitting a user = telling Zluri that user is no longer active
To keep users active, include them in every upload

Groups (Snapshot): Upload 1: Engineering, Marketing, Sales Upload 2: Engineering, Marketing → Sales group is REMOVED

Group Users (Snapshot):

Upload 1: John is in Engineering, Marketing Upload 2: John is in Engineering → John REMOVED from Marketing

Incremental Mode (Default for Incremental Entities)

Behaviour:

Only the records you upload are added
Existing records remain untouched
No data is ever removed or replaced

Examples:

Transactions (Incremental):

Week 1 Upload: Jan 1-7 transactions (50 records) Week 2 Upload: Jan 8-14 transactions (45 records) Result: 95 total transactions preserved

User Activity (Incremental):

Upload 1: Monday logins Upload 2: Tuesday logins Result: Both days' activities are preserved

What this means:

You can upload only new/changed records
Safe to upload partial data sets
Historical data is never lost