App Builder

Last Updated: May 06, 2019 12:42PM EDT
App Developer
Playbooks enabled for the user’s Organization; the user’s Organization has permissions enabled for the app build and release functionalities

Overview

The App Builder is a Python development environment that allows users to create, edit, and release Playbook apps directly in ThreatConnect®. It includes development environment “basics” like debugging, viewing of build logs, version control, auto-complete, and release management, as well as unique features specific to ThreatConnect. It provides common snippets of code (including the ability for users to create their own snippets), as well as easy management of input and output variables. Its integrated debugger includes automatic creation of a test Playbook and a live-debugging process. Its version control system allows commenting on commits and reversion to prior versions. The App Builder can also be used to view and modify code in existing apps and import third-party app libraries.

The Playbook Apps Screen

On the top navigation bar (Figure 1), click Playbooks to display the Playbooks screen (Figure 2).

Click on the Apps tab at the top left of the screen, and the Apps screen will appear (Figure 3).

NOTE: This screen may also be accessed by hovering the cursor over Playbooks on the top navigation bar and choosing Apps from the dropdown menu that appears.

When the Show Released Apps slider at the top right of the screen is toggled to off (gray), as in Figure 3, then the screen will display all App Builder projects in the user’s Organization in a table with the following six columns:

  • Type: This column displays icons that illustrate the type of App Builder project in each row. The wrench icon indicates that the project has not been released. The wrench icon with a green checkmark indicates that the project has been released as an app (i.e., is available for installation by the user as a Playbook app in ThreatConnect and may be made available through TC Exchange).
  • Name: This column displays the name of the project. Click on the name to open the project in the App Builder screen. See “The App Builder Screen” for more information.
  • Version: This column provides the version number of the project. Version numbers are determined when the app is released. See “Releasing an App” for more information.
  • Labels: This column displays any labels that have been applied to the project. Labels are keywords that are used to classify projects. For example, labels such as “In Design” and “QA” can be used to track the development or status of a project, and labels such as “Utility” and “Signatures” or the creator’s name or initials can be used to make filtering projects more manageable. Labels are also searchable tags that enable an app to be returned in the search results of the Add App search bar in the Playbook Designer. For example, a search for “AMA” will return apps with this label even when the names of the apps do not contain “AMA.”
  • Updated: This column displays the date and time that the project was last updated.
  • Vertical ellipsis menu: The vertical ellipsis icon in the rightmost column provides options for cloning the project, deleting the project, and downloading the project. See “Cloning an App or a Project,” “Deleting a Project,” and “Downloading a Project,” respectively, for more information.

The apps listed in the table can be sorted and filtered by using the menus above the table:

  • Name: Enter a search string in the box to search for a project by name. As letters are entered, the screen will narrow down the selections to ones that contain the entered characters.
  • Status: Use the Status dropdown menu to display only Released or Unreleased projects, or select All to display all projects.
  • Label: Use the Label dropdown menu to display a scrollable multi-select list of available labels. Selecting one or more labels will cause only projects with those labels to be displayed.

Click the three big plus buttons at the top center of the screen to create a new app (project), clone an existing app (project), and import a project from a saved file, respectively. See “Administrative Functions for Projects and Apps” for more information. The New dropdown menu at the top left of the page provides the same options: Create App, Clone Existing App, and Import Project. If the user has viewed a project in the App Builder since logging into their ThreatConnect account, then a fourth button displaying a segment of the most recently viewed project will be displayed at the top center of the screen (Figure 4). Clicking this button will open this project in the App Builder. After two projects have been viewed, a fifth button similar to the fourth one will open, so that the user has clickable shortcuts to the two most recently viewed projects.

When the Show Released Apps slider at the top right of the screen is toggled to on (orange), then the screen will display existing apps on TC Exchange that the user can clone into the App Builder as a starting point for modification into new apps (Figure 5). Typically, these apps have been built by ThreatConnect, but they also include released apps in the user’s Organization.

NOTE: “Released” in the Show Released Apps slider refers to an app being released on TC Exchange. “Released” in the Status menu of the screen when the Show Released Apps slider is toggled to off, and in the checkmark in the icon, refers to App Builder projects that have been finalized and are available for installation on the user’s instance or for release to TC Exchange.

The released apps are displayed in a table with the following four columns:

  • Type: indicates that the app is available on TC Exchange. This is the only type available in the column.
  • Name: This column displays the name of the app. In this table, the app name is not clickable, because the apps themselves may not be edited in the App Builder. However, they may be cloned as a new project and edited in the App Builder.
  • Version: This column provides the version number of the app. Version numbers are determined when the app is released. See “Releasing an App” for more information.
  • Clone: Clicking the icon in the rightmost column creates and opens a clone of the app in the App Builder, enabling the user to use this app as a starting point for modification as an App Builder project.

The New dropdown menu at the top left of the page provides the same options shown when the Show Released Apps slider is toggled to off: Create App, Clone Existing App, and Import Project.

Administrative Functions for Projects and Apps

Creating a New Project

To create a new project, select Create App from the New dropdown menu at the top left of the Apps screen, or click the big Create App plus button from the Apps screen with the Show Released Apps slider toggled to off. The Create App window will appear (Figure 6).

  • Name: Enter a name for the project. Naming conventions such as starting the project’s name with the initials of the project’s creator in brackets may be helpful for sorting and filtering projects.
  • Template: Choose one of the given templates for the project. The templates provide a framework for the type of project being created, but the details are fully customizable.
  • Click the CREATE button to create the project.

NOTE: If ThreatConnect modifies the templates or adds new ones, then the options in this window may be different than the ones shown in Figure 6.

The new project will open in the App Builder screen. See “The App Builder Screen” for more information about creating, editing, and configuring projects in the App Builder screen.

Cloning an App or a Project

Cloning an App

To clone an existing app that has been released to TC Exchange, select Clone Existing App from the New dropdown menu at the top left of the Apps screen, or click the big Clone App plus button from the Apps screen with the Show Released Apps slider toggled to off. The Show Released Apps slider will toggle to on (or the screen will refresh if the slider is already toggled to on), and the screen will display all apps that are on TC Exchange and available for cloning into the App Builder (Figure 5). Click the icon in the rightmost column for the app to be cloned. A new version of the app will open in the App Builder.

Cloning a Project

App Builder projects can be cloned from the Apps screen via the vertical ellipsis menu in the rightmost column for the project to be cloned. Selecting the Clone option from this menu will cause the Clone App? screen to appear (Figure 7).

Click the CLONE button to open a cloned version of the project in the App Builder screen. A project can also be cloned from the App Builder screen via the Actions menu. See “The App Builder Screen” for more information.

Importing an App

Apps may be imported from .abx files outside of ThreatConnect. To import a file, select Import Project from the New dropdown menu at the top left of the Apps screen, or click the big Import Project plus button from the Apps screen with the Show Released Apps slider toggled to off. Select an .abx file for import from the browser window that appears. The file will open as a project in the App Builder screen.

Editing a Project

To edit a project, click on the name of the project in the table on the Apps screen when the Show Released Apps slider is toggled to off (Figure 4). The project will open in the App Builder screen. See “The App Builder Screen” for more information about editing and configuring apps in the App Builder screen.

Downloading a Project

App Builder projects may be downloaded as .abx files onto the user’s local computer and, if desired, shared with other users and imported as an App Builder project in another ThreatConnect instance. This is a useful way to share projects across instances. To download a project, click on the vertical ellipsis menu for the project in the table on the Apps screen when the Show Released Apps slider is toggled to off (Figure 4) and select the Download Project option. The project will download as an .abx file.

Deleting a Project

To delete an App Builder project, click on the vertical ellipsis menu for the project in the table on the Apps screen when the Show Released Apps slider is toggled to off (Figure 4) and select the Delete option. If the project is unreleased, or if the project has been released as an app, but there are no Playbooks using it, then the Delete App? window will appear with options to cancel (CANCEL) or confirm (DELETE) the deletion (Figure 8).

If the project has been released as an app and there is at least one Playbook using the app, the Delete App window will appear with a table of Playbooks that use it (Figure 9).

A green checkmark in the Active column of the table indicates that the Playbook is active. The name of the Playbook is provided in the Name column. Clicking a Playbook’s name will open the Playbook in the Playbook Designer in a new browser tab.

The app may not be deleted until the app is removed from the Playbook(s) using it. Click the DISMISS button to return to the Apps screen.

The App Builder Screen

The App Builder screen (Figure 10) contains features and components that enable the user to build a Playbook app and are customizable in the user interface.

Layout

The layout for the App Builder is organized by tabs and is customizable. Each tab may be moved by clicking on it and dragging it to a new location. For example, the Build Log> tab at the top center of Figure 10 could be moved to share an area with the Summary tab, as shown in Figure 11.

The width and height of each tab group (e.g., Summary and Build Log in Figure 11) can be customized by clicking on one of the borders and dragging it to a new location. This operation will work on only some of the borders. For example, the bottom borders at the bottom of the screen cannot be dragged.

Adjustments to the App Builder layout will persist when viewing different apps. To reset the layout, click the Settings icon at the top right corner of the screen and choose Reset Layout. The Reset Layout window will appear (Figure 12).

Click the RESET button to reset the layout back to the default.

Name Text Box

The Name text box at the top left of the screen displays the name of the project. Click on the pencil icon to edit the name (Figure 13).

Click the icon to accept the changes or the icon to reject them.

Actions Menu

The Actions menu at the top right of the screen provides options for cloning the project, downloading its last release (.tcx file), and downloading it as an App Builder project (.abx file) (Figure 14).

Clone

Select Clone from the Actions menu to clone the project. A clone of the project will automatically open in the App Builder screen, as evidenced by the project’s name, which will be Clone of <original app name> (Figure 15). To return to the original project, click the Back button of the web browser, or return to the Apps screen and click on the name of the original project to open it in the App Builder screen.

Download Last Release

Select Download Last Release to download the latest release of an app as a .tcx file. If the project has been released as an app, then it will download onto the user’s computer. If the app project not been released as an app, then an error message will appear at the top right of the screen (Figure 16).

Download Project

Select Download Project to download the project as an .abx file. The project will download once this selection is made.

Summary Tab

The Summary tab provides a snapshot of the state of the project and how it is used (Figure 17).

  • Version: This section provides the version number of the project or app. Version numbers are determined when the app is released. See “Releasing an App” for more information.
  • Usage: This section provides the number of times the project is used in a Playbook.
  • Executions: This section provides the number of times the project has been executed as an app.
  • Modified: This section provides time and date information for when the project was last modified.
  • Built: This section provides time and date information for when the project was last built (i.e, the code was compiled), or “Not Built” if it has not been built or its most recent build was unsuccessful. A green checkmark indicates that it was successfully built. A red exclamation point indicates that it was not successfully built. The App Builder incrementally builds as the user types, but there are some cases for which a manual build is required to fully build the project—for example, if a dependency is added or parameters have been modified. To execute the manual build, click the circular arrow icon.
  • Released: This section provides time and date information for when the project was released as an app to the App Catalog, or “Not Released” if it has not been released. To release the app, the user may click the circular arrow icon. See “Releasing an App” for more information.

Metadata Tab

The Metadata tab contains three fields that provide metadata for the project (Figure 18).

  • Category: Enter a category for the project. This field is open ended and can be used to classify apps in any way that works best for the users on the ThreatConnect instance. As letters are entered, a dropdown menu will appear that will narrow down the selections to existing categories that contain the entered characters. The user may enter a new category instead of choosing one of the provided selections.
  • Labels: Enter any labels for the project. Labels are keywords that are used to classify projects. For example, labels such as “In Design” and “QA” can be used to track the development or status of a project, and labels such as “Utility” and “Signatures” or the creator’s name or initials can be used to make filtering projects more manageable. Labels are also searchable tags that enable an app to be returned in the search results of the Add App search bar in the Playbook Designer. For example, a search for “AMA” will return apps with this label even when the names of the apps do not contain “AMA.” As letters are entered, a dropdown menu will appear that will narrow down the selections to existing labels that contain the entered characters. The user may enter a new label instead of choosing one of the provided selections. More than one label may be applied to a project.
  • App Note: Enter general information about the app and its parameters. The App Note will appear when the Display Notes slider is toggled to on in the Edit section of the Playbook Designer when configuring the app. See Playbooks and the next sub-section of this article for more information.

App Note

To enter an app note, click on the pencil icon next to the App Note text. The Edit Note drawer will open on the left-hand side of the screen (Figure 19).

Enter the text for the app note in the Description box. Markdown may be used (Figure 20).

To preview the Markdown, click the Preview Markdown link. The Description box will show how the app note will look with the Markdown rendered (Figure 21).

Click the View Text link to return to the unrendered text. Click the SAVE button to save the app note and close the Edit Note drawer.

Contents Tab

The Contents tab is a clickable table of contents for the files that compose the app (Figure 22).

The selected file, indicated by gray shading (e.g., app.py in Figure 22), is the file that shows in the Code Editor in the middle of the App Builder screen (Figure 10). (See “Code Editor” for more information about the Code Editor.) Files may be added to the project by dragging and dropping a file from a browser window into the Drop a file, or browse to upload. square or by clicking on this square to open a browser window for file selection.

NOTE: The code that first appears in the app.py file is determined by the type of app chosen in the Create App window (Figure 6).

Select the Show non-editable files checkbox to view the files associated with the app that may not be edited (Figure 23). These files may be viewed in read-only form in the Code Editor, as indicated by the lock icon next to them.

Although these files cannot be edited by the user, their contents are automatically customized as the user enters information into the App Builder. For example, Figure 24 shows the contents of the install.json file for the project. The name of the app is on line 3, and the app note as entered in Markdown in Figure 20 is on line 13.

Files

Creating a New File

To create a new file, click the Create File icon. The Create File window will open (Figure 25).

The Path may not be edited. Enter a Name for the file, and then click the CREATE button. The new file will open in the Code Editor (Figure 26).

Files may also be created in directories in the project contents. See “Directory Administration” for more information.

File Administration

Files added by the user via upload or the Create File icon may be renamed or deleted. To access these administrative functions, hover the cursor over the name of the file in the Contents tab. An ellipsis will appear to the right of the file name (Figure 27).

Hover the cursor over the ellipsis, and two icons will appear (Figure 28).

To rename the file, click the pencil icon in Figure 28. The Rename File window will appear (Figure 29). Enter a new name for the file, and then click the SAVE button.

To delete the file, click the trash icon in Figure 28. The Confirm window will appear (Figure 30). Click the REMOVE button to confirm the deletion.

NOTE: Files that are required by the platform installer may not be renamed or deleted.

Directories

Creating a New Directory

To create a new directory, click the Create Directory icon. The Create Directory window will open (Figure 31).

The Path may not be edited. Enter a Name for the directory, and then click the CREATE button. The new directory will appear in the Contents tab (Figure 32).

NOTE: Directories may not be selected for viewing in the Code Editor because they are not files.

Directory Administration

To access the administrative functions that may be performed on directories, hover the cursor over the name of the directory in the Contents tab. An ellipsis will appear to the right of the directory name (Figure 33).

Hover the cursor over the ellipsis, and five icons will appear (Figure 34).

To rename the directory, click the pencil icon in Figure 34. The Rename Directory window will appear (Figure 35). Enter a new name for the directory, and then click the SAVE button.

To delete the directory, click the trash icon in Figure 34. The Confirm window will appear (Figure 36). Click the REMOVE button to confirm the deletion.

To create a file in the directory, click the Create File icon in Figure 34. The Create File window will open (Figure 37).

The Path may not be edited. Note that the given path indicates that the new file will be in the directory. Enter a Name for the file, and then click the CREATE button. The new file will open in the Code Editor (Figure 38).

Once a directory contains at least one file, its contents can be collapsed and expanded by clicking on the arrow to its left.

To create a new directory in the directory (i.e., a sub-directory), click the Create Directory icon in Figure 34. The Create Directory window will open (Figure 39).

The Path may not be edited. Note that the given path indicates that the new directory will be in the existing directory. Enter a Name for the directory, and then click the CREATE button. The new directory will appear in the Contents tab within the original directory (Figure 40).

To upload a file to the directory, click the Upload File icon in Figure 34. Select a file for upload from the browser window that opens.

Code Editor

The Code Editor displays any file in the project, including Python source code, and offers syntax highlighting and autocomplete functionality (Figure 41).

To enter or edit code, click the cursor in the desired location and begin typing or editing.

Click the screen-mode icon at the top right corner of the Code Editor to toggle to full-screen mode (Figure 42). To exit full-screen mode, click the screen-mode icon again.

Snippets Tab

The Snippets tab contains small portions of code that can easily be inserted into a file in the Code Editor with a single click. The available snippets are organized into groups in the Snippets tab, as in Figure 43, which displays three groups, with the Metric group expanded to show the snippets it contains.

Hovering over a snippet will cause the Insert Code icon to appear to its right (Figure 44).

Hover over the Insert Code icon to view a pop-up bubble containing a preview of the snippet’s code (Figure 45).

To insert a snippet into the Code Editor, position the cursor in the desired location in the Code Editor and click the Insert Code icon.

NOTE: The browser’s “Undo” operation can be used to remove a snippet that was erroneously inserted.

Users can create their own groups and snippets. To do so, click the plus icon at the top right corner of the Snippets tab. The Create Snippet window will appear (Figure 46).
  • Group: Enter the name of the group. Entering the name of an existing group will insert the snippet in that group. Entering the name of a group that does not exist will create a new group into which the snippet will be inserted.
  • Name: Enter a name for the snippet.
  • Snippet: Enter the snippet’s code.
  • Click the SAVE button to save the snippet.

User-created snippets may be edited and deleted. To access these operations, hover the cursor over the snippet. In addition to the Insert Code icon, a pencil icon and a trash icon will appear (Figure 47).

Click the pencil icon in Figure 47 to edit the snippet. The Edit Snippet window will appear (Figure 48).

To change the snippet’s group, enter a different group’s name in the Group field. Once the snippet has been edited, click the SAVE button.

Click the trash icon in Figure 47 to delete the snippet. The Delete Snippet window will appear (Figure 49).

Click the DELETE button to delete the snippet.

Inputs and Outputs Tabs

The Inputs and Outputs tabs enable the user to determine and manage an app’s input parameters (i.e., the fields that are viewed in the configuration pane for the app in the Playbook Designer) and output variables (Figure 50).

NOTE: These tabs may be separated and viewed simultaneously by dragging and dropping one of them into a different location.

Input Parameters

To create a new input parameter, click the + New Input button on the Inputs tab. The Create Parameter: window will appear (Figure 51).

NOTE: The choice of UI Element will determine the rest of the fields in the Create Parameter: window. Figure 51 shows the options for the TextField element, which is the element that appears by default when the Create Parameter: window is open.

NOTE: The Data Type checkboxes will be disabled when Dropdown, Checkbox, or Multiselect Dropdown is selected as the UI Element.

  • Label: Enter a name for the parameter. This is the name that will be displayed to users of the app.
  • Variable Name: This field will autofill the name of the corresponding input variable for the parameter, based on the provided label. For example, if the label is “Sample Input Parameter”, then the Variable Name will fill as “sample_input_parameter”. This field may not be edited.
  • UI Element: Use the dropdown list to select the type of element (TextField, Dropdown, Checkbox, Multiselect Dropdown, or Key/Value List) that will render for this parameter in the configuration pane of the app in the Playbook Designer.
  • Default Value: Enter a default value for the parameter. When Checkbox is selected as the UI Element, the Default Value section will show True and False radio buttons, one of which should be selected as the default value. When Multiselect Dropdown is selected as the UI Element, multiple values separated by the pipe (|) character may be entered as default values. This field will not appear when Key/Value List is selected as the UI Element.
  • Enable Multi-line: Select this checkbox to display a TextField input field with multiple lines when configuring the app. This checkbox will appear only when TextField is selected as the UI Element.
  • Data Type: Select one or more types of data that the parameter will take. These data types are the kinds of variables that users designing Playbooks that utilize the app will be allowed to enter. The letter to the left of each selection provides a quick reference to the type of data, with the array versions of a data type having the same letter as the non-array versions (e.g., both String and StringArray are represented by “S”), but appearing in a square instead of a circle.
  • Advanced Options:

    NOTE: The Advanced Options section will not appear when Dropdown or Multiselect Dropdown is selected as the UI Element.

    • Required: Select this checkbox to require the user to enter a value for the parameter.
    • Hidden: Select this checkbox if the parameter should be a hidden parameter. A hidden parameter is a parameter that is not visible when configuring the app in a Playbook.
    • “Allow” checkboxes:
      • Text Variables: Select this checkbox to allow text variables to be entered as values for this parameter.
      • Encrypted & Allow Keychain Variables: Select this checkbox to enable encryption and allow keychain variables to be entered as values for this parameter.
      • Allow File Variables: If the Binary or BinaryArray checkbox is selected, then this checkbox will appear in place of the other two Allow checkboxes. Select this checkbox to allow file variables to be entered as values for this parameter.
    • Expose Key as Output Variable: Select this checkbox to expose the key as an output variable. Then use the dropdown menu next to it to select the data type for the output variable that contains the key. This checkbox will appear only when Key/Value List is selected as the UI Element.
  • Dropdown Options: Enter the values to be provided in the dropdown list, separated by the pipe (|) character. This field will appear when Dropdown or Multiselect Dropdown is selected as the UI Element.
  • Required: Select this checkbox to require the user to enter a value for the parameter. This checkbox will appear when Dropdown or Multiselect Dropdown is selected as the UI Element. It is also present for the other UI Element types in the Advanced Options section.
  • Help Note: Text entered here will appear in the Inputs section of the App Note, which is the text that appears when the Display Notes slider is toggled to on in the Edit section of the Playbook Designer when configuring the app. Markdown may be used. To preview the Markdown, click the Preview Markdown link, and the note will render the Markdown in the box.
  • Click the SAVE button to save the parameter.

The parameter will appear on the Inputs tab, along with letter representations of the data types it takes (Figure 52).

Hovering over the variable will cause the Insert Code icon to appear (Figure 53).

To insert the parameter into the Code Editor, position the cursor in the desired location in the Code Editor and click the Insert Code icon. For example, in Figure 54, the sample parameter was inserted on line 23.

NOTE: The browser’s “Undo” operation can be used to remove a variable that was erroneously inserted.

Click the vertical ellipsis icon for the parameter to access options for editing or deleting it (Figure 55).

Clicking the Edit option in Figure 55 will cause the Edit Parameter window to open (Figure 56).

Make any changes, and then click the SAVE button.

Clicking the Delete option in Figure 55 will automatically delete the parameter.

NOTE: No confirmation window for the Delete option will appear. The deletion will happen immediately.

NOTE: If code for an input parameter has been inserted into the Code Editor and then the parameter is deleted, the inserted code will remain. It will not be automatically deleted with the parameter.

Output Variables

To create a new output variable, click the + New Output button on the Outputs tab (Figure 57).

The Create Output window will appear (Figure 58).

  • Name: Enter a name for the output variable.
  • Type: Select one or more variable types from the dropdown menu.
  • Click the SAVE button to save the variable.

The variable will appear on the Outputs tab, along with letter representations of the data types it can be output as (Figure 59).

Hovering over one of the data types will cause the Insert Code icon to appear for that data type (Figure 60).

To insert the variable for that data type into the Code Editor, position the cursor in the desired location in the Code Editor and click the Insert Code icon. For example, in Figure 61, the sample variable was inserted on line 23.

NOTE: The browser’s “Undo” operation can be used to remove a variable that was erroneously inserted.

Click the ellipsis icon for the variable to access options for editing or deleting it (Figure 62).

Clicking the Edit option in Figure 62 will cause the Edit Output window to open (Figure 63).

Make any changes, and then click the SAVE button.

Clicking the Delete option in Figure 62 will automatically delete the variable.

NOTE: No confirmation window for the Delete option will appear. The deletion will happen immediately.

NOTE: If code for an output variable has been inserted into the Code Editor and then the variable is deleted, the inserted code will remain. It will not be automatically deleted with the variable.

VIM Mode

Projects may be edited on the App Builder screen in VIM mode, which uses VIM-emulated keybindings. To switch to VIM mode, click the Settings icon at the top right corner of the screen and toggle the VIM mode slider to on (orange), as in Figure 64.

Building an App

Apps are built for the first time when they are created, based on the default code for the app type chosen in the Create App window (Figure 6), and then incrementally as the user types. However, there are some cases for which a manual build is required to fully build the project—for example, if a dependency is added or parameters have been modified. An app must be built before it can be debugged, tested, and released.

To build an app, click the icon in the Built section of the Summary tab (Figure 65).

If the build is unsuccessful, the img alt="" src="/customer/portal/attachments/926415" /> icon will appear in place of the icon, and the timestamp will be updated. The project will need to be modified and built successfully in order to proceed with debugging, testing, and release.

If the build is successful, the icon will appear in place of the icon, and the timestamp will be updated.

Build Log Tab

The log of the most recent build will be available in the Build Log tab (Figure 66).

In addition to the build log, this tab displays the Status of the build (Successful or Unsuccessful) and any Status Message that is available. If a build is unsuccessful, a Rebuild button will appear here.

Debugging and Testing an App

Once an app has been built successfully, it may be debugged and tested via the Live Debug function. Toggle the Live Debug slider at the top right of the App Builder screen (Figure 10) to on (orange) to activate the live debugger (Figure 67).

A successful build is required for the live debugger to work. If the app has not been built successfully, then an attempt to toggle the Live Debug slider will fail (Figure 68).

In order to test an app, a Playbook that uses the app must be created. Click the Generate a playbook to test this App text. A test Playbook will open in a new window (Figure 69).

The test Playbook links the new app with an HttpLink trigger. Other triggers, apps, and operators may be added as well. The Edit App pane allows the user to view and test the input parameters that were created on the App Builder screen. The icon on the app indicates that this app is in development.

Once the test Playbook is created, it will continue to exist, even if its browser tab is closed or the user logs out of ThreatConnect. Once the user returns to the app in the App Builder or re-toggles the Live Debug slider, the App Builder screen will provide a link to the test Playbook, as well as information on whether the Playbook is active or not (Figure 70). Use the circular arrow icon to refresh the listing—for example, to show a change in status (active or inactive) or to display any new Playbooks that were created using the project.

As demonstrated in Figure 69, the test Playbook can be used to view the app in order to verify the input parameters and the output variables. Make sure to enter information into the input parameters so that a test run of the app will have the required information for the app to work.

Toggle the Display Notes slider to on (orange) to view the App Note entered in the Metadata tab, as well as the output variables and the current version of the app (Figure 71).

Hover the cursor over the hashtag at the top left of the app icon in Figure 69 to view a pop-up bubble containing the output variables (Figure 72).

To begin the debugging process, the test Playbook must be active. Toggle the Active slider at the top right of the test Playbook screen (Figure 69) to on (orange). If further information or changes are required in order to activate the Playbook, a red error message will appear by the slider (Figure 73).

To view details about the error, click on the red exclamation point icon next to the Settings menu for the Playbook (Figure 74).

Once a Playbook is successfully activated, the Playbook will switch to execution mode (Figure 75).

To execute the Playbook for debugging and testing, click on the green exclamation point icon next to the Active slider and select Execute Endpoint from the dropdown menu (Figure 76).

Return to the browser tab with the App Builder screen, which will have changed to display tabs that correspond to debugging functions (Figure 77).

Debug Mode

When in debug mode, the Code Editor becomes the Debugger tab. Use the icons at the top of the tab to orchestrate the debugging process:

  • Continue : Clicking this icon instructs the debugger to continue the debugging process, stopping only when a breakpoint is encountered or the program exits.
  • Step Over : Clicking this icon instructs the debugger to continue execution until the next line in the current function is reached or it returns.
  • Step Into : Clicking this icon instructs the debugger to execute the current line, stopping at the first possible occasion.
  • Step Out : Clicking this icon instructs the debugger to continue execution until the current function returns.
  • Clear Breakpoints : Clicking this icon instructs the debugger to clear all breakpoints in the current session.
  • Update Global Variables : Clicking this icon instructs the debugger to update all global variables for the app.
  • End and Exit : Clicking this icon instructs the debugger to end the debugging session and exit the program.

NOTE: Hovering over each icon will cause a pop-up bubble that describes the icon’s function to appear.

In addition to the Debugger tab, the App Builder screen displays a number of other tabs that provide information that can be used for debugging the app:

  • Usage: This tab provides information on test Playbooks that use the app, including whether each Playbook is running and active.
  • Contents: This tab is the same as it is in the App Builder screen when live debugging is turned off. See “Contents Tab” for more information.
  • Arguments: Select the Show standard parameters checkbox to display a list of all of the standard parameters associated with an app and their values for the test execution of the Playbook. Standard parameters are a fixed set of parameters passed to all apps and used by the software developer’s kit (SDK) to perform various low-level functions. They are available in this tab for troubleshooting, but are hidden by default.
  • Secure Params: Click on the small triangle icon to the right of the Arguments tab, and the text Secure Params will appear below it. Click on that text, and the Arguments tab will be replaced by the Secure Params tab, which will list the arguments not passed during command-line execution, but retrieved securely in memory once the app is executing. Select the Show standard parameters checkbox to display a list of the parameters and their values for the test execution of the Playbook. To return to the Arguments tab, click on the triangle icon again and then click on the Arguments text that appears below it.
  • Breakpoints: This tab displays a list of all of the breakpoints in the debugging session, including the line number and file name. Breakpoints can be added at any executable line of code (i.e., not comments or empty lines). Toggle breakpoints by clicking on the gutter to the left of the line numbers of the code. When a breakpoint is toggled on, a breakpoint icon will appear, and the breakpoint will be added to the list in the Breakpoints tab. Click on the breakpoint icon to remove it.
  • Variables: This tab lists values for all variables in the current execution.
  • Call Stack: This tab displays the program call stack for the line that is currently executing.
  • App Log: This tab displays a log for the execution of the app.
  • Standard Output: This tab displays the values of the output variables.
  • Standard Error: This tab provides information about the errors that occurred during the execution.

NOTE: The app cannot be edited when the App Builder screen is in debug mode. The code in the Code Editor is presented in read-only format.

Releasing an App

Once an app has been debugged and is ready to be made available to other users, it may be released. From the App Builder screen with Live Debug toggled to off (Figure 10), click the icon in the Released section of the Summary tab. The Release App drawer will appear with the Type step selected (Figure 78).

Choose the type of release (Patch, Minor, or Major), using the guidance provided in the descriptions. These release types are based on the Semantic Versioning System. The right-hand side of the drawer shows how each type of release will change the version number for the app.

Once a type is selected, the Release Notes step will be displayed (Figure 79).

Enter text describing the release in the text box. This step is important because it enables developers to communicate app changes to their users. Markdown is allowed. Use the Preview Markdown link to preview the rendered version of the Markdown.

Click the NEXT button, and the Release step will be displayed (Figure 80).

The top of the screen will display the current version number and the new version number. Use the radio buttons to determine the permissions for the app. Selecting the Allow all organizations to use this app. button will make the app available to Playbook users in all Organizations on the given instance of ThreatConnect. Selecting the System Administrator should control permissions per organization. button will enable the System Administrator to control access to the released app in the TC Exchange App Catalog. Note that if the latter button is selected, but previous versions of the app were already released to all Organizations on the instance, then the previous versions will remain available to Playbook users in all Organizations on the instance, while access to the newly released version will be controlled by the System Administrator.

Click the RELEASE button to release the app. When the app is released, a green success message will appear at the top right of the screen (Figure 81).

The Released section of the Summary tab will update to include the date and time of release.

Source Control

The Source Control tab allows the user to create versions (commits) of apps, comment on commits, and revert to prior versions of an app (Figure 82).

NOTE: Commits are not the same as release versions. They are an informal system of saving different phases of an app’s development, whereas releases are official, documented versions of an app. Release versions are numbered according to the scheme provided in Figure 78. However, when an app is released, a commit for the release is automatically created as well.

The table provided in the tab provides the following pieces of information for each commit:

  • Id: Each commit is given a unique ID number.
  • Message: The user may provide a message with information about the commit, such as what was changed or different for that version. If the commit was generated automatically by a release, then the message will state that the commit is for a released version, and it will provide the official version number.
  • Timestamp: The timestamp provides the date and time that the commit was made.
  • Reset: Click the Reset link to revert back to the commit.

To create a commit, click the COMMIT CHANGES button. The Commit Changes window will appear (Figure 83).

NOTE: If the COMMIT CHANGES button is grayed out, there are no new changes to commit since the last commit. Once changes have been made, the button will become available.

Enter a Message to describe the changes for the commit, and then click the COMMIT button.

To revert to a previous commit, click the Reset link for that commit. The Reset Project to Commit window will appear (Figure 84).

Click the PROCEED button to revert to the chosen commit. The project will return to its state in the chosen commit, and a new commit will be created for the reset action (Figure 85).

Validations

The Validations tab provides validations as changes are made to the project. Validations provide early warnings of build or runtime errors before they happen. Validations must be fixed prior to building or debugging a project (Figure 86).

20084-01 EN Rev. B

Contact Us

  • ThreatConnect, Inc.
    3865 Wilson Blvd.
    Suite 550
    Arlington, VA 22203

    Toll Free:   1.800.965.2708
    Local: +1.703.229.4240
    Fax +1.703.229.4489

    Email Us



https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete