Boomi Code Search – Leveraging Atomsphere API

The Boomi Atomsphere API

If you like me would like to search though all your Boomi components for a certain text, the choice is very straightforward, because there is only one.

You have to code it yourself.

For this and many other uses, Boomi has their Atomsphere API, which does indeed expose quite a lot of functionality, but not quite as much as you might want.

Possible uses of the api:

• Search code for text
• Test code for known coding issues with external tools
• Start execution of processes
• Query a specific process execution for its results
• …….

Boomi does have a relatively thorough documentation of their API here, but the learningcurve from day 0 until you have a working (and useful) solution can be steep as this is mainly a list of the different Boomi objects with all their attributes. If you know every nook and cranny of Boomi, the object-names may be obvious, but to everybody else they may not be obvious.

On this page, there is a “Getting started with the API” which does help a little, but it could have helped a little more. This page gives a little more help to get started, but still not enough in my opinion.

There are two ways to use the AtomsphereAPI. From a Boomi process, you can use a special connector to the api (which does not require a separate license, but does have some usage limits), but you can also call the API using a REST technique from any programming language (same usage limits apply). When using the Boomi connector, it actually handles some tasks for you automatically, that you will have to code yourself, if you choose the REST approach (two of which are the use of API token in stead of password and the automatic fetching of all pages when Boomi returns a paged result).

In my case, I initially thought that it would be much easier to do it in a boomi process (Boomi is easy, you know), but when I finally made it work, my solution was neither flexible, easy to understand or easy to use. But at that time I had at least learned to understand the API well enough to make it reasonable easy to implement it in C#.

In retrospect, I guess that what you need to consider first, is if your quest is a typical GUI task or if it is a commandline-task. Use Boomi for the latter and otherwise the REST API.

For my C# “Search all current Boomi objects for a given text”, I identified the following main tasks:

1. Authenticate to Boomi
2. Finding the Boomi object(s) in the API list that you want to query
   • Be aware, that many tasks may require you to query multiple objects – using output from one to query the other.
3. Construct the URL to call
4. Find out how to make a call to that object (what is the format of the request)
5. Handle paging
6. Interpret the response (what is the format)

---

Authenticate to Boomi

To authenticate to boomi, you need a user who has access to the Boomi account.

Since the account can be used in several programs to access the Boomi API, they recommend, that you create and use a service account for this (a normal account, specifically created to access the API, and possibly with fewer privileges on Boomi)

Whichever user you use, you will need to provide some kind of password as well. You can use either:

• a standard password (the one normally used to log on to the Boomi platform)
• an API Token

For several reasons, Boomi recommends to only use API tokens to access the API:

• You may not want to change you password every time you suspect you ought to do it.
• An API token, is an automatically created unintelligeble string that can be easily created and (not at least)revoked.
• You can create up to 5 API tokens for each user account (where each token can be used for a separate purpose)

To authenticate to Boomi in the REST call, you simply use BASIC authentication, passing the base64 encoded concatenation of username and password – separated by a colon.

If you want to use an api-token instead of password, the username should be prepended with “BOOMI_TOKEN.” and then just use the token in stead of the password.

Finding Boomi objects

For this task, it is relatively easy to find the relevant objects. From the previously linked list over API objects, two of them seem reasonable:

• Component Metadata
• Component

where  you use the Component Metadata API to fetch a list of selected metadata for the components and afterwards use the Component API to fetch the actual content of each component together with all metadata.

Construct the URL to call

The base URL for calls to Boomi Atomsphere API is:

https://api.boomi.com/api/rest/v1/accountID/

where accountID is the ID of the authenticating account.

You can find the authenticating account  in the URL where you log on to the Boomi Platform.

Find out how to use the two apis

There are two different ways of calling the Component Metadata API. Using a GET call, you can get the metadata for a single component, but to query for multiple components, you need to make a POST call passing along some query parameters.

Query for a single component

Send an HTTP GET to:

https://api.boomi.com/api/rest/v1/accountID/ComponentMetadata/componentId

where accountId is the ID of the authenticating account for the request and componentId is the exact ID of the component you are attempting to GET.

Response

 <ComponentMetadata componentId="" version="" name="" type="" subType="" createdDate="" createdBy="" modifiedDate="" modifiedBy="" deleted="" currentVersion="" folderName="" folderId="" copiedFromComponentId="" copiedFromComponentVersion=""/> </ComponentMetadata>

Query for multiple components

Send an HTTP POST to:

https://api.boomi.com/api/rest/v1/accountId/ComponentMetadata/query

where accountId is the ID of the authenticating account for the request.

XML request:

<QueryConfig xmlns="http://api.platform.boomi.com/">
  <QueryFilter>
    <expression operator="and" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GroupingExpression">
        <nestedExpression operator="EQUALS" property="componentId"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleExpression">
           <argument>456789a-bcde-f0123-4567-89abcdef012</argument>
        </nestedExpression>
    </expression>
  </QueryFilter>
</QueryConfig>

Response

xxxx