1. Vladimir Dyuzhev
  2. TransitMap for OSB

Overview

HTTPS SSH

TransitMap: a Utility for Generating Interconnectivity Diagrams for Oracle OSB

Why TransitMap?

It's hard to visualize complex OSB domains.

It's twice as hard to explain the planned or completed changes to people who aren't involved in the project but who need to know: e.g., release management, production support, and other architects.

TransitMap aims to make these tasks just a bit easier by creating an SVG diagram of an OSB domain or a selected subset of it.

The generated diagram is interactive. You can select specific resources to see their connectivity and flow.

PlaygroundAnimated.gif

See it in action! (Unzip and open in a browser)

What is TransitMap?

TransitMap is a standalone Java JAR application, intended to run as part of an OSB build or manually from a command line.

TransitMap supports and maps:

  • Proxies
  • Business services
  • Flows AKA split-joins
  • JMS queues and topics

It uses the d3.js library to generate SVG data-driven graphics.

Currently only OSB 11 is supported, though porting to OSB 12 should be trivial.

Download TransitMap here.

Usage

Generating a Diagram from OSB Sources

IMPORTANT! If you domain has dynamic routes, you may have to add those links to TransitMap manually or via a script. Read the section Mapping Dynamic Routes below.

To generate a diagram of a domain, point TransitMap to an OSB workspace directory (i.e. the source code as checked out from a version control system).

java -jar TransitMap.jar C:\Work\OSB\Workspace\

TransitMap will collect all the resources under the given directory, as well as their static and, in many cases, dynamic links.

The output file will be created in the current directory by default and called TransitMap.html.

Generating Diagram from an OSB Domain (beta)

TransitMap can map an existing domain. Just point it under $DOMAIN_DIR/osb/config/core/:

java -jar TransitMap.jar /srvrs/osb/domains/SFT11/osb/config/core -b

Note the -b flag: it maps the backend services, too (optional).

TransitMapBackends.png

Setting HTML File Name

To save the output HTML file under a different name or location, use the -o (--output) option. It should have a file name as its value.

java -jar TransitMap.jar -o C:\Work\Diagrams\Domain1.html C:\Work\OSB\Workspace\

Mapping a Subset of the Domain

For many documentation purposes, mapping the whole domain isn't necessary. Often only a specific project or a set of resources is sufficient.

To include only some of the found resources in the diagram, use the -i (--include) option. The value is a Java regular expression. If a resource (proxy, business service, etc.) file name matches the expression, it is included in the map.

java -jar TransitMap.jar -i "CustomerProfile.*" C:\Work\OSB\Workspace\

Please note that the value is a regular expression, not a wildcard. The value "any number of any symbols" is written as ".*" (dot-star), not "*" (star).

Here's a (masked) example of a project mapped in isolation:

CustomerProfileExample.png

You can use multiple instances of the -i option.

Excluding a Subset of Resources

Some resources may be redundant and could confuse the overall picture. For example, a DynamicRoute proxy that is used by many other resources should be removed from the map, or it will create a star-like connectivity diagram where it will be hard or impossible to see the actual flow. (Instead, the source and target resources that use the dynamic routing should be connected directly with the help of a script-generated relation file. Please see below under Mapping Dynamic Routes section.).

To exclude a resource or a set of resources, provide an -x (--exclude) option. The value is a Java regular expression. If a resource file name matches the expression, it is removed from the map, along with all links that go to and from the removed resource.

java -jar TransitMap.jar -x "Common/.*Routing.proxy" C:\Work\OSB\Workspace\

You can use multiple instances of the -x option.

Mapping Dynamic Routes

Rarely, a domain only has static routes. Usually at least some of the resources are invoked using dynamically formed routing expressions.

For some domains, all routing is done via a dynamic routing framework, a configuration XQuery that defines which resources call which other resources.

The bad news is that TransitMap can't automatically figure out those dynamic links. Since each team invents its own dynamic routing framework, it isn't possible to support them all in the main TransitMap code.

The good news is that you can help TransitMap to find the dynamic links. You can provide it with the list of dynamic routes as an external JSON relation file, and it will read it and trust it just like it is the sources themselves.

A relation file can be generated by a script. For example, I use a Perl script for our home-brew framework.

Or a file can even be created manually on an ad hoc basis - say, to present a proposed change to a project.

Example

The following relation file will generate a typical store-enrich-forward diagram:

{"name":"Submit/EntryProxy.proxy","uri":"/Submit","title":"/EntryProxy"}
{"name":"Submit/Store.biz","uri":"jms:///cf/StoreAndForwardQueue"}
{"name":"Process/Read.proxy","uri":"jms:///cf/StoreAndForwardQueue"}
{"name":"Process/Parallel.flow"}
{"name":"Process/Enrich.proxy"}
{"name":"Process/Callout.proxy"}
{"name":"Process/Callout.biz"}

{"source":"Submit/EntryProxy.proxy","target":"Submit/Store.biz"}
{"source":"Process/Read.proxy","target":"Process/Parallel.flow"}
{"source":"Process/Parallel.flow","target":"Process/Enrich.proxy"}
{"source":"Process/Parallel.flow","target":"Process/Callout.proxy"}
{"source":"Process/Callout.proxy","target":"Process/Callout.biz"}

Run it:

java -jar TransitMap.jar example.json

The output is:

TransitMapFromJSON.png

Note that JMS resource StoreAndForwardQueue is added by TransitMap. Its project property is the same as the first resource that refers it, in this case "Submit" from Store.biz. I could move it to Process project however by adding it explicitly:

{"name":"StoreAndForwardQueue","project":"Process","type":"jms"}

This extra line moves the queue:

TransitMapFromJSON2.png

(In fact, there is a bug: the StoreAndForwardQueue should be spelled simply as

{"name":"StoreAndForwardQueue.jms","project":"Process"}

but that did not work. I will try and fix it soon.)

Passing Relation Files to TransitMap

TransitMap takes relation files as arguments, just like it takes a source directory:

java -jar TransitMap.jar C:\Work\OSB\Workspace\ C:\Work\OSB\Workspace\dynamic-routing.json

Adding a Dynamic Link

To create a link between two resources, add a JSON object into a relation file:

{"source":"Foo/Bar/Baz.proxy","target":"Foo/Bar/Bak.biz"}

Note: each JSON record must be on its own line.

The source and target properties are full paths to the resources in the source tree. It is important that the file names have the following extensions:

  • *.proxy is a reference to a proxy service
  • *.biz is a reference to a business service
  • *.flow is a reference to a flow (aka split-join)
  • *.jms is a reference to an (external to OSB) JMS queue or topic resource

Adding a New Resource

To add a resource, place a JSON object describing that resource into a relation file:

{"name":"Foo/Bar/Baz.proxy","project":"Foo","type":"proxy","uri":"/Services/Baz"}

Only the name property is mandatory. Just as for link's source and target, it is a full file name with an extension.

The project property defines what stripe the resource is placed into on the diagram. All resources belonging to the same project are placed into the same stripe. If project is not defined, it is inferred from the file name, i.e., it's the first component of the name.

The type property defines how the resource is drawn. Proxies ("proxy") are drawn as regular boxes, business services ("biz") as triangles, flows ("flow") as multi-boxes and JMS queues ("jms") as ovals. If the value is not provided, the type is inferred from the file name extension.

The uri property is currently used only for proxies. It's value is showb next to HTTP entry proxies. There could be future uses for it for business services and other resource types, so feel free to provide it, if the value is known.

The same resource or link can be found multiple times in a relation file. Duplicate links (i.e., links with the same source and target properties) are just ignored, and for duplicate resources (i.e., resources with the same name property), the later entry overwrites the same values of the previous entry. Duplicate resources, however, keep the values that were in the previous entry but are not found in the later one.

Note: that you do not have to add JMS resources if you have links to them. TransitMap will create them automatically. However, you may want to create them however to set the project property to another value.

Happy Mapping!

Addendum A: All Options TransitMap Supports

When executed with no options or with -h flag:

java -jar TransitMap.jar -h

TransitMap prints all the available options, as shown below:

TransitMap v1.3: An Utility for Generating Inter-Connectivity Diagram for Oracle OSB

Usage:

java -jar TransitMap.jar [-h|--help] (-o|--output) <output> [(-t|--template) <template>] [(-k|--key) <key>] [(-i|--include) <include>] 
  [(-x|--exclude) <exclude>] [dir-or-file1 dir-or-file2 ... dir-or-fileN] [-n|--no-xq] [-r|--related] [-b|--backends]

  [-h|--help]
        Provide this help

  (-o|--output) <output>
        HTML file to generate (default: TransitMap.html)

  [(-t|--template) <template>]
        HTML template instead of standard one (optional)

  [(-k|--key) <key>]
        Key to replace in the HTML template, e.g. -k TRANSIT_MAP_TITLE=PROD_01
        Multiple keys are OK.

  [(-i|--include) <include>]
        Services to include (e.g. to map only selected projects). The value is a
        regular expression. Multiple entries are OK.
        Example: -i CustomerProfile.*

  [(-x|--exclude) <exclude>]
        Services to exclude (e.g. to hide a Dynamic Routing implementations).
        The value is a regular expression. Multiple services are OK.
        Example: -x Common/.*Routing.proxy

  [dir-or-file1 dir-or-file2 ... dir-or-fileN]
        Root directory of OSB configuration in its 11g source form or
        manually- or script-created relation files to process.

  [-n|--no-xq]
        Do not try to find references in embedded XQs (default: do scan embedded
        XQs).

  [-r|--related]
        When using -i, include resources that are directly linked to the
        included ones, even if the linked resources would not be included
        otherwise.

  [-b|--backends]
        Show backend services in the diagram. It is only useful when collecting
        sources from a domain's osb/config/core/ location or if Biz URIs are
        provided in a relation file.