webMethods API Gateway tutorial
API Gateway in 10.1 will communicates with the Digital Event Services (DES) component which runs within the API Gateway server.
Digital Event Services (DES) enables API Gateway to communicate by exchanging digital events. Digital events are typed and serialized data structures that are used to convey or record information about the execution of a runtime. This information can be application information, such as the state of a business process step, including any associated business data, or it can be system information, for example, how much memory and how many threads an application is using.
Supported Version: 10.1 onwards
Prerequisites: Install API Gateway and Integration Server with publish and subscribe enabled license on different installation directories.
About the Authors
Software AG product suite 10.1 includes a product called API Gateway, which itself runs on top of Integration Server + OSGi. Unlike other layered products of IS, API Gateway is not designed to be installed along with Mediator and CloudStreams. Also this requires a special license key for IS, which DISABLES some basic capabilities of IS – notably pub/sub. This makes API Gateway to NOT co-exist with IS (pub/sub), Mediator and Cloud Streams under single environment (same or different installation directory).
API Gateway in 10.1 will also communicates with the Digital Event Services (DES) component which runs within the API Gateway server. But Digital Event Services uses the publish-subscribe model. Applications can both emit and subscribe to streams of events of a given event type. When publishing a digital event, the originating application emits the event without considering whether other applications might receive the event, or whether the event might be archived to an event repository. On the other hand, applications that are consumers of events subscribe to digital events of a specific event type.
When events are published to DES from API Gateway, Messaging services are endpoints where events are visible. Depending on the application's capabilities to subscribe to events, we can tag the messaging service as either a destination, a source, or both. Universal Messaging services can be used to send or receive events from or to DES. To view the events published to DES from API Gateway we have to configure Universal Messaging as default service group for DES component of API Gateway.
Since API Gateway Integration Server instance will not allow us to subscribe to any event which comes to DES, we have to use separate Integration Server with pub/sub enabled on it. Both API Gateway DES component and the Integration Server instance with pub/sub enabled should be configured with single/same Universal Messaging.
The architecture diagram looks as shown below:
CONFIGURE UNIVERSAL MESSAGING FOR DES IN BOTH API GATEWAY AND INTEGRATION SERVER WITH PUBLISH/SUBSCRIBE:
Configure Universal Messaging as default service group for DES:
Go to folder location <installation directory>\profiles\IS_default\configuration\DigitalEventServices\servicegroups\ and open " service-groups.json " file. Verify that default service group is mentioned as Universal Messaging.
If not, change it to Universal Messaging by adding below lines.
Configure Universal Messaging URL for DES :
Go to folder location <installation directory>\profiles\IS_default\configuration\DigitalEventServices\services\UniversalMessaging\ and open "service-UniversalMessaging.json" file. Update the Universal Messaging URL with correct host name and port.
The file should look as shown below:
CONFIGURE UNIVERSAL MESSAGING FOR INTEGRATION SERVER FOR PUBLISH/SUBSCRIBE:
1.Configure Universal Messaging URL in on Integration Server Admin UI
2.Enable Universal Messaging and Digital Event Services connections on Integration Server Admin UI
CREATE DES DOCUMENTS ON INTEGRATION SERVER
When an event is generated from API Gateway, event will have different types of data. The types of data for each event type can be seen in event type file available in DES type repository folder. This data directly not be accessible on Integration Server. Hence the documents and parameters on the Integration Server should be created manually which will have exactly same data parameters as that of DES event type file.
API Gateway emits different event types. All the Transaction related event type files will be under "events" folder and Performance related event type files will be available under metrics folder in the below location of installation directory:
|Files under events folder||Files under metrics folder|
Note: Files name ending characters will be system generated and it may be different.
Both API Gateway and Integration Server with Publish and Subscribe installation will have same files under above mentioned location and files name will also be same.
Open each of the .dx files and create the documents with same parameters and types in Integration Server by creating same folder structure in a Package.
The package will look like as mentioned below:
Note: Attached a package (APIGatewayDES.zip) which can be used in 10.2 instances. The package has below shown doc structures and respctive triggers and services.
Except API and Application document, all other documents should be publishable set to TRUE and Connection Alias Name should be "IS_DES_CONNECTION" as shown below.
Note: Again verify the event type files names on both API Gateway and Integration Server installation directories. Both should be same, else delete all the event type files from <Integration Server installation directory>\common\DigitalEventServices\TypeRepository\eventtypes\des\apigateway\runtime folder and copy and paste again from <API Gateway installation directory>\common\DigitalEventServices\TypeRepository\eventtypes\des\apigateway\runtime folder
GENERATE DIGITAL EVENTS FROM API GATEWAY TO DES AND MONITOR ON UNIVERSAL MESSAGING ENTERPRISE MANAGER
1. Login to API Gateway as an Administrator
2. Create a SOAP API on Gateway using "Import API from URL" option by providing url: http://<GatewayISHost>:<GatewayISPort>/ws/EchoWS?wsdl
3. Edit created API and Apply "Log Invocation" Policy for the API with Digital Events as Destination.
4. Save and Activate the API on Gateway
5. Invoke API created on API Gateway with Gateway Endpoint.
6. API Gateway published events can be Snooped in Enterprise Manager by connecting to respective Universal Messaging
Note: Events from API Gateway will be pushed to DES only if the respective policies are applied for the APIs on Gateway.
TRIGGER A SERVICE IN INTEGRATION SERVER ON EVENT GENERATION FROM API GATEWAY
1. Create a flow service on Integration Server with pub.flow:tracePipeline and use respective event document as a input to print the event details on server log
2. Create a WebMethods Messaging Trigger to run the flow service on event reception to Universal Messaging from API Gateway
3. Verify the named objects on Enterprise Manager on creation of triggers in Integration Server
Note: Restart the Integration Server if the named objects are not visible in Enterprise Manager even after the successful creation on Trigger.
4. Again generate an event from API Gateway to invoke the trigger and to view the event details on Integration Server