Skip to main content

Multi-Org upgrade path

Zuora

Multi-Org upgrade path

  1. Last updated
  2. Save as PDF

Select your upgrade path to Zuora Multi-Org from one of the following use cases that best suits your requirements:

Upgrade Single Tenant to Zuora Multi-Org

As a first step to migrate your single tenant to Zuora Multi-Org, contact Zuora Global Support team. They will direct you to the Zuora Multi-Org team to help you understand the migration process. 

Next, enabling Zuora Multi-Org for a single tenant with existing transactional data is done through the Multiple Organization APIs using the following steps:

  1. Create a Zuora Multi-Org organizational hierarchy
  2. Label the key objects: 
    1. Customer Accounts
    2. Products in the Product Catalog
    3. Users
  3. Repeat Step 2 to label all the key objects. 
  4. Review the audit log actively for labeling changes to the key objects.
  5. After thoroughly reviewing, ensure that appropriate internal change management actions are initiated to familiarize your org users with their visibility within the organizational hierarchy.
  6. Verify and activate Zuora Multi-Org  

In addition to the three key objects specified in Step 2, at least 100+ dependent objects will also be labeled based on the labels created in Step 3. 

See the Multiple Organizations API reference for details about data labeling.  

Upgrade existing Data Access Controls (DAC) tenant to Zuora Multi-Org

Data Access Control (DAC) allows businesses to customize and control user access within Zuora Billing. A hierarchy of tags was leveraged to enforce access to a Zuora object. This hierarchy of tags has a tree structure where tags are assigned to users and objects. However, certain constraints including no API support, and having no autonomy over user access controls led to the creation of Zuora Multi-Org.

Migrating from Data Access Controls (DAC) enabled tenant to Zuora Multi-Org   Edit section

There are 2 use cases where a business would want to migrate to Multi-Org from their existing DAC-enabled setup:

  1. Businesses can leverage the existing DAC tag hierarchy to create the new Org. hierarchy in Zuora Multi-Org as a 1:1 mapping.
  2. Businesses can create a brand new Org. Hierarchy in Zuora Multi-Org 

Upgrade to Zuora Multi-Org with existing DAC tag hierarchyEdit section

This section explains Use Case 1 in detail on how a business that has an existing DAC-enabled tenant can upgrade to Zuora Multi-Org using the same tag hierarchy created in DAC with a 1:1 mapping

  dac-hierarchy.png       DAC Tag hierarchy.png

Fig 1. DAC Tag Hierarchy 1:1 mapping to Multi-Org  Hierarchy

 

Here are a few terms and concepts to familiarize yourself before getting started:

Zuora DAC Zuora Multi-Org.

Root

Root is referred to as the global entity by default. 

Root

Root is referred to as the global organization (default parent)

Segments

Children under the root level.

Org. Units

Each of the children under the root is referred to as an org. unit.
Points to remember before upgrading a DAC-enabled tenant to Zuora Multi-Org    Edit section
  1. DAC customers must be enabled with Invoice Settlement capability to upgrade to Zuora Multi-Org  
  2. DAC allows the removal of children and associated date after they have been added to an Org. Hierarchy with limitations on the ability to delete a node that has children under it.
  3. In DAC, a user with access to the parent has implicit access to all the objects that are children of the parent.
  4. In Multi-Org objects are visible only if the user has explicit permission to access one or more Org. units.

For a DAC customer:

The following are backward-incompatible API changes 

Originally there was a xxx__h field where xxx is the hierarchy API name, in the API payload. Once the customer is migrated to Multi-Org the xxx__h will no longer exist. This will be replaced by new organization-related fields including "organizationLabels" or "organizationLabel".

Existing API Payloads for DAC customers:

The following APIs have xxx__h field in their response body:

Method  URI Field Path
GET /accounts/{account-key} basicInfo.tags
GET /accounts/{account-key}/summary basicInfo.tags
GET /catalog/product/{product-id} tags
GET catalog/products products.tags

The following APIs have xxx__h field in their request body:

Method URI Request body field
POST /orders newAccount.tagging
PUT /accounts/{account-key} tagging
PUT /orders/{orderNumber} newAccount.tagging

 

Steps to Upgrade to Zuora Multi-Org through APIs 

As a first step to migrate to Zuora Multi-Org contact Zuora Global Support team. They will direct you to the Zuora Multi-Org team to help you with the migration process. 

The steps mentioned below are only to demonstrate the working of our internal upgrade API to help you (DAC customers) understand what this upgrade does, and does not require you to perform any of these actions. 

Upgrading an existing DAC-enabled tenant with the first existing active org hierarchy among multiple org hierarchies through a 1:1 mapping to the newly enabled Zuora Multi-Org hierarchy involves the following steps:

  1. Cloning the DAC tag hierarchy to create the new Zuora Multi-Org organizational hierarchy.
  2. Labeling the key objects based on the DAC tags: 
    1. Customer Accounts    
    2. Products in the Product Catalog
    3. Users
  3. Deactivating the DAC tag hierarchy.
  4. Activating the Zuora Multi-Org org hierarchy

See the Multiple Organizations API reference for details on Data Labeling.

Once Multi-Org is activated, a user will only have access to the data they are permitted by the org admin.

Co-existence of Zuora Multi-org as a leaf entity in the Zuora Multi-entity environment

Zuora Multi-Org is designed to cater to the needs of various customers. These include customers who expect autonomy over settings and require hard segmentation of organizational or business boundaries. Especially when businesses do not need to be intermingled or need to run regionally. And that is why the coexistence of Multi-Org and the existing Multi-Entity framework becomes indispensable. 

Migrating from Multi-Entity to Multi-Org   Edit section

There are 3 use cases where a business would want to migrate to Multi-Org from their existing multi-entity setup:

  1. Enabling Zuora Multi-Org for a leaf sub-entity in an existing Multi-Entity setup
  2. Collapsing all the entities (including the root) in a multi-entity setup into a single entity in Zuora Multi-Org  
  3. Disconnecting a left sub-entity in a multi-entity setup after Zuora Multi-Org is enabled and running it as a standalone tenant. 

Use Case #2 does not follow an automatic process. Please contact the Zuora Global Support team to discuss the detailed data migration solution suitable for you. 

Enabling Multi-Org for Use cases 1 and 3 can be categorized under one of the two upgrade scenarios as mentioned below:

Upgrade to Zuora Multi-Org. with existing transactional data If there is existing transactional data in the sub-entity being upgraded to Zuora Multi-Org., then you would need to upgrade the sub-entity by following the process mentioned in the Upgrade to Zuora Multi-Org with existing transactional data section below.

 
Upgrade to Zuora Multi-Org. with no transactional data If the sub-entity to be upgraded is a new sub-entity or tenant then you can simply upgrade to Zuora Multi-Org. before using the tenant for any transaction.

Upgrade to Zuora Multi-Org with existing transactional data Edit section

This section explains use case 1 in detail on how a business has an existing Multi-entity environment can upgrade a leaf sub-entity within that Multi-Entity setup to Zuora Multi-Org  

Here are a few terms and concepts to familiarize before getting started:

Zuora Multi-Entity  Zuora Multi-Org. 

Root

The root is referred to as the global entity (By default) but you can select a preferred root name. 

Root

Root is referred to as the global organization (default parent)

Sub-Entity

Each child entity under the global entity is referred to as a sub-entity. 

Org. Units

Each of the children under the root is referred to as an org. unit.
Points to remember before upgrading a Multi-Entity sub-entity to Zuora Multi-Org   Edit section
  1. Only a leaf sub-entity in a Multi-Entity setup can be upgraded to Zuora Multi-Org 
  2. User access controls and data segmentation will have to be set up separately for the Zuora Multi-Org sub-entity as compared to the existing Multi-entity setup. The user and application behavior may vary for Zuora Multi-Org from Multi-Entity.
  3. You must have Zuora Universal User (One ID) activated for a seamless login experience between Zuora Multi-Entity and Zuora Multi-Org sub-entity.
  4. The behavior of platform components like custom objects, workflows, etc., may vary between Zuora Multi-Entity and Zuora Multi-Org sub-entity.
  5. Financial roll-ups will work for Zuora Multi-Org sub-entity and do not apply to Multi-Entity.
  6. Settings including Invoice Numbering, Product in the Product Catalog, Product Rate Plan Changes, Notifications, etc. that exist at a per-entity level will be applied at the tenant level post upgrade and apply to all org units in Zuora Multi-Org  
  7. Product sharing across sub-entities in a Multi-entity setup will differ from sharing products in the product catalog in Zuora Multi-Org setup.
  8. Any transactional data within a closed accounting period will be subject to the labeling and data segmentation rules of Zuora Multi-Org  The same will apply to any transactional data in the accounting period that closed after the enablement of Zuora Multi-Org  
  9. Zuora Revenue will exclusively sync 1:1 through the OTR sync with each org unit defined in Zuora Billing.
Steps to enable Zuora Multi-Org through APIs  Edit section

Enabling Zuora Multi-Org for a leaf sub-entity of Multi-Entity with existing transactional data is done through the Multiple Organization APIs involves the following steps:

  1. Create a Zuora Multi-Org organizational hierarchy
  2. Label the key objects: 
    1. Customer Accounts
    2. Products in the Product Catalog
    3. Users
  3. Repeat Step 2 to label all the key objects. 
  4. Review the audit log actively for labeling changes to the key objects.
  5. After thoroughly reviewing, ensure that appropriate internal change management actions are initiated to familiarize your org users with their visibility within the organizational hierarchy.
  6. Verify and activate Zuora Multi-Org  

In addition to the three key objects specified in Step 2, at least 100+ dependent objects will also be labeled based on the labels created in Step 3. 

See the Multiple Organizations API reference for details about data labeling.  

Once Zuora Multi-Org is activated in the sub-entity of the Zuora Multi-Entity setup, data segmentation rules take effect. As a result, any user that had access to all the data within the sub-entity will be restricted to access only the data based on the user's roles in the Multi-Org setup provided by the IT admin. And the org unit that the user now belongs to.