Dynamic Parameters Validation

Updated: June 1, 2020
Contents

Video Tutorial

Introduction

Default Product definition in the CloudBlue Connect only includes static definition of the Ordering-phase parameters. In order to support dynamic validation, this capability needs to be explicitly enabled in the Product definition:

When enabled, this capability allows Vendor to declare a Webhook that will be used to perform dynamic validation of the Asset parameters in the Draft State by Provider Systems that are capable of such validation as schematically illustrated below:

Which allows implementing complex multi-step order population and validation scenarios by Providers:

Please refer to the following paragraphs of this article for details about this process.

Defining Webhook

Once Dynamic Validation capability is enabled, Vendors need to create a corresponding handler and declare Webhook that will link product and handler with the validation business logic.

In order to declare a Webhook, please go to the Extensions > Webhook and choose Create:

Define name and description that will later clearly define the purpose of the webhook definition:

Choose Product with the Dynamic Validation capability enabled to be linked with the webhook handler:

Choose the “Draft asset request validations” Webhook type :

Choose URL and other HTTP parameters and create a webhook:

You will be able to adjust these settings later if needed in the Webhook object details:

Once created, you can test dynamic validation using the Create Asset Wizard.

Testing Webhook

The simplest way to test dynamic validation is to use the Create Asset wizard. Navigate to the Assets module and click “Create”:

And choose Product that has Dynamic Validation capability enabled:

For such products, Parameters assignment screen will perform the dynamic validation function:

This screen will simulate Provider systems behavior and in case of errors from the validation script will show them to the user:

Also allowing to skip dynamic validation and fallback to the “inquiring” scenario where parameters are asked from the user after asset creation.

Webhook Details

Firewall

Validation handler is triggered by the CloudBlue Connect from the IP addresses managed under the special egress.connect.cloudblue.com domain as illustrated by the following diagram:

Please refer to the Firewall Configuration article for details.

Payload

The payload of the webhook consists of the Asset Request object:

{
    "id": "PR-2901-1844-5270-001",
    "type": "purchase",
    "reason": "",
    "status": "draft",
    "created": "2020-05-30T07:12:20+00:00",
    "updated": "2020-05-30T07:12:26+00:00",
    // ...
    "asset": {
        "id": "AS-2901-1844-5270",
        "status": "draft",
        // ...
        "params": [
            {
                "id": "order_parameter",
                "name": "Order Parameter",
                "type": "text",
                "description": "Parameters are important",
                "value": "123",
                "value_error": "",
                "value_choices": [],
                "title": "The Order Parameter"
            },
            // ...
         ],
        "tiers": {
            // ...
        },
        "configuration": {
            "params": []
        },
        "marketplace": {
            "id": "MP-54865",
            "name": "Germany",
            "icon": "/media/PA-239-689/marketplaces/MP-54865/icon.png"
        },
        "contract": {
            "id": "CRD-00000-00000-00000",
            "name": "ACME Distribution Contract"
        }
    }
}

CloudBlue Connect expects the same representation that was sent to the handler to be received from the handler with the “asset.params” section modified as required for the handler.

It is expected, that the “value_error” property of the corresponding parameter will contain an error description string in the case of any validation errors. In the case of a successful validation, “value_error” is expected to be empty.

Caller Authentication

Webhook handler can use different means of the caller authentication when required:

  1. Every webhook is sent with the JWT token in the Authentication header – see http://jwt.io for details. The JWT token can be used to validate the authenticity of the caller using the secret value available in the Webhook details.
  2. Custom Headers can be added to the Webhook payload to allow simple header-based secret validation.
  3. Custom body attributes can be appended to the webhook body in the webhook configuration.
  4. Firewall rules can be used to allow inbound connections from the egress.connect.cloudblue.com only

Altogether allowing flexible authentication configuration that will meet the needs of any complexity.

Example

Create Test Product

Create a sample Product with a single ordering phase parameter id =ordering_param_1‘ that will be used by the sample handler business logic below.

Sample Handler using Flask

To test the dynamic parameters validation functionality, you can use the following sample webhook handler written using flask (https://flask.palletsprojects.com) framework.

#!/usr/bin/env python
# dynamic-validation-example.py

from flask import Flask, request, json
api = Flask(__name__)

def get_parameter_by_id(params, id):
    for param in params:
        if param['id'] == id:
            return param
    raise Exception('Parameter {id} not found.'.format(id=id))

def set_parameter(params, param):
    ret = []
    for p in params:
        if p['id'] == param['id']:
            ret.append(param)
        else:
            ret.append(p)
    return ret

@api.route('/validate', methods=['POST'])
def do_validate():

    data = request.json
    params = data['asset']['params']

    param_1 = get_parameter_by_id(params, 'ordering_param_1')
    param_1['value_error'] = 'This error is from the validation script!'
    params = set_parameter(params, param_1)

    data['asset']['params'] = params
    return data

if __name__ == '__main__':
    api.run()

This script defines that POST handler at the /validate path that unconditionally returns an error associated with the ‘ordering_param_1‘ allowing you to add any custom/test logic on top.

Copy this script to your machine and run it with the simple command:

$ python ./dynamic-validation-example.py

 * Serving Flask app "dynamic-validation" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
127.0.0.1 - - [30/May/2020 23:00:59] "POST /validate HTTP/1.1" 200 -

Which will run the webserver on your local machine on port 5000.

Expose Handler to the Internet using Ngrok

Running on port 5000 on your local host will obviously not allow CloudBlue Connect to trigger it, unless your machine is exposed directly to the internet. So you will need to make this script accessible from the internet for the CloudBlue connect to be able to trigger it.

A simple way to do that is with the ngrok (https://ngrok.com) tunnel. Download and install ngrok to your machine and make local port 5000 visible to the internet by running the following command:

$ ngrok http 5000

ngrok by @inconshreveable

Session Status                online
Account                       CloudBlue Connect
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://YOUR-SUBDOMAIN.ngrok.io -> http://localhost:5000
Forwarding                    https://YOUR-SUBDOMAIN.ngrok.io -> http://localhost:5000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Your sample validation handler is now accessible via the http://YOUR-SUBDOMAIN.ngrok.io/validate URL.

Update Webhook URL

Now that you have dynamically generated http://{YOUR-SUBDOMAIN}.ngrok.io/validate handler, update your Webhook URL setting with that value to allow CloudBlue Connect communicating with the sample validation script.

Test Validation with the Create Asset Wizard

Now that everything is ready, go the Parameters step of the Create Asset wizard and click “create”. You should see the following error message:

Which means that your custom validation logic from the sample script has successfully returned error value. You can add additional validation logic from here as required by your business logic.

Is this page helpful?
Translate with Google
Copied to clipboard