andy_tillo952264

Boomi Flow and GetGuru: How to Flow your Knowledge through AtomSphere and Back Again!

Blog Post created by andy_tillo952264 Employee on Oct 3, 2017

Today we had a call around GetGuru and how we could use it internally. GetGuru is a knowledge management solution that we've been trying to enable easier use/context around. I heard that it had an API we could hook into, so I thought this a perfect situation to try to tie our frontend (Boomi Flow) to a backend piece from GetGuru. In this post we'll show you how to add new knowledge cards to your GetGuru environment by way of Boomi Flow and AtomSphere!

 

 

The Big Idea

Ok, so here's what we're trying to do here:

  1. Create a Boomi Flow to present a UI to enter information to create a new Guru card.
  2. Upon submission, the Flow invokes an AtomSphere integration process using the Flow Service Listener connector.
  3. The process uses the HTTP Client connector to call a Guru API to create the card.

 

Ready? Let's get started!

 

Setting Up Postman

To help understand the GetGuru API, grab some internal IDs to use later, and create some sample request and response data to assist with importing Profiles in AtomSphere, a great utility to use is Postman. Postman acts as a middle-man and can see all the data as to where it is going, and what response it wants it in.

 

So…we can deduce what to send from this: https://help.getguru.com/articles/7ideXKXi-Creating-Cards

 

Specifically this:

getguru says this:

 

Postman is a great place to start, as you know what to enter in each of those because of two things:

  1. The very first page of GetGuru says this: https://help.getguru.com/articles/XipkRKLi-Guru-API-Overview
    To test your authentication credentials, you can use the curl command line tool.
    curl -u USER:TOKEN https://api.getguru.com/api/v1/teams -D -

If your credentials were correct, you should receive a response that lists information about your Guru team:

 

HTTP/1.1 200 OK
Content-Type: application/json

 

[ {
 "status" : "ACTIVE",
 "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "dateCreated" : "2016-01-01T00:00:00.000+0000",
 "name" : "My Guru Team"
}]

 

To validate you’re able to send, use curl:

 

C:\curl\src>curl -u andytillo+getguru@boomi.com:84fd3d22-703c-4c18-aad2-623841ddc31d https://api.getguru.com/api/v1/teams -D -

HTTP/1.1 200 OK

Content-Type: application/json

Server: Jetty(9.4.1.v20170120)

transfer-encoding: chunked

Connection: keep-alive

 

[ {

 "status" : "ACTIVE",

 "id" : "d50be168-8e81-48c9-8306-6d4eea484ef3",

 "dateCreated" : "2017-09-14T02:20:08.197+0000",

 "totalUsers" : 1,

 "profilePicUrl" : "https://assets.getguru.com/photo-1442876906995-6761040d1f0b.jpg",

 "name" : "FlowTest"

} ]

 

C:\curl\src>curl -u andytillo+getguru@boomi.com:84fd3d22-703c-4c18-aad2-623841ddc31d https://api.getguru.com/api/v1/boards

[ {

 "lastModified" : "2017-09-15T02:41:39.176+0000",

 "id" : "81d55e9c-3922-46cf-be89-877477e6f3ca",

 "collection" : {

   "id" : "c576da5d-80d1-4606-9543-7da62ee13421",

   "name" : "General"

 },

 "lastModifiedBy" : {

   "status" : "ACTIVE",

   "email" : "andytillo+getguru@boomi.com",

   "firstName" : "Andy",

   "lastName" : "Tillo"

 },

 

So now we know the BoardID and the CollectionID that GetGuru says we need to have to make a call, as well as what GetGuru WANTS to receive, in JSON format, we can deduce that we can copy that GetGuru snippet, and save it to a .JSON file on your desktop. Call it Getguru_WANTS_THIS_INPUT.JSON.

 

The file should look like this:

 

{

 "preferredPhrase": "What _I_need",

 "content": "content_goes_here",

 "shareStatus": "TEAM",

 "collection" : { "id" : "c576da5d-80d1-4606-9543-7da62ee13421" },

 "boards": [{"id" : "81d55e9c-3922-46cf-be89-877477e6f3ca"}]

}

A little tip: You can put whatever you want in between the “” --Boomi takes that out and just uses the skeleton of what is in there!

 

Setting up AtomSphere

Now make that code map INTO the HTTP client header here:

 

Opening that link up looks like this (we’ll talk about the left side later on):

 

To get the data on that right side, click “choose” (make sure dropdown is JSON):

 

Import:

 

Now you can map the fields like this (cause it knows the JSON format now):

 

Now send it on to the HTTP Client connector:

 

Here's the HTTP Client Connection:

 

And the HTTP Client Operation (note all you have to change is the JSON input header):

 

Now it’s going to come OUT of the HTTP connector (from GetGuru) with a bunch of new stuff! Conveniently, stuff we saw when we ran the Postman query at the beginning, remember?

 

So all that stuff below, is what the RESPONSE from GetGuru is sending back, ergo, we can now copy that whole bunch of text there, and do the same thing we did with the first map. It’s now a sample of what we want to get OUT and eventually send back to Flow! Copy/Paste it all into a new JSON profile with “Import” the same way as before, and open the next map:

 

Now, again, do the same mapping dragging/dropping exercise! But this time, with that OUTPUT from GetGuru, and map it BACK to what we originally were LISTENING for from Flow:

 

So this is the part where we talk about that piece I said we’d talk about later --The first shape, the LISTENER. Because that is ultimately what we’re mapping BACK to. We LISTEN for Flow to send us something, and then take that data and push it through the HTTP Client connector, and ultimately back to Flow with the same variables as we requested in the first place.

 

Don’t forget this little guy (return documents), he’s important:

 

Here’s what the Start shape config looks like (the LISTENER):

 

Click the pencil in “operation” and it’ll show you this:

 

These guys are just saying “LISTEN” for a request (profile). It’s just sitting there, waiting for Flow to talk to it. When it receives something, it starts its business. Here’s that first listener call:

 

(We’ll show how we get those variables in the next section, let’s finish up with this one first.)

 

The RESPONSE PROFILE: “Give this back to Mwho” is a set of variables that you’re telling Flow to keep an eye out for, cause they’ll be coming back to you --notice they are the EXACTLY SAME SPELLING as the last Map Shape that we tied them to --don’t mess that one up, or you’ll be banging your head for a while! 

 

NOTE: In order to get response back from AtomSphere the Output Names in Message Action must match the Response Profile Names from AtomSphere Listener.

If any changes are made to the profiles in the AtomSphere Flow Listener process then you must update/refresh the Boomi flow service associated with that Process.

 

 

Then DEPLOY that process:

 

And deploy the Flow Service that ties that action to your Process:

 

So as everything is tied up on the AtomSphere side, let’s go see what we set up in Flow…

 

Setting up Flow

It’s a very simple flow to create in Flow. (Or if you want to take the easy way out, get the Flow config from the attached JSON file below!)

 

The first thing you want to do is import that AtomSphere connector in your tenant. Click Services-->Install Service.

 

Call it whatever you want, and the URL is based on the Flow Service setup in AtomSphere:

 

You get the first part of your URL from AtomSphere-->Manage→:

 

You get the second part of your URL for the Service in AtomSphere from the Flow Service here:

 

You get your username and password from AtomSphere-->Manage→[Atom of choice]-->Shared Web Server:

 

Once you enter that info, click “Save Service”:

 

Now we’re cookin’! You have mapped AtomSphere to Flow, and Flow to AtomSphere now!

 

Go back to your Flow and click (or make) the first page component:

 

Edit page layout. Notice you’re just mapping components now:

 

Create each component as an “input” with your choice of variable name (type: string) on the right side:

 

The magic comes in when you click (or create) the “send to getguru” button. This is where the magic happens!

 

Note: Prior to that, you may need to setup the “New message service” and choose your service:

 

OTHER NOTE: if you DON’T see your service in there, Navigate to Shared Elements at the top right corner to import it:

 

 

Now, back to the message config we were talking about:

 

Notice how the INPUTS are the same name as the REQUEST PROFILE in AtomSphere:

 

Then note how the OUTPUTS are the same as the RESPONSE profile in AtomSphere LISTENER process; convenient, huh?

 

These need to be spelled EXACTLY the same, don’t forget that --these are the magic sauce! Note the VALUE names on the OUTPUTs --these are what we’re going to be calling in the last STEP shape in Flow, to show the user after it’s gone through the pipe!

 

The final step is just showing back to the page, those variables that you captured in the OUTPUT section:

 

We’re done! Now let’s see how it works. Publishing/running the flow looks like this:

 

...and when we hit “send” it looks like this:

 

Bada boom, you just made a card in GetGuru.com via Flow and Boomi!

Extra Credit

A trick of the trade (or a test of your skills of what you’ve learned) --you now have the CardID that was given back to you up above:

CardID: d9206c70-22bb-4fcc-90c7-1d8d72ce15f9

 

You can navigate directly to a card like this: https://app.getguru.com/#/facts/<CARD_ID_HERE>. How can you concatenate some strings together to show the user a link like that, instead of just a Card ID?

 

Andy Tillo is a Boomi Sales Engineer for the Boomi Flow product based in Seattle, WA. I come from an infrastructure background, so it is nice to have something more code-based to sink my teeth into! Boomi Flow has been a great platform to get there!

Attachments

Outcomes