The built-in Static Analysis Prioritization example is designed to teach you how to write a flow that retrieves static analysis violations from DTP through the DTP REST API and update their metadata in bulk. The flow is sectioned into several examples that serve as discussion points for learning how flows and nodes function. In this tutorial you'll learn how to set the Static Analysis Prioritization example flow up and how individual processes in the flow execute specific functions.
The following DTP REST APIs are used in this example:
Table of Contents:
Setting Up the Example
If you need additional help understanding how a node works, you can click on the node to view its documentation in the Info tab.
The nodes in Example #1 provide a method for assigner all retrieved violations to a new user.
The flow retrieves static analysis data via the /staticAnalysisViolation REST API provided by DTP. See Using DTP APIs for details.
Double-click the Get violations for Build node. This node is a DTP REST API node, which is a specific type of node for making requests to the DTP REST API (see Working with Nodes for all available nodes). The endpoint in the node points to /v1.2/staticAnalysisViolations?buildId={{payload}}. This node retrieves data based on the build ID specified when you set up the flow. It returns the static analysis violations payload to msg.staticAnalysis.
Double-click the Set the assigneeName function node. The node contains JavaScript that processes the violations and prepares for a new payload from the next REST API call.
Extension Designer functions use the lodash JavaScript utility library. The first part of the code initializes lodash as a variable, which enables you to sort and split arrays of violations data.
var _ = context.global.lodash; |
Line 5 splits the staticAnalysisViolations array into multiple arrays of 100 violations each. This reduces the payload to a safe size when sending back to DTP REST API. Processing a large payload in a single call may trigger an unexpected error from Extension Designer (see Working with Nodes).
Lines 7 through 16 create new msg arrays to prepare for the next prioritization API call. This API expects a JSON object. Each example will show you different way to set fields under Violations metadata. Review API documentation to learn more about the acceptable payload.
In this example, the assignee is set to johndoe. All violations called in the API will be assigned to johndoe once the flow is processed. You can add your own logic to assign different users if necessary.
The flow will only be able to assign violations to existing DTP users who are members of the project associated with the data. See User Administration for details.
At line 20, the flow sends a two dimensional array of one element. You can also can send multiple messages in a specific order. This function node only expects one output by sending an array of message objects into the output. The flow will send msg objects one at a time to the next flow, which is similar to looping through the array and returning each message asynchronously (see https://nodered.org/docs/writing-functions#multiple-messages for additional information).
The payload is prepared for the prioritization API. The next DTP REST API node completes the transaction.
The prioritization API is an unpublished, undocumented, and unsupported API. However, the API allows you to POST with a prioritize payload and apply changes to all violation IDs passed to it.
Click the Inject Build node to run the flow and see outputs in the debug tab.
Based on number of violations, you may see multiple transactions from the prioritization REST API.
All logic flows in this example differ only in terms of preparation of the Prioritization payload.
Double-click the Find and set the priorityId function node.
Lines 10 through 18 contain the JavaScript for setting the priority. In the example, priority is set to Critical for all violations passed.
Double-click the Set the violationAction function node.
Lines 11 through 15 contain the JavaScript for defining what action should be taken on the violations. In this example, violationAction is set to Fix.
Actions are defined in DTP. You can query the /v1.4/metadata/violationAction API to see what values are available for the violationAction field. You can use any available value specified in the response.
This metadata can be customized and every DTP server may have different set of actions. Review the /metadata/violationAction API documentation for additional information.
This example is very similar to Example 2 - Set Priority and Example 3 - Set Action. In this example, all violations are classified as Extreme. Double-click the Find and set the classificationId function node and review the JavaScript.
Double-click the Set the dueDate function node and review the JavaScript. The Moment JavaScript library is initialized in line 2. Moment is used in this example to get the date and time in a string. Moment is also used to calculate tomorrow's date as a string to set dueDate field.
Double-click the Set the referenceNumber function node and review the JavaScript. In this example, the referenceNumber field is set in the violation metadata.
The reference number could be used for the ID of external systems, such as JIRA and Bugzilla, for later use.
Double-click the Set the comment function node and review the JavaScript. In this example, a comment is added to the violation.
Notice that comments are not part of the fields object. A comment is an additional property associated with the prioritize object.
This is an advanced example that demonstrates how you can group static analysis violations based on severity and process the violations accordingly.
Double click the Group violations and set relevant priorityId function node and review the JavaScript. Instead of returning an array from the msg array, the node.send() method is used to push a msg object to the next node asynchronously (see https://nodered.org/docs/writing-functions#sending-messages-asynchronously for additional information about sending messages asynchronously).
You can query the /v1.4/metadata DTP REST API to see the metadata values available in your DTP.
