Cloud Services

Enterprise Marketplace

Provisioning adapter creation
Published On Oct 08, 2024 - 8:47 AM

Provisioning adapter creation

Provides guidelines on creating a provisioning adapter that allows you to support fulfillment requests.
Provisioning adapters must be created to support fulfillment requests for the following orderTypes:
  • New:
     Provisioning new catalogs, resources, and stacks
  • EditSOI:
     Changing/upgrading existing stacks
  • Delete:
     De-provisioning stacks
  • serviceAction:
     Performing operations on stacks such as reboot, turnOn, and turnOff
For more information, see Provisioning request/response payloads.
For each of those above orderTypes, the Cancel and Retry failure management actions should also be supported. For example, if a new stack/resource might fail on the provider end, at which point you have these options:
  • It can be retried with the same stack configuration by requesting the adapter to retry the provisioning of the same order. The adapter should be able to identify that this is a retry request and then retry the failed or partially provisioning resources.
  • It can be canceled by the user by initiating a cancellation request to the adpater, and the adapter can cleanup any partially provisioned resources on its end.
In either case, the fulfillment service must send the appropriate headers in the provisioning payloads to identify whether the request is cancel, retry, or regular provisioning.

Communication modes

These modes of communication can be used between the Enterprise Marketplace platform (fulfillment-service) and the adapters. A different mode can be configured for each tenant, and depending on whether the adapter is deployed internally in the cluster or is deployed externally.
  • Message broker communication using RabbitMq as-a-service:
     Use this method when the Adapter is deployed outside of where Enterprise Marketplace is located. This is the default mode for out-of-the-box adapters. Messaging queues need to be defined for newly onboarded adapters if this mode is chosen.
  • Direct http communication between fulfillment-service and adapters enabled by adapters explicitly registering the provisioning endpoints via client-registration APIs:
     Use this method when the adapter is internally deployed alongside Enterprise Marketplace where the stacks can communicate internally without the need for https/SSL. Out-of-the-box adapters that are internal have moved to this mode for simplicity. 
YOu must select a mode for any newly onboarded adapter that is NOT out-of-the-box. There is NO default mode defined for newly onboarded adapters.

Cancel action

A Cancel action can be used on a failed provisioining or or de-provisioning fulfillment request. The API to cancel fullfillment is
POST /v4/fulfillment/cancelservice
. See the Swagger documentation for more information. Cancellation can be triggered from any of these stages:
  • PreProvisioning Stage
  • Provisioning Stage
  • PostProvisioning Stage
If a particular fulfillment is cancelled, then subsequent stages are not processed. Cancellation happens only in Enterprise Marketplace and the adapters are not notified by default. Therefore, the adapters must be designed to perform this cleanup. If the adapter wants to be notified for cancellation events, then the adapter needs to register with the following configuration to enable provisioning of cancellation requests via the adapter:
POST /v4/api/fulfillment/configuration
Sample payload: 
{    "configKey": "providerConfig_amazon",    "configValue": {        "providerCode": "amazon",        "adapterSupportsCancelOperation": true    }}
The configKey will be of the format - "providerConfig_" + providerCode.
Check the swagger documentation for corresponding PUT/DELETE/GET APIs. This configuration is only supported in the Provisioning Stage today. Pre and Post hooks do not honor this config and are cancelled immediately.
If the config is set to
true
 then the Cancellation behaves like normal provisioning requests where the order-fulfillment-request is sent (with
action = cancel
 in the headers) and the polling starts immediately to poll for the cancellation status. The status polling request will also include the header
action = cancel
. Adapter can send
CancellationSuccessful
 to mark the fulfillment as
Cancelled
 or the adpater can send
CancellationFailed
 in which case the fulfillment will be reverted back to the
Failed
 status.

Retry action

A failed provisioning or de-provisioning fulfillment request can be retried using the following API:
POST /v4/fulfillment/retryservice
. If a fulfillment is retried from a particular stage and is successful, then subsequent stages will continue to execute as usual. Retry requests behave like regular provisioning requests wherein order-fulfillment-request is sent first (with
ICB-RetryType = Manual
 in the headers) and waits for the order-fulfillment-response before starting the status polling on the retried fulfillment. The status polling request will also include the header
ICB-RetryType = Manual
. Payloads sent to the adapter will remain the same as regular orderfulfillment/provisioningstatus requests. Adapters are expected to perform any partial cleanup of resources, if required on receiving the retry request. The presence of the ICB-RetryType header means that this request was previously failed and is being retried.
A retry can be initiated from any of the following stages:
  • PreProvisioning Stage
  • Provisioning Stage
  • PostProvisioning Stage

PreProvisioning and PostProvisioning stages

The adapter can also support pre-provisioning-hook and post-provisioning-hook stages. The pre/post hooks are configured using fulfillment policies. Only orders that meet the criteria for those policies will be enabled for pre/post hooks. Adapters listening for those specific hooks should support them. Pre/Post hooks should support all orderTypes if enabled by adapters. In addition, failure management actions like Cancel and Retry will be enabled on PreProvisioning/PostProvisioning stages, if that particular stage fails. Currently Cancel is not required to be supported by adapters. Retry should be supported. 
To create pre- and post-provisioning hooks, complete these steps:
  1. Create a Pre/Post hook subscription using the following API and payload:
    POST {API-Gateway}/emp/common/clients
    . 
    {
    "name": "SnowProvisioningHook", //unique name
    "provider_code": "snow", // Pre/Post prov adapter unique provider code.
    "applicable_for": [
        {
            "id": "integration",
            "values": [
                "ProvisioningPreHook | ProvisioningPostHook" // predefined integration type
            ]
        }
    ],
    "callback": {
        "url": "{snow_adapter_host}:3009/provision/snow/adapter/v2/hook",
        "certs": {
            "endpoint_ca_cer": "",
            "endpoint_cer": "",
            "endpoint_key": ""
        },
        "connection_protocol": "http | https" // for https certs must be present
        }
}
  2. Create a fulfillment policy using the routingKey generated in the previous step using the following API and payload:
    POST <API_GATEWAY>/v4/api/fulfillment/policies
    . 
    {
    "context": [
        {
            "tagType": "sampleComponent1",
            "tagValueCodes": [
                "sampleComponent1tagCode"
            ]
        },
        {
            "tagType": "sampleComponent2",
            "tagValueCodes": [
                "sampleComponent2tagCode"
            ]
        }
    ],
    "endDate": "2019-07-29T11:11:15.614681525Z",
    "name": "sampleName",
    "policyType": "fulfillments",
    "rules": [
        {
            "rule_name": "sampleName",
            "priority": 1,
            "condition": [
                "integrationType == postprovisioning"
            ],
            "outcome": [
                {
                    "routingKey": "snow"
                }
            ]
        }
    ],
    "startDate": "2019-07-24T11:14:15.614681525Z",
    "status": "active"
}
For Pre/Post hook request payload contract below, fulfillment-service will call the prehook/posthook adapter with the following payload on the resgistered callback URL if configured. When the adapter receives this http request, they can continue to process the request in a separate thread asynchronously, but should respond to this http call with 200 OK as acknowledgement of receiving the request. 
{
    "orderNumber": "11JPDET4MS",
    "submittedDate": "2022-06-23T06:17:46Z",
    "orderType": "New | Delete | EditSOI | ServiceAction | Transfer",
    "serviceFulfillmentId": "AAKASBJASJBSAUUYR712",
    "serviceInventoryId": "SAUUYR712",
    "version":  "3.0"
}
For the Pre/Post hook response payload contract below, after the adapter completes processing the pre/post request, it should call either
POST /v2/api/callback/prov_prehook_response
 (prehook response URL) or
POST /v2/api/callback/prov_posthook_response
 (posthook response URL) on fulfillment-service with the following payload to mark the pre/post stage as either completed or failed. 
{
    "orderNumber": "11JPDET4MS",
    "serviceFulfillmentId": "AAKASBJASJBSAUUYR712",
    "status": "Failed | Completed",
    "version": "3.0",
    "comments": "",
    "additionalMessage": "",
    "forceUpdate": true | false
}
Do you have two minutes for a quick survey?
Take Survey