Kyndryl Bridge

Experience Kyndryl Bridge

Create an action using GitHub
Published On Jun 14, 2024 - 10:57 AM

Create an action using GitHub

Details how to create custom actions for CAS from GitHub.
For actions to be correctly received and imported in CAS, 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.json, and action-template.json

Prerequisites

The following prerequisites must be met before creating actions using GitHub:
  • Actions are supported only by Ansible playbook or Ansible Tower (AT).
  • The playbook must be hosted in one GitHub repository.
  • GitHub provider and access via token must be available.
  • Set up the 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 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": "${_resourceInfo}.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 block. Inputs to 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.
[ { "id": "pb_aws_state_operations_on_off_restart", <--- Unique id can be "pb_<provider>_<folder-name>_<file-name>" used inside integration template "version": "1.0.0", <-- version should be used inside integration template "name": "on_off_restart.yml", <-- playbook file name "type": "playbook", "start": true, <-- true for main playbook "requires": [] <-- define other dependent playbook for them start can be false } ]
After the playbook is created and successfully tested, you need to create the action definition for
Custom action
.
the action files are properly updated, stored them in a .zip file format and follow the steps described in onboard action.
Do you have two minutes for a quick survey?
Take Survey