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 with the message processors specified in 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 from 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 |
Important
|
Starting with v3.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. |
Important
|
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.
|
Note
|
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.
-
Click the popup and check for available updates.
-
Click the Connector version checkbox and click Next and follow the instructions provided by the user interface.
-
Restart Studio when prompted.
-
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:
-
In Anypoint Studio, click File > New > Mule Project.
-
Enter a name for your new project and leave the remaining options with their default values.
-
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.
-
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:
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 |
Note
|
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
The Zuora connector has three message processors. The Invoke SOAP Service processor is capable of calling operations specified in the Zuora WSDL and can determine what type of objects the operation expects.
Invoke SOAP Service
-
Invoke SOAP Service - Use this processor for calling a Zuora SOAP operation.
The processor uses multi-level DataSense to provide the lists of operations in the input Zuora WSDL, and a list of object types that can be used for the chosen operation. The Service dropdown contains the services available in the WSDL file.
+
The second level presents the user with all the available operations from the WSDL
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. For Zuora API version 75, the available SOAP operations are:
-
Amend: the Amend call is used to change a subscription. See Zuora’s documentation for Amend.
-
Create: the Create call is used to create one or more objects of a specific type. See Zuora’s documentation for Create.
-
Delete: the Delete call is used to delete one or more objects of the same type. See Zuora’s documentation for Delete.
-
Execute: the Execute call is used to split an invoice into multiple invoices. See Zuora’s documentation for Execute.
-
Generate: the Generate call is used to generate an on demand invoice for a specific customer. See Zuora’s documentation for Generate.
-
Get User Info: the Get User Info call can retrieve information about the user.
-
Login: the Login call takes a user name and a password and logs you in to the Zuora server. See Zuora’s documentation for Login.
-
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 Zuora’s documentation for Query.
-
Query More: the Query More call allows to request additional results from a previous query() call. See Zuora’s documentation for Query More.
-
Subscribe: the Subscribe call can perform many actions. Use the subscribe() call to bundle information required to create at least one new subscription. See Zuora’s documentation for Subscribe.
-
Update: the Update call updates the information in one or more objects of the same type. See Zuora’s documentation for Update.
Note
|
Observe the syntax for calling an operation from the Zuora SOAP
API using the connector. The Operation and
Entity are passed in the
|
-
Query -This processor allows the user to query for records using a DataSense Query Language to construct the query and provide DataSense for the query Output.
Using the Query Builder the user can easily construct queries and add filters to them. If the DataSense Query Language does not have the capability to construct the desired query, the user can opt to use Native Query Language, but this mode does not support DataSense. This processor uses a Paginated Query to return all the records from the database that match the given query.
The Rest processors have 2 fields Entity Id and Entity Name that allows you to use the Zuora Multi Entity API see Multi Entity API. The Rest processors are:
-
Post Usage - This operation imports usage data for one or more accounts taken from a csv file given as input. If the import is submitted succesfully, the operation returns a POJO containing an URL used to check the status of the import. The URL can be given as input to the Check Import Status processor to retrieve the status of the import. For more information see See Zuora Post Usage
-
Check Import Status - This operation receives an import URL and returns the current status of the import. If the import failed, the response may contain some information with the reason of the failure.
-
Get Export File Content - This operation returns the content of a an export file that contains queried data from Zuora.
-
Get Export File Stream - This operation returns a stream that represents an export file that contains queried data from Zuora.
-
Zuora Aqua Processors -This is a collection of processors and sources that enables the user to interact with the Zuora AQUA Api. See Zuora Aqua Api Documentation The following processors/sources are available:
-
Aqua post query - This processor submits an aggregated list of ZOQL and Export ZOQL queries in a stateful or stateless mode. See Zuora’s documentation for Post Query. The project and partner are required to be completed in order for this request to be stateful. Stateful requests have more features than the stateless requests. For more information see Zuora Stateless vs Stateful Mode. If the Aqua post query request is successful, the processor returns a job that has a batch for each query in the request. Using other processors, the user can check the status of the job and retrieve the results of its batches. If the request fails, the job will not be created and the result will contain some information about the cause of the failure. The Save Job To Object Store flag, if set to true, will cause all the ids of the jobs created by the PostQuery operation to be saved in a Persistent Object Store whose name is given by the Object Store Name field, to be used by the Aqua Get Batch Result source. If the flag is set to true and no object store is given, a default object store zuoraPostQueryObjectStore is used.
-
Aqua get job results -This processor receives a String representing a jobId and returns an object representing the status of that job. See Zuora Get Job Details
-
Aqua delete job -This processor deletes the current job, only if the job is not complete and returns the information about the cancelled job. See Zuora Delete Job
-
Aqua get last completed job -This processor returns the details of the last completed job of a stateful request represented by the partnerId and projectId . Zuora Get Last Completed Job
-
Aqua operations for pooling results - The last 2 processors/sources work together with aquaPostQuery to continuously check the status of a given job. When the job is finished, the job is returned and the content of it’s batches can be extracted. The Source Aqua get batch results periodically checks an object store for jobs to check. When it determines a job is completed, it returns the job in form of a POJO. Because a Source does not have DataSense by default, the Aqua get job metadata processor can be used to transform the POJO returned by the source to a job so the user can use DataSense on it. The object store used by the source is populated with jobs by the Aqua post query processor if the Save Job To Object Store flag is set to true.
-
Aqua get batch results - This source optionally can receive a name for a persistent object store (if no name is provided, a default object store zuoraPostQueryObjectStore is used) to periodically check the status of the jobs stored in that object store. The polling period can be modified by changing the Polling Period field. When a job is completed, the source will return it as a POJO.
-
Aqua get job metadata -this processor receives a POJO that represents a result returned by the Aqua get batch results source and converts it to a Job object. This way, an user can retrieve the metadata of the Job object and map the job structure to other elements further down the flow. An example of how this operations could work together is: In the first flow the Post Query creates a new job and stores the job in an object Store. The source from the second flow periodically checks the jobs present in the object store. When it concludes a job is completed, it returns the job result as a pojo. The next processor(Aqua get job metadata), converts the POJO to a Job object to provide dataSense to the user. The user then can download the query results by going through each Batch from the Job and using the Get export file stream processor to download the file.
-
-
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
-
File connector - accepts data from files, such as a CSV, into a flow.
-
Transform Message - Transforms data structure and format to produce the output Zuora connector expects.
-
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.
Namespace: http://www.mulesoft.org/schema/mule/zuora
Schema Location: http://www.mulesoft.org/schema/mule/connector/current/mule-zuora.xsd
Tip
|
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.
|
<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.
-
Add the repository information to your project’s pom.xml file:
<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>
-
Add the module as a dependency to your project for the latest release version:
<dependency> <groupId>org.mule.modules</groupId> <artifactId>mule-module-zuora</artifactId> <version>RELEASE</version> </dependency>
Or for the latest version:
<dependency> <groupId>org.mule.modules</groupId> <artifactId>mule-module-zuora</artifactId> <version>SNAPSHOT</version> </dependency>
-
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:
<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:
-
In Anypoint Studio, click File > New > Mule Project, name the project, and click OK.
-
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.
-
In the Search bar type "zuora" and drag the Zuora connector onto the canvas. Configure as before.
-
Click the Invoke SOAP Service operation. Choose Create operation and Account object. DataSense brings the structure of the Account as well as the output structure of the Create operation.
-
For the second flow click the Invoke SOAP Service operation. Choose Create operation and Contact object. DataSense brings in the structure of the Contact as well as the output structure of the create operation.
-
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.
NoteIf "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".
-
The mapping for the three transforms should look like this:
1) transform for creating account
2) transform for creating contact
3) transformer for updating account
-
The flows appear as:
-
After you create the flows, right-click the project name in the and click Run As > Mule Application.
-
Create and post a JSON file that has the structure presented in the transforms at the endpoints that belong to each flow. As an example, below are a few valid JSON files:
Create Account Input:
Create Contact Input(for AccountId, the id from the account created by the previous flow can be used):
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):
Example Use Case - XML
Paste this into Anypoint Studio to interact with the example use case application discussed in this guide.
<?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>
</mule>
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
-
It is advisable to set the Reconnection Strategy to Reconnect Forever to make sure that the Session Id can be successfully refreshed.
-
To take full advantage of DataSense functionality with the Zuora connector, design-time best practice dictates that you should build an application in this particular order:
-
CONFIGURE the connector
-
TEST the connection
-
INITIATE DataSense metadata extraction
-
BUILD the rest of your flow
-
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
-
Access the Zuora Connector Release Notes.