Understanding workflows and usage

To start using Workflow Builder, open a Workshop application and use the keyboard shortcut Command + I (macOS) or Ctrl + I (Windows) to view the relevant Workflow Builder graph depicting the objects, Actions, and Functions that back the application.

Interface

Workflow Builder's interface consists of the two main components, as seen in the following notional screenshot:

  1. Graph panel: An interactive graphical view of the entities backing your workflow and the relationships between them.
  2. Workshop panel: An interactive view of the selected Workshop applications.

Example Workflow Builder graph with split screen.

Graph panel

When you select nodes on the graph panel, you can see the corresponding Workshop components highlighted on the Workshop panel. This makes it easy to see the exact places that are using specific nodes and can help show you where specific objects are being used.

Example Workflow Builder node on graph.

When you select a specific node on the graph, you can use the Pin option to pin it to the left sidebar or view more details about the node.

Example Workflow Builder node on graph.

To see all linked dependencies for a particular node, select the icon corresponding to the input type you want to see on the graph.

You can view the icons of each node type in the legend at the top right of the graph panel. Object type nodes are represented using the icon specified in the Ontology.

In the example below, we want to see the nine Actions dependent on the Outage Alert object. Select the same icon location inline on the object to show and hide those dependencies from view.

Example object with Actions expanded out.

Review details of a specific node by selecting the node and then opening the selection details panel on the left side of the screen. Details displayed vary depending on the type of node selected. The following is a list of sample details that can be found for each resource:

  • Objects: A list of properties and where those properties are used throughout the workflow (see property provenance linked below), linkages, backing data source, and so on,
  • Functions: Inputs, outputs, dependencies, repository, and other relevant metadata.
  • Actions: API, RID, input data, Ontology edits, and submission criteria.
  • AIP Logic Function: Dependencies, automations, and metadata about creation details.
  • Language models: Model descriptions and metadata on model creator and context windows.
  • Workshop applications: Metadata about creation and Action, Function, and object dependencies.
Sample **Selection details** tab on the Workflow Builder graph.

Additional details

For Functions, you can view the code when you select the node. This includes the objects from which your Function reads and a description of the logic. You can also bulk upgrade Functions used in Workshop applications.

Example function code.

For Actions, you can view the Action function code, the Action log, and the option to upgrade the Action. You can also bulk update the submission criteria on Actions.

Example Action log.

For objects, you can view a preview of the object data.

Example object view.

For Automate, you can view property usages and dependencies on the sidebar.

Example Automate view.

Workshop panel

On the Workshop panel, you can select different components and view the corresponding nodes highlighted on the Workflow Builder graph.

At the bottom of the Workshop panel, the Entities section shows all backing objects and Actions used in the application. When you select a specific entity, you can view exactly where the entity is used throughout the Workshop application.

If you have multiple Workshop applications on your graph, you can use the dropdown menu at the top to toggle between Workshop application views.

Example Workflow Builder workshop panel with multiple workshops in the dropdown menu.

To reopen the Workshop panel, select any Workshop application on the graph and press I, or double-click on the node.

Color legend

Workflow Builder provides a color legend system to help manage security and view metadata about specific applications. Examples of color legends are below:

Example Workflow Builder graph with custom colors.

  • Node type: Shows the type of resource that each node represents on your graph.
  • Custom color: Adds colors into the legend by right-clicking nodes to create a new color group, selecting an existing one, or dragging colors from the legend onto nodes.
  • Ontology permissions: Review the Managing security section.
  • Resource permissions: Review the Managing security section.
  • Application views: Colors the Workshop applications based on how many views that application had over the past four weeks, in both view and edit mode.
  • Out of date functions: Review the Action-backed Function upgrades section.
  • Folder: Colors the nodes based on the folder each node lives in.
  • Functions repository: Colors the Function nodes based on the Functions repository each node lives in.
  • Model usage: Review the AIP usage metrics section.

Managing security

Example Workflow Builder with security coloring.

The color legend allows you to view both Ontology and resource permissions. There are two types of Ontology permissions:

  • Definition: Whether or not the specified user can view or edit entity definitions.
  • Data and execution: Whether or not the specified user can view object data or execute Actions.

To understand the access permissions of a specific user, you can input their username into the View as dropdown menu for a preview.

AIP usage metrics

Model usage coloring

Example Workflow Builder with model usage coloring.

Workflow Builder also allows you to view model metrics for model requests and token usage. There are three types of model usage metrics:

  • Successful: Total successful model requests or tokens used in attempts made by the specified model.
  • Attempted: Total attempts made by the model, including successful and rate-limited attempts.
  • Rate-limited: Total rate-limited attempts made.

Under Model usage, specify whether you want to view Model requests or Token usage metrics.

Model requests shows the total number of specified requests on model nodes in your Workflow Builder.

Example Workflow Builder with model requests coloring.

Token usage shows the number of tokens used for Workshop applications, Automations, or third-party OSDK applications. Token counts on Logic nodes are the token counts used in the Logic application debugger.

Example Workflow Builder with token usage coloring.

Model usage charts

You can view the token usage or model requests over time for Workshop applications, Automations, and third-party applications (Ontology SDK applications) over time in a line chart by selecting the nodes and opening the Model usage charts panel at the bottom.

Example Workflow Builder with token usage coloring.

To view the specific value for a particular resource, hover over the graph itself. The same filters that are used in the color legend explained above also appear in the charts panel.

Perform refactors and understand your workflows

To help you understand and easily perform refactors in your workflow, Workflow Builder provides a simple way for you to understand attached properties, update outdated variables and Action-backed Functions, or bulk edit submission criteria on Actions.

Property provenance

You can track the usage of each property within any object throughout your entire workflow. Select the object on the graph, and view the Selection details panel on the left to see where each property is being used.

The number shown next to each property refers to the amount of functions, Actions, linkages, Workshop applications, and more depending on the context.

Example Workflow Builder object and its property provenance.

Function-backed Action upgrades

To identify and upgrade outdated function-backed Actions, begin by navigating to the color legend. From there, select the Out-of-date functions option. This Action will highlight all the outdated functions in red, giving you a clear visual indication. Next, choose the specific Actions for which you wish to upgrade the backing function. Upon selection, any outdated Actions related to your choice will appear in the panel located at the bottom of the screen for further action.

Example of upgrading actions.

After you upgrade your Actions, a proposal will be created in Ontology Manager. Here, you can ask for a review of the changes (for example, the function upgrades) and once approved, you will be able to merge the proposal.

Example of upgrading actions in Ontology Manager.

Function-backed Workshop application upgrades

To upgrade functions used in Workshop applications, select the Workshop node and open Update Workshop applications on the bottom panel.

Example of upgrading functions for a particular Workshop.

There are two upgrade options:

  • All or nothing: Upgrade the functions in the workshop only if all of them can upgrade without breaking changes. If there are any breaking changes, nothing will be upgraded.
  • Partial: Upgrade only the functions without breaking changes. Functions that would cause breaking changes will not be upgraded.

To select the desired version of the functions to be upgraded, select Select versions.... This will open up a pop up where you can select the desired version for each function repository as well as the version for all functions created by AIP Logic or compute modules. If nothing is specified, it will automatically take the repository's latest version.

Example of upgrading functions for a particular Workshop application.

When a function cannot be upgraded, a yellow warning icon will appear next to that function.

When a function is already up-to-date, a gray check mark icon will appear next to that function.

If a function can be successfully updated, a green check mark icon will appear.

Select the blue Upgrade option to upgrade your Workshop module function to the target versions. This will open a pop up listing which Workshop modules will be upgraded.

Example of upgrading functions for a particular Workshop application.

Select Upgrade for the changes to go into effect. The successfully upgraded Workshop application will appear on the pop up.

Example of upgrading functions for a particular Workshop application.

Bulk update Action submission criteria

You can update an Action's submission criteria to match the submission criteria of a source Action. From the Workflow Builder graph, select the Actions you wish to update. Then, navigate to Update submission criteria from the bottom panel.

Example of upgrading Functions for a particular Workshop application.

On the left side of the panel, select the source Action whose submission criteria you want applied to the other Actions. The submission criteria of the source Action can be viewed under the selected source Action.

When completed, select the blue Update x actions button where x is the number of Actions that will be updated. This will create a proposal you can approve and submit for the changes to take effect.

Keyboard shortcuts

To view the list of keyboard shortcuts available to you, Select Help > View hotkeys.

The available hotkeys are as follows

GlobalmacOSWindows
Undo last changeCmd + ZCtrl + Z
Redo last changeCmd + YCtrl + Y
Redo last changeCmd + Shift + ZCtrl + Shift + Z
Save graphCmd + SCtrl + S
GraphmacOSWindows
Zoom to fit nodes
Zoom to fit nodesHomeHome
Show/hide Workshop application split viewII
Deselect all nodesEscEsc
Copy nodes to clipboardCmd + CCtrl + C
Remove selected nodesDeleteDel
Remove selected nodesBackspaceBackspace
Lay out all nodesCmd + Shift + ACtrl + Shift + a
Hierarchy layoutShift + LShift + L
Lay out nodesLL
Clustered hierarchy layoutAlt + LAlt + L
Grid layoutGG
Vertical layoutVV
Horizontal layoutHH
Select all nodesCmd + ACtrl + A
Invert selection (select unselected nodes)Cmd + ICtrl + I
Select downstream nodes
Select upstream nodes
Select all downstreamShift + →Shift + →
Select all upstreamShift + ←Shift + ←