Skip to main content

Workflows

In Tangram Pro™, Workflows are created in Component Implementation Workspaces. Workflows are series of tasks run against Component Implementations to generate Component Software Interfaces, documentation, and assurance artifacts.

Create a Workflow#

Component Workflows are built by configuring and connecting Plugins in the Tangram Pro™ UI. Workflows can be run manually by clicking the Run Workflow button or automatically with Webhooks to your source code repositories.

How to build a Workflow#

  1. Add a new workflow in a Component Implementation Workspace
  2. Add Subcomponent Workflows and Plugins to the Workflow Tree as Tasks
  3. Order Tasks and create dependencies in the Workflow Tree
  4. Click Save Changes

The Workflow is saved and can be run manually or triggered by a Webhook.

Step One: Add a New Workflow#

Adding a new workflow is a simple process in the Workflow section of a Component Implementation Workspace. Workflows require a name and can have a description added.

Image92

How to add a new Workflow in Tangram Pro™#

  1. Open a Component Implementation Workspace and click on the Workflows Icon in the menu
  2. Click +New Workflow
  3. Enter a Workflow Name and Details
  4. Click Create Workflow

The new Workflow is created and listed in the Workflows Panel.

Now that your Workflow exists you can start adding and configuring tasks.

Step Two: Add Workflow Tasks#

Workflows require at least one Task before they can be run. New Workflow tasks can be created by adding Plugins to the Workflow Tree. If any of the subcomponents in the Implementation have their own Workflows, those Workflows can also be included as a task.

Image93

PLUGINS are third-party tools provided in Tangram Pro™ to configure and use as workflow Task. Check out the Plugins section to learn more about the tools available for use.

How to add tasks to a Workflow#

  1. Click on the Workflow Name
  2. Click Add Tasks or the Edit Icon at the top of the panel
  3. Click on a subcomponent Workflow or plugin you wish to add to the Workflow, then drag it into the Workflow Tree space and drop it there. If a plugin is chosen, update its configuration.
  4. Repeat Step 4 until all desired tasks have been added, then click Save Changes

The Workflow is saved and is ready to be run.

Image94

Plugin Configuration#

Each plugin in Tangram Pro™ has unique configuration options. You can open plugin configuration options and edit them for your specific use by clicking a Setting Gear Icon on its task in the Workflow Tree.

Image95

Step Three: Manage Workflow Trees#

Unless otherwise specified, workflow tasks are run in parallel. The Workflow Tree allows users to reposition tasks and create Dependencies to specify the order in which tasks are run in a workflow.

The Workflow Tree displays of all the tasks in a workflow and the dependencies between them. Dependencies specify the order in which each task will be run, and which tasks need to be completed before others can begin.

How to create dependencies in Workflow Trees#

  1. Add at least two Tasks to a Workflow Tree
  2. Click on the Dependency Icon for the first Task to run
  3. Click on the list item for the task to run next
  4. Repeat Steps 2 and 3 until you have completed ordering your tasks, then click Save Changes

A Dependency Line is created between the tasks in the Workflow tree and when run, the Workflow will follow the prescribed path.

Image96

Tasks may have multiple dependencies or be dependent on multiple other tasks. Creating dependencies specifies the order that tasks will be run when a workflow is triggered. All of a task's dependencies must complete before that task can begin running.

How to remove dependencies from Workflow Trees#

  1. Hover over a Dependency Line
  2. Click X, then click Save Changes

The dependency is removed immediately.

Image97

Edit a Workflow#

Tasks in a Workflow Tree can be updated and removed using the task's Setting Gear Icon.

How to update tasks in a Workflow Tree#

  1. Click the Setting Gear Icon on the selected plugin task
  2. Update the task's configuration
  3. Click Done

Changes to the task's configuration are applied to the Workflow.

How to remove tasks from a Workflow Tree#

  1. Click the Setting Gear Icon on a plugin task
  2. Click the Delete Button

The task is removed from the Workflow.

Image98

Webhooks#

Tangram Pro™ Workflows can be run automatically through integrations with GitHub, GitLab, and Bitbucket repositories. Users can create Webhooks for each Workflow to trigger a new run each time a Push is made to a repository.

Webhooks can be added to and removed from an existing Workflow in the Workflow Panel. Creating a Webhook requires navigating between the platform's site and Tangram Pro™..

How to add a Webhook to a Workflow#

  1. Click on the Add Webhook button for a Workflow
  2. Select a platform, then enter a branch or tag name for triggering the Workflow and click Next
  3. Navigate to your Platform's site and set up the Webhook using the URL and Secret provided by Tangram Pro™
  4. Return to Tangram Pro™ and click Finish and Close

The Webhook is now active and will trigger a Workflow run as configured.

Entering a branch or tag name is optional. If no branch or tag name is specified, the Workflow will be triggered with every PUSH event.

By default, a Webhook will trigger a Workflow run every time code is pushed to the connected repository. Tangram Pro™ provides the option to specify when a trigger should run. To use this feature, simply type the name of the repository tag or branch that should be used to trigger a Workflow.

Specifying a branch or tag is optional. Leave the field blank if no specification is desired.

Image99

Wildcard Characters#

Tangram Pro™ supports the use of wildcard characters when specifying a tag for triggering a Workflow.

A WILDCARD is a placeholder character that makes a tag more extensible. It is represented by an asterisk (*) and allows multiple tags to trigger the same Workflow.

Using the wildcard character creates a more generic tag. For example, a tag like 1.1.* will trigger a workflow run for any tag that begins with 1.1. Webhook tags specified without a wildcard character will only be triggered when a PUSH is made using the exact tag.

GitHub Webhooks#

Tangram Pro™ Workflows can be triggered by PUSH events from GitHub.com and GitHub Enterprise repositories. The setup is nearly identical for the two platforms.

How to set up a GitHub.com repository Webhook#

  1. Navigate to a GitHub.com repository and click Settings
  2. Select Webhooks and click Add Webhook
  3. Paste the URL and Secret from Tangram Pro™ into the Payload URL and Secret fields
  4. Set the Content Type to application/json
  5. Click Add Webhook
  6. Return to Tangram Pro™ to complete setup

How to set up a GitHub Enterprise repository Webhook#

  1. Navigate to a GitHub Enterprise repository and click Settings
  2. Select Hooks and click Add Webhook
  3. Paste the URL and Secret from Tangram Pro™ into the Payload URL and Secret fields
  4. Set the Content Type to application/json
  5. Click Add Webhook
  6. Return to Tangram Pro™ to complete setup

GitLab Webhooks#

Tangram Pro™ Workflows also support Webhooks to GitLab.com and GitLab Enterprise projects. The setup is the same for both platforms.

How to set up a GitLab repository Webhook#

  1. Navigate to a GitLab project and hover over Settings
  2. Click on Integrations
  3. Paste the URL and Secret provided by Tangram Pro™ into the URL and Secret Token fields
  4. Click Add Webhook
  5. Return to Tangram Pro™ to complete setup

Bitbucket Webhooks#

Bitbucket repositories can also be integrated with Tangram Pro™ to trigger Workflows. Bitbucket.com and Bitbucket Enterprise have slightly different configuration needs.

How to set up a Bitbucket.com repository Webhook#

  1. Navigate to a Bitbucket.com repository and click Settings
  2. Select Webhooks and click Add Webhook
  3. Name the Webhook and paste the URL provided by Tangram Pro™ into the URL field
  4. Click Save
  5. Return to Tangram Pro™ to complete setup

How to set up a Bitbucket Enterprise repository Webhook#

  1. Navigate to a Bitbucket Enterprise repository and click Repository Settings
  2. Select Webhooks and click Create Webhook
  3. Name the Webhook and paste the URL and Secret from Tangram Pro™ into the URL and Secret fields
  4. Click Create
  5. Return to Tangram Pro™ to complete setup

Run a Workflow#

It's easy to run a Workflow in Tangram Pro™.

How to run a Workflow manually#

  1. Open the Workspace for a component and click on the Workflows Icon
  2. Click on the Workflow you wish to run
  3. Click Run

The Workflow will begin running. A new job is added to its Jobs list and the status of each task is shown on screen.

Image100

Workflow Jobs#

Clicking on a Workflow Name opens its Details Page where the Workflow can be managed and run manually. Each Workflow run creates a new Job which shows the status of each task and, when complete, provides ways to view and download Workflow output.

WORKFLOWS are a sequence of tasks run against components.

A JOB is an execution or running of a workflow.

Statuses and outputs are accessible for all current and past Workflow runs in Tangram Pro™.

Image101

Workflow Outputs#

Each task in a Workflow provides a different set of outputs. Every task has a Log which can be viewed in Tangram Pro™ and download to a local machine, and Artifacts which can be downloaded as a .tar file. Some Workflow tasks also provide Results which, like logs, can be viewed in Tangram Pro™ and downloaded to a local machine.

The type of outputs available for a task are specific to the plugin. See the Plugins section to learn more about what Tangram Pro™ offers.

Workflow Logs#

Workflow logs can be viewed for tasks that are currently running and can be viewed and downloaded for tasks that have completed.

How to view and download Workflow logs#

  1. Click on a Workflow to view its Jobs List
  2. Click on an Active or Previous Job list item to view the Workflow Tasks
  3. Click Download Logs to download the log file to a local machine*
note

This feature is only available for tasks that have completed.

Image102

Workflow Artifacts#

Generated Code, CSI, and assurance evidence are output as Workflow artifacts. Users can download artifacts from each task as a .tar file by clicking the Download Artifacts button.

How to download Workflow artifacts#

  1. Click on a Workflow to view its Jobs List
  2. Click on an Active or Previous Job list item to view the Workflow Tasks
  3. Click the Download Artifacts button for a task

Artifacts will be downloaded to your local environment.

Image103

Workflow Plugins#

The Tangram Pro™ Workflow Engine supports the use of various third-party tools and provides custom code generation tools for creating Component Software Interfaces (CSI). Each of these tools function as Plugins that can be added as workflow Tasks.

Code Gen Plugins#

Code Generation Plugins are custom tools built by Tangram Flex. They generate code that connects components together. There are two version available: Code Gen and Code Gen 3.0.

CODE GEN#

This plugin generates UCI Component Software Interface (CSI) code in C++. It can be configured to use ZeroMQ, RabbitMQ, ActiveMQ or Kafka transports.

CODE GEN 3.0#

Tangram Flex's Code Gen 3.0 plugin is a more robust version of Code Gen. It can be configured to generate CSI code or to generate transform code in both C++ and Java. It can be configured to use ZeroMQ, RabbitMQ, Kafka, or ActiveMQ transports.

FLEX TRANSPILER#

This plugin uses Tangram's Flex transpile to generate code to transform one message into another. It can output code in C++ or Java.

Compiler Plugins#

Tangram Pro™ includes code-compiling tools that can be configured as Workflow tasks.

ANT#

Ant is a plugin that compiles Java code. It executes ant at the code root and is often used in Workflows to compile the output of Code Gen 3.0.

CLANG++#

A plugin that uses clang++ to compile a set of files or to check C++ code syntax.

G++#

This plugin is a G++ compiler. It can be used to compile a single file, multiple files using a glob to find the files, or a CPP project according to a Makefile.

GRADLE#

A compiler for Java code. This plugin executes Gradle at the code root and is often used in workflows to compile the output of Code Gen 3.0.

MAVEN#

A compiler for Java code. This plugin executes Maven at the code root and is often used in Workflows to compile the output of Code Gen 3.0.

Assurance Plugins#

Workflows that include Assurance tools can generate evidence you can use to build confidence in your code. There are three basic Assurance perspectives:

  1. Safety --- software is free from unexpected behaviors, instability, and errors.
  2. Security --- software is analyzed for vulnerabilities, exposed functionality, and permissions.
  3. Correctness --- software adheres to design, works within the system context, and meets requirements.

Each Assurance tool functions differently. The types of evidence generated varies by tool. Selecting the proper Assurance tools is important to gaining confidence in your code.

The goal of building Assurance into Workflows is not to remove the testing and certification process. Instead, Tangram Pro™ provides tool to understand software. This allows engineering teams to build confidence in their systems.

BAGGAGE HANDLER#

Baggage Handler is an assurance tool that allows users to set options to use to assure a file. Baggage handler is used for C++ code.

CPPCHECK#

CppCheck is a static analysis tool that analyzes source code to find potential bugs and undefined behavior in C++ code. CppCheck produces a list of potential bugs in the root of the generated source code.

CPPCHECK MISRA#

A version of CppCheck that includes MISRA Compliance checking. This plugin runs against a directory recursively with a custom stdout report format.

DEEPSTATE#

DeepState is a framework for testing C and C++ code. It provides a common interface for various symbolic execution and fuzzing engines. DeepState can be configured to run in a Workflow several ways:

  • To check specification by randomly generating test cases with LLVM's LibFuzzer

  • To check specification by symbolically generating test cases with Angr

  • To check specification by symbolically generating test cases with Manticore

  • To check specification by concolically generating test cases with Eclipser

KLEE#

KLEE is a symbolic virtual machine. It can make variables inside of a program symbolic, and also generate stdin files and command line arguments. The KLEE plugin can be run over an annotated C or C++ program.

INFER#

Infer is a static analysis tool for detecting for null pointer dereferences, memory leaks, coding conventions and unavailable APIs in Java and C++ code. The Infer plugin in Tangram Pro™ can analyze program built using the gradle, ant, and maven build systems. It can also be used with an exported cmake compilation database and make.

JUNIT-QUICKCHECK#

Junit-quickcheck supports writing and running property-based tests in JUnit. In Tangram Pro™, the junit-quickcheck plugin can be configured to use gradle to build a project or build test harnesses with JavaC, ant, or maven when a Workflow runs.

SCAN-BUILD#

Scan-build is a static analyzer. As a Tangram Pro™ plugin, it can be configured as a Workflow task to analyze a C/C++ project using the cmake build system or to be run on a Makefile.

SPOTBUGS#

Another static analysis tool, Spotbugs looks for bugs in Java code. It can be included in a Tangram Pro™ workflow and configured to work with gradle, ant, or maven.

DOXYGEN#

Doxygen is a tool that generates documentation within code. It extracts documentation from source files and can be used for creating standard documentation.