Manifest contents for a CICS bundle

Each CICS® bundle contains a bundle manifest that describes the contents of the bundle. A bundle manifest describes the bundle, which resources to design or modify in the CICS region when provisioned, and dependencies required for the CICS bundle to successfully enable.

The manifest for a CICS bundle is called cics.xml and is in the META-INF subdirectory. The bundle manifest is written in XML and conforms to a schema. For more information, see Vendor interfaces. The bundle manifest is encoded in UTF-8 and contains information about the bundle itself, as well as bundleparts (the definitions, exports, imports, application entry points, and policy scopes provided by the bundle).

Bundle information

The manifest contains an optional <meta-directives> element that contains information about the bundle; for example, it can contain a time stamp of the time when the bundle was created.

The manifest also includes details on the version information of the CICS bundle.

Definitions

The <define> element defines CICS resources that will be managed by the CICS bundle. Each resource definition includes:

A name for the artifact.
A resource type that is defined as a URI.
A relative path location to a file in the bundle. The file contains metadata for the resource.

Some definitions lead to CICS creating one or more resources dynamically; for example a http://www.ibm.com/xmlns/prod/cics/bundle/EVENTBINDING resource type creates an EVENTBINDING resource and one or more CAPTURESPEC resources. Other definitions, such as the http://www.ibm.com/xmlns/prod/cics/bundle/POLICY resource type, are used by CICS only in runtime processing and have no equivalent CICS resource definition.

CICS provides a registration and callback interface for users who wish to manage non-CICS resources, alongside those provided by CICS. For more information, see Containers used in the callback interface and Artifacts that can be deployed in bundles.

Exports

The <export> element provides additional information about the resources or services that a bundle can provide. CICS does not use export statements in its processing of bundles. Exports that have been specified can be viewed in provisioned CICS bundles using SPI, CMCI, and tooling such as the CICS Explorer®.

Imports

The <import> element defines dependencies to other resources that are required by the bundle. Each dependency has a name and a type, but no path attributes. The dependency also has an attribute that describes how CICS handles the BUNDLE resource installation if one of the required imports is not present in the CICS region. The BUNDLE resource can remain disabled, enable with warning messages, or enable with no warnings. The default behavior is that all imports are required; the BUNDLE resource can be installed but not enabled.

In a CICS bundle that is packaged as part of an application deployed on a platform, public or private resources can be defined as dependencies, including private programs that are autoinstalled by an application. CICS checks first for a private resource with the specified type and name in the same application as the CICS bundle that contains the <import> element in the bundle manifest file. If more than one version of the application is installed, the current application context determines the version of the private resource that is imported. If the resource is not found as a private resource for the application, CICS checks for a public resource in the CICS region that matches the specified type and name, and imports that resource. You cannot import private resources from other applications.

Users can extend the <import> list to include their own user resource types. For more information, see Artifacts that can be deployed in bundles

Application entry points

If your CICS bundle is part of a CICS application, you can define one or more application entry points in the bundle manifest. An application entry point identifies a resource that is an access point to an application. Application entry points are used to control users' access to different versions of an application that is deployed on a platform. They are also used to create an application context to monitor the resource usage for applications and to identify an application being run.

The <entrypoint> element in the <modify> element defines an application entry point. The bundle manifest can contain 0 to many <modify> elements for application entry points. The <entrypoint> element specifies the name of the CICS resource, the type of resource, and the application operation. It is possible to specify an application entry point for a resource that is not managed by that CICS bundle.

Policy scopes

A policy scope is used to limit a policy to a specific application operation. When a policy is deployed with an application scope, the policy applies to all user tasks with matching platform, application and application version information in their application context. A policy scope is used to further limit a policy to only those user tasks that also match the operation.

The <policyscope> element in the <modify> element defines a policy scope for a policy. The bundle manifest can contain 0 to many <modify> elements for policy scopes. The <policyscope> element specifies the name of the application operation and the name of the policy to apply to user tasks for that operation. The name of the operation must be defined by a separate <entrypoint> element and the policy must be defined by a <define> element either in the same bundle or in a separate bundle which is deployed with the bundle defining the policy scope.

Example of a manifest

The following example shows a manifest for a CICS bundle that contains a program definition that is also an application entry point, together with a policy and policy scope for user tasks for that application entry point.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<manifest xmlns="http://www.ibm.com/xmlns/prod/cics/bundle" bundleVersion="1"
    bundleRelease="0" build="IntB-201705232112">
    id="CustomerRecordsStore"
    bundleMajorVer="1"
    bundleMinorVer="200"
    bundleMicroVer="4"                     1 
    <meta_directives>
        <timestamp>2018-01-25T14:59:32.092Z</timestamp>
    </meta_directives>                     2 
    <import
        name="ADDC"
        type=http://www.ibm.com/xmlns/prod/cics/bundle/TRANSACTION
        optional="false" warn="false"/>    3 
    <define
        name="ADDCUST"
        type=http://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM
        path="ADDCUST.program"/>           4 
    <define
        name="CUSTLIB"
        type=http://www.ibm.com/xmlns/prod/cics/bundle/LIBRARY
        path="CUSTLIB.library"/>           5 
    <define
        name="NewCustomer"
        type=http://www.ibm.com/xmlns/prod/cics/bundle/POLICY
        path="NewCustomer.policy"/>        6 
    <modify>
        <entrypoint
            name="ADDCUST"
            type=http://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM
            operation="add_customer"/>     7 
    </modify>
    <modify>
        <policyscope
            name="NewCustomer"
            type=http://www.ibm.com/xmlns/prod/cics/bundle/POLICY
            operation="add_customer"/>     8 
    </modify>
</manifest>

Contains information on the bundle project including the bundle ID and bundle version.
The meta directives element contains the date and time the bundle was created.
The bundle imports a transaction resource that must be present and enabled in the provisioned system to enable this CICS bundle. This CICS bundle does not declare or manage the transaction resource.
The bundle defines a PROGRAM resource, including the name of the resource and the path to the XML file that defines the resource attributes.
The bundle defines a LIBRARY resource to dynamically load the defined PROGRAM, including the name of the resource and the path to the XML file that defines the resource attributes.
The bundle defines a POLICY resource, including the name of the policy and the path to the XML file that defines the policy attributes.
The bundle declares a PROGRAM resource as an application entry point for a particular operation.
The bundle declares that the POLICY is to be applied only to tasks which match the specified operation.