Batch Operations

Batch operations enable users to perform and manage SIM actions for a large number of SIMs including tasks such as activating and transferring thousands of SIMs to a sub-account in a single action. These operations are handled asynchronously by the system.

How Batch Operations Work

Batch operations are managed by uploading a CSV file. This file identifies the required operation, and the SIMs targeted for these actions. The CSV file is structured with the comma (,) character serving as a delimiter between the CSV fields, for example: field1,field2,field3. The initial line of the CSV file acts as a Header and defines the fields that must be included in the CSV file for each SIM (subscriber) action performed within the selected batch operation. Subsequent lines correspond to individual subscriber actions. The batch operation file uses system internal identities, UUIDs, to designate SIMs and other system entities such as plans, accounts, and statuses.

Significance of UUIDs

A UUID functions as a unique identifier, similar in concept to a serial number, ensuring reliable tracking of each entity. Within the floLIVE Connectivity Management Platform (CMP), UUIDs are used to identify entities including SIM cards, accounts, plans, products, and various associated parameters. UUIDs are generated using standardized algorithms that minimize the risk of collisions (i.e., two different entities being assigned the same ID). While the exact method can vary, each UUID features a combination if various factors such as:

  • Timestamp: The current date and time.
  • Random Numbers:Cryptographically secure random number generators.
  • Hardware Address (MAC Address): A unique identifier for a device's network interface (though this is less commonly used now for privacy reasons).
  • Namespace Identifiers: Predefined values to distinguish between different types of UUIDs

NOTE: Because of the combination of these factors, the probability of of generating the exact same UUID is extremely low.

Reasons for UUID Usage

UUIDs ensure that every entity within the CMP is uniquely identifiable, even across different accounts and systems. The UUID string is essential for:

  • Data Integrity: Prevents confusion and errors when managing large datasets. Without a unique identifier, the system could misinterpret the selected entity and perform actions that might have unexpected results.
  • Batch Operations: Allows the system to accurately target specific entities during bulk actions. Batch operations rely on UUIDs to perform the proper process on selected items.
  • API Operations: Allows external system integration to accurately target specific entities during API integration. API calls rely on UUIDs to perform the proper process on selected items.
  • System Processes: Allows the system to perform actions or generate reports based on uniquely identified entities. System Reports can correctly display required information if the proper UUID are being used.

Understanding Parent and Child UUIDs

It is important to differentiate between the parentSIM UUID and the Child SIM UUID.

  • SIM UUID: Refers to the SIM entity definition in your current account.
  • Child SIM UUID: Refers to the SIM entity when created in one of your sub account (child account).

INSTRUCTIONS: Make sure you use the correct UUID depending on whether you are targeting the SIM card instance in your account or your child account. This is crucial to ensure the desired actions are properly performed on the intended entity.

Understanding Plans and Plan Instances

It is crucial to distinguish between the generic plan UUID and specific instances UUIDs that are created for individual SIMs:

  • Plan Catalog (Generic Definition): A Plan created in the CMP is a kind of template or blueprint. The plan settings may include a wide range of parameters such as data quota, SMS cap, cost, renewal settings, geo restrictions etc.
  • Plan Instance: When this Plan is attached to an individual SIM, this action generates a Plan instance UUID which identifies the exact plan applied on that particular SIM card, along with the data quota, SMS cap, cost, etc. for that SIM card at that specific point in time.

IMPORTANT: Make sure you accurately distinguish between the UUID associated with a Plan Catalog and the UUID that is associated with a SIM-specific Plan Instances. This is crucial to avoid billing errors and connectivity disruptions, which can occur when attaching or detaching the wrong entity.

EXAMPLE

Here is an example that shows the differences between a generic plan UUID and specific instances UUIDs that are created for individual SIMs. Lets assume you have one generic Plan “Platinum 10GB” and you intend to attach it to two SIM cards called “Sim-Alpha” and “Sim-Beta”. The process looks like this:

  1. You have 1 generic Plan UUID for the Platinum 10GB that looks like this: "00000000-0000-0000-0000-000000000000".

  2. When attaching the Platinum 10GB plan to Sim-Alpha you will have created individual Instance-Alpha and that new plan has its individual UUID, that looks like this "11111111-1111-1111-1111-111111111111".

  3. When attaching the Platinum 10GB plan to Sim-Beta you will have created individual Instance-Beta and that new plan has its individual UUID, that looks like this: “22222222-2222-2222-2222-222222222222”.

NOTE: Keep in mind that in this example you have 3 UUIDs instead of one for the same GENERIC offer: “Platinum 10GB”! The “attach” process uses the Plan catalog UUID but the “detach” command MUST use the individual plan SIM instance UUID!