Create custom aggregations

---

Overview

When consulting your results you can choose how your application is displayed using one of the default “perspectives/aggregation modes” available out of the box (depending on the perimeter/scope you choose) - these default modes are explained in User Interface Reference:

However, you may find that these default modes do not meet your requirements for displaying your application data. If so, you can create your own custom aggregation mode and display your objects as you have designed.

How does it work?

An aggregation is essentially a method of grouping specific items together, therefore the creation of a custom aggregation involves creating custom nodes that group together specific object types (or a mix of object types). When you choose to display your application using the custom aggregation mode, the items in your application are grouped into the custom nodes defined in your custom aggregation.

For example a custom aggregation has been created containing three custom nodes:

• Java classes
• Java methods
• SQL objects (any type)

This aggregation has then been applied to this example and simple client/server Java/SQL application:

Two ways to create a custom aggregation

When you create a custom aggregation you can choose between two creation modes, which differ in how the links between your custom nodes are handled:

• Map the real architecture - CAST Imaging calculates and draws the actual dependencies between your custom nodes for you, based on the relationships found in the code. This is the behaviour described throughout this page and the only behaviour available in previous releases. Use this mode to understand and document how the system is built today.
• Define & validate your target architecture - no links are calculated for you. Instead you draw the links you allow between your custom nodes, then validate the aggregation to compare your design against the code: allowed links are shown in green and violations in red. Use this mode when you have a target architecture in mind and want to find out where reality diverges from it.

Both modes use the same process for creating nodes, publishing, sharing and editing - see Step-by-step instructions below. The differences are described in Step 1, Step 2b and Step 2c.

Dynamic custom aggregations

Custom aggregations are dynamic - this means that the objects they display will automatically update when the application is re-analyzed and new objects are identified. For example, if the custom aggregation contains a custom node that captures Java Methods and the application is re-analyzed and new Java Methods are identified, then these objects will be automatically displayed in the custom aggregation. This behaviour was not present in previous releases (i.e. the custom aggregation remained static and was never updated with new objects identified in a new analysis).

Things to know about custom aggregations

• Custom aggregations are application specific. In other words, a custom aggregation will only be available for the specific application it was created in.
• Any user that has permission to view results in the application the custom aggregation was created in will be able to use the custom aggregation by default as soon as it is published, however, by default only the user that created the custom aggregation will be able to modify it. Edit access can be granted to additional users/groups using the Share button.
• Available in ≥ 3.6.6-funcrel
  A custom aggregation created using the Define & validate your target architecture creation mode cannot be published until it has been validated. If you close the aggregation before publishing it, the authorization links you have drawn are retained when you reopen it, but the links found in the code are not redisplayed - you will need to validate the aggregation again.
• When using a published custom aggregation, drilling down on a link between aggregated nodes, CAST Imaging will visually group resulting objects to show which aggregated node they belong to:
  • Drill-down objects are grouped visually so users can easily distinguish objects from Custom Node A versus Custom Node B.
  • Group names or labels indicate the parent aggregated node.

Step-by-step instructions

Step 1 - Create the custom aggregation

First ensure you are viewing the application you want to create the custom aggregation mode for, then click the dedicated icon in the header bar:

Then enter a name for the new custom aggregation: this name will be displayed in the left panel and publicly identifies it.

You are then asked to pick a starting point: choose the creation mode you want to use and click Continue:

• Map the real architecture - continue at Step 2 and work through the remaining steps as described below.
• Define & validate your target architecture - continue at Step 2 to add your custom nodes, then complete Step 2b and Step 2c before publishing.

When the aggregation has been created, you can then start adding your custom nodes.

Step 2 - Adding custom nodes

To add a custom node, click either of the Custom object icons:

A window will open displaying a list of all the objects in your application: use the filter options at the top of the screen to find the objects that you want to group in the custom node:

In this example we want the node to contain only Java Method object types, so we can use the Object type filter:

Click Save in the bottom right corner of the window to ensure the choice is applied and choose a name for the custom node:

The new custom node is then displayed:

Repeat this process until you have added all the custom nodes you require.

You can also clone any custom nodes you have added, to help speed up the configuration process - right click the custom node and select Clone:

Any links between nodes will be displayed as shown in the example below:

Step 2a - Adding Tags/Post-its to custom nodes

Tags/Post-its can be added to any custom node using the toolbar within the custom aggregation editor. Added Tags/Post-Its persist after the aggregation is saved and will appear in search and filter options where applicable.

Step 2b - Add the authorization links

In this mode, CAST Imaging does not calculate or display any links between your custom nodes when you add them: the aggregation deliberately shows the nodes on their own, so that you can state the design you expect before comparing it against the code.

Enable the Add authorization links toggle, then draw a link between two custom nodes to declare it. Each link you draw is an authorization link - a relationship that your target architecture allows:

• you can define as many authorization links as you need, but only one link between any given pair of custom nodes
• an authorization link describes your intended design rather than something found in the code, therefore it cannot be drilled down into
• an authorization link can be removed if you change your mind

Step 2c - Validate the aggregation

When you have drawn all your authorization links, click Validate Aggregation. CAST Imaging then compares the relationships found in the code against the links you have authorized. You cannot publish the aggregation until this has been done - until then the Publish option is disabled and displays the message Validate the aggregation before publishing:

The result of the validation is displayed using colour, and the Link Types section of the right panel explains what each colour means:

• Allowed - shown in green. A link exists in the code between two custom nodes and it complies with the rules you defined, in other words it matches one of your authorization links. This relationship is expected as per your design.
• Violation - shown in red. A link exists in the code between two custom nodes but it breaks a rule you defined, in other words no authorization link has been defined for it. Violations are grouped as escalated links.

Both types of link can be ungrouped or drilled down into to see the underlying object level links they represent.

Two further points to be aware of:

• shared links are excluded from the validation checks and continue to be displayed as normal links.
• while the aggregation remains unpublished, you can add further authorization links and validate it again.

When you publish the aggregation, all objects and links are displayed as they are in build mode, including the colour coding. The exception is shared links, which continue to appear in build mode only.

Step 3 - Publish the custom aggregation

Before users can use the custom aggregation you will need to publish it:

This will make it available as a scope in the left-panel for all users that have permissions to view the application.

You can also access your custom aggregations direct from the Overview/Welcome page:

If the custom aggregation was created using the Define & validate your target architecture creation mode, the Publish option is not available until the aggregation has been validated - see Step 2c.

Step 4 - Share the custom aggregation

Initially the custom aggregation can only be edited by the user that created it. Therefore if you would like other users to be able to modify it, use the Collaborate button:

Step 5 - Editing/cloning existing custom aggregations

To edit an existing custom aggregation, ensure it is not in “published” mode:

You can:

• rename the custom aggregation
• delete the custom aggregation
• add new or remove/edit existing nodes

You can clone an existing custom aggregation to help speed up the process of creating a new one: