Data Migration

Use the data import APIs to import data for users, subscriptions, groups, and devices and to import catalog item purchase information for a subscription. For example, create a subscription with a final status and a LastActivityUpdateTime and link that subscription to other objects (group, device, user, product offer).

The data import APIs are similar to the ObjectCreate APIs, such as MtxRequestUserCreate, but the data import APIs have additional parameters that allow more flexibility when migrating data. Using the data migration APIs, you can create an object in a dormant state (DormantState = 1). When an object is dormant, all usage is blocked for the object (for example, subscriptions, groups, devices). Sy policy actions are blocked because no usage takes place. No maintenance occurs.

You can link dormant and awake objects in any combination. For example, you can link a dormant user with an awake device and subscription.
Note: After you wake an object, you cannot revert it to a dormant state. You can modify dormant objects if the object status allows it. You can unlink dormant objects if the object status allows it.

Importing Subscriptions

When creating a subscription, notifications and events are not generated. The subscription is created in a dormant state and if aLastActivityUpdateTime is specified, it is used. If you do not specify the LastActivityUpdateTime, the current system time is set at the time of the API call.
Attention: Dormant subscriptions impact subscription counts for MATRIXX licensing.

The status is defined as one that allows creation according to the pricing configuration.

Importing Objects

When importing objects (subscriptions, groups, devices, and users), the objects are in a dormant state by default. To override this, set DormantState to 0. When an object is dormant, it does not cause the generation of events or notifications.

Charges to dormant objects are disabled. Charges due to purchase, activation, initial recurring, and so forth are suppressed for all application charge components. For example, if a subscriber purchases a catalog item that has a purchase charge, the balance does not change. Other pricing components, such as grants and discounts, are not disabled.

Important: Any granted assets have zero GL value. Because charges to dormant objects are disabled, they are not refunded or canceled.

Dormant objects can be activated using the wake APIs at a later time and you can update the LastActivityUpdateTime. If you do not specify the LastActivityUpdateTime, the current system time is set at the time of the API call. If you set the StatusValue field, it overwrites the current status. Otherwise, the current StatusValue is used. You can set the objects' CreationDate. If you do not specify the CreationDate, the current system time is set at the time of the API call.

Groups can have dormant groups or dormant subscriptions as members.

Importing Purchase Offers

You can import purchased offers for subscriptions, devices, and groups. The ImportPurchaseOffer APIs combine the behavior of the PurchaseOffer, ModifyOffer and AdjustBalance APIs; first, the default PurchaseOffer call is made, then any modifications specified (CycleEndDate and Status) and then any balance adjustments.

The ImportPurchaseOffer APIs include a BalanceImportOverrideArray which sets a balance amount to a specific value after all purchase and modify operations have completed (after grants have been applied). For this balance override operation, you must identify the balance to change. Because a resource ID is only assigned after an offer is purchased, a combination of a balance TemplateId or TemplateExternalId and an offer ID or external ID is used. The BalanceIdData parameter is from the specified offer in the purchased item array so that the resource ID of the target balance can be unknown before it is created. BalanceIdData is used for data migration only.

A TemplateId or TemplateExternalId does not ensure that a unique balance is identified as it is possible that different offers can require the same balance as separate instances (for example, private or non-private and so forth). To ensure that a unique balance is identified, OfferIdData is used with BalanceIdData. This allows the combination of a TemplateId or TemplateExternalId from BalanceIdData with a ProductOfferId or ExternalCatalogItemId from OfferIdData to identify a unique balance to adjust to an absolute amount.
Note: OfferIdData is only used during the ImportPurchaseOffer balance adjustment process to identify a specific balance. This is why it is part of the BalanceOverride MDC where:
  • Amount = value to set the balance to.
  • BalanceIdData (TemplateID/ExternalTemplateID) = identifying information to find the balance.
  • OfferIdData (ProductOfferID/ExternalCatalogItemID) = if there are multiples of the same balance template, OfferIdData distinguishes the specific balance associated to the offer purchased at the start of this call.

If a subscriber purchases the same offer twice, either the BalanceTemplateId or ExternalBalanceTemplateId can be used to identify a unique balance.

ExternalCatalogItemId is part of the purchase call and identifies the MtxPurchasedOffer. You can specify a unique ExternalCatalogItemId for each offer in the purchase call. Because this is the specific purchased offer (not a product offer), it is used to identify a unique balance.
Note: The MtxPurchasedOfferData MDC accepts a CatalogItemId, ProductOfferId or ExternalId. When importing, you must specify a ExternalCatalogItemId or a ProductOfferId if there are no duplicate offers purchased. If the strings are not unique, and a balance adjustment operation is performed as part of the ImportPurchaseOffer call, and a unique balance is not identified using the data provided, the operation will fail.

When importing a purchased offer, the offer is considered to have been paid for previously. The purchase amount does not affect the main balance, and if configured, the purchase amount is not requested using Pay Now. GL events are not generated.

When importing purchased offers, balance credit limits are not checked and the balance is loaded as is. If you do not specify offer balances, default balances are applied according to the pricing configuration. You can specify multiple balances and you can adjust balances.

If you do not specify the StartTime, the current system time is set at the time of the API call.

If an offer is configured in pricing so that it is always purchased as preactive, the offer changes status when the subscriber changes status, or the status is changed using the SubMan APIs; if a preactive offer misses its activation date because a subscriber is dormant, when the subscriber is changed from dormant to awake, the offer changes from preactive to active because its activation date is in the past. If the activation date is in the future, then the offer does not change state. When the offer is activated, balances are created.

For periodic offers, the following apply:
  • If the CycleStartTime is empty, the API call time is used if the purchased item is active. The value remains empty if the purchased item is pre-active.
  • If the CycleEndTime is in the past, that time is used.
  • If the CycleEndTime is empty, the API call time is used with the period.

If an offer enters a new cycle while the owning object is dormant, it is not processed; all maintenance activities are suspended on the object.

Applying Eligibility Rules

When importing product offers, you can set the EligibilityCheck parameter to 0, 1 or leave it empty. If the value is true (default), eligibility rule evaluation is performed. If false, eligibility rule evaluation is skipped.

Waking Objects

When waking dormant objects, all functionality, such as usage, maintenance cycles, system triggers, policy, and recurring processing, is activated. The following also applies:
  • Waking subscriptions:
    • For all associated users found, you can optionally specify that if a user is dormant it changes to awake.
    • For all associated devices found, you can optionally specify that if a device is dormant it changes to awake.
  • Waking users:
    • For all associated subscriptions found, if wakeAssociatedSubscriber is true, if a subscription is dormant it changes to awake.
    • For all associated groups found, if wakeAssociatedGroup is true, if a group is dormant it changes to awake.
    • If wakeAssociatedGroup and wakeAssociatedSubscriber are true, other subscriptions in the associated groups that are not subscriptions directly associated with the user do not change.
  • Waking devices:
    • If the associated subscription is dormant, and wakeAssociatedSubscriber is true, it changes to awake. Other devices associated with the subscription do not change.
  • Waking groups:
    • For all associated users found, if a user is dormant, it changes to awake.
The following objects can use the listed APIs to wake the associated objects.
  • Devices: MtxRequestSubscriptionImportWake
  • Subscriptions: MtxRequestUserImportWake, MtxRequestDeviceImportWake
  • Groups: MtxRequestUserImportWake
  • Users: MtxRequestSubscriptionImportWake. MtxRequestGroupImportWake

When waking these objects, if event generation is configured in My MATRIXX, an MtxImportWakeEvent EDR is generated . For more information about configuring event generation, see the discussion about event mapping in My MATRIXX.

Deleting Dormant Objects

When you delete a subscription, the subscription status policy is checked to determine if it is allowed. If the subscription deletion also specifies linked device deletion, both status policies must allow deletion or the objects are not deleted. Events and notifications are generated. You can delete a subscription and device in any of the following states:
  • Subscription is dormant; device is dormant.
  • Subscription is dormant; device is awake.
  • Subscription is awake; device is dormant.