Skip to main content

Deprecated: Use Single Subscription and Amendments

Zuora

Deprecated: Use Single Subscription and Amendments

When you create an amendment and sync it to Salesforce, the original version of the subscription is deleted by default, and a new subscription with a new Salesforce ID is created in Salesforce. If your custom application requires a lookup reference to the original subscription, follow the steps in this article to enable and use the single subscription when creating amendments in Zuora Quotes. 

The following two new fields were added to support the single subscription for amendments:

  • The Subscription Number field (Zuora__SubscriptionNumber__c) was added to the Subscription object as an External ID. If this feature is enabled in your tenant, Zuora Salesforce Connector will upsert a Subscription using the Subscription Number. Since Subscription Number does not change across Subscription versions, Subscription records in Salesforce will have the same Salesforce Record ID across multiple Subscription versions.
  • The Charge Number field (Zuora__SubscriptionChargeNumber__c) was added to the Subscription Product Charge object as an External ID. If this feature is enabled in your tenant, Zuora Salesforce Connector will upsert a Subscription Product Charge using the Charge Number. Since Charge Number does not change across Subscription Product Charge versions, the Subscription Product Charge records in Salesforce will have the same Salesforce Record ID across multiple Subscription Product Charge versions.

To enable and use the single subscription and amendments:

  1. Stop existing sync operations.
  2. Ensure that the user who performs Zuora Salesforce Connector has the field-level Visible access to the new fields listed above, Subscription Number and Charge Number in Salesforce. See Setting Field-Level Security in Salesforce for checking and setting the field-level access for profiles.
  3. Migrate subscription and charge numbers.
  4. Contact Zuora Support to enable the tenant permission, Only Update Salesforce Subscription For Sync, to use the single subscription in your Zuora Sandbox.
  5. Test Zuora Connector for Salesforce CRM thoroughly in the API Sandbox.
  6. If all testing is successful in the API Sandbox, repeat steps 1 to 6 to enable your tenant permission in your Production environment.

Migrate Subscription and Charge Numbers

To migrate subscription and charge numbers:

  1. In Salesforce, open Developer Console.
  2. In the Query Editor tab, type the below query and click Execute:
    SELECT count(id) FROM Zuora__Subscription__c WHERE Zuora__SubscriptionNumber__c=null
  3. If count(id) returns zero in the Query Result window, skip to Step #5.
  4. If count(id) returns a value greater than zero in the Query Result window, you need to migrate the data to fill into the value of these two fields by executing the apex class.
    1. Navigate to Debug > Open Execute Anonymous Window.
    2. In the Enter Apex Code window, type: 
      Database.executeBatch(new Zuora.SubAndChargeNumberBatchMigration('Subscription__c'));
    3. Click Execute.
    4. Recheck the job status with the query in Step #2.
  5. In the Query Editor tab, type the below query and click Execute:
    SELECT count(id) FROM Zuora__SubscriptionProductCharge__c
    WHERE Zuora__SubscriptionChargeNumber__c=null
  6. If the query times out before completing, run the query in Data Loader.
  7. If count(id) returns zero in the Query Result window, your upgrade is complete. Exit the process.
  8. If count(id) returns a value greater than zero in the Query Result window, you need to migrate the data to fill into the value of these two fields by executing the apex class.
    1. Navigate to Debug > Open Execute Anonymous Window.
    2. In the Enter Apex Code window, type: 
      Database.executeBatch(new Zuora.SubAndChargeNumberBatchMigration('SubscriptionProductCharge__c'));
    3. Click Execute.
    4. Recheck the job status with the query in Step #7.
  9. Monitor the Apex job status.
    1. Navigate to Setup > Monitor > Jobs > Apex Jobs.
    2. Check the status of the jobs for the SubAndChargeNumberBatchMigration class.
    3. The following error does not impact the data migration and can be ignored:
      First error: Insert failed. First exception on row 0; first error: FIELD_INTEGRITY_EXCEPTION, There is already an item in this list with the name COM8903_OnlySubUpdate_Charges: Name: [Name]

Troubleshooting

This section contains troubleshooting tips for issues that you might encounter after activating the single subscription setting:

  • Sync failure after activating the single subscription setting

The error looks like "... field 'Zuora__SubscriptionNumber__c' is not readable... ."  To fix this issue, follow the above steps #3 and #4 given at the top of this article.

  • There are two subscriptions with the same name, one with the Zuora__SubscriptionNumber__c value null and one with a non-null value.

When you execute the apex job, if you receive the error, “First error: Update failed. First exception on row 6 with id a1390000002BWLnAAO; first error: DUPLICATE_VALUE, duplicate value found: Zuora__SubscriptionNumber__c duplicates value on record with id: a1390000002BbHA:”, you have two subscriptions with the same name.

Manually delete the subscription with the null Zuora__SubscriptionNumber__c value and then follow the above steps #3 and #4 given at the top of this article.

Execute the following SOQL to check whether there is any other duplicated data:

SELECT count(id), name FROM Zuora__Subscription__c GROUP BY name Having count(id)>1