Product provisioning

After your customer purchases the product, they need to provision it before they can use it. This section describes how to configure provisioning for your products.

On the Product provisioning page, you can define how your product is deployed and actions to take when creating or cancelling a subscription.

Provisioning actions

Actions automatically make API calls and run scripts; they're triggered by user events, as described in the overview of API callbacks.

Events

An event may contain a single provisioning action, or a group of them. The following events support provisioning actions.

  • Subscription Create: occurs when a customer creates a new subscription
  • Subscription Cancel: occurs when a customer cancels their subscription
  • Deployment: occurs when explicitly requested by a customer or can be part of subscription creation

For example, when a customer purchases a subscription, the Subscription Create event can be configured with multiple actions. You can define the first action to log the purchase information in your SAP system, the second to deploy the product, and the third to send a confirmation email to the customer.

Multiple actions in an event

API calls and script actions are executed in order, from top to bottom. All actions for a given event must execute successfully for the event to be successful.

Suppose, for example, a deployment has three API calls. The first call succeeds, the second fails, and therefore the third is not executed. The effects of the first API call remain in place and are not "undone." There is no rollback of the first call. However, because some calls in the deployment are not executed successfully, the deployment status is marked as failed.

See add a provisioning action for information about how to create an event using actions.

Action chains

Provisioning actions can be chained. This means that response values can be captured and used as input to a subsequent action within the event.

Response values cannot currently be captured and used at a later time. They must be used within the working event.

Subscription Create

The Subscription Create event occurs when a customer purchases (creates) a new subscription. Like the other events, it can contain multiple provisioning actions that are executed in order and able to use action chains.

See add a provisioning action for information about how to create a Subscription Create event.

Subscription Cancel

The Subscription Cancel event occurs when a customer cancels a subscription. Like the other events, it can contain multiple provisioning actions that are executed in order and able to use action chains.

See add a provisioning action for information about how to create a Subscription Cancel event.

Deployment

The Deployment event determines what occurs when your customers deploy the product. This event can be triggered manually by customers or as part of creating a subscription. Like the other events, it can contain multiple provisioning actions that are executed in order and able to use action chains.

See add a provisioning action for how to create a Deployment event.

You can view your deployments at:

Go to Deployments

Add a provisioning action

View the product information.

  • If you've created a new product, the product information is displayed after you click Create.
  • If you're editing an existing product, select that product from the list and then click Edit to view the product information.

Go to Products

Proceed with the following.

  1. Click Product provisioning from the side menu.

    If it's not visible, click Provisioning to expand the side menu.

  2. Click Add for the provisioning action you're adding (Subscription Create, Subscription Cancel, or Deployment).

    Verify the Lifecycle description matches the provisioning action you're creating.

  3. Under Type, select API Callback or AWS Script.

  4. Configure the API call or AWS script.

Configure an API call

Update the provisioning details

Enter the details for the provisioning step.

  • Description provides details about the action.
  • URL is the endpoint URL for the API call.
  • Under Request Type, select one of the following options:
    • Post: Create a resource.
    • Get: Retrieve information about a resource.
    • Put: Update a resource.
  • Under Content Type, select one of the following options:
    • Form URL-Encoded
    • JSON
    • Custom JSON

Set the API credentials

Enter the credentials for interacting with the API.

Under Type, select one of the following options:

  • None
  • Basic Authentication
    • Enter Username and Password.
  • OAuth
    • Enter tokenUrl, clientId, and clientSecret.

Set API parameters

Add key-value pairs that are request parameters sent with the API call. The values can be static, contain placeholders for values replaced during deployment, or a combination of both.

  • Choose one of the following actions:
    • To add a new parameter, click Add.
    • To update an existing parameter, select that parameter from the list and then click Edit.
    • To delete an existing parameter, select that parameter from the list and then click Delete.
  • Parameter Name is a descriptive name of the parameter.
  • Default Value is the value to be used by the parameter. You can allow customers to override this with a customer input field they set during configuration.

    Optionally, select Field to add placeholders, output from other actions, or custom field values to the default value field.

Examples

You can use placeholders in URLs, query strings, and content bodies.

  • URL: http://www.example.com/{<placeHolder>}/myservice

  • Query string: http://www.example.com/myresource/myservice?var1={<placeHolder1>}&var2={<placeHolder2>}

  • Content body: { "mykey": "{<placeHolder>}" }

Set customer input fields

When deploying a product with an API callback, the customer completes a form built using input fields.

You can add items from your list of API parameters to the list of Customer Input Fields by clicking Input Field for the item. This allows customers to add their values to the API parameter field when configuring their deployment.

  • Choose one of the following actions:
    • To manually add a new customer input field, click Add.
    • To update an existing field, select that field from the list and then click Edit.
    • To delete an existing field, select that field from the list and then click Delete.
  • Parameter Name is a descriptive name of the parameter input field.
  • The following fields are optional and can be overridden by customers when configuring their deployment.
    • Label is a descriptive label of the parameter input field.
    • Default Value is the value to be used by the parameter input field.
    • Description is a description of the parameter.

Set output fields

Output fields allow you to take output from this call and use it as input for the next call.

  • Choose one of the following actions:
    • To add a new output, click Add.
    • To update an existing output, select that output from the list and then click Edit.
    • To delete an existing output, select that output from the list and then click Delete.
  • Under Output Mapping, fill in the following.
    • Output Variable Name is a descriptive name of the output field.
    • Mapped Variable Name is the name of the variable to be used in the next API call. It contains the output value from this call.

Example of API call creating output: create entitlement

The API call, "Create entitlement," creates an output field with the mapped variable, entitlement, that can be used in subsequent API calls.

Example of a provisioning action creating an output variable that can be used by subsequent provisioning actions.
Example of a provisioning action creating an output variable that can be used by subsequent provisioning actions.
Example of a provisioning action creating an output variable that can be used by subsequent provisioning actions.

Example of API call using output: create report key

The output variable, entitlement, from "Create entitlement" is used as input to this API call, "Create report key," in the URL.

Example of a provisioning action using a mapped variable from a previous provisioning action.

When you're done, click Save. Click Preview to see how the product appears in your marketplace without publishing.

When you're ready to publish the updates, click Publish. Review these guidelines before publishing.

Notes on API calls

  • Only JSON responses are supported.
  • Following redirects is not currently supported.
  • Only GET, POST and PUT methods are supported.
  • Only 2xx status codes are considered successful.
  • The binary file substitute parameter returns a signed and timed URL to the file in a GCS bucket.
  • Currently, output variables can only be defined from root-level objects in JSON responses. Data types must be a string, number, or bool.

Example

The following is an example of a valid JSON response.

{
  "first_name": "Jane", // <== OK to extract
  "last_name": "Doe", // <== OK to extract
  "addresses": [ // <== Can't extract from nested datatype
    { "address": "1234 main st", "city": "mycity", "state": "zip": "11111" },
    ...
  ]
  "is_customer": true
}

Test API calls

As a best practice, use cURL to test and verify API calls prior to entering the calls into Orbitera.

Example

curl -D --X POST -d '{"foo": "bar"}' http://register.example.com/api/newSignup/

Configure an AWS script

Update the provisioning details.

Enter the details for the provisioning step.

  • Description provides details about the action.
  • Deployment Script holds the script used by AWS for the action. Click Upload to add your AWS script.
  • Cloud Account is the AWS account used to authenticate when running the script. Select the correct account from the dropdown list.

Select the Amazon Machine Images and regions

  • Select the regions supported by the script from the list by clicking each one where your Amazon Machine Images (AMIs) reside.
  • From the list of AMIs, select the machine images where you want the script to run.

Set the script parameters

This list of parameters and default values is parsed from the script. You can change the default values or select the Public checkbox to let the user enter values.

Outputs from previous scripts or API callbacks can be used as default values. Select the row where you want to insert the output from the previous scripts using the Insert menu.

When you're done, click Save. Click Preview to see how the product appears in your marketplace without publishing.

When you're ready to publish the updates, click Publish. Review these guidelines before publishing.