Programmer Guide

Plugin Package

Business API Ecosystem plugins must be packaged in a zip. This file will contain all the sources of the plugin and a configuration file called package.json in the root of the zip. This configuration file allows to specify some aspects of the behaviour of the plugin and contains the following fields:

  • name: Name given to the resource type. This is the field that will be shown to providers

  • author: Author of the plugin.

  • formats: List that specify the different allowed formats for providing an asset of the given type. This list can contain the values “URL” and “FILE”.

  • module: This field is used to specify the main class of the Plugin.

  • version: Current version of the plugin.

  • media_types: List of allowed media types that can be selected when providing an asset of the given type

  • pull_accounting (optional): This flag is used to indicate that the service defined by the plugin is not pushing accounting information to the usage API of the Business API Ecosystem, but exposing an API that must be queried to retrieve this information.

  • form (optional): This field is used to define a custom form that will be displayed for retrieving asset-specific meta data. This field is defined as an object where keys are the name of the metadata property and values define the following information:

    • type: Type of the particular metadata property. Allowed values are text, textarea, checkbox and select mapping the form input types to be displayed for retrieving the data.

    • label: Label to be displayed jointly with the form input.

    • default: Default value to be used if no value provided for the property

    • placeholder (text and textarea): Placeholder to be included within the form input

    • options (select): List of valid options when the input is a select. It includes text and value for each entry.

Following you can find an example of a package.json file:

{
    "name": "Test Resource",
    "author": "fdelavega",
    "formats": ["FILE"],
    "module": "plugin.TestPlugin",
    "version": "1.0",
    "media_types": ["application/zip"],
    "form": {
        "auth_type": {
            "type": "select",
            "label": "Auth type",
            "options": [{
                "text": "OAuth2",
                "value": "oauth2"
            }, {
                "text": "API Key",
                "value": "key"
            }]
        },
        "token_required": {
            "type": "checkbox",
            "label": "Token required?",
            "default": true
        },
        "auth_server": {
            "type": "text",
            "label": "Auth Server",
            "placeholder": "https://authservice.com/auth"
        }
    }
}

The source code of the plugin must be written in Python and must contain a main class that must be a child class of the Plugin class defined in the Charging Backend of the Business API Ecosystem. Following you can find an example of a plugin main class.

from wstore.asset_manager.resource_plugins.plugin import Plugin

class TestPlugin(Plugin):
    def on_pre_product_spec_validation(self, provider, asset_t, media_type, url):
        pass

    def on_post_product_spec_validation(self, provider, asset):
        pass

    def on_pre_product_spec_attachment(self, asset, asset_t, product_spec):
        pass

    def on_post_product_spec_attachment(self, asset, asset_t, product_spec):
        pass

    def on_pre_product_spec_upgrade(self, asset, asset_t, product_spec):
        pass

    def on_post_product_spec_upgrade(self, asset, asset_t, product_spec):
        pass

    def on_pre_product_offering_validation(self, asset, product_offering):
        pass

    def on_post_product_offering_validation(self, asset, product_offering):
        pass

    def on_product_acquisition(self, asset, contract, order):
        pass

    def on_product_suspension(self, asset, contract, order):
        pass

    def get_usage_specs(self):
        return []

    def get_pending_accounting(self, asset, contract, order):
        return [], Date()

Implementing Event Handlers

It can be seen in the previous section that the main class of a plugin can implement some methods that are inherited from the Charging Backend Plugin class. This methods can be used to implement handlers of the different events of the life cycle of a product containing the asset. Concretely, the following events have been defined:

  • on_pre_product_spec_validation: This method is executed when creating a new digital product containing an asset of the given type, before validating the product spec contents and saving the asset info in the database. This method can be used for validating the asset format or the seller permissions to sell the asset.

  • on_post_product_spec_validation: This method is executed when creating a new digital product containing an asset of the given type, after validating the product spec and saving the asset info in the database. This method can be used if the plugin require to know some specific info of the asset model

  • on_pre_product_spec_attachment: This method is executed when creating a new digital product containing an asset of the given type, after saving the product spec in the catalog API database but before attaching the product spec id to the asset model. This method can be used if the plugin require to know the id in the catalog of the product spec

  • on_post_product_spec_attachment: This method is executed when creating a new digital product containing an asset of the given type, after saving the product spec in the catalog API database and after attaching the product spec id to the asset model. This method can be used if the plugin require to know the id in the catalog of the product spec

  • on_pre_product_spec_upgrade: This method is executed when a digital product is being upgraded (a new version of the asset has been provided). This method can be used in order to validate the new digital asset before saving the upgrade

  • on_post_product_spec_upgrade: This method is executed when a digital product have been upgraded. This method can be used to send notifications or retrieve new information of the product specification.

  • on_pre_product_offering_validation: This method is executed when creating a new product offering containing an asset of the given type, before validating its pricing model. This method can be used to make extra validations on the pricing model, for example check if the unit of an usage model is supported by the given asset

  • on_post_product_offering_validation: This method is executed when creating a new product offering containing an asset of the given type, after validating its pricing model. This method can be used to make extra validations on the pricing model, for example check if the unit of an usage model is supported by the given asset

  • on_product_acquisition: This method is called when a product containing an asset of the given type has been acquired. This method can be used to activate the service for the customer and give him access rights.

  • on_product_suspension: This method is called when a product containing an asset of the given type has been suspended for a customer (e.g he has not paid). Tjis method can be used to suspend the service for the customer and remove his access rights

  • get_usage_specs: This method must be implemented when the flag pull_accounting is set to true and must return the list of usage specifications the service is able to monitor. For each usage specification a name and a description must be provided (e.g name: API Call, description: Number of calls made to…)

  • get_pending_accounting: This method must be implemented when the flag pull_accounting is set to true. This method must implement the client able to access to the service the plugin is defining in order to retrieve pending accounting information for a giving contract. It must return the list of pending accounting including:

    • date: Timestamp of the accounting record

    • unit: Monitored unit

    • value: Actual usage made by the customer

As can be seen in the Plugin example, the different handler methods receive some parameters with relevant information and objects. In particular:

on_pre_product_spec_validation

  • provider: User object containing the user who is creating the product specification (The User object is described later)

  • asset_t: String containing the asset type, it must be equal to the one defined in package.json

  • media_type: String containing the media type of the asset included in the product being created

  • url: String containing the url of the asset included in the product being created

on_post_product_spec_validation

  • provider: User object containing the user who is creating the product specification (The User object is described later)

  • asset: Asset object with the recently created asset (The Asset object is described later)

on_pre_product_spec_attachment

  • asset: Asset object where the created product specification id is going to be attached

  • asset_t: String containing the asset type, it must be equal to the one defined in package.json

  • product_spec: JSON with the raw product specification information that is going to be used for the attachment. (The structure of this JSON object can be found in the Open Api documentation)

on_post_product_spec_attachment

  • asset: Asset object where the created product specification id has been attached

  • asset_t: String containing the asset type, it must be equal to the one defined in package.json

  • product_spec: JSON with the raw product specification information that has been used for the attachment. (The structure of this JSON object can be found in the Open Api documentation)

on_pre_product_spec_upgrade

  • asset: Asset object that have been upgraded

  • asset_t: String containing the asset type, it must be equal to the one defined in package.json

  • product_spec: JSON with the raw product specification information that is going to be used for the upgrade. (The structure of this JSON object can be found in the Open Api documentation)

on_post_product_spec_upgrade

  • asset: Asset object that have been upgraded

  • asset_t: String containing the asset type, it must be equal to the one defined in package.json

  • product_spec: JSON with the raw product specification information that has been used for the upgrade. (The structure of this JSON object can be found in the Open Api documentation)

on_pre_product_offering_validation

  • asset: Asset object included in the offering being created

  • product_offering: JSON with the raw product offering information that is going to be validated. (The structure of this JSON object can be found in the Open Api documentation)

on_post_product_offering_validation

  • asset: Asset object included in the offering being created

  • product_offering: JSON with the raw product offering information that has been validated. (The structure of this JSON object can be found in the Open Api documentation)

on_product_acquisition

  • asset: Asset object that has been acquired

  • contract: Contract object including the information of the acquired offering which contains the asset. (The Contract object is described later)

  • order: Order object including the information of the order where the asset was acquired. (The Order object is described later)

on_product_suspension

  • asset: Asset object that has been suspended

  • contract: Contract object including the information of the acquired offering which contains the asset

  • order: Order object including the information of the order where the asset was acquired

get_pending_accounting

  • asset: Asset object whose usage information has to be retrieved

  • contract: Contract object including the information of the acquired offering which contains the asset

  • order: Order object including the information of the order where the asset was acquired

Handler Objects

Following you can find the information regarding the different objects used in plugin handlers

  • User: Django model object with the following fields
    • username: Username of the user

    • email: Email of the user

    • complete_name: Complete name of the user

  • Asset: Django model object with the following fields
    • product_id: Id of the product specification which includes the asset

    • version: Version of the product specification which includes the asset

    • provider: User object of the user that created the asset

    • content_type: media type of the asset

    • download_link: URL of the asset if it is a service in an external server

    • resource_path: Path to the asset file if it is uploaded in the server

    • resource_type: Type of the asset as defined in the package.json file of the related plug-in

    • is_public: If true the asset can be downloaded by any user without the need of acquiring it

    • meta_info: JSON with any related information. This field is useful to include specific info from the plugin code

Additionally, it includes the following methods:

  • get_url: Returns the URL where the asset can be accessed

  • get_uri: Returns the url where the asset info can be accessed

  • Contract: Django model with the following fields
    • item_id: Id of the order item which generated the current contract

    • offering: Offering object with the information of the offering acquired in the current contract (The offering object is described later)

    • product_id: Id of the inventory product created as a result if the acquisition of the specified offering

    • pricing_model: JSON with the pricing model that is used in the current contract for charging the customer who acquired the included offering

    • last_charge: Datetime object with the date and time of the last charge to the customer

    • charges: List of Charge objects contaning the info of the different times the customer has been charged in the context of the current contract

    • correlation_number: Next expected correlation number for usage documents. This field is only used when the pricing model is usage

    • last_usage: Datetime object with the date and time of the last usage document received. This field is only used when the pricing model is usage

    • revenue_class: Product class of the involved offering for revenue sharing

    • terminated: Specified whether the contract has been terminated (the customer has no longer access to the acquired asset)

  • Offering: Django model with the following fields
    • off_id: Id of the product offering

    • name: Name of the offering

    • version: Version of the offering

    • description: Description of the offering

    • asset: Asset offered in the offering

  • Charge Django model with the following fields
    • date: Datetime object with the date and time of the charge

    • cost: Total amount charged

    • duty_free: Amount charged without taxes

    • currency: Currency of the charge

    • concept: Concept of the charge (initial, renovation, usage)

    • invoice: Path to the PDF file containing the invoice of the charge

  • Order: Django model with the following fields
    • order_id: Id of the product order

    • customer: User object of the customer of the order

    • date: Datetime object with the date and time of the order creation

    • tax_address: JSON with the billing address used by the customer in the order

    • contracts: List of Conctract objects, one for earch offering acquired in the order

Additionally, it includes the following methods:

  • get_item_contract: Returns a contract given an item_id

  • get_product_contract: Returns a contract given a product_id

Managing Plugins

Once the plugin has been packaged in a zip file, the Charging Backend of the Business API Ecosystem offers some management command that can be used to manage the plugins.

When a new plugin is registered, The Business API Ecosystem automatically generates an id for the plugin that is used for managing it. To register a new plugin the following command is used:

python manage.py loadplugin TestPlugin.zip

It is also possible to list the existing plugins in order to retrieve the generated ids:

python manage.py listplugins

To remove a plugin it is needed to provide the plugin id. This can be done using the following command:

python manage.py removeplugin test-plugin