Provisioning and Managing Integration Packs via the API

Document created by Adam Arrowsmith Employee on Apr 25, 2016Last modified by Adam Arrowsmith Employee on May 23, 2017
Version 6Show Document
  • View in full screen mode

This article describes the sequence of AtomSphere platform API calls to provision and manage integration packs. Deploying integration packs requires a number of prerequisites including several steps which can only be performed by the Dell Boomi account management team.

 

 

Overview

The installation and management of integration packs can be automated through AtomSphere platform APIs. This is a common requirement for partners who wish to embed the integration setup and management within their own applications and abstract the AtomSphere user interface from their end users. To learn more about what integration packs are, their use cases, and how to create them see Integration Packs.

 

The sections below detail the API calls required to provision and manage integration packs. To see these API calls in action, we have created the Integration Pack Demo Application Overview. This is a fully-functioning example web application that demonstrates how to use the APIs to embed the integration pack configuration experience within another application.

 

 Get an example process demonstrating the API calls described below using the AtomSphere Partner API Connector from the Process Library here.

 

Before You Begin...

 

Prerequisites

  • Parent account has partner features enabled: Process Library, Integration Packs, Cloud Management, Account Groups, and Partner API
  • Pricebook configured in the Partner Portal (PRM) - Must work with your Dell Boomi account manager
  • Integration pack created and published
  • Private cloud installed
  • Account group created
  • Integration pack and cloud shared via account group
  • "Service user" added to "ALL ACCOUNTS" account group to use for API calls

 

Assumptions and Limitations

  • Assumes environments will be enabled in the subaccounts (recommended).
  • The integration packs will be deployed to cloud atoms only. Installing a local atom cannot be automated via the API currently. If a local atom is required, the provisioning flow must be interrupted to manually create a subaccount-specific user that can be used in the atom installer. After the atom is installed, the remainder of the configuration can continue via the API.
  • If web service listener processes are included in the integration pack, the shared web server including web service users cannot be configured via the API.
  • API, Certificate, and Process Route components cannot be included in integration packs.

 

Part 1: Create New Integration Pack Instance

 

1. Provision New AtomSphere Subaccount

If installing a subsequent integration pack in an existing account, this step can be skipped.

 

The calls in this step should use Partner API against the PARENT ACCOUNT.

 

  1. Call Execute AccountProvision to create a new subaccount into which the integration pack will be installed.
    • Note this call is processed asynchronously so you will need to repeatedly query the AccountProvisionResult status before continuing.
    • This request contains the details to describe the new account including name and contact information as well as the account features to enable. You will need to work with your Dell Boomi account manager to setup and obtain the product code(s) specific to your account.
    • Use the status field to activate the account. The account can be activated account immediately when provisioned. Alternatively it can be provisioned as a trial account and activated later.

  2. Receive the new Account ID. This Account ID will need to be permanently stored somewhere in the embedding application so that you can always reference the correct AtomSphere account for the given embedding application tenant.
  3. Obtain the Account Group ID that shares the integration pack and to which the new subaccount will be assigned. Call Query AccountGroup to obtain the ID dynamically. Alternatively find the ID in the AtomSphere UI and hard code into the call.
    1. Call Create AccountGroupAccount with the Account ID and AccountGroup ID to assign the account. This entitles the subaccount to be able to install the integration pack.

    If the private cloud atom is shared from a different account group than the integration pack, call Create AccountGroupAccount to also assign the new subaccount to that account group.

     

    2. Install Integration Pack in Subaccount

     

    The calls in this step should use regular API against the SUBACCOUNT.

     

    1. Call Create Environment to create a new environment in the subaccount. Receive the new Environment ID.
      • Note: If installing additional integration packs in the same subaccount this step can be skipped.
    2. Obtain the Integration Pack ID to install. Call Query IntegrationPack to obtain the ID dynamically. Alternatively find the ID in the AtomSphere UI and hard code into the call.
    3. Call Create IntegrationPackInstance using the Integration Pack ID. Receive the new Integration Pack Instance ID.
    4. Call Create IntegrationPackEnvironmentAttachment using the Integration Pack instance ID and Environment ID to deploy the integration pack instance to the specified environment.

     

    3. Create Cloud Atom (Private Cloud)

    If installing additional integration packs in the same subaccount that should be deployed to the same Cloud Atom this step can be skipped.

     

    The calls in this step should use regular API against the SUBACCOUNT.

     

    1. Obtain the Cloud ID to which the integration pack should be deployed. Call Query Cloud to obtain the ID dynamically. Alternatively find the ID in the AtomSphere UI and hard code into the call.
    2. Call Create Atom using the Cloud ID. Receive the new Atom Instance ID.
    3. Obtain the Environment ID to which the Integration Pack Instance was deployed from above. Call Query Environment to obtain the ID dynamically. Alternatively find the ID in the AtomSphere UI and hard code into the call.
    4. Call Create EnvironmentAtomAttachment using Atom Instance ID and Environment ID to attach the new cloud atom instance to the environment.

     

    4. Activate or Modify Subaccount

    The calls in this step should use Partner API against the PARENT ACCOUNT.

     

    If the subaccount was not activated during initial provisioning or if changes need to be made to the subaccount's contact information or enabled features, call Update AccountProvision using Account ID.

    • To activate, set status to "active".
    • To modify account features, include productCode(s). Again you will need to work with your Dell Boomi account manager to obtain the appropriate codes for your account.
    • This call is processed asynchronously so you will need to repeatedly query the AccountProvisionResult status before continuing.

     

    Part 2: Configuration and Ongoing Management

    All calls below should use regular API against the SUBACCOUNT except where noted.

     

    The embedding application will generally need to present the configuration information as a form to the end user, collect input, and save to the platform API.

     

    Query/Update Extensions

    To retrieve and set environment extensions as part of integration pack configuration:

    1. Call Get EnvironmentExtensions using Environment Id (call Query Environment to obtain dynamically) to retrieve the various extensible values such as connection fields and process properties.
      • If using multi-install integration packs, the Integration Pack Instance ID must be provided as well for context.
    2. Call Update EnvironmentExtensions using Environment Extensions ID to save the new extension values.
      • IMPORTANT: You must include ALL environment extension field values (except passwords) in the update call, not just the ones that changed. Otherwise any existing values will be removed.

     

    Query/Update Schedules

    To retrieve and set process schedules as part of integration pack configuration:

    1. Call Query ProcessSchedules using Atom Instance ID (call Query Atom to obtain dynamically) to retrieve the existing schedules for the processes within the integration pack.
    2. Call Update ProcessSchedules using Process Schedules ID, Atom Instance ID, and Process ID to save the new schedule(s).

     

    Query Execution History

    To retrieve process execution results (i.e. what you see in Process Reporting):

    1. Call Query ExecutionRecord.
      • Note only the process-level information is available. Document-level information including tracked fields is not available.
      • Common filters to consider include executionTime, status, and process ID.
      • Remember execution history is available for 30 days.

     

    Query Events

    To retrieve events such as errors and user-defined notification events:

    1. Call Query Event.
      • Common filters to consider include eventDate, eventLevel, eventType, and status.
      • Remember events are available for 7 days.

     

    Execute Process Ad Hoc

    To execute a given process similar to clicking the "Run Now" button in the UI:

    1. Call Execute Process using the Process ID/Name and Atom ID.
      • IMPORTANT: Note the call response simply acknowledges the execution request to the platform. It does not indicate the successful initiation or completion of the process nor does it return the new Execution ID.
      • The request can include dynamic process property values that will be available to the process.

     

    Cancel Process Execution

    To cancel an in-progress process execution:

    1. Call Query ExecutionRecord using filter status=pending to retrieve in-progress Execution IDs.
    2. Call Cancel Execution using the desired Execution ID.
      • This call must be made using the Partner API against the PARENT ACCOUNT and referencing the subaccount using the overrideAccount querystring parameter.

     

    Download Process Log

    To download the detailed process log for a given execution:

    1. Call Create Process Log using the Execution ID. This returns a download URL for the log file.
      • Note the Atom must be online.
    2. Access the download URL (HTTP Get) to receive the process log as a .zip file.

     

    AtomSphere API Reference

    5 people found this helpful

    Attachments

      Outcomes