Tutorial: creating resource definitions YAML

Audience

This tutorial is for CICS application developers who want to create a resource definitions YAML file that aligns with a resource model by using an IDE. The resource model is defined by a CICS system programmer, as explained in Tutorial: creating resource model YAML.

Learning objectives

You will learn:

• How to create a resource definitions YAML file.
• How to add a resource definitions schema to your IDE to help to align your resource definitions with the resource model.

This tutorial does not cover using the CICS TS resource builder import capability to analyze existing CSD resources and import resources into resource model and resource definition files. Try this in Tutorial: importing existing CSD resource definitions.

Tutorial scenario

The tutorial creates resource definitions that align with the resource model that is created in Tutorial: creating resource model YAML using VS Code as an example IDE.

Note: CICS TS resource builder schemas can be used with other IDEs, including Eclipse and Intellij.

In this scenario, you will:

• Understand the YAML structure of the resource definitions file
• Create a resourceDefinitions YAML block
• Add a resource definition based on a model-defined resource type
• Define values for attributes that are defined as mandatory in the resource model
• Add additional, non-mandatory attributes
• Add comments to your YAML
• Try out the IDE troubleshooting functions

You will use auto-complete in VS Code for YAML files that adhere to the resource definition JSON schema. You will define a resourceDefinitions YAML block, add a new resource, and add key: value pairs to define the application resource. If you have any problems, see Issue: VS Code does not display valid auto-complete options.

Find out more about VS Code in Getting started with VS Code - User Interface in the VS Code documentation.

Before you begin

• Generate a resource definitions schema from resource model YAML. For example, generate a resource definitions schema from the resource model YAML created in Tutorial: creating resource model YAML.
• Configure your IDE to use the resource definitions schema.

Understand the YAML structure of the resource definitions file

The application resources are defined in YAML by using the following YAML structure:

• Only model-defined resource types can be specified. Each resource type is a line in the resourceDefinitions YAML.
• Only attributes that are defined in the public block of the resource model YAML file can be specified. Attributes that are defined as mandatory (required: true) in the resource model YAML must be specified.

Find out more in CICS TS resource builder YAML syntax.

Create a resourceDefinitions YAML block

Create a resourceDefinitions YAML block to configure the YAML file as a resource definitions YAML file.

• Click ctrl + space to display the resourceDefinitions block.
• Click return to create the resourceDefinitions block.

Tip: If you used the steps in Configure an IDE to use a schema, the resourceDefinitions YAML block is created.

Add a new resource definition

Each resource definition is added as a new item in a list. Only model-defined resource types that are defined in the resource model YAML can be added to the resource definitions YAML file. Other resource types do not appear in the resource type auto-completion drop-down list. Adding them invalidates the resource definitions YAML file as input to the CICS TS resource builder zrb build command.

Click ctrl + space after the - dash that represents an item in the YAML list to display an auto-completion drop-down list of resources that can be defined.

Select a model-defined resource and click return to automatically create the resource as a list item.

Add values to mandatory attributes

When you add a new resource definition, any mandatory attributes are automatically added as key: value pairs on subsequent lines.

key: value pairs are used to define the value of attributes, where the key is the resource attribute type and the value is the value of the attribute. The values of the attributes must conform to:

• The values that are allowed for that type and version of CICS TS resource.
• The YAML syntax used by CICS TS resource builder YAML files.
• Any additional constraints on the prefix, pattern, or name that the system programmer specified in the resource model.

If you define a value of a resource attribute that does not align with the resource model, an error message displays. In the example, defining the group value to be WEBAPP$ results in an error String does not match the pattern of "^[A-Z0-9]+$".

Each key:value pair is nested in the resource definition, defined on a new line that is indented by 1 or more spaces. A colon and a space ": " separates the value from the key.

You must be consistent with the number of indentation spaces used for listing resources and the key:value pairs indented from the resource. Do not use tabs to indent key: value pairs.

Hover help provides a description of the model-defined resource type.

Add non-mandatory attributes

To add non-mandatory attributes to your new resource definition:

• Add a new line
• Ensure that you have used the correct indents.
• Click ctrl and space to display the non-mandatory attributes that the resource model allows to be defined. Valid attributes for defining the resource definition are tagged with a spanner icon.
• Select an attribute.
• The non-mandatory attribute is added, ready for the value to be defined.

Only attributes that are defined as public for the model-defined resource type appear as options in the attribute auto-completion drop-down list. If a non-public attribute is added to the resource definitions YAML without using the auto-completion drop-down list, the IDE returns an error message Property <property name> is not allowed".

Add another resource

To add another resource definition to your resource definitions YAML:

• Add a new line
• Add a - and ensure you have used the correct indents. If the - dash doesn't appear, you can add it.
• Click ctrl and space to display the possible model-defined resource types.
• Select a model-defined resource type.
• The model-defined resource type is added and mandatory attributes are added, ready for the values to be defined.

Add comments

You can add comments within a line or on a new line by writing a comment after a hash sign that is followed by a space # .

Try out IDE troubleshooting functions

Hover over a parameter or value to see parameter info, warning messages, and error messages. For example, the following image shows the information displayed when you hover over the group attribute.

Hover over an error that is highlighted in the file to display the problem. For example, the following image shows a problem with the value of the group attribute for a client-urimap model-defined resource. The description indicates that the name string does not match the pattern that the group value must adhere to.

In addition to hovering over the individual errors highlighted in the file, you can open the problems view to get a list of problems detected in your file.

1. Open View.
2. Select Problems from the menu. The VS Code views Terminal, Problems, Output and Debug Console display.
3. Select the Problems tab to view any error messages.

Next steps

• Explore the syntax of the resource definitions files. See CICS TS resource builder YAML syntax.