Splunk® Enterprise

Knowledge Manager Manual

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Create workflow actions in Splunk Web

Enable a wide variety of interactions between indexed 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.
  • Perform an external search (using Google or a similar web search application) on the value of a specific field found in an event.
  • Launch secondary Splunk searches that use one or more field values from selected events.

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 Manager

You can set up all of the workflow actions described in the bulleted list at the top of this chapter and many more using Manager. To begin, navigate to Manager > 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 Manager, 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 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 Splunk 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.

For more information about event types, see "About event types" in this manual.

Control workflow action appearance in field and event menus

When workflow actions are set up correctly, they appear in dropdown menus associated with fields and events in your search results. For example, you can define a workflow action that sets off a Google search for values of the topic field in events. (The topic field turns up in webserver events associated with the access of Splunk documentation topics. It has the name of a particular Splunk documentation topic as its value.)

Depending on how you define the Google search workflow action in Manager, you can have it appear in field menus for events containing a topic field:

Wf actions field menu ex.png

Alternatively, you can have the workflow action appear in the event menus for those same events:

Wf actions event menu ex.png

Or you can choose to have it appear in both the event menu and the field menus for events containing a topic field.

Note that in the event depicted above, the topic field has a value of LicenseManagement. The menus for this event display the workflow action Google LicenseManagement. Clicking on this workflow action sets off a Google search for the term LicenseManagement. This is an example of a "GET link" workflow action, and it's one of three kinds of workflow actions that you can implement in Splunk. Read on for instructions on setting up all three.

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.

To define a GET workflow action, go to the detail page and set Action type to link, set Link method to get. Then you define a Label and URI as appropriate.

Note: 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. However, if you're 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 from escaping the field value. See "Use the $! prefix to prevent escape of URL or HTTP form field values" below for more information.

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:

GET workflow action ex1.png

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. For example, if you have a field called topic in your events and you want its value to be included in the label for a Google workflow action, you might set the Label value to Google $topic$.

In the above example, if the value for topic in an event is CreatefieldactionsinSplunkWeb the field action displays as Google CreatefieldactionsinSplunkWeb in the topic field menu.

The URI field enables you to define 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. In the above example, this URI uses the GET method to submit the topic value to Google for a search.

You can choose whether the workflow action displays in the event menu, the field menu(s), or both. You can also identify whether the link opens in the current window or a new window.

You can also arrange for the workflow action to apply only to a specific set of events. You can indicate that the workflow action only appears in events that have a particular set of fields or which belong to a specific event type or set of event types.

Example - Provide an external IP lookup

You have configured 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

POST workflow actions are set up in a manner similar to that of GET link actions. Go to the workflow action detail page and set Action type to link, set Link method to post, and define a Label and URI as appropriate.

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: Variables passed in POST link actions via URIs are automatically HTTP-form encoded during transmission. This means you can include values that have spaces between words or punctuation characters. However, if you're 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 from escaping the field value. See "Use the $! prefix to prevent escape of URL or HTTP form field values" below for more information.

These arguments are key and value combinations that will be sent to a web resource that responds to POST requests. 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.

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

You've 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:

POST wf action example.png

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 fields that you use to define the specifics of the 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) using . If left blank it runs over all time by default.

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

Example - Launch a secondary search that finds errors originating from a specific Ruby On Rails controller

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.

2. Set Action type to Search.

3. Enter the following Search string: sourcetype=rails controller=$controller$ error=*

4. Set an Earliest time of -24h. Leave Latest time blank.

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

Splunk provides 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 search job that returned the event
  • @offset - Refers to the offset of the event in the search job
  • @namespace - Refers to the namespace from which the search 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 topic=WhatisSplunkknowledge and select the Google this field and value field action. the resulting Google search is topic WhatisSplunkknowledge.

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 targeted to events that have the following fields: _cd, source, host, index.

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 to be used in workflow actions, it is often necessary to escape these fields so they can be safely passed via HTTP to some other external endpoint. Sometimes this escaping may be undesirable. In these cases, you can use the $! prefix to prevent Splunk from automatically escaping the field value. In the case of GET workflow actions, it prevents URL escape. In the case of POST workflow actions, it prevents HTTP form escape.

Example - Passing an HTTP address to a separate browser window

Say you have a GET workflow action that works with a field named http, which has fully formed HTTP addresses as values. This workflow action is designed to simply open a new browser window pointing at the HTTP address value of the http field. This won't work if the new window is opened with an escaped HTTP address. So you use the $! prefix. Where you might normally set the URI field to $http$ for this workflow action in Manager, you instead set it to $!http$ to keep the HTTP address from escaping.

PREVIOUS
Look up fields from external data sources
  NEXT
Configure workflow actions through workflow_actions.conf

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


Was this documentation topic helpful?

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.

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