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.
- 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:
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.