Table of Contents
Swagger documentation: GET /API/Fields/ServiceDefinition
This page describes how you can define your offerings and services by implementing the Get Services Definition endpoint. In the interworks.cloud platform, services are defined as products which belong to a product type.
- The product type is the most fundamental entity for defining a service in the platform. It establishes the properties and attributes of the service which affect the provisioning, billing, ordering, marketing aspects of services on the platform.
- Products are used by product managers to define the editions of a service by setting specific values for each attribute. In this way, the products are “instances” of the product types, meaning that you can have many products of the same type, while each product has only one product type.
To get familiar with the interworks.cloud product model, please refer to the Defining your Product Catalog page before implementing this endpoint.
The minimum requirement to implement this endpoint is to use it to define your product types. Such an approach is useful for fewer, less complex services. This way, the products can be created manually. Otherwise, for a large amount of products that are changed or updated on a regular basis, it is strongly recommended to use this endpoint to create the products.
Defining your Product Types
This endpoint should return one or more product types. The amount of product types to implement depends on the services you are offering. It is a good practice to create a product type per product family (e.g. for Microsoft services we have different product types for the Office 365 plans and the Dynamics plans).
Generic Fields
The following screenshot displays the available options for creating a product type in the BSS portal. These are the generic fields you should also define for your product type.
"ID": "myservice",
"Name": "Example Service",
"Description": "The definition of an example service",
"AutoExecuteAddonCancelRequest": false,
"AutoExecuteSubscriptionCancelRequest": false,
"AutoExecuteSubscriptionDowngradeRequest": false,
"QuantityLimit": 0,
"QuantityLimitLocked": false,
"AllowMultipleSubscriptions": true,
"Scope": "Both",
"PortalURL": "https://portal.vendor.com",
"CreditInvoicePolicy": "NoRefund"
"LockOptions": ["Quantity", "AllowMultipleSubscriptions"]
"DisableChangeQuantity": false,- AutoExecuteNewOrders – This parameter must be set to true since one of the reasons to implement a service manager is to automatically deliver the service to the customer upon order completion. This parameter should be set to false only if there is a reason for an order to be reviewed before it is executed. For more details about this flow, please refer to: Defining Not Automatically Executed Product Types.
- Cancellation Request Fields – Cancellation Request Fields specify whether the request (as suggested by the name of the field) from the customer is applied automatically, or must be manually approved (or rejected) in the BSS. For a detailed description of these fields, please refer to: Defining the Cancellation Policy per Product Type
- AutoExecuteAddonCancelRequest
- AutoExecuteSubscriptionCancelRequest
- AutoExecuteSubscriptionDowngradeRequest
- QuantityLimit – Whether to limit the purchasable quantity for the product type. This limit is applied per subscription and not per customer. It cannot be used to set the max number of licenses a customer can purchase. To set a max order quantity for a specific product, please see: Apply Min/Max Order Quantity for a Product.
- -1 – By setting the value to -1 you specify that there is no limit and the customer can specify any quantity (e.g. number of licenses) in their order.
- Any positive integer – A subscription cannot have a quantity more than this limit. For example, suppose you have determined a limit of 50 licenses and you have a subscription with 30 licenses. In that case, your customer will not be able to purchase more than 20 extra licenses for this subscription.
- QuantityLimitLocked – A value of true locks the quantity limit toggle checkbox so it cannot be checked or unchecked from a BSS administrator. We suggest setting it always to true for not allowing the administrator to bypass the quantity policy you have implemented.
- Scope – The scope of the product type with regards to its potential use. Can contain the following values:
- Customer – A product of this product type can only be purchased by a reseller for an end customer (and not for their personal use)
- Reseller – Can only be purchased by a reseller for their own use (and cannot be resold to an end customer)
- Both – Can be purchased by a reseller for their own use, and resold to the end customer
- AllowMultipleSubscriptions – Whether to allow a single customer to have multiple subscriptions to the same product type. It is highly recommended to have this parameter set to true, to create a new subscription in the BSS each time a specific customer purchases the same product. To always have a single subscription per product and customer combination, you should not use this option because it cannot always be enforced. For example, when there are price changes, the interworks.cloud platform will create a second subscription even when this option is enabled.Please use the pre-check mechanism to enforce this logic instead.
- PortalURL – The URL to be used for the setup action, for services in the workspace.
- CreditInvoicePolicy – The policy based on which the product can be refunded. May contain:
- Days – The product is eligible for a refund based on the days it has been in use for
- Hours – The product is eligible for a refund based on the hours it has been in use for
- NoRefund – Cannot be refunded
- LockOptions – Specify the fields that cannot be edited by the user. E.g., if the list contains “AllowMultipleSubscriptions“, this means that the Maintain One Active Subscription per Product option cannot be changed.
- DisableChangeQuantity – Specifies whether the quantity of the subscription can be edited by the user.
Product Type Attributes
Each product type can have a list of attributes. There are attributes that are used for defining the edition of your service and properties for displaying options to the customers during ordering:
- Product Characteristics are the properties that define the product. The values of the fields in the ProductCharacteristic object are used to create distinct products with different characteristics. An example of a product characteristic is the number of gigabytes your backup plan includes.
- Order Characteristics have to do with providing options to users to select when ordering the product. An example of an order characteristic is the domain your customers have to provide to set up their tenants in your system.
"Usage": "ProductCharacteristic",
"Kind": "PredefinedChooseOne",
"ID": "edition",
"SortOrder": 2,
"Name": "Edition",
"Description": "Please select the edition of the provided service",
"UsageSpecified": true,
"KindSpecified": true,
"IsRequired": true,
"IsSyncLocked": 0,
"LinkedToQuantity": false,
"AllowUnlimited": false,
"PredefinedValues": [
{
"ID": "1",
"Code": "1",
"Name": "Basic",
"IsDefault": false,
"ResourceId": 0,
"ExtraParameters": null
},
{
.....
}
],
"ExtraParameters": null,
"SliderMin": 0,
"SliderMax": 0,
"SliderStep": 0
- Usage – Can be ProductCharacteristic or OrderCharacteristic
- Kind – The type of value the characteristic holds. The following table describes the supported field types and the extra properties that can be used:
| Kind | Extra Properties | Accepted Values | UI Example |
| Text | No additional fields | Any string of alphanumeric characters |  |
| Numeric | LinkedToQuantity, AllowUnlimited | Integers |  |
| DateTime | No additional fields | Date values in the user format |  |
| Boolean | No additional fields | True/False |  |
| PredefinedChooseOne | PredefinedValues* | Any value specified in predefined values |  |
| PredefinedChooseMany | PredefinedValues* | Any values specified in predefined values |  |
| CustomMultipleValues | [todo] | ||
| Slider | LinkedToQuantity, SliderMin*, SliderMax*, SliderStep* | Integers |  |
*The fields marked with an asterisk are required for the specific value of Kind
- ID – An alphanumerical value which identifies the product type
- SortOrder – The order in which to display the attribute
- Name – The name of the attribute
- Description – A description of the attribute
- UsageSpecified – Must always be equal to true
- KindSpecified – Must always be equal to true
- IsRequired – Whether it is required to specify a value for the attribute
- IsSyncLocked – This field is only applicable for order characteristics. When set to true, the attribute cannot be changed from the BSS when editing the subscription.
- LinkedToQuantity – Whether the specific characteristic affects the quantity of the subscription, and therefore the price of the order and the licenses to be provisioned. For example, if the attribute is users, the value of the attribute (as specified in the field Value) must be multiplied by the quantity of the subscription to determine the actual quantity to be provisioned. In this case, the value LinkedToQuantity must be true. If the attribute does not affect the quantity of the subscription, the value of LinkedToQuantity must be equal to false.
Please refer to this page to see how to calculate the resources to be provisioned for products that have this field set to true. - AllowUnlimited – Whether to allow an unlimited amount of the specific attribute.
- PredefinedValues – For certain values of Kind such as PredefinedChooseOne or PredefinedChooseMany, this field specifies the options which will be available to select as an array of text strings.
- SliderMin – The minimum value for a slider attribute
- SliderMax – The maximum value for a slider attribute
- SliderStep – The value by which a slider attribute increases or decreases
Product Type Rules
You may set rules for specific values of product characteristics to determine whether other product characteristics or order characteristics are shown or hidden during the ordering process.
"RuleList": [
{
"ID": "ruleForAttributeA",
"Name": "Rule for Attribute A",
"Description": "An example rule for Attribute A",
"RuleConditions": [
{
"ConditionField": "productAttributeA",
"ConditionOperator": IsEqualTo,
"ConditionValue": "Thessaloniki",
"RuleField": "productAttributeB",
"RuleOperator": NotContains,
"RuleValue": "Athens;Crete"
}
]
},
{
"ID": "ruleForAttributeB",
"Name": "Rule for Attribute A",
"Description": "An example rule for Attribute A",
"RuleConditions": [
{
"ConditionField": "productAttributeB",
"ConditionOperator": IsEqualTo,
"ConditionValue": "Athens",
"RuleField": "productAttributeC",
"RuleOperator": IsNotAvailable
}
]
}
]- ConditionField – The attribute for which to apply the condition
- ConditionOperator – The operator of the condition. The field may contain the following values:
- Contains
- NotContains
- StartsWith
- EndsWith
- IsEqualTo
- IsDifferentFrom
- ConditionValue – The value of the attribute
- RuleField – The attribute to update if the condition is evaluated to true
- RuleOperator – The operator of the rule inside the condition. The field may contain the following values :
- IsAvailable
- IsNotAvailable
- Contains
- NotContains
- StartsWith
- EndsWith
- IsEqualTo
- IsDifferentFrom
- RuleValue – The value to set to the attribute in RuleField if the condition is evaluated to true
Defining your Products
ProductsCollection contains all your products, with their attributes as defined in the Product Type.
{
"ID": "Product_1_basic",
"Code": "Product_1",
"Name": "Product_1_Name",
"Description": "This is the description of Product_1.",
"AttributeList": [
{
"ID": "edition",
"Values": "Basic"
}
],
"ChargeType": "RecurringPrepaid",
"UnitType": "Monthly",
"UnitBillingCycles": [
"Monthly",
"Annually"
],
"UpdateOptions": [
"Name",
"UnitBillingCycles",
"Prices",
"Currency"
],
"AvailableCurrencies": [
"EUR",
"USD"
],
"IsActivated": true,
"BillingOptionRecurringChargePrepaid": {
"BillingType": "RecurringChargePrepaid",
"NoOfDecimals": 2,
"ChargeRule": "PARTIAL",
"UpFrontBilling": true
}
}- ChargeType – The value of this field is always RecurringPrepaid for recurring services.
- UnitType – An alphanumeric value describing the type of a single unit of the product, e.g. Licenses, Users, Gigabytes, Virtual Machines, Domains. In other words, specifies what the quantity of the product is measured in. Unit types can be managed in the Setup mode of the BSS.
- AvailableCurrencies – Contains an array of currencies in which the product can be made available.
- UnitBillingCycles – For the time being, the service manager only supports the units listed here. If your implementation contains a business scenario which requires a different unit, please contact interworks.cloud Support. Please note that if a unit which is not listed here is used, the product will not be created.
- Monthly
- Annually
- TwoYears
- ThreeYears
- SixYears
- UpdateOptions – This field specifies the properties which are updated every time the endpoint is called. Only applies to the following fields:
- Name
- UnitBillingCycles
- TrialOffer
- TrialAttributes
- Prices
- RelatedProducts
- Currencies
- IsActivated – Whether the product is activated
- BillingOptionRecurringChargePrepaid – contains the options seen in the figure below:
- BillingOptionRecurringChargePrepaid consists of the following fields:
- BillingType – Must be “RecurringChargePrepaid” for recurring services
- ChargeRule – Whether to charge for the partial or full billing period
- BillingDate – Whether to specify a specific billing date, use the customer’s option or exclude the product from prorata.
- CustomerOption
- ExcludeFromProrata
- SpecificBillingDate,
- SpecificBillingDate – The billing date which only applies if BillingDate is set to SpecificBillingDate. The value can be any integer ranging from 1 to 31.
- NoOfDecimals – An integer specifying the number of decimal digits in the price ranging from 0 to 10
- UpfrontBilling – Whether to bill the client upfront
- FreePeriod – A boolean value which determines whether to charge the first billing period
Product Prices
Product Prices can be defined by setting the following fields:
- Currency – The currency for the purchase and sale prices in the standard three letter acronym/abbreviation.
- Units – Contains the following fields:
- BillingCycle – The duration of the billing cycle (Monthly, Annually, etc.)
- Price – The sale price
- Cost – The purchase price
- PriceProtectionTerm – A numerical value for the duration for which price protection applies (in months).
"Prices": [
{
"Currency": "EUR",
"Units": [
{
"BillingCycle": "Monthly",
"Price": 56.1,
"Cost": 51,
"PriceProtectionTerm": 6
},
{
"BillingCycle": "Annually",
"Price": 673.2,
"Cost": 612,
"PriceProtectionTerm": 12
}
]
},
{
"Currency": "USD",
"Units": [
{
"BillingCycle": "Monthly",
"Price": 184.8,
"Cost": 168,
"PriceProtectionTerm": 12
},
{
"BillingCycle": "Annually",
"Price": 2217.6,
"Cost": 2016,
"PriceProtectionTerm": 12
}
]
}Please note the following points:
- It is optional to set product prices with the Get Services Definition Endpoint.
- When the endpoint is called to add or update prices, only prices in currencies activated in your BSS will be affected.
- The Price and Cost fields will be rounded to the nearest amount of decimal places specified in the NoOfDecimals field, and cannot exceed 10 decimal places. It is recommended to provide numbers with the expected amount of decimal places to avoid rounding.
Specifying the Billing Frequency
In this section, specify the frequency at which the subscription is billed to the customer.
new Product() {
....
....
BillingFrequencyOptions = new List<BillingFrequencyOption>()
{
new BillingFrequencyOption(){
BillingCycle = ProductUnitBillingCycle.Annually,
InstallmentPlans = new List<InstallmentPlan>()
{
new InstallmentPlan(){ Installments = 12, Frequency=1},
new InstallmentPlan(){ Installments = 6, Frequency=2},
new InstallmentPlan(){ Installments = 4, Frequency=3},
new InstallmentPlan(){ Installments = 3, Frequency=4}
}
}
}
}- BillingCycle – As above, the billing cycle e.g., Monthly, Annually etc.
- InstallmentPlan – Specify the amount of Installments, as well as their Frequency (in months) In the example above, an annual billing cycle consists of 12 installments per 1 month, 6 installments per 2 months, etc.
Defining Product Addons
The available addons for the product are specified with the same fields as the product. The main difference is the Products field, which contains a list of ID(s) of the product(s) for which this addon is available.
"Addons": [
{
"ID": "1_dummyAddon_1",
"Products": [
"6_dummyProduct_1"
],
"Code": "1_dummyAddon_1",
"Name": "1 x 1_dummyAddon_1",
"Description": "Yfox m dfiso onzsj",
"Attributes": [
{
"ID": "ppuGeneralResourceText",
"IsPrimaryKey": false,
"Values": [
"Cbqeae"
],
"Update": false
}
],
"ChargeType": 1,
"UnitType": null,
"UnitBillingCycles": [
0,
1
],
"UpdateOptions": [
1,
2,
5
],
"UsageType": "Metered",
"ChargeRule": "Partial",
"Prices": [
{
"Currency": "EUR",
"Units": [
{
"BillingCycle": 0,
"Price": 216.48,
"Cost": 196.8
},
{
"BillingCycle": 1,
"Price": 2597.76,
"Cost": 2361.6
}
]
},Set Trial Options for a Product
"TrialEnabled": true,
"TrialDuration": 10,
"TrialDurationType": "Days",
"TrialQuantity": 5If TrialEnabled is set to true, the product has a trial period specified by the values in the other three fields:
- TrialDurationType – The unit of time. Can be either Days or Months
- TrialDuration – The amount of time units
- TrialQuantity – The amount of trial licenses
For example, a trial duration of 2 months would be “TrialDurationType”: “Month” and “TrialDuration”: 2
These options are only updated if UpdateOptions contains the field TrialOffer.
For more information on Trial Options, please see: Enable Product Trials
Product Upgrade and Downgrade Paths
An upgrade path is created when one or more products is set to be an upgrade of another product. The “path” formed from products to their respective upgrades may be linear, or as complex as required, depending on the upgrade options set for each product.
For example:
| Product | Upgrade Options |
| A | B, C |
| B | D |
| C | None |
| D | None |
Customers who own product A may any of the following upgrade paths:
- A→B→D
- A→C
Customers who own product B may follow this upgrade path :
- B→D
RelatedProducts – A list of product IDs related to the current product, as well as their relationship, which may be Upgrade or MutualExcluded. The following is an example of this element, for product A:
"RelatedProducts":{
{"productB", "Upgrade"},
{"productC", "Upgrade"},
}Mutually Exclusive Products
Two or more products which are mutually exclusive cannot be owned at the same time by a single customer. Usually, products are set as mutually exclusive with their respective upgrades, so users cannot purchase or own both a product and its upgraded version. The following example shows that the product B is an upgrade of the current product, but the two products are mutually exclusive as well:
"RelatedProducts":{
{"productB", "Upgrade"},
{"productB", "MutualExcluded"},
}The following rules are applied for two mutually exclusive products A and B:
- A customer who has an active subscription for product A cannot buy product B and vice versa.
- If there is an upgrade path from A to B, when the customer attempts to purchase B (while they already have an active subscription for A), the system will suggest to upgrade the subscription from A to B.
- A customer who attempts to upgrade any amount of licenses of a subscription from A to B will be required to upgrade all licenses of A to B. The same applies for downgrading the subscription from B to A.