The Actions feature in Cortex enables users to perform common functions within the portal, such as deploy a service, file a ticket, get an access token, or provision resources. Actions is designed to make it easier for developers to accomplish day-to-day activities and trigger different actions from a single place.
Actions are essentially a way to hit APIs with a configured payload based on a service. This works regardless of whether you’re calling an internal API, external API, GitHub API, or any webhook URLs. For example, a Cortex developer might use Actions to deploy our backend to production, hitting the GitHub API in order to do so.
You can access Actions from the menu at the top of the portal. The Actions page has two views: Actions, which presents a list of all action types, and My Execution History, which offers a view into all of the actions you have initiated in Cortex.
Creating an action
To create an action, go to the Action page and select Create Action next to the search bar. Only managers and admins have the ability to create an action, but all users have the ability to run an action.
First, enter a human-readable name for the action. You also have the option to provide a description for the action.
You then have the option to define action inputs — these are the fields that a user sees or has to fill out before running an action. While not required, action inputs are helpful for developers.
You have four options for input types:
- Dropdown: selection from multiple fields
- Input: short text field
- Textarea: long text field
- Toggle: boolean true/false operation
If you were creating a “deploy to production” action, you might use a dropdown for a developer to select an environment to deploy to, an input for them to enter the branch, and a toggle to determine whether to send a notification, for example. All of this information will be sent in the payload to the API you’re trying to hit.
When you add an input, the name you choose will create a key, or a unique identifier for the input field — this will be used later on to create your templatized payloads for APIs. At this point, you can also determine whether a field is required to trigger an action.
Once you’ve named your action and defined its inputs, you’ll configure the payload for your action in the Action definition section. The first step is selecting the HTTP method: DELETE, GET, PATCH, POST, or PUT. If there’s a target URL, enter that under URL at this stage as well.
In Headers, you’ll enter the HTTP headers for your action. Cortex has included some quick links to common headers below the header fields.
Let’s say you want to add a token — under Header Key, you’d enter Authorization, and under Header Value, you’d enter Bearer followed by your HTTP token. It’s safe to enter API keys in the header fields because these are encrypted, just like tokens are stored for other integrations in Cortex.
The next step is defining the payload. If you are appending custom data to a specific service, you’ll first define the hardcoded key for your action. The values in your payload are dynamic, which allows you to templatize based on inputs. Cortex uses a templating framework called mustache, which allows you to use the input key you created earlier to generate the payload with the specific values entered by a user when triggering an action.
Note: You can use the same function to templatize service names in the URL at this stage. This allows you to make an API call to Cortex based on a service tag.
The next stage is setting Filters. First, select the Filter type:
- A Global action is accessible from the main Actions page and is not necessarily tied to a specific service. For example, filing a security issue in Jira would be a global action, since there is no reason that action must be connected to a specific service.
- An Entity-based action is tied to a specific service, which means a user will need to select an entity when running that action. For example, deploying would be an entity action, since it is tied to a specific service or resource.
If you select Entity, you also have the ability to filter further by Category and groups. You’ll use Category to decide whether the action applies to services or resources. You can also filter the action by groups.
Under Permissions, you’ll define who can run an action. Select Admin if you want only admins to trigger an action; select All if all users can trigger the action.
The last step is deciding whether to save your action in Draft status. Like with permissions, only admins can view an action in draft status, while all users can see published actions. We recommend testing the action in draft status a few times before publishing, so you can be sure the payload works properly before it’s available to all users.
Running actions & viewing execution history
You can run an action by selecting any of of the available options from the Actions page — clicking an action name will open a modal where you can enter the appropriate inputs.
You can also run an action from a specific service’s page by selecting Actions from the left-hand menu.
Select the action you want to trigger for that entity and fill out the appropriate fields. When you run an entity-based action like Deploy from a service or resource page, the entity name will already be filled out for you.
When you select Run Action, Cortex will display the loading state for your action, as well as the final response from the API, so you know whether the action succeeds or fails.
This is the same information you’ll find in Execution History — this tab displays all of the actions that you have run, as well as the status of each of those actions.
Click any of the actions in Execution History to view the request you made: the expanded view will display headers, the body of your action (the final payload), the entity associated with the action (if entity-based), and the API response. If your action fails, Cortex will display an error message.
Admins can also see the global history for each action by clicking an action and navigating to the History tab within that page.
This will show admins who ran an action, as well as all of the other relevant information. Note that admins also have the ability to run an action from this page.