Development Spec
Entitlement System
Technical Development Specification #
Version 4.1
Zuora Client Services
08/11/2015
Wesley Spears
Louis Livingston
Zuora Inc.
1051 Foster City Blvd
Suite 600
Foster City,CA94404
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.1Purpose
1.2Intended Audience
2. Requirements
2.1Business Requirements
2.2Technical Requirements
2.3Assumptions
2.4Known Issues / Limitations
3. Technical Design
3.1 Overview
3.2 Obtaining the Entitlement Mapping System Webapp
3.3 Launching the Entitlement Mapping System Webapp
3.4 Task Section
3.5 Entitlements Index
3.6 View Entitlements Modal
3.7 Add/Edit Entitlement Modal
3.8 Search Bar
3.9 Export Button
3.10 Upload File Modal
3.10.1 Create/Update
3.10.2 Delete
3.11 Update Catalog Button
3.12 Database
3.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 Purpose
The 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.2Intended Audience
This solution is intended for all clients seeking to outsource entitlement management of their Zuora subscriptions through a 3rd party application.
2.Requirements
2.1Business Requirements
Business Requirement / DescriptionBR1073 / Solution 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
BR1075 / The client will have the ability to create entitlement records to apply to one or multiple rate plans found in the Zuora database
BR1076 / The 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
BR1078 / The 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, although the format is different than that used to create and update
2.2Technical Requirements
Technical Requirement / DescriptionTR 1 / Solution 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.3Assumptions
- There is no limit to the number of entitlement records that can be created under one particular task
- There is no limit to the number of rate plans that can be connected to a single entitlement record
- There is no limit to the number of custom fields tied to a single rate plan
- No two rate plans within a product have the same name
2.4Known Issues / Limitations
TBD
-
3.Technical Design
3.1Overview
Zuora 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.2Obtaining the Entitlement Mapping System Web App
The 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.3Launching the Entitlement Mapping System Web App
The 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.
Figure 2: Relationship Diagram showing flow of pages in the web app.
Figure 3: Screenshot of example Task Section
3.4Task Section
The 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 to 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.5Entitlements Index
Once 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.
Figure 5: Screenshot of example View Entitlement Modal
3.6View Entitlement Modal
The 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.
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
3.7Add/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.8Search Bar
The 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.9Export Button
The 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.
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.10Upload FileModal
The 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
3.10.1Create/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.
Figure 11: Screenshot of the Upload File Modal in the Delete mode