Introduction

The Anypoint™ Connector for Zuora lets you connect to the Zuora platform. The connector exposes convenient methods for taking advantage of the capabilities of Zuora, allowing you to access the entire Zuora functional suite.

The connector executes API calls targeting Zuora’s SOAP API and REST API. All required request headers and error handling are abstracted from you and built into the connector.

Read through this user guide to understand how to set up and configure a basic flow using the connector. Track feature additions, compatibility, limitations and API version updates using the Zuora Connector Release Notes. Review the connector operations and see how they work be reviewing the Technical Reference alongside the Demo Applications.

MuleSoft maintains this connector under Select support policy.

Prerequisites

This document assumes that you are familiar with Mule, Anypoint Connectors, and Anypoint Studio Essentials. To increase your familiarity with Studio, consider completing a Anypoint Studio Tutorial. This page requires some basic knowledge of Mule Concepts, Elements in a Mule Flow, and Global Elements. Further, it assumes you are familiar with Zuora .

Hardware and Software Requirements

For hardware and software requirements, please visit the Hardware and Software Requirements page.

To use the Zuora connector, you need:

  • Anypoint Studio - An instance of Anypoint Studio. If you do not use Anypoint Studio for development, follow the instructions in Configuring Maven Dependencies for your project.

  • A Zuora account - Contact Zuora team to learn more about Zuora and how you can obtain an account: Zuora.

  • Zuora WSDL - To use the SOAP API, a Zuora WSDL must be provided to the connector. Sign into Zuora Production or Zuora Sandbox, navigate to Settings, then click Z-Billing Settings > Download the Zuora WSDL.

Compatibility

Application/Service Version

Mule Runtime

Mule Enterprise Edition 3.5.2 and newer

Zuora

v75

Starting with v.3.0.0, the Zuora connector is licensed commercially with Anypoint Platform as are other Select connectors. Prior versions will remain freely available to the community.
Support for TLS1.0 is discontinued in Zuora. If by default the application tries to use TLS1.0, then, when running it, the following VM argument should be added: -Dhttp.protocols=TLSv1.1,TLSv1.2 This will ensure the fact that TLS1.1 or TLS1.2 will be used for the communication with Zuora.
WSDL Versions
The Zuora connector can use WSDL versions older than version 75, but only version 75 has been tested in detail.

Install the Connector

You can install the connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Upgrading from an Older Version

If you’re currently using an older version of the connector, a small popup appears in the bottom right corner of Anypoint Studio with an "Updates Available" message.

  1. Click the popup and check for available updates.

  2. Click the Connector version checkbox and click Next and follow the instructions provided by the user interface.

  3. Restart Studio when prompted.

  4. After restarting, when creating a flow and using the Object Store Connector, if you have several versions of the connector installed, you may be asked which version you would like to use. Choose the version you would like to use.

Additionally, we recommend that you keep Studio up to date with its latest version.

Creating a New Project

To use the Zuora connector in a Mule application project:

  1. In Anypoint Studio, click File > New > Mule Project.

    Create new project

  2. Enter a name for your new project and leave the remaining options with their default values.

    Create new project dialog box

  3. If you plan to use Git, select Create a default .gitignore file for the project with default ignores for Studio Projects, and then click Next.

  4. Click Finish to create the project.

Configure the Zuora Global Element

To use the Zuora connector in your Mule application, you must configure a global Zuora element that can be used by the Zuora connector (read more about Global Elements). The global parameters are:

zuora-config

Field Description

Username

Enter the username to log into Zuora.

Password

Enter the corresponding password.

EndPoint

Enter the address of the endpoint responsible for handling the SOAP requests. The default value is https://apisandbox.zuora.com/apps/services/a/75.0

Rest EndPoint

Enter the base of the endpoint responsible for handling the REST requests. The default value is https://apisandbox.zuora.com/apps/api/

Wsdl Location

Enter the path to the Zuora WSDL. You can give the absolute path to the file, or you can give the relative path to the file, where the parent directory is src/main/resources

Zuora Connector uses a session id to authenticate to Zuora when executing flows. The life of a session Id varies depending on how the Zuora environment is configured. When executing flows, if no reconnection strategy is set for the connector, when the session id will be invalidated, the API call will fail. To ensure the call will be successful, a reconnection strategy must be created to refresh the session id.

Using the Connector

Zuora connector has 3 processors. The Invoke SOAP Service processor is capable of calling the operations provided in the input Zuora WSDL. The connector can use the operations and objects from the Zuora WSDL and can determine what type of objects the operation expects. The use cases for the Zuora Connector are:

  1. Invoke SOAP Service - Use this processor for calling a Zuora SOAP operation. The processor uses multi-level dataSense to provide the lists of operations the input Zuora WSDL has, and a list of object types that can be used for the chosen operation. The first level contains the services available in the wsdl file. invoke-soap-first-step The second level presents the user with all the available operations from the WSDL invoke-soap-first-step The third level presents all the available object types for the chosen operation. If the operation does not use an object with a specific type, or it uses no input, the Entity field will have Undefined value. invoke-soap-first-step For Zuora API version 75, the available SOAP operations are:

    1. Amend: the Amend call is used to change a subscription. see Zuaora’s documentation for Amend.

    2. Create: the Create call is used to create one or more objects of a specific type. see Zuaora’s documentation for Create.

    3. Delete: the Delete call is used to delete one or more objects of the same type. see Zuaora’s documentation for Delete.

    4. Execute:, the Execute call is used to split an invoice into multiple invoices. see Zuaora’s documentation for Execute.

    5. Generate:, the Generate call is used to generate an on demand invoice for a specific customer. see Zuaora’s documentation for Generate.

    6. Get User Info: the Get User Info call can retrieve information about the user.

    7. Login: the Login call takes a user name and a password and logs you in to the Zuora server. see Zuaora’s documentation for Login.

    8. Query: the Query call sends a query expression by specifying the object to query, the fields to retrieve from that object, and any filters to determine whether a given object should be queried. see Zuaora’s documentation for Query.

    9. Query More: the Query More call allows to request additional results from a previous query() call. see Zuaora’s documentation for Query More.

    10. Subscribe: the Subscribe call can perform many actions. Use the subscribe() call to bundle information required to create at least one new subscription. see Zuaora’s documentation for Subscribe.

    11. Update: the Update call updates the information in one or more objects of the same type. see Zuaora’s documentation for Update.

  2. Get Export File Content - This operation returns the content of a an export file that contains queried data from Zuora.

  3. Get Export File Stream - This operation returns a stream that represents an export file that contains queried data from Zuora.

Generally speaking, the Zuora connector can be used as an outbound connector. A description of this scenario follows.

Outbound Scenario

Use as an outbound connector in your flow to push data into Zuora. To use the connector in this capacity, simply place the connector in your flow at any point after an inbound endpoint (see image below).

Basic Example

zuora_outbound

  1. File connector - accepts data from files, such as a CSV, into a flow.

  2. Transform Message - Transforms data structure and format to produce the output Zuora connector expects.

  3. Zuora connector (outbound) - Connects with Zuora, and performs an operation to push data into Zuora.

Connector Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

If you are manually coding the Mule application in Studio’s XML editor or other text editor, define the namespace and schema location in the header of your Configuration XML, inside the <mule> tag.
1
2
3
4
5
6
7
8
9
10
11
12
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:connector="http://www.mulesoft.org/schema/mule/zuora"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/zuora
               http://www.mulesoft.org/schema/mule/connector/current/mule-zuora.xsd">

      <!-- put your global configuration elements and flows here -->

</mule>

Using the Connector in a Mavenized Mule App

After you download and install the connector, use the following steps to make the Zuora connector available to inside a Mule application for use and to package the application with the connector. If you use Anypoint Studio, it will do this automatically for you.

  1. Add the repository information to your project’s pom.xml file:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    
    <repositories>
       <repository>
            <id>mule-ee-releases</id>
            <name>MuleEE Releases Repository</name>
            <url>https://repository-master.mulesoft.org/nexus/content/repositories/releases-ee/</url>
        <repository>
            <id>mule-ee-snapshots</id>
            <name>MuleEE Snapshots Repository</name>
            <url>https://repository-master.mulesoft.org/nexus/content/repositories/ci-snapshots/</url>
        </repository>
    </repositories>
  2. Add the module as a dependency to your project for the latest release version:

    1
    2
    3
    4
    5
    
    <dependency>
        <groupId>org.mule.modules</groupId>
        <artifactId>mule-module-zuora</artifactId>
        <version>RELEASE</version>
    </dependency>

    Or for the latest version:

    1
    2
    3
    4
    5
    
    <dependency>
        <groupId>org.mule.modules</groupId>
        <artifactId>mule-module-zuora</artifactId>
        <version>SNAPSHOT</version>
    </dependency>
  3. If you plan to use this module inside a Mule application, you need to include it in the packaging process. That way the final zip file that contains your flows and Java code also contains this module and its dependencies. Add a special "inclusion" to the configuration of the Mule Maven plugin for this module as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    <plugin>
        <groupId>org.mule.tools</groupId>
        <artifactId>maven-mule-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
            <excludeMuleDependencies>false</excludeMuleDependencies>
            <inclusions>
                <inclusion>
                    <groupId>org.mule.modules</groupId>
                    <artifactId>mule-module-zuora</artifactId>
                </inclusion>
            </inclusions>
        </configuration>
    </plugin>

Demo Mule Applications Using Connector

Example Use Case

The following example shows how to create an Account, a Contact, then update that Account to an active state and use the created contact for billing:

  1. In Anypoint Studio, click File > New > Mule Project, name the project, and click OK.

  2. In the search field, type "http" and drag the HTTP connector to the canvas. Use 3 HTTP connectors to create 3 separate flows. Click the HTTP connector, click the green plus sign to the right of Connector Configuration, and in the next screen, click OK to accept the default settings. Name the endpoints /create-account, /create-contact and /update-account.

  3. In the Search bar type "zuora" and drag the Zuora connector onto the canvas. Configure as before.

  4. Click the Invoke SOAP Service operation. Choose Create operation and Account object. Datasense brings the structure of the Account and brings the output structure of the create operation.

  5. For the second flow click the Invoke SOAP Service operation. Choose Create operation and Contact object. Datasense brings the structure of the Contact and brings the output structure of the create operation.

  6. For the third flow click the Invoke SOAP Service operation. Choose Update operation and Account object. Datasense brings the structure of the Account and brings the output structure of the update operation. Add Transform Message components, one in front of and one after the connector.

    If "Payload - Unknown" is shown in DataWeave then the method either has no input or it returns nothing. If DataWeave detects any input for the method, it appears as: "Payload - Unknown".
  7. The mapping for the 3 transformers should look like this:

    1) transformer for creating account transformer-create-account

    2) transformer-for-creating-contact transformer-create-contact

    3) transformer-for-updating-account transformer-update-account

  8. The flows appear as:

    create-account

    create-contact

    update-account

  9. After you create the flows, right-click the project name in the package-explorer and click Run As > Mule Application.

  10. Create and post a JSON file that has the structure presented in the Transformers at the endpoints that belong to each flow. As an example, below are a few valid JSON files:

    Create Account Input:

    create-account

    Create Contact Input(for AccountId, the id from the account created by the previous flow can be used):

    create-account

    Update Account Input (for Id, the id from the account created by the first flow can be used. For the other 2 fields, the id from the contact created by the second flow can be used):

    create-account

Example Use Case - XML

Paste this into Anypoint Studio to interact with the example use case application discussed in this guide.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:zuora="http://www.mulesoft.org/schema/mule/zuora" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd
http://www.mulesoft.org/schema/mule/zuora http://www.mulesoft.org/schema/mule/zuora/current/mule-zuora.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <zuora:config name="Zuora__Basic_Authentication" username="${config.username}" password="${config.password}" doc:name="Zuora: Basic Authentication" wsdlLocation="${config.wsdlLocation}" endpoint="${config.endpoint}" restEndpoint="${config.restEndpoint}">
        <reconnect-forever/>
    </zuora:config>
    <flow name="zuora-subscribe-operations-createAccount-demoFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/create-account" doc:name="HTTP"/>
        <logger message="'Input:'#[payload]" level="INFO" doc:name="Logger"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/xml
%namespace ns0 http://api.zuora.com/
%namespace ns1 http://object.api.zuora.com/
---
{
        ns0#create: {
                ns0#zObjects: {
                        ns1#AllowInvoiceEdit: false,
                        ns1#AutoPay: false,
                        ns1#Batch: "Batch1",
                        ns1#BillCycleDay: "1",
                        ns1#Currency: "USD",
                        ns1#Name: payload.Name,
                        ns1#PaymentTerm: "Due Upon Receipt",
                        ns1#Status: "Draft"
                }
        }
}]]></dw:set-payload>
        </dw:transform-message>
        <zuora:invoke-soap-service config-ref="Zuora__Basic_Authentication" soapMetadataKey="ZuoraService-Soap-http://api.zuora.com/||create||Account-zObject" doc:name="Create Account"/>

        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="'Output:'#[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="zuora-subscribe-operations-createContact-demoFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/create-contact" doc:name="HTTP"/>
        <logger message="'Input:'#[payload]" level="INFO" doc:name="Logger"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json_1.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/xml
%namespace ns0 http://api.zuora.com/
%namespace ns1 http://object.api.zuora.com/
---
{
        ns0#create: {
                ns0#zObjects: {
                        ns1#AccountId: payload.AccountId,
                        ns1#Address1: payload.Address1,
                        ns1#City: payload.City,
                        ns1#Country: "Romania",
                        ns1#FirstName: payload.FirstName,
                        ns1#LastName: payload.LastName,
                        ns1#State: payload.State
                }
        }
}]]></dw:set-payload>
        </dw:transform-message>
        <zuora:invoke-soap-service config-ref="Zuora__Basic_Authentication" soapMetadataKey="ZuoraService-Soap-http://api.zuora.com/||create||Contact-zObject" doc:name="Create Contact"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="'Output:'#[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="zuora-subscribe-operations-updateAccount-demoFlow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/update-account" doc:name="HTTP"/>
        <logger message="'Input:'#[payload]" level="INFO" doc:name="Logger"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:input-payload doc:sample="json_7.json"/>
            <dw:set-payload><![CDATA[%dw 1.0
%output application/xml
%namespace ns0 http://api.zuora.com/
%namespace ns1 http://object.api.zuora.com/
---
{
        ns0#update: {
                ns0#zObjects: {
                        ns1#Id: payload.Id,
                        ns1#BillToId: payload.contactId,
                        ns1#SoldToId: payload.contactId,
                        ns1#Status: "Active"
                }
        }
}]]></dw:set-payload>
        </dw:transform-message>
        <zuora:invoke-soap-service config-ref="Zuora__Basic_Authentication" soapMetadataKey="ZuoraService-Soap-http://api.zuora.com/||update||Account-zObject" doc:name="UpdateAccount"/>

        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
payload]]></dw:set-payload>
        </dw:transform-message>
        <logger message="'Output:'#[payload]" level="INFO" doc:name="Logger"/>
    </flow>

Connector Performance

To define the pooling profile for the connector manually, access the Pooling Profile tab in the applicable global element for the connector.

For background information on pooling, see Tuning Performance.

Best Practices

  1. It is advised to set the Reconnection Strategy to Reconnect Forever to make sure that the Session Id can be successfully refreshed.

  2. To take full advantage of the functionality DataSense and the Zuora connector have to offer, design-time best practice dictates that you should build an application in a particular order:

    1. CONFIGURE the connector

    2. TEST the connection

    3. INITIATE DataSense metadata extraction

    4. BUILD the rest of your flow

    5. ADD and configure DataWeave

      The objective of this design-time strategy is to set the pieces of the integration puzzle in place, then "glue them together" with DataWeave. Rather than designing a flow sequentially, from the inbound endpoint, this type of "align, then glue together" strategy ensures that you are utilizing DataSense, wherever possible, to pre-populate the information about the structure and format of the input or output data in a Transform Message component. The diagram in the section below prescribes a process that follows this best practice in the context of a flow that uses a Zuora connector. For further information, read DataSense Best Practices. To take full advantage of the functionality

Resources