Zuora Integration

About Zuora

Zuora represents a comprehensive cloud-based subscription management platform that help organizations administer the subscription lifecycle of their customers. Zuora combines subscription commerce, billing and financing solutions in a single package. General Zuora capabilities include:

• Price and package your products with unlimited flexibility
• Configure, price, and quote for recurring revenue businesses
• Securely manage generated subscriptions, payments and required accounts
• Recognize recurring revenue and stay aligned with your accounting system
• Measure your business and understand your subscribers

The following provides instructions on how to integrate Zuora to the CloudBlue Connect platform via the Workato automation system.

Rules and Limitations

It is important to note that the integration with the Zuora platform includes a set of rules and limitations that are described below:

• In case an order with multiple products is generated on the Zuora platform, it is required to assign each product to a separate subscription.
• Product Rate Plan (that includes an identifier for your item object on the Connect platform) should represent one item type on the Connect platform.
• In case it is necessary to change a subscription, it is required to generate one change subscription request at a time. Otherwise, your second unprocessed request will fail automatically. Note, however, that the system allows creating several different requests (e.g., purchase and update requests) per a subscription.
• Some actions that are associated with pending orders (i.e., cancel, suspend, resume) are currently not supported. Such actions are saved immediately and without waiting for the approval from the CloudBlue Connect platform.

Zuora Configuration

Sign into your Zuora account and follow the provided instructions to perform configurations that are required for the following operations on the Workato platform.

Custom Field Creation

Custom fields allow storing additional information on many objects in Zuora. Custom fields are also essential for working with Zuora API. Add a new custom field on the Zuora platform as follows:

Navigate to Settings > Billing > Manage Custom fields and then select your required field model. Thereafter, click Add New Field within the Indexed Fields section. Therefore, by using the following configuration forms, set up Data type, Label, API name, and Picklist values (in case the Picklist data type is selected).

The following provides a list of custom fields that are required for working with the CloudBlue Connect platform. The following also contains required attributes for each custom field:

Subscription Fields

Create the custom fields on the Zuora platform to work with the subscription requests on the Connect platform. It is necessary to specify required valued as described below:

1. Connect Inquiry Link

• Data type: Text
• Field Label: Connect Inquiry Link
• API Name: InquiryLink__c
• Length: 255
• UI Read Only: Yes
  

2. Connect Status

• Data type: Text
• Field Label: Connect Status
• API Name: ConnectStatus__c
• Length: 20
• UI Read Only: Yes
  

3. Connect Last Order

• Data type: Text
• Field Label: Connect Last Order
• API Name: ConnectLastOrder__c
• Length: 50
• UI Read Only: Yes
  

4. Connect External UID

• Data type: Text
• Field Label: Connect External UID
• API Name: ConnectExternalUID__c
• Length: 100
• UI Read Only: Yes
  

5. Connect Error Message

• Data type: Text
• Field Label: Connect Error Message
• API Name: ConnectErrorMessage__c
• Length: 255
• UI Read Only: Yes
  

6. Connect Activation Link

• Data type: Text
• Field Label: Connect Activation Link
• API Name: ConnectActivationLink__c
• Length: 255
• UI Read Only: Yes
  

7. Connect Marketplace

• Data type: Picklist
• Field Label: Connect marketplace
• API Name: ConnectMarketplace__c
• Picklist Values: Paste your Marketplace names separated by a new line (refer to Workato Connection for details)
  

Product Field

The following custom field allows working with products on the CloudBlue Connect platform:

1. Connect Product ID

• Data type: Text
• Field Label: Connect Product ID
• API Name: ConnectProductID__c
• Length: 50
• UI Read Only: Yes
  

Product Rate Plan Field

A product rate plan is the part of a product that your customers subscribe to. Namely, this custom field allows working with product items on the CloudBlue Connect platform.

1. Connect Product Item ID

• Data type: Text
• Field Label: Connect Product Item ID
• API Name: ConnectProductItemID__c
• Length: 50
• UI Read Only: Yes

Account Field

The Account Field, as the name implies, allows working with accounts on the CloudBlue Connect platform.

1. Connect External UID

• Data type: Text
• Field Label: Connect External UID
• API Name: ConnectExternalUID__c
• Length: 100
• UI Read Only: Yes
  

Products Mapping

Once required custom fields are defined, it is necessary to map your Connect products on the Zuora platform. There are two scenarios for mapping your Connect products to the Zuora platform depending on the number of item types. Both scenarios are described below:

A) Connect product features a single item type

The following provides instructions on how to map a Connect product with a single item type to the Zuora subscription management platform:

1. Enter the product identifier from Connect to Connect Product ID on Zuora (i.e., ConnectProductID__c from your defined Product Field custom field).
2. Copy-paste the item identifier from the Connect product profile page to Connect Product Item ID on the Zuora platform (i.e., ConnectProductItemID__c from the Product Rate Plan custom field).

B) Connect product features multiple items

Mapping a Connect product that features multiple item types requires you to create multiple Zuora products that includes the same Connect Product ID and corresponding Connect Item IDs. Namely, it is required to map your Connect product with multiple item types to Zuora as follows:

1. Create multiple products on Zuora and enter the same Connect product identifier to Connect Product ID (i.e., ConnectProductID__c from the Product Field custom field).
2. Copy-paste required item IDs to Connect Product Item ID within your created Zuora products (i.e., ConnectProductItemID__c from the Product Rate Plan custom field).

Custom Objects

The Zuora platform features a uniform custom data service for managing your custom objects. These custom objects can be used to extend the data model to accommodate your specific use cases. Configure the following custom objects on the Zuora platform that should represent the CloudBlue Connect objects.

Navigate through Platform > Custom object and click the Create button to start creating Connect objects. Thereafter, enter the required values for your new custom objects as follows:

1. Fulfillment Request

• Field type: Text
• Name: Fulfillment Request
• API Name: FulfillmentRequest__c
• Required: No
• Filterable: Yes
  

2. Subscription Number

• Field type: Text
• Name: Subscription Number
• API Name: SubscriptionNumber__c
• Required: Yes
• Filterable: Yes
  

3. Message

• Field type: Text
• Name: Message
• API Name: Message__c
• Required: No
• Filterable: No
  

4. Inquiry Link

• Field type: Text
• Name: Inquiry Link
• API Name: InquiryLink__c
• Required: No
• Filterable: Yes
  

5. Order Number

• Field type: Text
• Name: Order Number
• API Name: OrderNumber__c
• Required: No
• Filterable: Yes
  

6. Status

• Field type: Text
• Name: Status
• API Name: Status__c
• Required: No
• Filterable: Yes
  

Subscription Activation Dates

Setting up subscription activation dates is required to enable the functionality to schedule the processing of new and updated subscriptions for Vendors on the CloudBlue Connect platform. Therefore, the Zuora platform will automatically activate subscriptions on your specified time and date and pass required subscription data to the Workato system and consequently generate fulfillment requests on Connect.

Enable this functionality on the Zuora platform by navigating through Settings > Billing > Define Default Subscription and Order Settings. Thereafter, enable this feature by using the Require Service Activation of Orders option.

Note that you can use the Require Customer Acceptance of Orders option in case you must enter a customer acceptance date to activate a subscription. The customer acceptance date is the date on which the customer accepts the services or products within a subscription. Refer to the Zuora Integration for more details.

Pending Orders

Orders are generated on the Zuora platform once customers acquire product and establish contractual relationship with merchants. Zuora provides two statuses for order objects: Pending and Completed. Therefore, pending orders can be created by the following order actions:

• Create subscription
• Remove product
• Add product
• Update product

In case subscription activation dates are specified, pending orders are created via the create subscription actions. Note that to use add product, remove product, and update product actions, it is required to contact Zuora Support and ask the support to enable limited availability for pending orders.

Other actions that are associated with pending orders (i.e., cancel, suspend, resume) are currently not supported. Such actions are saved immediately and without waiting for the approval from the CloudBlue Connect platform.

Generating Credentials

Creating your OAuth client on the Zuora platform is required to successfully provide your Zuora credentials and integrate this platform to the Workato system. Follow the steps below to generate the required Zuora credentials:

1. Access the Settings section on Zuora and proceed to Administration > Manage Users.
2. Locate the required user within the following table. Note that the user’s status should be Active. Otherwise, it is required to activate your user or choose a different user. Select the user by clicking the user’s First Name, Last Name, or User Name.
3. Scroll down to the OAuth clients subsection and locate New OAuth client to create a new client.
4. Enter the your OAuth client name and provide your required Client Secret value.
5. Click Create to finalize your OAuth client creation.

Upon the successful creation, the Client ID and Client Secret values appears on the screen. Save the Client ID, Client Name and Client Secret values for the Zuora credentials configuration on the Workato platform.

Connector Configuration

Once the Zuora configuration is finalized, it is necessary to use generated credentials to successfully configure the Zuora connector on Workato. Therefore, the Zuora platform will be integrated to the Workato system. The following showcases how to locate and configure required application connector on Workato.

Access your created Workato project and proceed to the Connections section. Click the Create Connection button and search for the Zuora connector. Once the Zuora connector is selected, it is required to fill out the provided Connect to Zuora form as follows:

• Authorization Type: OAuth 2.0
• Client ID: Specify your generated Zuora client identifier.
• Client Secret: Enter your provided Zuora client secret.
• Environment: Select your required Zuora tenant (e.g., US Production).
• Zuora SOAP API version: 107

As a result, the Zuora application connector will be successfully configured. Click the Connect button to launch your configured connector.

Zuora HTTP Connector

The HTTP connector configuration is required to establish connection with the Zuora API and to successfully integrate the Zuora platform with CloudBlue Connect. Access the Connections section from your Workato project and start configuring your Zuora HTTP connector as follows:

• Authentication Type: OAuth (client credentials grant).
• OAuth token URL: Enter your Zuora endpoint + /oauth/token (e.g. https://rest.apisandbox.zuora.com/oauth/token).
• OAuth2 Client ID: Specify your generated Zuora client identifier.
• OAuth2 Client Secret: Enter your provided Zuora client secret.
• How does the API require credentials to be sent to request a token: Body.

Click the Connect button once the Zuora HTTP Connector configuration is finalized. Therefore, the Workato system allows launching the provided recipes and test out the connection as described below.

Activating Recipes

Once your Zuora connector and HTTP connectors are configured successfully, you can activate the imported recipes and consequently test out your implemented integrations. Activate the imported recipes as follows:

Access your Workato project and navigate through the Recipes section. Click on the ellipsis icon next to your selected recipe and select the Start option to activate it. It is required to activate the following main recipes:

• Buy Product Flow
• Change Subscriptions
• Update Provisioned Subscriptions and Orders
• Usage Update

Note that once the aforementioned recipes are activated and you start to work with the Zuora platform and CloudBlue Connect, other recipes should be launched automatically by the Workato system.