Skip to main content

Upgrade Zuora 360

Zuora

Upgrade Zuora 360

  1. Last updated
  2. Save as PDF

The article covers all the required upgrade tasks from the earliest supported version of Zuora 360. Even if you are upgrading from a later version of Zuora 360, we recommend that you review all the required tasks and upgrade as it applies to the current state of your Zuora 360 org.

If you do not have Zuora 360 installed, you can contact Zuora Global Support to request an installation link, then perform the standard installation as described in Installing Zuora 360.

Time Required for the Zuora 360 Upgrade

Zuora recommends that you schedule the first full sync to a time that will not affect your business processes. Examples of the configurations that can affect upgrade performance are:

  • Object triggers implemented on the most-used objects (Billing Account, Subscription, Subscription Charges, Invoices), especially if the triggers are using complex security sharing logic.
  • Cascade deletes of child objects, if you have defined master/detail relationship between these objects and other custom objects.

Prepare to Upgrade Zuora 360

Before you upgrade Zuora 360, determine the Installed Version of Zuora 360 in your org:

  1. In Salesforce, navigate to Setup > Installed Packages. 
  2. Note the Version Number of the 360 package.

High-level Upgrade Steps

Follow the below steps to upgrade Zuora 360 to the latest version:

  1. Install the Zuora 360 managed package in Salesforce.
    Contact Zuora Global Support for the installation link. See Install the Zuora 360 Package for detailed information. Return to the upgrade steps when the installation completes.
  2. Add the tabs for Zuora 360 to your Salesforce org:
    • Schema Setup
    • Connection Setup
  3. Update object permissions to sync users.
    If your sync users do not have the System Administrator profile, assign permissions to sync users.
  4. Update field permissions to sync users.
    If your sync users do not have the System Administrator profile, assign permissions to sync users.
  5. Assign page layouts to user profiles.
  6. Update the Invoice page layout.
  7. Grant access to Apex classes to profiles.
  8. Review and update your Order Builder code for the date time field type changes and time zone support.
  9. Update field sets.
  10. Review and migrate new fields via migration settings.
  11. Perform a sync of Account & Related Objects.

The remainder of this article describes the above steps in detail. 

Assign Page Layouts to User Profiles

Assign the latest page layouts listed in the following table to your sync user profiles.

Object Page Layout to User
Billing Account
(Zuora__CustomerAccount__c)		 Billing Account Z-Force Layout v.2.9
Invoice
(Zuora__ZInvoice__c)		 ZInvoice Z-Force Layout v2.100
Invoice Payment
(Zuora__PaymentInvoice__c)		 PaymentInvoice Z-Force Layout v2.5

Payment
(Zuora__Payment__c)

 Payment Z-Force Layout v2.7
Subscription
(Zuora__Subscription__c)		 Subscription Z-Force Layout v2.6
Subscription Product & Charge
(Zuora__SubscriptionProductCharge__c)		 Subscription Charge Z-Force Layout 2.9


To assign the page layouts to user profiles:

  1. Navigate to Setup > Create > Objects.
  2. Click the object.
  3. In the Page Layouts section, click Page Layout Assignment.
  4. Click Edit Assignment.
  5. Click the profile.
  6. With the profile, click the Page Layout To Use field, and select the page layout shown in the table above.
  7. Repeat the Step #6 to assign all applicable user profiles and page layouts.
  8. Click Save.

Update the Invoice Page Layout 

A new menu item was added to allow inline viewing of the invoice PDF. The option is available as a button or a custom link.

To edit the Invoice page layout to add the button or the custom link for Invoice PDF:

  1. Navigate to Setup > Create > Objects.
  2. Click Invoice. 
  3. In the Page Layouts section, click the Edit link next to ZInvoice Z-Force Layout v2.100.
  4. Click Buttons to add the buttons.
  5. Alternatively, click Custom Links to add the links to view or download invoice PDFs.
  6. Drag Invoice PDF and View Invoice PDF down to the bottom of the page and drop it into position.
  7. Click Save.

Grant Access to New Apex Classes

To each applicable user profile, grant access to the Apex classes:

  1. Navigate to Setup > Manage Users > Profiles.
  2. Click the profile to whom you want to grant access to.
  3. On the Profile page, click Apex Class Access.
  4. Click Edit.
  5. On the Apex Class Access page, click and add all Apex classes with the namespace "Zuora" from the Available Apex Classes section to the Enabled Apex Classes section.
  6. Click Save.

DateTime Field Changes and Time Zone Support

A number of dateTime type fields were changed to the Date type in the version 69 of Zuora WSDL. If you have custom code using Order Builder, follow the steps to review and update affected code:

  1. Review Date Field Changes in the SOAP API for the list of affected fields whose type was changed to Date from dateTime.
  2. Upgrade your Zuora WSDL version in the API Connection Setting to 69 or higher.
  3. Upload the version 69 or higer of Zuora WSDL in Schema Setup. 
  4. Update your Order Builder code to reflect the changes.
    The following global methods were updated or added to support the changes related to time zone support in Zuora. Review your Order Builder code for the changes and make updates where needed.
Global Method Version Changed Change
Zuora.zUtil.getZuoraDate 2.100 The method now returns a string that includes the Salesforce user's time zone offset.
Zuora.zUtil.getZuoraDateOnly 2.100 The method returns a date only string for the Date type fields in version 69 or higher of Zuora WSDL.

Grant Permissions on New Custom Objects

To enable access to the new objects added, grant the Read, Create, Edit, and Delete permissions on these objects to the sync user profile.

Additionally, grant the Read and Edit field level permissions on all fields in the new objects to the same sync user profile.

The following new custom objects were added in this and previous versions.

If you are upgrading from a version higher than what is specified in the Added in Version column, you do not need to grant permissions to that object.

Object Name 
(API Name)		 Added in Version
Refund
(Zuora__Refund__c)		 2.7
Refund Invoice Payment
(Zuora__RefundInvoicePayment__c)		 2.7
Subscription Product Feature
(Zuora__SubscriptionProductFeature__c)		 2.9
Payment Gateway
(Zuora__PaymentGateway__c)		 3.0
Subscription Rate Plan
(Zuora__SubscriptionRatePlan__c)		 3.0
Subscription Rate Plan Charge Tier
(Zuora__SubscriptionRatePlanChargeTier__c)		 3.0
Invoice Item
(Zuora__InvoiceItem__c)

4.0

This feature is in Early Adopters program. You only need to grant permission to this object if the Zuora Tenant setting is enabled.

 

To each applicable profile, to grant permissions for the new custom objects:

  1. Navigate to Setup > Manage Users > Profiles.
  2. Click the sync user profile to which you want to grant permissions.
  3. Click Object Settings.
  4. After reviewing the permissions, if you want to change, click the object.
  5. On the Profile page, click Edit.
  6. In the Object Permissions section, select Read, Create, Edit, and Delete.
  7. In the Field Permission section, select Read and Edit for all the fields.
  8. Click Save.
  9. Repeat the Steps #4 - #7 for each new object.

Grant Permissions on New Custom Fields

Grant the Read and Edit permissions to the sync user profile on the following new fields. 

If you are upgrading from a version higher than what is specified in the Added in Version column, you do not need to grant permissions to those fields.

Object Name Field Name

Added in Version
Billing Account
  • Additional Email Addresses
  • Allow Invoice Edit
  • Bcd Setting Option
  • Communication Profile Id
  • Invoice Delivery Prefs Email
  • Invoice Delivery Prefs Print
  • Invoice Template Id
  • Notes
  • Payment Gateway
  • Sold To Address1
  • Sold To Address2
  • Sold To City
  • Sold To Country
  • Sold To Fax
  • Sold To Postal Code
  • Sold To State
  • Sold To Work Email Email
  • Sold To Work Phone
  • Tax Exempt Certificate ID
  • Tax Exempt Certificate Type
  • Tax Exempt Description
  • Tax Exempt Effective Date
  • Tax Exempt Expiration Date
  • Tax ExemptIssuing Jurisdiction
  • Tax Exempt Status
  • Total Invoice Balance
 3.0
Invoice
  • Credit Balance Adjustment Amount
 3.0
Subscription
  • Cancelled Date
  • Opportunity Close Date
  • Opportunity Name
  • Original Id
  • Previous Subscription Id
  • Quote Business Type
  • Quote Number
  • Quote Type
 3.0
Subscription Product & Charge
  • Apply Discount To
  • Bill Cycle Day
  • Bill Cycle Type
  • Billing Period Alignment
  • Charged Through Date
  • Discount Amount
  • Discount Level
  • Discount Percentage
  • DMRC
  • DTCV
  • Included Units
  • Is Last Segment
  • List Price Base
  • Number Of Periods
  • Original Id
  • Original Product Rate Plan Charge Id
  • Overage Calculation Option
  • Overage Price
  • Overage Unused Units Credit Option
  • Price Change Option
  • Price Increase Percentage
  • Processed Through Date
  • Product RatePlan Charge Id
  • Rev Rec Code
  • Rev Rec Trigger Condition
  • Segment
  • Specific Billing Period
  • Subscription Rate Plan
  • Trigger Date
  • Trigger Event
  • Unused Units Credit Rates
  • UsageRecordRatingOption
  • UseDiscountSpecificAccountingCode
  • Version
 3.0

 

To each applicable profile, grant permissions for all newly added fields:

  1. Navigate to Setup > Manage Users > Profiles.
  2. Select the profile to which you want to grant field-level permissions.
  3. Click Object Settings.
  4. After reviewing the permissions, if you want to change, click the object.
  5. Click Edit.
  6. In the Field Permissions section, select the Read and Edit permissions for each new field.
  7. Click Save.
  8. Repeat the Steps #4 - #7 for each object with newly added fields listed in the table above.

Update Field Sets

The following table lists the changes needed in field sets. Review the field sets in your org and make changes as necessary. 

Object Field Set Changed
in
Version		 Field Change
Subscription Product & Charge
(Zuora__SubscriptionProductCharge
__c)		 SubscriptionCharges 4.8

If you turned on the Get Subscriptions From 360 Zuora Config setting, add the new field to the field set to display the name in the Select Billing Account table in the quoting flow:
Subscription Rate Plan Charge Name 
( Zuora__SubscriptionRatePlanChargeName
__c)

Migrate New Fields via Migration Custom Settings

If you have a big volume of data, syncing all the data for updated objects can potentially take a long time after a package upgrade. You can use the Migration Custom Setting to control the sync of the updated objects.

By default, the Migrated field in the Migration Keys is set to true, and the data for the updated objects are not migrated in the first sync session after the Zuora 360 upgrade. If you want the fields populated in the existing object records, take the below steps to trigger the data migration of the fields in next Zuora 360 sync session.

The following are the migration keys, the Zuora 360 package versions the keys were added, and the fields added or updated.

Added
in

Version

 Migration Key Object.Field Synchronized
4.2

PE-501-Charge

 
  • Rate Plan Charge.Billing Timing
  • Product Rate Plan Charge.Billing Timing
4.2 PE-520-PaymentMethod
  • PaymentMethod.TokenID
3.44

PE_303_SubscriptionProductCharge
  • Subscription Product & Charge.Weekly Bill Cycle Day
3.4

PE-81_Subscription
  • Subscription.Current Term
  • Subscription.Current Term Period Type
  • Subscription.Initial Term Period Type
  • Subscription.Renewal.Term.Period.Type
3.3

COM11312_BillingAccount
  • Billing Account.Communication Profile Id
    (Zuora__Communication_Profile_Id__c)
3.2

MultiEntity_BillingAccount
  • Billing Account.Entity ID
3.2 MultiEntity_Product
  • Product(Zuora__Product__c).Entity ID
3.0

CPQ_InvoiceMigration
  • Invoice.Credit Balance Adjustment Amount
3.0

CPQ_Subscription
  • Subscription.Original Id
  • Subscription.Cancelled Date
  • Subscription.Previous Subscription Id
3.0

CPQ_SubscriptionCharge
  • Subscription Product & Charge.Apply Discount To
  • Subscription Product & Charge. Bill Cycle Day
  • Subscription Product & Charge.Bill Cycle Type
  • Subscription Product & Charge.
    Billing Period Alignment
  • Subscription Product & Charge.
    Charged Through Date
  • Subscription Product & Charge.Discount Amount
  • Subscription Product & Charge.Discount Level
  • Subscription Product & Charge.Discount Percentage
  • Subscription Product & Charge. DMRC
  • Subscription Product & Charge.DTCV
  • Subscription Product & Charge.Included Units
  • Subscription Product & Charge. Is LastS egment
  • Subscription Product & Charge.List Price Base
  • Subscription Product & Charge.Number Of Periods
  • Subscription Product & Charge. Original Id
  • Subscription Product & Charge.
    Overage Calculation Option
  • Subscription Product & Charge.Overage Price
  • Subscription Product & Charge.
    Overage Unused Units Credit Option
  • Subscription Product & Charge.
    Price Increase Percentage
  • Subscription Product & Charge.
    Processed Through Date
  • Subscription Product & Charge.
    Product Rate Plan Charge Id
  • Subscription Product & Charge.Rev Rec Code
  • Subscription Product & Charge.
    ev Rec Trigger Condition
  • Subscription Product & Charge.Segment
  • Subscription Product & Charge. Specific Billing Period
  • Subscription Product & Charge.Trigger Date
  • Subscription Product & Charge.Trigger Event
  • Subscription Product & Charge.
    Unused Units Credit Rates
  • Subscription Product & Charge.
    Usage Record Rating Option
  • Subscription Product & Charge.
    UseDiscountSpecificAccountingCode
  • Subscription Product & Charge.
    Original Product Rate Plan Charge Id
  • Subscription Product & Charge.Price Change Option
  • Subscription Product & Charge.Billing Timing
  • Subscription Product & Charge.Version
  • Subscription Product & Charge.
    Subscription Rate Plan
3.0 COM-9137_Quote_Subscription
  • Quote.Quote Type
  • Quote. Quote Business Type
  • Quote.Quote Number
  • Quote.Opportunity Close Date
  • Quote.Opportunity Number
3.0 COM-9137_SoldToContact
  • Billing Account.Sold To City
  • Billing Account.Sold To Country
  • Billing Account.Sold To Address1
  • Billing Account.Sold To Address2
  • Billing Account.Sold To State
  • Billing Account.Sold To Postal Code
  • Billing Account.Sold To Fax
  • Billing Account.Sold To Work Email
  • Billing Account.Sold To Work Phone
2.111

COM_10097_SubscriptionCharge
  • Product Rate Plan Charge.Up To How Many Periods
  • Product Rate Plan Charge.Up To Periods Type
  • Product Rate Plan Charge.End Date Condition
  • Subscription Product & Charge.Up To How Many Periods
  • Subscription Product & Charge.Up To Periods Type
  • Subscription Product & Charge.End Date Condition
  • Subscription Product & Charge.Specific End Date
2.110

COM-8422_InvoiceMigration
  • Invoice.Posted Date
  • Invoice.Generated Date
2.110

COM-8422_PaymentMethod
  • Payment Method. Mandate Creation Date
  • Payment Method.Mandate Update Date
2.110

COM-8422_SubscriptionMigration
  • Subscription.Original Created Date
2.110

COM-8422_RefundMigration
  • Refund.Refund Date
2.110 COM-8422_PaymentMigration
  • Paymen.Effective Date
2.104

COM8903_OnlySubUpdate_Subscription
  • Subscription.Subscription Number
2.104 COM8903_OnlySubUpdate_Charges
  • Subscription Product Charge.Charge Number
2.80

COM618_RateplanId
  • Subscription Product & Charge.Rate Plan ID

 

To trigger the data migration in the next sync session:

  1. In your Salesforce org, navigate to Setup > Develop > Custom Settings.
  2. Click Manage for MigrationSettings.
  3. For each setting you want to migrate, repeat the steps:
    1. Click the setting key.
    2. Click Edit.
    3. Clear the Migrated field.
    4. Click Save.

To check the status of the migration jobs:

  1. Navigate to Setup > Jobs > Apex Jobs.
  2. Check the status of the post-installation job, ChainedJob, in the Apex Jobs table.
  3. If ChainedJob failed, navigate to Setup > Administration Setup > Monitoring >  Debug Logs to see detailed information of the failure or error.
  4. If you cannot find any useful information under Debug Logs, contact Zuora Global Support for assistance.