This user guide contains a description of the different tasks that can be performed in the Business API Ecosystem using its web interface. This section is organized so the actions related to a particular user role are grouped together.
The Business API Ecosystem supports organizations as defined by the FIWARE IdM. These organizations can use the system as if they were users, being possible to create organizations catalogs and offerings or acquire them.
To use the platform on behalf an organization the user belongs, it is needed to change the platform context. To do that, it is used the Switch Session option of the user menu.
All the users of the system can configure their profile, so they can configure their personal information as well as their billing addresses and contact mediums.
To configure the user profile, the first step is opening the user Settings located in the user menu.
In the displayed view, it can be seen that some information related to the account is already included (Username, Email, Access token). This information is the one provided by the IdM after the login process.
The profile to be updated depends on whether the user is acting on behalf an organization or himself. In both cases, to update the profile, fill in the required information and click on Update.
For users, personal information is provided.
Note
Only the First name and Last name fields are mandatory
For organizations, general organization info is provided.
Once you have created your profile, you can include contact mediums by going to the Contact mediums section.
In the Contact Medium section, there are two different tabs. On the one hand, the Shipping addresses tab, where you can register the shipping addresses you will be able to use when creating orders and purchasing products.
To create a shipping address, fill in the fields and click on Create
Once created, you can edit the address by clicking on the Edit button of the specific address, and changing the wanted fields.
On the other hand, if you have the Seller role you can create Business Addresses, which can be used by your customers in order to allow them to contact you.
In the Business Addresses tab you can create, different kind of contact mediums, including emails, phones, and addresses. To create a contact medium, fill in the fields and click on Create
You can Edit or Remove the contact medium by clicking on the corresponding button
If the external IDPs feature is enabled, admins should login in the system with the local IDPs by directly accessing to the login URL in the browser:
https://[marketurl]/login
If the external IDP is disabled, the login button will use the local IDP.
If the user of the Business API Ecosystem is an admin, he will be able to access the Administration section of the web portal. This section is located in the user menu.
Admin users are authorized to create the system categories that can be used by Sellers to categorize their catalogs, products, and offerings.
To create categories, go to the Administration section, and click on New
Then, provide a name and an optional description for the category. Once the information has been included, click on Next, and then on Create
Categories in the Business API Ecosystem can be nested, so you can choose a parent category if you want while creating.
Existing categories can be updated. To edit a category click on the category name.
Then edit the corresponding fields and click on Update.
If the external IDPs option is enabled, admins are authorized to register them using the Administration section.
To list existing IDPs access to IDPs:
To register a new IDP click in New. In the displayed form, fill the IDP EORI with the EORI given to the IDP by the trust provider (i.e iShare). Provide a name and an optional description and fill Server with the URL of the IDP.
If the user of the Business API Ecosystem has the Seller role, he will be able to monetize his products by creating, catalogs, product specifications and product offerings. All these objects are managed accessing My Stock section.
The Catalogs section is the one that is open by default when the seller accesses My Stock section. This section contains the catalogs the seller has created.
Additionally, it has been defined several mechanisms for searching and filtering the list of catalogs displayed. On the one hand, it is possible to search catalogs by keyword using the search input provided in the menu bar. On the other hand, it is possible to specify how catalog list should be sorted or filter the shown catalogs by status and the role you are playing. To do that, click on Filters, choose the required parameters, and click on Close.
To create a new catalog click on the New button.
Then, provide a name and an optional description for the catalog. Once you have filled the fields, click on Next, and then on Create
Sellers can also update their catalogs. To do that, click on the name of the catalog to open the update view.
Then, update the fields you want to modify and click on Update. In this view, it is possible to change the Status of the catalog. To start monetizing the catalog, and make it appear in the Home you have to change its status to Launched
Product Specifications represent the product being offered, both digital and physical. To list your product specifications go to My Stock section and click on Product Specifications
In the same way as catalogs, product specifications can be searched by keyword, sorted, or filtered by status and whether they are bundles or not. To filter or sort product specifications, click on Filters, choose the appropriate properties, and click on Close
Additionally, it is possible to switch between the grid view and the tabular view using the provided buttons.
To create a new product specification click on New
In the displayed view, provide the general information of the product spec. including its name, version, and an optional description. In addition, you have to include the product brand (Your brand), and an ID number which identifies the product in your environment. Then, click on Next.
In the next step, you can choose whether your product specification is a bundle or not. Product bundles are logical containers that allow you to sell multiple products as if it were a single one. Once you have selected the right option click on Next
If you have decided to create a bundle, you will be required to choose 2 or more product specs to be included in the bundle.
In the next step you can choose if your product is a digital product. If this is the case, you will be required to provide the asset.
Note
If you are creating a product bundle, you will not be allowed to provide a digital asset since the offered ones will be the included in the bundled products
For providing the asset, you have to choose between the available asset types, choose how to provide the asset between the available options, provide the asset, and include its media type.
The next step in the creation of a product is including its characteristics. For including a new characteristic click on New Characteristic
In the form, include the name, the type (string or number) and an optional description. Then create the values of the characteristic by filling the Create a value input and clicking on +.
Once you have included all the characteristic info, save it clicking on Create
Once you have included all the required characteristics click on Next
In the next step you can include a picture for your product spec. You have two options, providing an URL pointing to the picture or directly uploading it. In addition, it is possible to include multiple file attachments to the product spec, such as images, PDF documentation, etc. Once provided click Next
In the last step, you can specify relationships of the product you are creating with other of your product specs.
Once done click on Next and then on Create
Sellers can update their products. To do that click on the product specification to be updated.
Update the required values and click on Update. Note that for start selling an offering that includes the product specification you will be required to change its status to Launched
Note
For digital products it is not allowed to update the version using this form. Instead it is required to follow the process for upgrading the product version.
The basic information of the product specification is not the only information that can be updated, but it is also possible to update the Attachments and the Relationships by clicking of the related tab.
The displayed details form can be used for digital products specifications in order to provide new versions of the digital assets being offered. This can be done by clicking on Upgrade.
In the displayed form, it is required to include a new version for the product specification and to provide the new digital asset to be offered.
Note
All the customers who have acquired an offering including the current product specification will be able to access to the new version of the digital asset.
Product Offerings are the entities that contain the pricing models and revenue sharing info used to monetize a product specification. To list your product offerings, go to My Stock section and click on Offerings
The existing product offerings can be searched by keyword, sorted, or filtered by status and whether they are bundles or not. To filter or sort product offerings, click on Filters, choose the appropriate properties, and click on Close
Additionally, it is possible to switch between the grid view and the tabular view by clicking on the specific button.
To create a new offering click on New
In the displayed form, include the basic info of the offering. Including, its name, version, an optional description, and an optional set of places where the offering is available. Once the information has been provided click on Next
In the next step, you can choose whether your offering is a bundle or not. In this case, offering bundles are logical containers that allow you to provide new pricing models when a set of offerings are acquired together. Once selected click on Next
If you want to create a bundle you will be required to include at least two bundled offerings.
In the next step you have to select the product specification that is going to be monetized in the current offering. Once selected click on Next.
Note
If you are creating an offering bundle, you will not be allowed to include a product specification
Then, you have to select the catalog where you want to publish you offering and click on Next
In the next step, you can optionally choose categories for you offering. Once done, click on Next
Next, it is possible to include the License or terms and conditions to be applied to the offering being created. There are three different options for prividing such information: (1) For data, there is a set of standard open data licenses that can be chosen, (2) providing custom terms and conditions using a wizzard, and (3) providing terms and conditions providing free text.
It is possible to include some SLA information attached to the offering in the step of the form. To do that, click on Define new metric button. In the displayed form. choose a metric, provide its value and click on Add metric.
Once all the metrics have been provided click on Next
The next step is the most important for the offering. In the displayed form you can create different price plans for you offering, which will be selectable by customers when acquiring the offering. If you do not include any price plan the offering it is considered free.
To include a new price plan the first step is clicking on New Price Plan
For creating the price plan, you have to provide a name, and an optional description. Then, you have to choose the type of price plan between the provided options.
The available types are: one time for payments that are made once when purchasing the offering, recurring for charges that are made periodically (e.g a monthly payment), and usage for charges that are calculated applying the pricing model to the actual usage made of the acquired service.
If you choose one time, you have to provide the price and the currency.
If you choose recurring, you have to provide the price, the currency, and the period between charges.
If you choose usage, you have to provide the unit to be accounted, the currency, and the price per unit
In addition to the basic pricing models it is possible to include price alterations using the Price Alteration section. In this regard, it is possible to provide two types of alterations: (1) Price components, enable to extend the model with a complementary pricing (e.g an initial or recurring fixed payment in a usage model). (2) fees and discounts, which are applied to the original model when some condition is satisfied (e.g a 2% discount when more that 10k calls has been made)
You can update or remove plans by clicking on the corresponding action button.
Once you have created you pricing model click on Next
In the last step of the process, you have to choose the revenue sharing model to be applied to you offering between the available ones. Once done, click on Next and then on Create.
Sellers can also edit their offerings. To do that click on the offering to be updated.
In the displayed form, change the fields you want to edit and click on Update. Note that for start selling you offering you have to update its status to Launched
It is also possible to update the Price Plans and Categories of the offering by accessing to the related tab.
Revenue Sharing Models specify how the revenues generated by an offering or set of offerings must be distributed between the owner of the Business API Ecosystem instance, the provider of the offering, and the related stakeholders involved.
To manage RS models go to the Revenue Sharing section.
In this view, you can see the revenue sharing models you have available. By default it will appear the default RS model which establishes the revenue distribution between you and the Business API Ecosystem instance owner.
You can create a new RS model clicking on New
In the first step of the process you have to provide a product class, which identifies the RS model, and the percentage you want to receive. The platform percentage is fixed and cannot be modified. Once provided click on Next
In the next step, you can optionally add more stakeholders to the RS model. To do that click on New Stakeholder
Then, select the Stakeholder between the available users, and provide its percentage. Finally, save it clicking on Create
Note
The total percentage (provider + platform + stakeholders) must be equal to 100
Finally, click on Next and then on Create
Sellers can also update their RS model. To do that click on the RS model to be updated.
Then, update the required fields (including the stakeholders if you want), and click on Save Changes
Sellers can manage the transactions related to their products in order to know how much money their products are generating, and to launch the revenue sharing process. To manage your seller transactions go to Revenue Sharing and click on Transactions
In the displayed view, you can see the transactions pending to be paid to you and your stakeholders. It is also possible to display the transactions in tabular way
These transactions are aggregated and paid by the Business API Ecosystem periodically once a month. Nevertheless, if you need to be paid, you can force the revenue sharing calculus and payment of your pending transactions by manually generating a revenue sharing report.
To create a new report click on New Report
In the displayed modal, choose the product classes to be calculated and click on Create
This process will aggregate all the transactions with the selected product classes, calculate the amount to be paid to each stakeholder using the related revenue sharing model, generate a revenue sharing report, and pay the seller and the stakeholders using their PayPal account.
You can see the generated reports clicking on RS Reports
Note
Sellers would need to have a PayPal account associated to the email of their FIWARE IdM account in order to be paid for their products
Sellers can manage the orders they have received in order to see the chosen characteristics, read customer notes, or process the order in case it has been acquired a physical product.
To view your received orders go to My inventory section, click on Product orders, and open the Received section.
You can view the details of a received order clicking on the order date
In the displayed view you can review the details of the order and the details of your products acquired by the customer, including the chosen characteristics.
Additionally, you can view the customer notes clicking on the Notes tab
You can also give a reply to customer notes including it in the text area and clicking on the send button
If the acquired product is not digital, the order needs to be processed manually by the seller, in the sense that the seller will have to send the acquired product to the customer. To deal with this situation, the order details view allows sellers to manually change the status of the order.
To reject a received order you have to click in the Reject button located in the search or in the details view of the order.
In case you accept the order and send the product to the customer, you have to put it as inProgress clicking on the Sent button
Finally, when the product arrives at its destination, you have to put it as Completed clicking on the Delivered button
All of the users of the system have by default the Customer role. Customers are able to create orders for acquiring offerings.
All the available (Launched) offerings appear in the Home page of the Business API Ecosystem, so they can be seen by customers.
Additionally, customers can select a specific catalog of offerings by clicking on it.
Moreover, customers can filter the shown offerings by category using the categories dropdown and choosing the wanted one.
Customers can also filter bundle or single offerings using the Filters modal as well as choosing its sorting.
Finally, customers can search offerings by keyword using the provided search bar
Customers can open the details of an offering by clicking on it
In the displayed view, it is shown the general info about the offering and its included product, the characteristics of the product, the price plans of the offering, and the existing relationships.
Customers can create orders for acquiring offerings. The different offerings to be included in an order are managed using the Shopping Cart.
To include an offering in the shopping cart there are two possibilities. You can click on the Add to Cart button located in the offering panel when searching, or you can click on the Add to Cart button located in the offering details view.
If the offering has configurable characteristics, multiple price plans or terms and conditions, a modal will be displayed where you can select your preferred options
Once you have selected your preferences for the offering click on Add to Cart
Once you have included all the offerings you want to acquire to the shopping cart, you can create the order clicking on Shopping Cart, and then on Checkout
In the displayed form, you can include an optional name, an optional description, or an optional note. Notes can include any additional information you want to provide to the sellers of the acquired offerings.
Then, you have to choose a priority for your order, and select one of your shipping addresses.
Once you have provided all the required information you can start the order creation clicking on Checkout
In the next step, you will be redirected to PayPal so you can pay for the offerings according to their pricing models
Finally, you will see a confirmation page
The products you have acquired are located in My Inventory, there you can list them, check their status, or download different assets.
In this view, it is possible to filter you products by its status. To do that click on Filters, select the related statuses, and click on Close
It is also possible to switch between the grid and tabular views using the related buttons
You can manage a specific acquired product clicking on it
In the displayed view, you can see the general info of the acquired product, and the characteristics and pricing you have selected.
Additionally, you can see your charges related to the product accessing to the Charges tab
In this tab, you will find detailed information of the different charges and you will be able to download the related invoice clicking on Download Invoice
Moreover, this product view allows to download the related assets when the product is digital. To do that click on Download
In case the chosen pricing model defines a recurring payment or a usage payment, you will be able to renew your product clicking on Renew. After clicking, you will be redirected to PayPal to pay the related amount.
Note
If you product has expired and you do not renew it, it will be suspended, which means you will not have access to the acquired service until you pay
If the acquired product has a usage based price plan, you will be able to see your current consumption accessing the Usage tab
Customers can manage some aspects of the orders they have created. To see your requested orders, go to My Inventory and click on Product Orders
In the displayed view, you can see the orders you have created, which can be filtered by its status. To do that, click on Filters, select the wanted statuses, and click on Close
For those orders that include offerings of non digital products, you will be able to cancel them if the seller has not yet started the process. To do that, locate the order to be canceled and click on Cancel
Moreover, you can review the details of the order. To do that click on the date of the order.
In the displayed view, you can see all the details of the order, as well as the included products. In addition, you can leave a note for the seller in the Notes tab
To leave a note, write it in the provided text area and click on the send button
