Planning a JSON service provider application

In general, CICS® applications should be structured to ensure separation of business logic and communications logic. Following this practice will help you to deploy new and existing applications in a web service provider in a straightforward way. You will, in some situations, need to interpose a simple wrapper program between your application program and CICS web service support.

Figure 1 shows a typical application which is partitioned to ensure a separation between communication logic and business logic.
Figure 1. Application partitioned into communications and business logic
A client interacts with communications logic in CICS Transaction Server, the communications logic issues an EXEC CICS LINK command to link to the business logic.
In many cases, you can deploy the business logic directly as a service provider application. This is illustrated in Figure 2.
Figure 2. Simple deployment of CICS application as a web service provider
A client interacts with web service support in CICS Transaction Server; web service support links to the business logic.
To use this simple model, the following conditions apply:
When using z/OS® Connect Enterprise Edition to generate the mapping between a JSON schema or Swagger document and application data structures:
z/OS Connect Enterprise Edition supports a broader range of application copybook structures than are supported by the CICS assistant. In most cases those copybooks will be supported unchanged. If not, you might interpose a wrapper program between the z/OS Connect Enterprise Edition service and your business logic. For more information, see z/OS Connect Enterprise Edition product documentation.
When you are using the CICS assistant to generate the mapping between JSON schema and application data structures:
The data types used in the interface to the business logic must be supported by the CICS assistant. If this is not the case, you must interpose a wrapper program between CICS web service support and your business logic.

You will also need a wrapper program when you deploy an existing program to provide a service that conforms to an existing web service description: if you process the web service description using the assistant, the resulting data structures are very unlikely to match the interface to your business logic.

When you are not using the CICS assistant:
Message handlers in your service provider pipeline must interact directly with your business logic.

Using a wrapper program

Use a wrapper program when the CICS assistant cannot generate code to interact directly with the business logic. For example, the interface to the business logic might use a data structure which the CICS assistant cannot map directly into a JSON message. In this situation, you can use a wrapper program to provide any additional data manipulation that is required:

Figure 3. Deployment of CICS application as a web service provider using a wrapper program
A client interacts with web service support in CICS Transaction Server; web service support links to a wrapper program; the wrapper program issues an EXEC CICS LINK command to link to the business logic.

You will need to design a second data structure that the assistant can support, and use this as the interface to your wrapper program. The wrapper program then has two simple functions to perform:

  • Move data between the two data structures.
  • Invoke the business logic using its existing interface.

Error handling

If you are planning to use the CICS assistant, you should also consider how to handle rolling back changes when errors occur. When a JSON request message is received from a service requester, the JSON message is transformed by CICS just before it is passed to your application program. If an error occurs during this transformation, CICS does not automatically roll back any work that has been performed on the message. For example, if you plan to add some additional processing on the JSON message using handlers in the pipeline, you need to decide if they should roll back any recoverable changes that they have already performed.

On outbound JSON messages, for example when your service provider application program is sending a response message to a service requester, if CICS encounters an error when generating the response JSON message, all of the recoverable changes made by the application program are automatically backed out. You should consider whether adding synchronization points is appropriate for your application program.