Create an action using GitHub
For actions to be correctly received and imported in Common Actions, the user needs to follow the following structure. The folder structure must contain the path where actions are stored. Each action must include three Json files: action-configuration.json, action-definition.jsonand action-template.json
Prerequisites
The following prerequisites must be met before creating actions using GitHub:
- Use only Ansible playbook or Ansible Tower (AT) to support actions.
- Host the playbook in a single GitHub repository.
- Configure GitHub provider access with a token.
- Set up access and job templates for AT.
Creating a custom action
Actions are divided into four component files:
Action Definition, Action Template and Action Configuration files must have the same version. Make sure the version is updated in all three files. Only one version can be published. However, multiple versions can be stored in draft state. To publish with a different version, retire and delete the old version first.
Action definition
This file allows you to define the important properties for a custom action.
Property | Type | Description |
|---|---|---|
actionConfigParams | Boolean | Action configurations are needed or not for the particular action. |
actionDefinitionId | String | Action is identified using actionDefinitionId . Used for mapping between action definition and action template. |
actionDefinitionVersion | Object | Describes version of action using id and label as key properties. |
actionDefinitionDisplayLabel | String | Action label to be displayed on UI. Used as a mapping between action definition and action configuration |
actionType | String | Supported action types are : provisionNew, viewOnly, basic, configChange, global, stateChange, deprovision, serviceRequest, incident . |
approvalStepRequired | Boolean | Is approval required or not. |
associatedTo | Object | Used to create association between action and particular resource type. resourceFamilies property is used to specify resourceFamily (resource type) of resource to which action needs to be attached. |
context | Object | Specifies context of the action. |
costImpact | Boolean | Cost impact of the action. |
description | String | Action Description. |
mcmpApplication | List | List of applications in which action needs to be present. eg. [ "mcmp:common:service", "mcmp:aiops:service" ] |
provider | Object | Content and target provider details using contentProvider and targetProvider as key properties. |
fulfillmentRoutingKey | String | Fulfillment Routing Key. |
status | String | Status of the action. |
systemConfigs | String | Any system configurations required. |
serviceType | String | Service type of the action. |
actionDefinitionRetriableTTL | String | Time to live in minutes for action definition retry. |
isRetriable | String | Is action retriable? Possible values are "true" or "false" . |
Action configuration
This file allows you to enable user pass inputs while performing any action.
Property | Type | Description |
|---|---|---|
configGroup | List | List of configuration groups. Currently only one configuration group is supported. |
configGroupName | String | Name to be displayed for configuration group on UI. |
configGroupCode | String | Unique identification code for configuration group. Used as a mapping between action configuration and action definition. |
configGroupSequence | Number | Sequence of configuration group. Starts with 0 . |
visibilityRules | List | Visibility Rules if any. |
configs | List | List of the configurations under a particular configuration group. |
configId | String | Unique identifier for the configuration. Should match with binding |
hidden | Boolean | The configuration can be hidden or not. |
isRequired | Boolean | The configuration can require input or not. |
editable | Boolean | This input can be editable or not. |
configName | String | Config/Input name to be displayed on UI. |
binding | String | Unique identifier for binding the input. Used to get value of input in action template. Should match with configId . |
description | String | Description of input field. Shown in ⓘ icon. |
inputType | String | Type of the input field. eg. freetext, selectOne |
sequence | Number | Sequence of config/Input. Starts with 0 . |
values | List | The values/options to select in the dropdown. Should be used only in case of inputType : selectOne . Key properties are valueId, value, label . |
default | Object | Default value for the input. Key properties are valueId, value, label . |
validation | String | RegEx based validation for input fields. |
errorMessage | String | Error message to be displayed if validation fails. |
derives | List | Configurations which can be derived from current configuration/input. |
Action template
This file allows you to specify the playbook and playbook inputs.
Property | Type | Description |
|---|---|---|
actionDefinitionId | String | Action is identified using actionDefinitionId . Used for mapping between action definition and action template. |
refid | String | Reference Id of action template |
provider | Object | Content and target provider details using contentProvider and targetProvider as key properties. |
description | String | Base64 encoded template is stored in description. |
The base64 encoded template has following properties:
Property | Type | Description |
|---|---|---|
actionTemplate | Object | Type of template. The fix value is: actionTemplate . |
ansiblerunner | Object | Template is run using ansible runner. This is a fixed value. |
playbookName | String | Relative path to the playbook file. |
playbookPath | String | URL to the repository. |
folderName | String | Relative path to the playbook folder. |
branchName | String | Optional parameter. GitHub branch from which playbook is to be fetched. Default branch is master . |
variables | List | List of input parameters to the playbook in form of object with key, value pair. eg. [{ "name": "req_action", "value": "update" },{ "vnet_name": "req_action", "value": "$.resourceName" }] |
Action catalog metadata
The metadata of action definition, action configuration and action template are stored in the action catalog metadata file.
Property | Type | Description |
|---|---|---|
provider | Object | Content and target provider details using contentProvider and targetProvider as key properties. |
sourcePath | String | Path of source actions folder. |
providerOfferingTypes | List | List of provider offering types. |
serviceOfferings | List | List of catalogs if any. |
operations | List | List of Operations if any. |
actions | List | List of actions in form of object containing action definition, action configuration and action template with jet properties as definition, configurationFile and templateFile respectively. |
Creating an Ansible playbook
This playbook is run based on the req_action. The required Ansible module, along with its input properties, is used inside a block. Inputs to the Ansible playbook are passed from the action template.
Name | Type | Description |
|---|---|---|
name | String | Name of the playbook. |
hosts | String | Type of device where you are working on. |
connection | String | Type of host connection. |
proxy_env | String | Production environment for HTTP or HTTPS protocol. |
set fact | String | Actual action that will be included in the playbook. |
| | |
subscription_id | String | Unique id for the Azure subscription. |
tenant | String | Instance. |
secret | String | Combination of up 40 characters. |
client_id | String | Application id. |
resource_group | String | The group where the resource belongs to. |
virtual_network_name | String | Name of the virtual network. |
service_endpoints | String | Entity that can be referenced. |
environment | String | Environment in provider. |
ignore_errors | String | Request to ignore errors. |
If any changes are done in playbook, make sure to manage the version. The version should be increased on the metadata file and the integration template afterwards. Finally, make sure to update the actions definitions and actions configurations file.
After the playbook is created and successfully tested, you need to create the action definition for Custom action. After the action files are properly updated, store them in a .zip file format and follow the steps described in Onboarding by discovery