CREATING YOUR FIRST APP
To help you learn how to create Apps for your organization, Zuora has created an open source Starter Package. This App is written in Ruby on Rails.
The Starter Package demonstrates several important aspects of App development, including:
- Using the Zuora REST API to access Zuora tenants
- Managing a database
- Providing a user interface
- Starting background workers
- Handling configuration data
To create an App that is based on the Starter Package:
Step 1: In Zuora Connect, navigate to My Connect > Developer, then click the Applications tab and click New Application:
The New Application dialog box opens.
Step 2: Enter a name for the App, then select Web Service from the Type list.
Step 3: Click the Modes tab, then click the white space to the right of “Universal”.
This expands the “Universal” mode:
Modes enable you to maintain a single codebase that addresses several different use cases. In this case, the App will only have one mode.
Step 4: In the “source” row, click Remove.
The remaining “target” row specifies that the App will require access to a single Zuora tenant. Because of how the Starter Package is coded, it is important that you do not change the “target” row.
Step 5: Click Save Application.
Zuora Connect creates the App:
The App’s code will be stored in a GitLab repository that is hosted by Zuora. You will access this repository in a later step.
Before the App’s code can run on the Zuora Central platform, you must create a “build” via Zuora Connect. The build will enable you to specify and configure the Zuora Central environment that the code will run in.
Step 6: Click the Builds tab, then click New build and select the App:
The New Application Build dialog box opens.
Step 7: Select the Zuora Central data center that you want the App’s code to run in, then select Test from the Environment list:
Step 8: Click Save Build.
Zuora Connect creates a Test build:
Because the Starter Package stores data in a PostgreSQL database, you must create a PostgreSQL database for the Test build.
Step 9: To create a PostgreSQL database for the Test build, first select Show Build from the build menu:
On the Resources tab of the page that opens, click Add Database to the right of “Databases”:
Step 10: To view the GitLab repository for the App, navigate to My Connect > Developer, then click the Applications tab and select GitLab Repo from the App menu:
The GitLab repository is configured so that merges trigger a pipeline that tests and deploys the code to the Zuora Central platform. The testing and deployment pipeline is controlled by the file
.gitlab-ci.yaml. The part of this file that contains
stage: deploy is not intended to be modified.
The repository has two branches:
test. These branches are protected, which means that you must create a merge request before merging to either branch.
test branch was created when the Test build was created. The
master branch was created when the App was created. Code in the
master branch will not be deployed to the Zuora Central platform until you create a Production build via Zuora Connect.
Step 11: Create an experimental branch in the GitLab repository, then clone the experimental branch in your local development environment.
See How to create a branch in the GitLab documentation for more information.
The remote URL of the GitLab repository is displayed on the Project page in GitLab:
See SSH in the GitLab Documentation for how to configure your SSH keys.
Step 12: Download and set up the Starter Package according to the README file.
As part of the setup process, you must specify the username and password of a Zuora user account. This is required to run the Starter Package in your local development environment. You can specify the username and password of your Zuora Developer Sandbox user account.
Step 13: Commit your modified Starter Package code to your local copy of the experimental branch, then push the experimental branch to the GitLab repository.
Step 14: In the GitLab repository, create a merge request to merge the experimental branch to the
See How to create a merge request in the GitLab documentation for more information.
After you create the merge request, GitLab starts a pipeline that tests the App’s code. You can monitor the pipeline on the Pipelines page:
Step 15: When the status of the pipeline is “passed”, accept the merge request:
After you accept the merge request, GitLab starts a pipeline that deploys the App’s code to the Zuora Central platform. If the pipeline passes, the Test build of the App is running as a web service on the Zuora Central Platform. The URL of the Test build is
To fully test the App, you must use Zuora Connect to create an instance of the App. This is because the Starter Package uses the Zuora Central Gem to obtain user configuration data from Zuora Central, rather than relying on hardcoded configuration data. See the next section for more information.
Apps are not required to obtain user configuration data from Zuora Central. However, if you want your Apps to support multiple users or multiple Zuora tenants, your Apps should make use of the Zuora Central Gem – or a reimplementation of the Zuora Central Gem in your preferred language.
If you choose to write your Apps in Ruby, Zuora also recommends that your Apps make use of the Zuora API Gem.
TESTING AN INSTANCE OF AN APP
Zuora Central provides a standardized way for users to create instances of Apps. When a user creates an instance of an App, the user specifies which Zuora tenants the App should access, any external systems that the App should access, and which actions the App should perform.
If you have created an App that supports multiple instances, you can test your App by using Zuora Connect to create an instance of your App. The Starter Package demonstrates how to create an App that supports multiple instances.
Before you can create an instance of an App, you must create a private listing of the App. To create a private listing of a App:
Step 1: In Zuora Connect, navigate to My Connect > Developer, then click the Listings tab and click New App:
The New App page opens.
Step 2: Enter a title, short description, type, and category for the listing.
You can enter additional details about the listing, but this is not necessary because you are creating a private listing. The details you enter will not appear publicly on the Connect Marketplace.
Step 3: Select the App from the Application list:
Step 4: Click Next until you reach the Sharing tab.
Step 5: Select Private from the Sharing Status list, then click Submit.
Zuora Connect creates a listing of the App. You can view the listing on the Listings tab of the Developer page:
Step 6: Hover over the listing, then click the name of the listing.
A preview of the listing’s Connect Marketplace page opens:
Step 7: Click Download, then close the dialog box that appears.
This step ensures that you can create instances based on the listing.
CREATING AN INSTANCE OF AN APP
To create an instance of an App:
Step 1: In Zuora Connect, navigate to My Connect > Tenants.
Step 2: Hover over the entry for your Zuora Developer Sandbox, then click Apps:
An overview of your Zuora Developer Sandbox opens.
Step 3: Click the Apps tab, then click New and select the App:
The New Configuration dialog box opens:
Step 4: Enter a name for the instance, then click Create.
Zuora Connect displays the instance:
You can then test the App via the user interface of the instance. To view the user interface of the instance, hover over the instance, then click Launch:
LISTING AN APP ON THE CONNECT MARKETPLACE
After you have developed and fully tested an App, and are ready to offer the App’s functionality to other organizations that use Zuora, you can submit the App to Zuora for certification. Certified Apps are eligible to be listed publicly on the Connect Marketplace.
The App certification process ensures that each App’s code is secure, scalable, and correctly supports multiple instances. The App certification process also ensures that the Apps in the Connect Marketplace have a consistent level of usability, branding, documentation, and support.
If you plan to submit an App to Zuora for certification, use the following checklist to help prepare your App for the certification process:
- Ensure that your App does not store authentication credentials of Zuora tenants or external systems. Your App must support multiple instances by obtaining user configuration data from Zuora Central
- In GitLab, merge your App’s code and check that the deployment pipeline passes
- In Zuora Connect, create a draft listing of your App. Enter as many details about the listing as possible
- In Zuora Connect, test your App by creating an instance of your App for every use case that you intend to support
- List the Zuora objects that your App interacts with. For each object, describe what your App does with the object
- List the external systems that your App interacts with. For each external system, describe how your App access the external system and what information your App sends to the external system
- Create user documentation for your App. The user documentation should describe:
- The purpose and features of your App
- Any security implications of using your App
- How to install your App, including any one-time configuration steps that must be performed before your App is ready to use
- How to use your App, including usage examples
- Any API operations that your App provides
- How to remove your App
- Add the pricing for your App or the pricing for connector and the standalone software
For additional information about submitting your App for certification, contact firstname.lastname@example.org.
Once your App has been certified by Zuora, and is listed publicly on the Connect Marketplace, you are considered a Zuora partner and can market and sell your App.