Merging Branches with the Boomi Enterprise Platform API


Introduction:

Boomi’s November 2024 release introduced Branch and Merge functionality into the Boomi Platform. This how-to guide walks through some new functionality with the Boomi Enterprise Platform API showcasing Merging Branches.

Disclaimer: This process and design is in no way intended to serve as an authoritative way of performing this query, but is instead aimed at showcasing functionality and empowering you as a developer to build upon this functionality.
Note: At the time of this writing, the API calls to the Boomi Enterprise Platform API are not currently supported with the branded Boomi Enterprise Platform API connector. I am instead using the REST Client technology connector to make the calls.
 

Before you Begin:

A connection to the Boomi Enterprise Platform API is required. Within the Platform Settings, there is a tab to create new Boomi Enterprise Platform API Tokens


 

When creating the token, it  will be visible once. Save the token somewhere secure.

Configuring the REST Client Technology Connector:

  • Base URL - https://api.boomi.com/api/rest/v1/{Account ID}
  • Authentication Type - Basic
  • User - BOOMI_TOKEN.{Platform Login Email}
  • Password - {Boomi Enterprise Platform API Token}

Configuration Steps:

 

Step Configuration:

Start Step - Data Passthrough

This process assumes that a source and destination branch name will be specified in Dynamic Process Properties. These properties can be set in a main process calling this process, or through a set properties step referring to a profile’s elements that are passed into this process. 

Branch

This process is broken up into two branches. The first branch creates the Merge Request, the second executes the Merge. 

[Branch 1] Process Call - [UTILITY] Create MergeRequest (by DPP_SOURCE_BRANCH_NAME, DPP_DESTINATION_BRANCH_NAME OR DPP_SOURCE_BRANCH_ID, DPP_DESTINATION_BRANCH_ID)

This step calls the modular process [UTILITY] Create MergeRequest (by DPP_SOURCE_BRANCH_NAME, DPP_DESTINATION_BRANCH_NAME OR DPP_SOURCE_BRANCH_ID, DPP_DESTINATION_BRANCH_ID). Instructions for configuring the process are as follows:

Start Step - Data Passthrough

This step is configured as a data passthrough to allow for the process document to flow through into this sub process.

Branch

This step splits the process into three branches. The first branch finds the Branch ID of the Source Branch, the second branch finds the Branch ID of the Destination Branch, and the third branch creates the actual Merge Request via the Boomi Enterprise Platform API.

[Branch 1] Decision - DPP_SOURCE_BRANCH_ID Empty?

This step determines if the first branch is necessary. The Boomi Enterprise Platform API requires that a Branch ID be specified, though by adding some extra logic, we can allow for the branch name to be given, adding an extra few steps to query for the ID. If the Dynamic Process Property, DPP_SOURCE_BRANCH_NAME is empty then it is assumed that the Source Branch’s name was given.

  • First Value - Dynamic Process property name of ‘DPP_SOURCE_BRANCH_ID’
  • Comparison - Equal To
  • Static value of ‘’
[True] [Branch 1] Set Properties - Set DPP_BRANCH_NAME = DPP_SOURCE_BRANCH_NAME

This step is necessary as the modular process we will be calling to query the branch ID based on the Branch name assumes the Dynamic Process Property: DPP_BRANCH_NAME will be given. 

  • Dynamic Process Property - DPP_BRANCH_NAME = Dynamic Process property name of ‘DPP_SOURCE_BRANCH_NAME’
[False] [Branch 1] Stop Step

This step ends branch 1 as DPP_SOURCE_BRANCH_ID is populated, therefore no querying is required.

[Branch 1] Process Call l - [UTILITY] Query Branch (by DPP_BRANCH_NAME)

This step calls the modular process [UTILITY] Query Branch (by DPP_BRANCH_NAME). See the Create Branch documentation to see the specific configuration for this process.

[Branch 1] Set Properties - Set DPP_SOURCE_BRANCH_ID

This step takes the returned ID from the process [UTILITY] Query Branch (by DPP_BRANCH_NAME) and stores the ID into the Dynamic Process Property - DPP_SOURCE_BRANCH_ID.

  • Dynamic Process Property - DPP_SOURCE_BRANCH_ID = XML Profile - Branch Query Response - @id (QueryResult/result/@id)
[Branch 1] Stop Step

This step marks the end of branch 1.

[Branch 2] Decision - DPP_DESTINATION_BRANCH_ID Empty?

This step determines if the first branch is necessary. The Boomi Enterprise Platform API requires that a Branch ID be specified, though by adding some extra logic, we can allow for the branch name to be given, adding an extra few steps to query for the ID. If the Dynamic Process Property, DPP_DESTINATION_BRANCH_NAME is empty then it is assumed that the Source Branch’s name was given.

  • First Value - Dynamic Process property name of ‘DPP_DESTINATION_BRANCH_ID’
  • Comparison - Equal To
  • Static value of ‘’
[True] [Branch 2] Set Properties - Set DPP_BRANCH_NAME = DPP_DESTINATION_BRANCH_NAME

This step is necessary as the modular process we will be calling to query the branch ID based on the Branch name assumes the Dynamic Process Property: DPP_BRANCH_NAME will be given. 

  • Dynamic Process Property - DPP_BRANCH_NAME = Dynamic Process property name of ‘DPP_DESTINATION_BRANCH_NAME’
[False] [Branch 2] Stop Step

This step ends branch 1 as DPP_DESTINATION_BRANCH_ID is populated, therefore no querying is required.

[Branch 2] Process Call l - [UTILITY] Query Branch (by DPP_BRANCH_NAME)

This step calls the modular process [UTILITY] Query Branch (by DPP_BRANCH_NAME). See the Create Branch documentation to see the specific configuration for this process.

[Branch 2] Set Properties - Set DPP_SOURCE_BRANCH_ID

This step takes the returned ID from the process [UTILITY] Query Branch (by DPP_BRANCH_NAME) and stores the ID into the Dynamic Process Property - DPP_SOURCE_BRANCH_ID.

  • Dynamic Process Property - DPP_DESTINATION_BRANCH_ID = XML Profile - Branch Query Response - @id (QueryResult/result/@id)
[Branch 2] Stop Step

This step marks the end of branch 2.

[Branch 3] Message - Construct Create Request

This step builds the XML profile that will be sent to the Boomi Enterprise Platform API to create the merge request.

  • Message - 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<bns:MergeRequest xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" sourceBranchId="{1}" destinationBranchId="{2}" strategy="OVERRIDE" priorityBranch="SOURCE"/>
  • Variables - 
    • {1} - Dynamic Process property name of ‘DPP_SOURCE_BRANCH_ID’
    • {2} - Dynamic Process property name of ‘DPP_DESTINATION_BRANCH_ID’
[Branch 3] REST Client

This step takes the newly created XML payload and sends it to the Boomi Enterprise Platform API creating the Merge Request.

  • Connection - Boomi Enterprise Platform API
  • Action - POST
  • Operation - Create Merge Request
    • Path - /MergeRequest
[Branch 3] Return Documents

Once the Merge Request is created, the Boomi Enterprise Platform API returns an ID that will be used later on in the main process. This return documents step passes the document containing that ID back to the process that called it.

[Branch 2] Process Call - [UTILITY] Execute MergeRequest (by DPP_MERGE_REQUEST_ID)

This step calls the modular process [UTILITY] Execute MergeRequest (by DPP_MERGE_REQUEST_ID). Configuration steps are as follows:

Start Step - Data Passthrough

This step is configured as a data passthrough to allow for the process document to flow through into this sub process.

Set Properties - Set DPP_PATH

The endpoint to merge the branches follows the format of: /MergeRequest/execute/{Merge Request ID}. In order to have the REST Client interact with the endpoint, we will set the path as a Dynamic Process Property to then be referenced as a Dynamic Operation Property in the REST Client step.

  • Dynamic Process Property - DPP_PATH = Static value of ‘/MergeRequest/execute/’ + Dynamic Process property name of ‘DPP_MERGE_REQUEST_ID’
Message - Construct Execute Request

This step creates the XML payload that will be sent to the Boomi Enterprise Platform API, merging the specified branches.

  • Message - 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<bns:MergeRequest xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="{1}" mergeRequestAction="MERGE">

</bns:MergeRequest>
  • Variables - 
    • {1} - Dynamic Process property name of ‘DPP_MERGE_REQUEST_ID’
REST Client

This step sends the XML payload to the Boomi Enterprise Platform API and merges the specified branches.

  • Connection - Boomi Enterprise Platform API
  • Action - POST
  • Operation - The operation is an intentionally non configured post operation, the path is set in the Dynamic Operation Properties
  • Dynamic Operation Properties - 
    • Path - Dynamic Process property name of ‘DPP_PATH’
Return Documents

This step marks the end of the sub process and passes the document back into the main process.

Return Documents

At this point in time, the Merge Request has been executed merging the two branches, the document can be returned to whatever system initiated this Merge Branch process