Getting Started with the TIBCO Cloud Integration - Connect Documentation Tool

One of the hardest and most time consuming parts of building and maintaining a migration or integration solution is providing accurate documentation. To help with this problem, we have released a documentation tool using Google Docs. With this tool, you can quickly and easily generate documentation all of your integrations. It produces a report that includes data about the TIBCO Cloud Integration organization, connections used and metadata from your solution, including filters, related entities, and field mappings for each map in the solution.

Benefits of the Documentation Tool

There are many potential use-cases for this tool. Here are some examples where the documentation tool would save significant time and/or effort:

• Project Documentation ? Create detailed documentation of an integration to demonstrate your progress or use as a final description of the work that you delivered (great for your boss or your client).
• Version Control ? Compare saved reports to find differences between solutions and maps over time.
• Branding and Customization ? Customize the report output to match your company image. You can change colors/backgrounds, add a company logo and more.
• Integration Maintenance ? Once your integration is up and running, you may need to change mappings. With this tool you can document your solution and quickly find all of the places where changes need to be made.

Enable API Access

Now that you have an idea of what the tool can do for you, let?s take a look at how to get started using it. Following the instructions on the Developer Portal, you can quickly set up the documentation tool to work with your organization(s).

The first step is to enable API access to your organization(s). For each organization where you will want to use the documentation tool, simply go to the More > Security menu and look at the rules under the Security page. Click on the add button (+) and edit the new rule to give it a name, check off the API Access checkbox and add the following IP range:

Once you?ve added the rule, it may take a few minutes to take effect in the documentation tool.

Using the Documentation Tool

Note: This set of instructions assumes you are in the AWS US East (N. Virginia) region. If your organization is in a different region or data center, see the documentation on the Developer Portal for information on updating the region in the Documentation tool. 

The next step is to save a copy to your own Google Docs environment. Go to the Scribe Labs ? Google Docs ? Documentation Tool link from your Google account. Then click File > Make a Copy and save it. Once you have saved a copy, please close the Scribe Labs copy so that it is not changed.

Now we have to connect to your TIBCO Cloud Integration account from the tool. Click on Scribe > Solution Documentation in the Google Docs menu. The first time you run it, you may get a pop-up asking for authorization. If you see that, click the Continue button and then the Allow button on the following screen.

You should now see the TIBCO Cloud Integration login from your Google Docs screen:

Then enter in your TIBCO Cloud Integration username and password and hit Submit. This will connect to your TIBCO Cloud Integration user account. Once the tool loads your account, select the organization and solution you wish to document:

Finally, hit the Submit button again and it will begin documenting. Once the tool starts to run close the login window and you can watch the report being updated in real time.

Upon completion, the first thing you should see is a tab called ?Org Details?. This tab will have information on the selected Organization in TIBCO Cloud Integration. Next there will also be a tab with information about the solution, including connections, status and scheduling information. Finally, there will be a tab for each map in the solution.

For each map tab, the documentation tool will go through the map and give all the configurations for each block:

You can see on the above sample the steps of the map documented, including mappings.

Extending the Tool

If you have developer resources available, you can also edit the code that runs the tool. From your copy of the documentation tool, simply click on Tools > Script Editor. Here you?ll find the code that runs the documentation tool, and you can make changes as needed. If you want to have a reference into the Scribe Online API, take a look at our Developer Portal. 

First Published  May 02, 2017

Author: Scott Hansen