Actions
The Actions tool allows users to perform common functions within Cortex, 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 developer might use Actions to deploy backend to production, hitting the GitHub API in order to do so.
You can access Actions from the main nav.
You can find all actions available to run in the Actions tab. Under My Execution History, you'll find all the actions you have initiated.
Creating an action
Click Create Action next to the search bar to create an action. While all users can run an action, only managers and admins can create 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 could 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.
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.
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:
- Global: The created action will be 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.
- Entity: The created action is tied to a specific service, which means a user will need to select an entity when running that action. For example, deployment would be an entity action, since it is tied to a specific service or resource.
Actions with a Global filter cannot include the template {{context.entity.*}} because there is no targeted entity. Including this information will cause the action to fail.
If you select Entity, you can then filter the specific types of entities that the Action applies to.
Under Permission, 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.
Cortex recommends testing an 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 and 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 directly from an entity's details page. Select Actions from the side nav.
Global actions and entity-based actions that apply to a given entity will be available on this page.
Select the action you want to trigger for that entity and fill out the appropriate fields. When you run an entity-based action from an entity's 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 on that page.
This will show admins who ran an action, as well as all of the other relevant information. Admins also have the ability to edit and run an action from this page.