Overview · Web view2.0 6/15/2015 Redraft Wes Spears Louis Livingston 3.0 6/24/2015 Change approach to include the use of Z-Hub Tasks Wes Spears Louis Livingston 4.0 7/21/2015 Final

Entitlement SystemTechnical Development Specification #

Version 4.1Zuora Client Services

08/11/2015

Wesley SpearsLouis Livingston

Zuora Inc. 1051 Foster City Blvd

Suite 600Foster City, CA 94404

Notice of Confidentiality © 2013 Zuora All rights reserved.This document is ZUORA Proprietary and Confidential Information and is subject to the terms of the ZUORA, Inc. Non-Disclosure Agreement. Neither this document nor its contents may be revealed or disclosed to unauthorized persons or sent outside the aforementioned institution without prior permission from ZUORA.

Development Spec

Revision History

Revision Date Description Revision Owner1.0 5/20/2015 Initial Draft Wes Spears

Louis Livingston

2.0 6/15/2015 Redraft Wes Spears

Louis Livingston

3.0 6/24/2015 Change approach to include the use of Z-

Hub Tasks

Wes Spears

Louis Livingston

4.0 7/21/2015 Final adjustments for base functionality

Wes Spears

Louis Livingston

4.1 8/11/2015 Adding callout details Wes Spears

Louis Livingstons

TABLE OF CONTENTS

1. OVERVIEW

1.1 Purpose1.2 Intended Audience

2. REQUIREMENTS

2.1 Business Requirements2.2 Technical Requirements2.3 Assumptions2.4 Known Issues / Limitations

3. TECHNICAL DESIGN

3.1 Overview3.2 Obtaining the Entitlement Mapping System Webapp3.3 Launching the Entitlement Mapping System Webapp3.4 Task Section3.5 Entitlements Index

Version 4.1 Confidential Page 2 of 18

Development Spec3.6 View Entitlements Modal 3.7 Add/Edit Entitlement Modal3.8 Search Bar3.9 Export Button3.10 Upload File Modal 3.10.1 Create/Update 3.10.2 Delete3.11 Update Catalog Button3.12 Database3.13 API REST Calls 3.13.1 Task Entitlements 3.13.2 Product, Rate Plan, and Charge Callouts

1.OVERVIEW

This document describes code to be designed and developed by Zuora Global Services, which will address business cases uncovered in discovery sessions, and defined in this document.

Once created, the adaptation, compilation, deployment, hosting and all ongoing management of the code libraries will be the responsibility of the customer.

Zuora services will participate in assisting the customer in their responsibilities, as needed.

1.1 PurposeThe solution will manage entitlements for items in the client’s inventory to the consumer. It will receive subscription information from the Zuora Product Catalog in order to determine entitlements and push that information into a customer’s system of choice via REST web service. It will be mostly universal in accepting data from client’s provision catalog.

1.2 Intended AudienceThis solution is intended for all clients seeking to outsource entitlement management of their Zuora subscriptions through a 3rd party application.


Development Spec

2.REQUIREMENTS

2.1 Business Requirements

Business Requirement

Description

BR1073Solution will provide the mapping from the Zuora product catalog to the entitlements for the users’ customers through a web app on RBM Connect

BR1074 Solution will have the flexibility to perform tasks throughout all client platforms

BR1075The client will have the ability to create entitlement records to apply to one or multiple rate plans found in the Zuora database

BR1076The client will also have the ability to make alterations to the values of the entitlement records created

BR1077

The client will have the ability to customize the entitlement records to their needs through changing the amount of the custom fields per record and the title of those fields

BR1078The client will be able to create different environments through RGB Connect Tasks to group entitlement records as needed

BR1079

The solution will allow the user to be able to search through entitlement records based on record name and ID, description, connected rate plans name and ID, connected products name and ID, connected charges name and ID, and custom fields

BR1080 The client will be able to export entitlements to a CSV file

BR1081

The client will be able to create and update multiple records simultaneously through uploading CSV files of the same format generated through exporting entitlement records

BR1082 The client will be able to delete multiple records through uploading a CSV file,


Development Spec

although the format is different than that used to create and update

2.2 Technical Requirements

Technical Requirement

Description

TR 1Solution should allow creation, updating, viewing, and destruction of entitlement records

TR 2

Solution will store records in PostGres datatable using hashes allowing for scalability. The back-end will handle parsing of hashes for clean viewing in webapp as well as exported CSV files

TR 3 Solution will create endpoints for callouts, returning JSON objects of entitlements attached to certain rate plans and charges

TR 4 Solution will be able to make call outs to Zuora product catalog based on the tenant who created the task. The catalog will be refreshed every 12 hours or when desired by client

TR 5 Solution will allow for grouping of entitlements by the use of the Z-Hub tasks. Each entitlement record will have a task ID ties to it

2.3 Assumptions1. There is no limit to the number of entitlement records that can be created under one

particular task2. There is no limit to the number of rate plans that can be connected to a single

entitlement record3. There is no limit to the number of custom fields tied to a single rate plan4. No two rate plans within a product have the same name

2.4 Known Issues / LimitationsTBD


Development Spec-

3.TECHNICAL DESIGN

3.1 OverviewZuora is being used as reference for the charge IDs, rate plans, and products of a client to enable the mapping of entitlement records to such objects. The Entitlement System is being created so that users can create, update, and delete provisions for rate plans and products. The records of these provisions will not be stored in the Zuora server, but instead will be held in a postgres table as a part of the RGB Connect database. The web app will not be used to alter data in Zuora servers or in clients’ servers, but instead will serve as a map from charge IDs located in Zuora to the appropriate entitlement records for each client.

3.2 Obtaining the Entitlement Mapping System Web AppThe EM System will be a product provided in and obtained from gaining appropriate privileges in RGB Connect.

Figure 1: Data flow between all systems

3.3 Launching the Entitlement Mapping System Web AppThe Entitlement Mapping System will be available as a part of the RGB Connect website. If the user has the appropriate privileges, the user will be able to access the app through the side bar after selecting Tools > Utilities > Entitlements.


Development Spec

Figure 2: Relationship Diagram showing flow of pages in the web app.

Figure 3: Screenshot of example Task Section

3.4 Task SectionThe Task Section will be the same as is in other tools in RGB Connect. This section in the Entitlements app will allow the user to separate entitlements into different environments as needed. The user will be able to create a new task or select one of the previously existing tasks Version 4.1 Confidential Page 7 of 18

Development Specto be able to view the index of appropriate entitlement records. The entitlements are separated based on the task ID, which is an attribute in the entitlement table in the database. Each task will have multiple buttons allowing the user to view task details, delete task, edit permissions, and view entitlements tied to that task. Clicking the “View Entitlements” button will redirect to the Entitlements Index page.

When a task is created, the system loads the product catalog from Zuora that is attached to the tenant that created the task. This product catalog is cached in the Entitlement System and is updated automatically every 12 hours. It also can be update on command by selecting the “Update Catalog” button in the Entitlements Index.

Figure 4: Screenshot of example Entitlements Index page

3.5 Entitlements IndexOnce the desired task has been selected, the Entitlements Index page will appear. This page includes a table displaying all of the entitlements tied to the selected task, where that task’s name will also be displayed. The table will include columns for the record name, description, and actions. For each record, in the actions column, there will be buttons to “Edit” and “Delete”. In the table, the entitlement name will also function as a link to view the entitlement information, which when clicked brings up the View Entitlement Modal. The “Edit” button will bring up the Add/Edit Entitlement Modal, and the “Delete” button will delete the record and refresh the Entitlement Index section table, after a confirmation pop-up. Also, above the table, the Entitlements Index will include a button for “Add Entitlement”, which brings up the Add/Edit Entitlement Modal, a button for Export, a button for Upload File, a button for Update Catalog, and a search bar for the appropriate entitlements.


Development Spec

Figure 5: Screenshot of example View Entitlement Modal

3.6 View Entitlement ModalThe View Entitlement Modal will be opened when the user clicks the entitlement record name on the Entitlement Index Page. The modal will contain all details about the selected entitlement record, including entitlement name and ID, associated task name and ID, description, associated Products and Rate Plans, and all custom fields. The modal will also include buttons “Edit”, which will close the current modal and bring up the Add/Edit Entitlement Modal in edit mode, and “Close” which will simply close the modal and return to the Entitlement Index Page.


Development Spec

Figure 6: Screenshot of the Add/Edit Entitlement Modal in the new mode, used for creating new entitlement records

Figure 7: Screenshot of the Add/Edit Entitlement Modal in the edit mode, used for updating pre-existing entitlement records


Development Spec3.7 Add/Edit Entitlement Modal

The Add/Edit Entitlement Modal is a form that has two different functions and can be displayed after three possible actions. When the “Add Entitlement” button is clicked on the Entitlements Index Page, the modal will be displayed in the new mode. The new mode allows the user to create a completely new entitlement record. When displayed with this functionality, the modal will display an empty field for the name, description, select options for connecting Rate Plans, and a button allowing the user the add custom fields.

The other function of the modal is the edit mode, which is used to change the values of existing entitlement records. The modal can be displayed with this function after the user clicks the “Edit” button for a certain entitlement in the Entitlement Index Page, or when the user clicks the “Edit” button in the View Entitlement Modal. The display in the edit mode will be similar to the new mode, where the only difference is the pre-existing data for the record will be shown. The name field will be populated, the connected Products and Rate Plans will be listed, and all custom fields will be shown. The modal will also have buttons “Save”, which will submit the form and save the data (either creating a new record or updating an existing one), and “Cancel”, which will dismiss the data. Both buttons will close the modal and return to the Entitlements Index Page.

The options for the dropdown select menus for the product and rate plans are based on the product catalog of the tenant that created the task. At first when the form options, the “Products” select is enabled, but the “Rate Plans” select is disabled. Upon selecting a product, the “Rate Plan” select is populated with the rate plans attached to the selected product and enabled. Also, each time the “Product” select is changed, the rate plans are repopulated to the appropriate rate plans in the “Rate Plan” select. When a rate plan is selected, it is added to the connected rate plans table. Any rate plan can be removed by clicking the “x” in the same row.

Similarly, the custom fields can be added to the form by selecting the “Add Custom Field” button, and custom fields can be removed by clicking the “x” next to the entry fields for the desired custom field.

3.8 Search BarThe search bar will be located at the top of the Entitlements Index and will allow the user to search for and filter the entitlement records that are displayed in the Entitlements Index section. The Search Bar will have the functionality to search against all details of each record. This includes the record name and ID, entitlement record description, connected Products’ name and ID, connected Rate Plans’ name and ID, the name and ID of the charges associated with the connected Rate Plans, and the keys and values of the custom fields for the record. For each key entered, the entitlements record table is filtered to only records that have attributes that match what is in the search bar.

3.9 Export ButtonThe Export Button is located in the Entitlements Index above the entitlements table. When the user clicks this button, a CSV file is generated based on the entitlements records tied to the task that has been selected to get to the Entitlements Index page. This CSV file includes the records’ IDs, names, descriptions, connected Products and Rate Plans, and the custom fields of each record. This is useful when the user wants to make a large amount of changes create a large number of records, or delete a large number of records, as the CSV file can be reapplied to the system using the “Upload File” button.


Development Spec

Figure 9: Screenshot of an example table (CSV file) created when exporting and used when importing. Note the “New Record”. When this file is imported, this row creates a new entitlement record due to the ID field being empty. All other

example records will be used to update pre-existing records.

3.10 Upload File ModalThe Upload File Modal is shown when the user clicks the “Upload File” button shown on the Entitlements Index page. The modal actually has two different functions, Create/Update and Delete. The function of uploading a file can be changed by changing the drop down select. On the change of the drop down select, the instructions for the file will also change. The modal includes a small set of instructions as well as an “Upload” button, allowing the user to select the CSV file to be uploaded. When the “Upload” button is selected, a browser window will open allowing the user to explore the local files. After selecting a file, the user would then need to click the “Import” button to apply the changes in the CSV file. The “Close” button will simply hide the Import Modal and dismiss any changes.

Figure 10: Screenshot of the Upload File Modal in the Create/Update mode


Development Spec

3.10.1 Create/Update

The first of the two functions possible when uploading a file is the Create/Update function. This is used when a user would like to create multiple new entitlement records at once, update multiple existing entitlement records at once, or both create and update multiple records at once. Both creating a updating can be done by uploading a single file.

To update an existing record, the ID column of the CVS should be populated with the desired record’s ID. The record with that ID will then be updated to the rest of the data listed in the CSV file for that record. Also in the CSV file, there are columns for the name, description, Rate Plan name, Product SKU (found in Zuora), Product name, and Custom Fields. The name and description should all be on the same row as the ID as listed, as well as the custom fields. For custom fields, the first column, in line with the column labeled “Custom Fields”, should be the field name for the first custom field. The next column in the same row should be the field value for the first custom field. For any other custom fields that should be added or updated, they should be listed consecutively on the same row following the same pattern (field name, field value, field name, field value...). For records that have multiple rate plans connected to them, the Rate Plan name, Product SKU, and Product name should be listed in the subsequent rows, with no other columns populated. These attributes should fall in the appropriate columns that are labeled “Rate Plan”, “SKU”, and “Product”, respectively. If there are any other columns populated in these rows, and error will appear and no records will be updated or created.

To create a new entitlement record, the format in a CSV file for a record will be identical as the form for updating a record with the exception of the ID field, which should be blank. Rows where the ID field is blank will create new record, except when these rows are used to show addition rate plans being attached to a record in a previous rows. The form of a CSV file, for both creating and updating records is shown in Figure 9.

If a file is uploaded that lists an ID that is not found, then an error message will appear and no records will be updated or created. This is also the case when uploading in the Delete functionality. Similarly, if a rate plan or product that does not exist is listed, then an error message will appear and no records will be updated or created.


Development Spec

Figure 11: Screenshot of the Upload File Modal in the Delete mode

Figure 12: Screenshot of an example table (CSV file) for deleting multiple entitlement records through the Upload File Modal in Delete mode

3.10.2 Delete

The Upload File also has a delete function for deleting multiple records at one. The format of the CSV file is much different than the Update/Create function. The format for the delete function is a single column with the list of IDs. The purpose of having a CSV file with a much different format allows the user to make sure they want to delete these records and mass amount of datas are not lost by mistake. In the case where a file is selected with the incorrect format, an


Development Specerror message appears and no records will be deleted. The format for CSV file to delete records is shown in Figure 12.

3.11 Update Catalog ButtonThe product catalog for the logged in tenant must be loaded for the purpose of selected Rate Plans to connect to a record when creating and updating. The product catalog is initially loaded when a task is created and automatically updated every 12 hours. If the user has made changes to the catalog within the tenant and would like to use these changes in creating or updating a record, clicking the Update Catalog Button allows that. The catalog will be reloaded incorporating any new or update products, rate plans, or charges.

Figure 13: Screenshot of PostGres entitlements datatable as shown in PGAdmin. Not the columns for rate plans, charges, and fields are stored as HStore which is stored as a hash. Also, not shown, the description field, listed last after updated

at.

3.12 DatabaseThe data used for the Entitlement system will be stored in its own separate Postgres table located in the existing RBM Connect database. The table will be of the form shown above in Figure 4. It will contain columns for the unique record ID, the task ID that maps the record to the appropriate task, the record name, the record description, the associated rate plans, the associated charges, the custom fields as defined by the user, and the time stamps “create at” and “updated at”. The columns for the rate plans, charges, and fields will all be stored using the HStore extension of postgres which allows the user to dynamically define custom fields. The column for the charges is never accessed by the user, but allows the user to search for entitlement records based on charge names and IDs. The column also uses HStore where the keys are the charge IDs and the values are the charge names. The fields column will be handled differently, however. These HStore elements will be able to be dynamically added as an entitlement record is created or updated. As the fields are added, the user will have the ability to defined the field key and field value. HStore gives the functionality to query against both the keys and the values of its fields.


Development Spec

Figure 14: Example of JSON object of entitlement records that is returned when making REST calls. This is an example of all entitlements connected to a task, because all record attributes are included (Section 3.13.1).

3.13 REST API CallsThere are two types of REST calls that can be made to the system in order to retrieve entitlement record information. One call will return all entitlements tied to a specified task, the other will be able to make calls based on either a product, product rate plan, or product rate plan charge. All calls will return a JSON object.

3.13.1 Task Entitlements


Development SpecThe first type of REST call will me for when a user would like to retrieve all entitlement

records tied to a specified task with all record information. The URL for such a call out is as follows:

http://connect.zuora.com/tools/utilities/entitlements_group/<task ID>/entitlements.json

The <task ID> is an integer ID that can be found in the Task Section for each task. The callout to a URL shown above with the task ID provided will return an array containing JSON objects for each entitlements that is tied to that task ID. Each JSON object for this call holds information for every attribute of an entitlement record. This includes entitlement record ID, task ID, name, description, connected products, connected rate plans, connected charges, and the custom fields created for the record.

3.13.2 Product, Rate Plan, or Charge Callouts

The other type of REST call will be when the user would like to return all entitlement records that are tied to a particular product, product rate plan, or product rate plan charge. The URL for such a callout is as follows:

http://connect.zuora.com/tools/utilities/entitlements_group/<task ID>/entitlements.json?product_id=<product ID>

http://connect.zuora.com/tools/utilities/entitlements_group/<task ID>/entitlements.json?rate_plan_id=<product rate plan ID>

http://connect.zuora.com/tools/utilities/entitlements_group/<task ID>/entitlements.json?charge_id=<product rate plan charge ID>

Similarly to the <task ID>, the <product ID>, <product rate plan ID>, and the <product rate plan charge ID> are all integer IDs. These IDs can be found inside of Zuora. Making a callout using the URLs with a product ID or a rate plan ID will return every entitlement record found within the task with the specified task ID that has the specified product or rate plan connected to it. All rate plans in Zuora may contain multiple charge IDs with in it. Using the URL with the charge ID as a parameter will return all entitlement records that have the parent rate plan of the charge ID connected to it, much like using the rate plan as a parameter.

For these returned entitlement records, not all attributes of the records will be included. The only information that will be included in these JSON objects will be the entitlement record ID, task ID, name, and custom fields created by the user.

Also, in the instance of a URL with a combination of parameters listed, the entitlement records that are returned will be based on the most specific parameter given. Product rate plan charge IDs will take precedence over product rate plan IDs which will take precedence over product IDs. An example of a URL with multiple parameters listed would be:

http://connect.zuora.com/tools/utilities/entitlements_group/<task ID>/entitlements.json?product_id=<product ID>&rate_plan_id=<product rate plan ID>&charge_id=<product rate plan

charge ID>


Development SpecThis example would return the same entitlement records that would be returned for making a callout to the URL containing only the product rate plan charge ID.

Callouts with multiple parameters given will not take into account IDs that do not match to their parent correctly. For example, if a product rate plan ID is given along with a product ID and the product rate plan is not a child of the given product, the product ID is ignored and the returned entitlement records will be the same as if the URL with only that product rate plan is given. The same is true for a charge ID listed with a mismatched product ID or mismatched product rate plan ID.


Documents

Overview · Web view2.0 6/15/2015 Redraft Wes Spears Louis Livingston 3.0 6/24/2015 Change approach to include the use of Z-Hub Tasks Wes Spears Louis Livingston 4.0 7/21/2015 Final