About workflow actions in Splunk Web

Enable a wide variety of interactions between indexed or extracted fields and other web resources with workflow actions. Workflow actions have a wide variety of applications. For example, you can define workflow actions that enable you to:

Perform an external WHOIS lookup based on an IP address found in an event.

Use the field values in an HTTP error event to create a new entry in an external issue management system.

Launch secondary searches that use one or more field values from selected events.

Perform an external search (using Google or a similar web search application) on the value of a specific field found in an event.

In addition, you can define workflow actions that:

Are targeted to events that contain a specific field or set of fields, or which belong to a particular event type.

Appear either in field menus or event menus in search results. You can also set them up to only appear in the menus of specific fields, or in all field menus in a qualifying event.

When selected, open either in the current window or in a new one.

Define workflow actions using Splunk Web

You can set up all of the workflow actions described in the bulleted list at the top of this chapter and many more using Splunk Web. To begin, navigate to Settings > Fields > Workflow actions. On the Workflow actions page you can review and update existing workflow actions by clicking on their names. Or you can click Add new to create a new workflow action. Both methods take you to the workflow action detail page, where you define individual workflow actions.

If you're creating a new workflow action, you need to give it a Name and identify its Destination app.

There are three kinds of workflow actions that you can set up:

GET workflow actions, which create typical HTML links to do things like perform Google searches on specific values or run domain name queries against external WHOIS databases.

POST workflow actions, which generate an HTTP POST request to a specified URI. This action type enables you to do things like create entries in external issue management systems using a set of relevant field values.

Search workflow actions, which launch secondary searches that use specific field values from an event, such as a search that looks for the occurrence of specific combinations of ipaddress and http_status' field values in your index over a specific time range.

Target workflow actions to a narrow grouping of events

When you create workflow actions in Splunk Web, you can optionally target workflow actions to a narrow grouping of events. You can restrict workflow action scope by field, by event type, or a combination of the two.

Narrow workflow action scope by field

You can set up workflow actions that only apply to events that have a specified field or set of fields. For example, if you have a field called http_status, and you would like a workflow action to apply only to events containing that field, you would declare http_status in the Apply only to the following fields setting.

If you want to have a workflow action apply only to events that have a set of fields, you can declare a comma-delimited list of fields in Apply only to the following fields. When more than one field is listed the workflow action is displayed only if the entire list of fields are present in the event.

For example, say you want a workflow action to only apply to events with ip_client and ip_server fields. To do this, you would enter ip_client, ip_server in Apply only to the following fields.

Workflow action field scoping also supports use of the wildcard asterisk. For example, if you declare a simple field listing of ip_* Splunk software applies the resulting workflow action to events with either ip_client or ip_server as well as a combination of both (as well as any other event with a field that matches ip_*).

By default the field list is set to *, which means that it matches all fields.

If you need more complex selecting logic, we suggest you use event type scoping instead of field scoping, or combine event type scoping with field scoping.

Narrow workflow action scope by event type

Event type scoping works exactly the same way as field scoping. You can enter a single event type or a comma-delimited list of event type into the Apply only to the following event types setting to create a workflow action that only applies to events belonging to that event type or set of event types. You can also use wildcard matching to identify events belonging to a range of event types.

You can also narrow the scope of workflow actions through a combination of fields and event types. For example, perhaps you have a field called http_status, but you only want the resulting workflow action to appear in events containing that field if the http_status is greater than or equal to 500. To accomplish this you would first set up an event type called errors_in_500_range that is applied to events matching a search like

http_status >= 500

You would then define a workflow action that has Apply only to the following fields set to http_status and Apply only to the following event types set to errors_in_500_range.

Control workflow action appearance in field and event menus

When workflow actions are set up correctly, they appear in menus associated with fields and events in your search results. You can arrange for workflow actions to be event-level (meaning they apply to an entire event), field-level (meaning they apply to specific fields within events), or both.

To select event-level workflow actions:

Run a search.

Go to the Events tab.

Expand an event in your search results and click Event Actions.

Here's an example of "Show Source," an event-level workflow action that, when clicked, displays the source for the event in your raw search data.

Alternatively, you can have the workflow action appear in the Actions menus for fields within an event. Here's an example of a workflow action that opens a Google search in a separate window for the selected field and value.

Both of these examples are of workflow actions that use the "GET" link method. This is one of three kinds of workflow actions that you can implement in Splunk Enterprise (the other two are "POST" link workflow actions and search workflow actions). Read on for instructions on setting up all three.

You can also define workflow actions that appear both at the event level and the field level. For example, you might do this for workflow actions that do something with the value of a specific field in an event, such as User_ID.

Set up a GET workflow action

GET link workflow actions drop one or more values into an HTML link. Clicking that link performs an HTTP GET request in a browser, allowing you to pass information to an external web resource, such as a search engine or IP lookup service.

Note: During transmission, variables passed in URIs for GET actions are URL encoded. This means you can include values that have spaces between words or punctuation characters. However, if you are working with a field that has an HTTP address as its value, and you want to pass the entire field value as a URI, you should use the $! prefix to keep Splunk software from escaping the field value. See "Use the $! prefix to prevent escape of URL or HTTP form field values" below for more information.

To define a GET workflow action:

1. Navigate to Settings > Fields > Workflow Actions.

2. Click New to open up a new workflow action form.

3. Define a Label for the action.

The Label field enables you to define the text that is displayed in either the field or event workflow menu. Labels can be static or include the value of relevant fields.

Use Apply only to the following fields to identify one or more fields. When you identify fields, the workflow action only appears for events that have those fields, either in their event menu or field menus. If you leave it blank or enter an asterisk the action appears in menus for all fields.

Use Apply only to the following event types to identify one or more event types. If you identify an event type, the workflow action only appears in the event menus for events that belong to the event type.

5. For Show action in determine whether you want the action to appear in the Event menu, the Fields menus, or Both.

6. Set Action type to link.

7. In URI provide a URI for the location of the external resource that you want to send your field values to.

Similar to the Label setting, when you declare the value of a field, you use the name of the field enclosed by dollar signs.

Variables passed in GET actions via URIs are automatically URL encoded during transmission. This means you can include values that have spaces between words or punctuation characters.

8. Under Open link in, determine whether the workflow action displays in the current window or if it opens the link in a new window.

9. Set the Link method to get.

10. Click Save to save your workflow action definition.

Example - Google search from field values

Here's an example of the setup for a GET link workflow action that sets off a Google search on values of the topic field in search results:

In this example, we set the Label value to Google $topic$ because we have a field called topic in our events and we want the value of topic to be included in the label for this workflow action. For example, if the value for topic in an event is CreatefieldactionsinSplunkWeb the field action displays as Google CreatefieldactionsinSplunkWeb in the topic field menu.

The Google $topic$ action applies to all events.

The Google $topic$ action URI uses the GET method to submit the topic value to Google for a search.

Example - Provide an external IP lookup

You have configured your Splunk app to extract domain names in web services logs and specify them as a field named domain. You want to be able to search an external WHOIS database for more information about the domains that appear.

Here's how you would set up the GET workflow action that helps you with this.

In the Workflow actions details page, set Action type to link and set Link method to get.

You then use the Label and URI fields to identify the field involved. Set a Label value of WHOIS: $domain$. Set a URI value of http://whois.net/whois/$domain$.

After that, you can determine:

whether the link shows up in the field menu, the event menu, or both.

whether the link opens the WHOIS search in the same window or a new one.

restrictions for the events that display the workflow action link. You can target the workflow action to events that have specific fields, that belong to specific event types, or some combination of the two.

Set up a POST workflow action

You set up POST workflow actions in a manner similar to that of GET link actions. However, POST requests are typically defined by a form element in HTML along with some inputs that are converted into POST arguments. This means that you have to identify POST arguments to send to the identified URI.

Note: During transmission, variables passed in URIs for POST actions are URL encoded, which means you can include values that have spaces between words or punctuation characters. However, if you are working with a field that has an HTTP address as its value, and you want to pass the entire field value as a URI, you should use the $! prefix to keep Splunk software from escaping the field value. See "Use the $! prefix to prevent escape of URL or HTTP form field values" below for more information.

1. Navigate to Settings > Fields > Workflow Actions.

2. Click New to open up a new workflow action form.

3. Define a Label for the action.

The Label field enables you to define the text that is displayed in either the field or event workflow menu. Labels can be static or include the value of relevant fields.

Use Apply only to the following fields to identify one or more fields. When you identify fields, the workflow action only appears events that have those fields, either in their event menu or field menus. If you leave it blank or enter an asterisk the action appears in menus for all fields.

Use Apply only to the following event types to identify one or more event types. If you identify an event type, the workflow action only appears in the event menus for events that belong to the event type.

5. For Show action in determine whether you want the action to appear in the Event menu, the Fields menus, or Both.

6. Set Action type to Link.

7. Under URI provide the URI for a web resource that responds to POST requests.

8. Under Open link in, determine whether the workflow action displays in the current window or if it opens the link in a new window.

9. Set Link method to Post.

10. Under Post arguments define arguments that should be sent to web resource at the identified URI.

These arguments are key and value combinations. On both the key and value sides of the argument, you can use field names enclosed in dollar signs to identify the field value from your events that should be sent over to the resource. You can define multiple key/value arguments in one POST workflow action.

Enter the key in the first field, and the value in the second field. Click Add another field to create an additional POST argument.

11. Click Save to save your workflow action definition.

Splunk software automatically HTTP-form encodes variables that it passes in POST link actions via URIs. This means you can include values that have spaces between words or punctuation characters.

Example - Allow an http error to create an entry in an issue tracking application

You have configured your Splunk app to extract HTTP status codes from a web service log as a field called http_status. Along with the http_status field the events typically contain either a normal single-line description request, or a multiline python stacktrace originating from the python process that produced an error.

You want to design a workflow action that only appears for error events where http_status is in the 500 range. You want the workflow action to send the associated python stacktrace and the HTTP status code to an external issue management system to generate a new bug report. However, the issue management system only accepts POST requests to a specific endpoint.

Here's how you might set up the POST workflow action that fits your requirements:

Note that the first POST argument sends server error $http_status$ to a title field in the external issue tracking system. If you select this workflow action for an event with an http_staus of 500, then it opens an issue with the title server error 500 in the issue tracking system.

The second POST argument uses the _raw field to include the multiline python stacktrace in the description field of the new issue.

Finally, note that the workflow action has been set up so that it only applies to events belonging to the errors_in_500_range event type. This is an event type that is only applied to events carrying http_error values in the typical HTTP error range of 500 or greater. Events with HTTP error codes below 500 do not display the submit error report workflow action in their event or field menus.

Set up a secondary search that is dynamically populated with field values from an event

To set up workflow actions that launch dynamically populated secondary searches, you start by setting Action type to search on the Workflow actions detail page. This reveals a set of Search configuration fields that you use to define the specifics of the secondary search.

In Search string enter a search string that includes one or more placeholders for field values, bounded by dollar signs. For example, if you're setting up a workflow action that searches on client IP values that turn up in events, you might simply enter clientip=$clientip$ in that field.

Identify the app that the search runs in. If you want it to run in a view other than the current one, select that view. And as with all workflow actions, you can determine whether it opens in the current window or a new one.

Be sure to set a time range for the search (or identify whether it should use the same time range as the search that created the field listing) by entering relative time modifiers in the in the Earliest time and Latest time fields. If these fields are left blank the search runs over all time by default.

Finally, as with other workflow action types, you can restrict the search workflow action to events containing specific sets of fields and/or which belong to particular event types.

Say your company uses a web infrastructure that is built on Ruby on Rails. You've set up an event type to sort out errors related to Ruby controllers (titled controller_error), but sometimes you just want to see all the errors related to a particular controller. Here's how you might set up a workflow action that does this:

1. On the Workflow actions detail page, set up an action with the following Label: See other errors for controller $controller$ over past 24h.

5. Using the Apply only to the following... settings, arrange for the workflow action to only appear in events that belong to the controller_error event type, and which contain the error and controller fields.

Those are the basics. You can also determine which app or view the workflow action should run in (for example, you might have a dedicated view for this information titled ruby_errors) and identify whether the action works in the current window or opens a new one.

Use special parameters in workflow actions

There are special parameters for workflow actions that begin with an "@" sign.
Two of these special parameters are for field menus only. They enable you to set up workflow actions that apply to all fields in the events to which they apply.

@field_name - Refers to the name of the field being clicked on.

@field_value - Refers to the value of the field being clicked on.

The other special parameters are:

@sid - Refers to the sid of the job that returned the event

@offset - Refers to the offset of the event in the job

@namespace - Refers to the namespace from which the job was dispatched

@latest_time - Refers to the latest time the event occurred. It is used to distinguish similar events from one another. It is not always available for all fields.

Example - Create a workflow action that applies to all fields in an event

You can update the Google search example discussed above (in the GET link workflow action section) so that it enables a search of the field name and field value for every field in an event to which it applies. All you need to do is change the title to Google this field and value and replace the URI of that action with http://www.google.com/search?q=$@field_name$+$@field_value$.

This results in a workflow action that searches on whichever field/value combination you're viewing a field menu for. If you're looking at the field menu for sourcetype=access_combined and select the Google this field and value field action, the resulting Google search is sourcetype accesscombined.

Remember: Workflow actions using the @field_name and/or @field_value parameters are not compatible with event-level menus.

Example - Show the source of an event

This workflow action uses the other special parameters to show the source of an event in your raw search data.

The Action type is link and its Link method is get. Its Title is Show source. The URI is /app/$@namespace$/show_source?sid=$@sid$&offset=$@offset$&latest_time=$@latest_time$. It's only applied to events that have the _cd field.

Try setting this workflow action up in your app (if it isn't installed already) and see how it works.

Use the $! prefix to prevent escape of URL or HTTP form field values

When you define fields for workflow actions, you can escape these fields so that they can be passed safely to an external endpoint using HTTP. However, in certain cases this escaping is undesirable. In these cases, use the $! prefix to prevent the field value from being escaped. This prefix prevents URL escape for GET workflow actions and HTTP form escape for POST workflow actions.

Example - Passing an HTTP address to a separate browser window

You have a GET workflow action that works with a field named http. The http field has fully formed HTTP addresses as values. This workflow action opens a new browser window that points at the HTTP address value of the http field. The workflow action does not work if it opens the new window with an escaped HTTP address.

To prevent the HTTP address from escaping, use the $! prefix. In Settings, where you might normally set URI to $http$ for this workflow action, instead set it to $!http$.

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

Feedback submitted, thanks!

You must be logged into splunk.com in order to post comments.
Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic.
If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk,
consider posting a question to Splunkbase Answers.

0
out of 1000 Characters

Your Comment Has Been Posted Above

We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website.
Learn more (including how to update your settings) here »