Tutorial: creating resource model YAML

Audience

This tutorial is for CICS system programmers who want to create resource model YAML.

Learning objectives

You will learn:

• How to create a resource model as a single resource model YAML file that contains both a resourceModel YAML block and application YAML block.
• What a resource definitions file that aligns with the resource model might look like
• How to define model-defined resource types and application-specific constraints.
• How model-defined resource types can be used as logical subsets of CICS resource types for extra flexibility in the resource model
• How the set of resources that the resource model allows a CICS application developer to define and any constraints on resource attributes are exposed to a CICS application developer in their IDE (if the CICS application developer uses a resource definitions schema generated from the resource model YAML).

This tutorial does not cover:

• Separating the application YAML from the resourceModel YAML into application constraint files. See Creating an application constraints YAML file.
• Ways of adding resource definitions to groups and lists. See Defining groups and lists.
• Using the supplied resource model schema in an IDE to create YAML. See Configuring an IDE to use a schema.
• 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 is based on creating a resource model that restricts an application developer to defining two types of CICS URIMAP resources:

• A model-defined resource type for calling outbound URIs, client-urimap.
• A model-defined resource type for calling URIs in CICS, server-urimap.

Prefix and pattern constraints for some values are defined at the application level for an application named CICS Sandpit Application.

The effect of the resource model on the IDE experience of a CICS application developer is shown by using VS Code as an example IDE.

In this scenario, you will:

• Understand the YAML structure of a resource model file.
• Create a resourceModel YAML block
• Add model-defined resource types
• Expose resource attributes to the application developer
• Constrain resource attribute string values to use prefixes and patterns
• Add an application YAML block
• Define resource attribute values that cannot be modified by an application developer

The scenario also shows what the application developer sees as a result of your actions.

Before you begin

Optionally, if you want to use the supplied resource model schema with an IDE to create the resource model, configure your IDE to use the resource model schema.

Understand the YAML structure of the resource model file

The resource model is defined in the YAML by using the following YAML structure:

• The schemaVersion attribute. This defines which version of the resource model schema the model was created against.
• All resource types that can be defined as resource definitions are known as model-defined resource types . In the defines YAML block of the resourceModel block, each model-defined resource type is added as a YAML block with an associated id property. When an application resource is defined in the resource definitions YAML, the value of the id is used to select the model-defined resource type required.
• Resource attribute constraints are defined by using key: value pairs.
• Application-specific prefixes, patterns, and values are defined in a constraints block within an application block, with each constraint added on a new line.

Find out more in CICS TS resource builder YAML syntax.

Define schemaVersion

Define the version of the resource model schema to be used using the schemaVersion attribute . Currently there is only one choice: resourceModel/1.0

schemaVersion: resourceModel/1.0

Create a resourceModel YAML block

Create a resourcemodel YAML block to configure the YAML file as a resource model YAML file. Define the target for the YAML defined resource definitions as CICS Transaction Server for z/OS® 6.1:

schemaVersion: resourceModel/1.0
resourceModel:
  target: cicsts-6.1.0

Add model-defined resource types

Model-defined resource types give you extra flexibility in defining standards. You can have multiple model-defined resource types for one type of CICS resource, giving you logical subsets of resource definitions based on their attributes.

Define a URIMAP resource as a model-defined resource type by creating a defines YAML block of type: urimap. As more than one standard for URIMAP resources is required, use the id property to label the first of the two standards as client-urimap:

schemaVersion: resourceModel/1.0
resourceModel:
  target: cicsts-6.1.0
  defines:
    - id: client-urimap
      description: For calling outbound URIs
      type: urimap

Define a second URIMAP model-defined resource type. Add another defines block to identify the other URIMAP standard as server-urimap:

schemaVersion: resourceModel/1.0
resourceModel:
  target: cicsts-6.1.0
  defines:
    - id: client-urimap
      description: For calling outbound URIs
      type: urimap
    - id: server-urimap
      description: For mapping URIs of incoming HTTPS requests
      type: urimap

Tip: Why are the resource type and attributes shown as uppercase in the text but in lowercase in the YAML example? By convention, CICS resource types and attributes are shown in CICS documentation in uppercase to distinguish them from regular English words. Enter them as shown in the example YAML.

Application developer

By adding the URIMAP resource definitions as model-defined resource types in the resource model YAML and generating a resource definitions schema for the application developer, the permitted resources are exposed by auto-completion in the IDE. The developer selects one of the two model-defined types:

The description that you added surfaces for the application developer in the hover help.

Expose resource attributes to the application developer

Add an attributes YAML block for the model-defined resource type.

The resource model uses an opt-in model. Only those attributes that are listed in the public YAML blocks of the model-defined type can be defined by the resource definitions YAML file that the application developer creates.

Add a public YAML block to the client-urimap model-defined resource type. Define the name, group, and path attributes as mandatory for the server-urimap model-defined resource type. You do this by adding the attributes to the public YAML block and setting the required key to true. Add the description attribute as optional for the server-urimap model-defined resource type by setting the required key to false.

schemaVersion: resourceModel/1.0
resourceModel:
  target: cicsts-6.1.0
  defines:
    - id: client-urimap
      description: For calling outbound URIs
      type: urimap
      attributes:
        public:
          name: 
            required: true
            description: Specfiy the name of URIMAP for outbound URIs
          group: 
            required: true
            description: Specify the name of the RDO group
          description: 
            required: false
          path:
            required: true
            description: Specify path component of client URIs

Application developer

Any description that you define for a public attribute is added to the IDE hover help generated for that attribute.

The following example shows a resource definitions YAML file that aligns with the current resource model:

resourceDefinitions:
  - client-urimap:
      name: APCLNT01
      description: URIMAP for calling outbound URIs
      group: WEBAPP
      path: /apclnt01

Application developer

If the resource definitions schema, generated from the resource model, is imported into an IDE, the IDE has the following behavior:

• When a new line is added to define a new resource type, the auto-completion function displays a list of the model-defined type client-urimap and server-urimap.

• If the client-urimap model is selected, the mandatory fields name, group, and path are added to the YAML. The optional field description is not automatically added, but is available in the auto-completion list when an additional attribute is added to a new line in the attributes block. Other resource types and attributes do not appear with auto-completion.

If a resource type is specified in the resource definitions YAML that is not included as a model-defined resource type in the resource model, or a resource attribute is specified that is not defined as a public attribute in the resource model, an error message is shown.

Constrain resource attribute values to use prefixes or patterns

You can constrain string attribute values of a model-defined resource type to a prefix or regex pattern. The constraint applies to that model-defined type for all applications. You can define constraints that apply only to an application; see Add an application YAML block.

By using key: value pairs within the resource attributes block, add constraints to the client-urimap:

• All name values must start with the characters AP.
• All group values used for calling outbound URIMAPs must match the regex pattern "^[A-Z0-9]+$", which constrains the value of the string to include only numbers 0 to 9 and uppercase characters A to Z.

For example:

schemaVersion: resourceModel/1.0
resourceModel: 
  target: cicsts-6.1.0
  defines:
  - id: client-urimap
    description: For calling outbound URIs
    type: urimap
    attributes:
      public:
        name: 
          required: true
          prefix: "AP"
          description: Specfiy the name of URIMAP for outbound URIs
        group: 
          required: true
          pattern: "^[A-Z0-9]+$"
          description: Specify the name of the RDO group
...

Add an application YAML block

You can define prefix, pattern, and value constraints at the application level by using the application YAML block. For example, you can define that the name of all URIMAP resource definitions that are associated with a particular application must begin with the prefix AP.

For this scenario, you simply create the application YAML in the same resource model YAML file as the resourceModel YAML. Typically, you create the application YAML in separate application constraints files.

1. Create an application YAML block to define application-specific standards for the CICS Sandpit Application and define the mandatory name property:

    application:
    name: CICS Sandpit Application

2. Constrain the name and group attributes of the client-urimap resource type to the prefix and pattern values. You do this by defining constraint identifiers in a constraints block. Define the id of the constraint identifiers as app-prefix and group-name.
3. Now you can reference the constraints by their identifiers in the model-defined resource type. In the resourceModel YAML, change the prefix: "AP" property of name to constraintId: app-prefix and change the pattern: "^[A-Z0-9]+$" property of group to `constraintId: group-name.

schemaVersion: resourceModel/1.0
application:
  name: CICS Sandpit Application
  constraints:
    - id: app-prefix
      prefix: AP
    - id: group-name
      pattern: "^[A-Z0-9]+$"
      
resourceModel: 
  target: cicsts-6.1.0
  defines:
  - id: client-urimap
    description: For calling outbound URIs
    type: urimap
      attributes:
        public:
          name:
            required: true
            constraintId: app-prefix
            description: Specfiy the name of URIMAP for outbound URIs
          group:
            required: true
            constraintId: group-name
            description: Specify the name of the RDO group

Define resource attribute values that cannot be modified by an application developer

Attributes that are defined in a private block of the resource model YAML cannot be defined or overridden in the resource definitions YAML file. Instead, any attributes and their values that are defined in the private block of the resourceModel YAML are added to the DFHCSDUP commands file that is generated by the CICS TS resource builder zrb build command.

Create a private block for the client-urimap model-defined resource. Define the following resource attribute values:

        private:
          host: 10.11.12.13
          usage: CLIENT
          status: ENABLED
          scheme: HTTPS

Any URIMAP resources defined in the resource definitions YAML file that align with the client-urimap model-defined resource type are built into the DFHCSDUP input commands file with the values that you set in the private block: HTTPS URIMAPs for CLIENT usage with status of ENABLED and HOST 10.11.12.13. The host, usage, status, and scheme attribute values cannot be altered by the resource definitions YAML file. There are two checks that these values are not modified:

• In the application developer's IDE if the resource definitions schema is used.
• When the DFHCSDUP commands file is built by the zrb build command.

Application developer

When creating resource definitions YAML, if the resource definitions schema is imported into an IDE, the host, usage, status, and scheme attributes do not display in the auto-completion menu. If the attribute is added without using auto-completion, the IDE returns an error message "Property <property name> is not allowed".

Add public and private attributes to the server-urimap model-defined resource type

Now that you have created the single resource model YAML file that is application-specific for the CICS Sandpit Application and defined and constrained the the client-urimap model-defined resource type, you can now add some public and private attributes to the server-urimap model-defined resource type. For example:

schemaVersion: resourceModel/1.0
application:
  name: CICS Sandpit Application
  constraints:
    - id: app-prefix
      prefix: AP
    - id: group-name
      pattern: "^[A-Z0-9]+$"

resourceModel:
  target: cicsts-6.1.0
  defines:
    - id: client-urimap
      description: For calling outbound URIs
      type: urimap
      attributes:
        public:
          name: 
            required: true
            constraintId: app-prefix
            description: Specfiy the name of URIMAP for outbound URIs
          group: 
            required: true
            constraintId: group-name
            description: Specify the name of the RDO group
          description: 
            required: false
          path:
            required: true
            description: Specify path component of client URIs
        private:
          host: 10.11.12.13
          usage: CLIENT
          status: ENABLED
          scheme: HTTPS
    - id: server-urimap
      description: for mapping URIs of incoming HTTPS requests
      type: urimap
      attributes:
        public:
          name: 
            required: true
            constraintId: app-prefix
          group: 
            required: true
            constraintId: group-name
          description: 
            required: false
          path:
            required: true
          program: 
            required: true
            constraintId: app-prefix
        private:
          usage: SERVER
          host: "*"
          status: ENABLED
          scheme: HTTPS
          transaction: CWBA

Next steps

• Generate the resource definitions JSON schema from the resource model, see Generating a resource definitions schema. The generated resource definitions schema is used by the application developer to create and validate resource definitions YAML that is restricted to your resource model.
• Extend your resource model by defining groups and lists for the resource definitions. See Defining groups and lists.
• Explore the syntax of the resource model files. See CICS TS resource builder YAML syntax.
• Try one of the other tutorials:
• Creating resource definitions YAML. This is what the application developer does to define application resources.
• Importing existing CSD resource definitions. This creates a resource model from resource definitions that have been extracted by DFHCSDUP from an existing CSD.