Create and maintain workflow actions in Manager
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
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_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_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.
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
Alternatively, you can have the workflow action appear in the event menus for those same events:
Or you can choose to have it appear in both the event menu and the field menus for events containing a
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:
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
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:
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
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.
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
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
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.
Configure field lookups
About tags and aliases
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18