Actions

Abort

The Abort action aborts the workflow.

The workflow is aborted immediately, in error. If the terminate flag is false, the workflow resumes on the next recurrence, otherwise it stops until either the event collection service is restarted, or the log source is edited.

The following table shows the parameters for the Abort action.

Table 1: Abort Action Parameters
Name	Data type	Required	Notes
reason	String	Yes	The reason why the workflow was aborted. This string displays in the log source status as an error message.
terminate	Boolean	No	Indicates whether the event retrieval loop is terminated. The default is False. Use this parameter only in extreme situations. The parameter puts the log source in error and stops it completely. The log source restarts only when the event collection service is restarted, or if the log source is edited. You can use the terminate parameter to stop the workflow on authentication failure to prevent account lockouts.

XML Example:

This action stops the current execution of the workflow, but it runs again on the next recurrence. Until the log source status is cleared or updated, it includes the following error message:

The password for <user value> has expired.

Add

The Add action adds a value to an array in the State.

The following table shows the parameters for the Add action.

Table 2: Add Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The location of the array. The path must reference an array value.
value	String/Number	Yes

XML Example:

This action adds the string "V2hhdCBhIHdvbmRlcmZ1bCB3b3JsZC4uLg==" to the State at location /tokens.

CallEndpoint

The CallEndpoint action calls an HTTP endpoint.

The following table shows the parameters for the CallEndpoint action.

Table 3: CallEndpoint Action Parameters
Name	Data type	Relationship	Required	Notes
method	Enumeration	Attribute	Yes	Possible values: GET POST PUT DELETE PATCH
url	String	Attribute	Yes	The base URL of the endpoint (excluding the query parameters).
savePath	String	Attribute	No	The response is stored as a JSON object with the following format: /response { status_code: 200, status_message: "OK", headers: { "Date": "Tue, 16 Jun 2020 17:31:29 GMT", "Content-Type": "application/json", }, body: ... } If you do not provide a savePath value, the endpoint response is not saved in a default location. A savePath value must be provided if you want to store the response.
sslConfiguration	SSLConfiguration	Subelement	No	For more information, see SSLConfiguration.
authentication	Authentication	Subelement	No	An Authentication object must be one of the following types: BasicAuthentication BearerAuthentication DigestAuthentication Akamai EdgeGrid Authentication Hawk Authentication
queryParameters	QueryParameter	Subelement	No	You can have more than one query parameter. For more information, see QueryParameter.
requestHeaders	RequestHeaders	Subelement	No	You can have more than one request header. For more information, see RequestHeader.
body	RequestBody UrlEncodedFormRequestBody XmlRequestBody	Subelement	No	The body must be one of the following types: RequestBody UrlEncodedFormRequestBody XmlRequestBody

The following table shows the parameters for SSLConfiguration.

Table 4: SSLConfiguration Structure
Name	Data type	Required	Notes
protocol	String	No	The SSL protocol to use. The default is TLSv1.2.
allowUntrustedServerCertificate	Boolean	No	Indicates whether untrusted server certificates are allowed. The default is False.

XML Example:

This example allows an untrusted server certificate.

The following table shows the parameters for BasicAuthentication.

Table 5: BasicAuthentication Structure
Name	Data type	Required
username	String	Yes
password	String	No

XML Example:

This example sets an authentication username and password.

The following table shows the parameters for BearerAuthentication.

Table 6: BearerAuthentication Structure
Name	Data type	Required	Notes
token	String	Yes	The access token.

XML Example:

This example sets an access token for authentication.

The following table shows the parameters for DigestAuthentication.

Table 7: DigestAuthentication Structure
Name	Data type	Required
username	String	Yes
password	String	Yes
realm	String	No
nonce	String	No
algorithm	String	No
qop	String	No
cnonce	String	No
nonceCount	String	No

XML Example:

This example sets a username and password for authentication.

The following table shows the parameters for Akamai EdgeGrid authentication.

Table 8: Akamai EdgeGrid Authentication Structure
Name	Data type	Required
accessToken	String	Yes
clientToken	String	Yes
clientSecret	String	Yes

The following table shows the parameters for Hawk authentication.

Table 9: Hawk Authentication Structure
Name	Data type	Required
keyID	String	Yes
key	String	Yes
algorithm	String	Yes
hash	String	No
ext	String	No
app	String	No
dlg	String	No

The following table shows the parameters for QueryParameter.

Table 10: QueryParameter Structure
Name	Data type	Required	Notes
name	String	Yes
value	String	Yes
omitIfEmpty	Boolean	No	Omits the parameter if the value is empty.

XML Example:

This example sets a name and value for a query, and omits the parameter if the value is empty.

The following table shows the parameters for RequestHeader.

Table 11: RequestHeader Structure
Name	Data type	Required	Notes
name	String	Yes
value	String	No
omitIfEmpty	Boolean	No	Omits the header if the value is empty.

XML Example:

This example sets a name and value for a request header.

The following table shows the parameters for RequestBody.

Table 12: RequestBody Structure
Name	Data type	Required	Notes
type	String	Yes	Must be a valid HTTP request content-type. For example, application/json.
encoding	String	Yes	Must be a valid HTTP body encoding type. For example, UTF-8.
content	String	Yes	Include the body content between the opening and closing tags of the <RequestBody> element.

XML Example:

This example sets a content-type, body encoding, and content for a request body.

The following table shows the parameters for UrlEncodedFormRequestBody.

Table 13: UrlEncodedFormRequestBody Structure
Name	Data type	Required	Notes
parameters	Map <String, String>	Yes	A collection of name/value pairs.

XML Example:

This example sets the name/value pairs for a URL encoded form request body.

The following table shows the parameters for XmlRequestBody.

Table 14: XmlRequestBody Structure
Name	Data type	Required	Notes
type	String	No	Must be a valid HTTP request content-type. For example, application/json.
encoding	String	No	Must be a valid HTTP body encoding type. For example, UTF-8.
content	XML	Yes	The actual XML content of the body must be nested within the <XmlRequestBody> element as subelements.

XML Example:

This example sets the content for an XML request body.

XML Example:

This action calls makes a POST request to https://${/host}/auth/oauth2/token with a request header and a request body, and saves the response in the State at /get_access_token.

ClearStatus

The ClearStatus action clears the runtime status of the protocol instance. This clears the status of the log source.

XML Example

This action clears any info, warning or error messages that are displayed for the log source.

Copy

The Copy action copies one part of the State to another.

The following table shows the parameters for the Copy action.

Table 15: Copy Action Parameters
Name	Data type	Required	Notes
sourcePath	JPath	Yes	The path to copy. This path can be either a static path or a query.
targetPath	JPath	Yes	The location to which the path is copied. This path overwrites anything that is stored at this location.

XML Example

This action copies the objects from the array at /events with a type_id of 4 to an array at location /interestingEvents, and erasing anything that was stored there previously.

Create JWTAccessToken

The JWTAccessToken action creates a JSON Web Token (JWT).

For more information, see JWT documentation.

The following table shows the parameters for the Create JWTAccessToken action.

Table 16: Create JWTAccessToken Action Parameters
Name	Data type	Relationship	Required	Notes
Header	KeyValuePairs	Subelement	Yes	The set of name/value pairs that form the JWT header. For more information, see Table 17.
Payload	KeyValuePairs	Subelement	Yes	The set of name/value pairs that form the JWT payload. For more information, seeTable 18
Secret	String	Subelement	Yes	In V1, the Secret must be a Base64 PKCS8 PEM file. In V2 or later, it can be either a PVKS1 or PVKS8 PEM file, and can be entered as plain text or Base64 encoded. For more information, see Table 19.
savePath	JPath	Attribute	Yes	The location in the state to store this value.

Table 17: Header Structure
Name	Data type	Description	Required	Notes
name	String	The name of the header.	Yes
value	String	The value of the header.	No

Table 18: Payload Structure
Name	Data type	Description	Required	Notes
name	String	The name of the payload.	Yes
value	String	The value of the payload.	No

Table 19: Secret Structure
Name	Data type	Description	Required	Notes
value	String	The value of the secret.	No

XML Example

This action creates a JWT with the provided header, payload and secret values, and saves it in the State at location /access_token.

Delete

The Delete action deletes an element from the State.

The following table shows the parameters for the Delete action.

Table 20: Delete Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The location of the element to delete.

XML Example

This action deletes the value that exists in the State at location /token

DoWhile

The DoWhile action loops a series of actions while a condition is true.

The condition is evaluated at the end of the loop. Even if the condition is never true, the contents are executed once. This action is different from the While action, where the condition is evaluated at the beginning of the loop.

The following table shows the parameters for the DoWhile action.

Table 21: DoWhile Action Parameters
Name	Data type	Required	Notes
condition	JPath	Yes	The condition that determines whether to continue looping.
actions	JPath Condition	Yes	Must be a JPath expression that resolves to a value of `true` or `false`. References to the State should not be within the `${}` notation for JPath conditions. See JPath.

XML Example

This action executes the nested CallEndpoint action and PostEvent action. If there is a value in the State at location /next_page the condition is true and the nested actions are executed, and the condition check is performed until the condition is false.

ForEach

The ForEach action executes a series of actions for each value in an array or object. In V1, the action works only for each value in an array.

The following table shows the parameters for the ForEach action.

Table 22: ForEach Action Parameters
Name	Data type	Description	Required	Notes
item	JPath	The path to store the current item of the iteration.	Yes	The path to store the current item of the iteration.
items	JPath	The array in the State to iterate.	Yes	The array in the State to iterate.
actions	Actions[]	The sequence of actions to execute for each iteration.	Yes	The sequence of actions to execute for each iteration. Cannot be empty.

XML Example

An array of objects exists in the State at /events. This action iterates through the array and executes the nested PostEvent action for each object in the array.

FormatDate

The FormatDate action formats a UNIX timestamp to a date.

The following table shows the parameters for the FormatDate action.

Table 23: FormatDate Action Parameters
Name	Data type	Required	Notes
pattern	String	Yes	See JavaDateTimeFormatter for possible values.
timeZone	String	No	See JavaDateTimeFormatter for possible values.
time	Number	No	The time to format, in milliseconds since epoch. The default is the current time.
savePath	JPath	Yes	The location to store the result.

XML Example

This action extracts the UNIX timestamp currently stored in the State at /bookmark and converts it to a meaningful timestamp in the following format in the UTC time zone.

The reformatted value is saved in the State at /formatted_bookmark.

GenerateHMAC

The GenerateHMAC action applies an HMAC hash to a given input.

The following table shows the parameters for the GenerateHMAC action.

Table 24: GenerateHMAC Action Parameters
Name	Data type	Required	Notes
algorithm	Enumeration	Yes	Possible values: MD5 SHA1 SHA256 SHA512
secretKey	String	Yes	The secret to use.
message	String	Yes	The input message to process.
saveFormat	String	Yes	Possible values: BASE64 HEX
savePath	JPath	Yes	The location to store the result.

XML Example

This action generates an HMAC hash of the value stored in the State at /value . The hash is generated in hex format by using the SHA1 algorithm and the provided secretKey, and is saved in the State at location /signature.

If/ElseIf/Else

The If/ElseIf/Else actions execute actions if a condition is satisfied.

The If/ElseIf/Else actions execute nested actions based on one or more mutually-exclusive conditions:

"If" conditions are always checked.
"ElseIf" conditions are only checked if all preceding "If" and "ElseIf" conditions were not satisfied.
"Else" actions have no condition; if none of the preceding "If" or "ElseIf" conditions were satisfied, the "Else" actions are automatically executed.

The following table shows the parameters for the If action.

Table 25: If Action Parameters
Name	Data type	Required	Notes
condition	JPath	Yes	The condition to evaluate. Cannot be empty.
actions	Actions[]	Yes	The sequence of actions to execute if the condition is true. Cannot be empty.

The following table shows the parameters for the ElseIf action.

Table 26: ElseIf Action Parameters
Name	Data type	Required	Notes
condition	JPath	Yes	The condition to evaluate. Cannot be empty.
actions	Actions[]	Yes	The sequence of actions to execute if the condition is true. Cannot be empty.

The following table shows the parameters for the Else action.

Table 27: Else Action Parameters
Name	Data type	Required	Notes
actions	Actions[]	Yes	The sequence of actions to execute if none of the preceding "If" or "ElseIf" conditions are true. Cannot be empty.

XML Example

In this example, the following actions are taken:

If the State value at location /status is 200, only the SetStatus action that sets the status to an INFO "Success" message is executed.
If the /status value is 401, only the SetStatus action that sets the status to an ERROR "Authentication Failure" message is executed.
If the /status value is 404, only the SetStatus action that sets the status to an ERROR "No Route Exists" message is executed.
If the /status value is anything else, only the final SetStatus action is executed.

Initialize

The Initialize action initializes a value in the State.

If a value exists in the location, the new value does not override the existing value.

Table 28: Initialize Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The location to initialize.
value	String/Number	Yes	The value to set.

XML Example

This action adds the value "1" to the State at location /bookmark, if no value exists at that location. If a value does exist at that location, the action does nothing.

Log

The Log action logs troubleshooting messages.

Troubleshooting messages are typically stored in the JSA log files at /var/log/qradar.error, var/log/qradar.log, and /var/log/qradar.java.debug

The following table shows the parameters for the Log action.

Table 29: Log Action Parameters
Name	Data type	Required	Notes
type	Enumeration	Yes	The log type. Possible values: INFO WARN ERROR DEBUG
message	String	Yes	The message to log.

XML Example

This action writes a DEBUG level log to the JSA logs that contain the specified message.

Merge

The Merge action merges an array into an array, or an object into an object.

The following table shows the parameters for the Merge action.

Table 30: Merge Action Parameters
Name	Data type	Required	Notes
sourcePath	JPath	Yes	The object or array to copy from.
targetPath	JPath	Yes	The object or array to merge into.

XML Example:

This action copies all objects that have a type_id value of 4 in the array at location /events in the State to the array at /cumulativeEvents. Any objects already in /cumulativeEvents are preserved.

ParseDate

The ParseDate action parses a date into a UNIX timestamp.

The ParseDate action is supported by the Java DateTimeFormatter. Some of the ParseDate action parameters are passed directly to Java.

The following table shows the parameters for the ParseDate action.

Table 31: ParseDate Action Parameters
Name	Data type	Required	Notes
pattern	String	Yes	The formatting pattern to use. See JavaDateTimeFormatter for possible values.
timeZone	String	No	The time zone to use. See JavaDateTimeFormatter for possible values.
date	String	Yes	The formatted date to parse.
savePath	JPath	Yes	The location to store the result.

XML Example:

This action converts the timestamp that is stored in the State at location /formatted_time to a UNIX timestamp and stores it in the State at location /timestamp. The current timestamp must be in the yyyy-MM-dd'T'HH:mm:ss'Z' format and represent a time in the Coordinated Universal Time (UTC) zone.

PostEvent

The PostEvent action posts an event to the JSA event pipeline, which allows the event to be parsed, correlated, and stored.

The following table shows the parameters for the PostEvent action.

Table 32: PostEvent Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The path of the element to post.
encoding	String	No	The encoding of the event. Possible values: UTF-8 BASE64 HEX The default is UTF-8.
source	String	Yes	The source (host) of the event. The source value is used to route the event within the event pipeline to the correct log source. The event is matched to the log source identifier of an existing log source. If no log source exists with a matching log source identifier, the event is stored without parsing and a copy of the event is sent to the log source autodetection engine. If a log source is autodetected from the event, it is created with its log source identifier set to the source value.

XML Example:

This action posts the string that is stored in the State at /event into the JSA event pipeline as an event. If a log source has a log source identifier that matches the value that is stored in /host, the event is routed to that log source.

PostEvents

The PostEvents action posts an array of events to the JSA event pipeline, which allows the events to be parsed, correlated, and stored.

The following table shows the parameters for the PostEvents action.

Table 33: PostEvents Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The path of the array element to post.
encoding	String	No	The encoding of the event. Possible values: UTF-8 BASE64 HEX The default is UTF-8.
source	String	Yes	The source (host) of the event. The source value is used to route the event within the event pipeline to the correct log source. The event is matched to the log source identifier of an existing log source. If no log source exists with a matching log source identifier, the event is stored without parsing and a copy of the event is sent to the log source autodetection engine. If a log source is autodetected from the event, it is created with its log source identifier set to the source value.

XML Example:

This action posts the array of strings that are stored in the State at /events into the JSA event pipeline as a series of events. If a log source has a log source identifier that matches the value that is stored in /host, the events are routed to that log source.

RegexCapture

The RegexCapture action captures part of a string with a regular expression (regex).

The following table shows the parameters for the RegexCapture action.

Table 34: RegexCapture Action Parameters
Name	Data type	Required	Notes
pattern	RegEx	Yes	The regular expression pattern. The pattern must contain only one capture group. The regex pattern must be a Java-type regex. For more information, see Class Pattern.
value	String	Yes	The value to capture from.
savePath	JPath	Yes	The location to store the result.

XML Example:

This action runs the regex that is defined in the pattern to the string stored in the State as /data. The capture group value is stored in the State at location /id. The provided regex captures one or more digits that follow "id=".

Set

The Set action sets a value in the State.

If a value exists at the location, the new value overrides the existing value.

The following table shows the parameters for the Set action.

Table 35: Set Action Parameters
Name	Data type	Required	Notes
path	JPath	Yes	The location to store the value.
value	String/Number	Yes	The value to set.

XML Example:

This action adds the value that is returned by the time() function to the State at location /current_time. If a value exists at that location, it is overwritten.

SetStatus

The SetStatus action sets the runtime status of the protocol instance. This information appears in the status of the log source.

The following table shows the parameters for the SetStatus action.

Table 36: SetStatus Action Parameters
Name	Data type	Required	Notes
type	Enumeration	Yes	The status type. Possible values include: INFO WARN ERROR
message	String	Yes	The status message.

XML Example:

This action sets the runtime status of the protocol instance to ERROR with a message that states: The password has expiredThis information is displayed as the log source status in the QRadar Log Source Management app and API.

Sleep

The Sleep action suspends the Workflow for a specified amount of time.

The following table shows the parameters for the Sleep action.

Table 37: Sleep Action Parameters
Name	Data type	Required	Notes
duration	Number	Yes	The amount of time to wait, in milliseconds.

XML Example:

This action causes the Workflow to pause execution for 5 seconds.

Split

The Split action splits a string.

For example, if an API returns a set of events as a long string, where each event is separated by a comma or other delimiter, you can split the string to use the PostEvent or PostEvents action.

The following table shows the parameters for the Split action.

Table 38: Split Action Parameters
Name	Data type	Required	Notes
value	String	Yes	The value to split.
delimiter	String	No	The delimiter is a regex expression. Defaults to "newline". If a delimiter is supplied with regex elements, it must be a Java-type regex.
savePath	JPath	Yes	The location to store the result.

XML Example:

This action splits the string "value 1,value 2,value 3" into an array of three strings "value1", "value2", and "value3". The strings are stored in the State at location /values.

While

The While action loops a series of nested actions while a condition is true.

The condition is evaluated at the beginning of the loop so if the condition is never true, it never executes its nested actions. This action is different from the DoWhile action, where the condition is evaluated at the end of the loop.

The following table shows the parameters for the While action.

Table 39: While Action Parameters
Name	Data type	Required	Notes
condition	JPath	Yes	The condition that determines whether to continue looping. A loop is an execution of all nested actions.
actions	JPath Condition	Yes	The sequence of actions to execute. Must be a JPath expression that resolves to a value of `true` or `false`. References to the State should not be within the `${}` notation for JPath conditions. See JPath.

XML Example:

This action executes the nested CallEndpoint action if a value exists in the State at location /next_page. The While action executes the nested CallEndpoint action until the /next_page value is null. If /next_page is always null, the nested action is not executed.

XPathQuery

The XPathQuery action executes an XPath query on an XML document value.

If an API returns a response in XML format, you can extract a certain value or set of values from the response. You can use XPath to extract values.

The following table shows the parameters for the XPathQuery action.

Table 40: XPathQuery Action Parameters
Name	Data type	Required	Notes
xmlPath	JPath	Yes	The location of the XML document in the State.
xPathQuery	XPath	Yes
singleton	Boolean	No	Interprets the results as a single value instead of an array. The default is False.
savePath	JPath	Yes	The location to store the result.

XML Example:

This action executes the XPath query "//event/id/text()" against the XML document that is stored in the State at /xml_events, and stores it in the State at location /event/id as a single value.

ON THIS PAGE

Abort

Add

CallEndpoint

ClearStatus

Copy

Create JWTAccessToken

Delete

DoWhile

ForEach

FormatDate

GenerateHMAC

If/ElseIf/Else

Initialize

Log

Merge

ParseDate

PostEvent

PostEvents

RegexCapture

Set

SetStatus

Sleep

Split

While

XPathQuery

Related Documentation