Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Actions

Actions are the building blocks of the workflow. Each action has a specific purpose, such as calling HTTP endpoints, or posting events to the JSA pipeline.

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:

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

UrlEncoded

FormRequest

Body

XmlRequestBody

Subelement

No

The body must be one of the following types:

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.

allow

Untrusted

Server

Certificate

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 QueryParameter.

Table 8: 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 9: 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 10: 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 11: 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 12: 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 13: 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 14: 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 15.

Payload

KeyValuePairs

Subelement

Yes

The set of name/value pairs that form the JWT payload. For more information, seeTable 16

Secret

String

Subelement

Yes

For more information, see Table 17.

savePath

JPath

Attribute

Yes

The location in the state to store this value.

Table 15: 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 16: 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 17: 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 18: 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 19: 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.

The following table shows the parameters for the ForEach action.

Table 20: 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 21: 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 22: 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 23: 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 24: 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 25: 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 26: 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 27: 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 28: 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 29: 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 30: 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 31: 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 32: 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 33: 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 34: 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 35: 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 36: 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 37: 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 38: 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.