We already talked about more fine grained control in an earlier WSO2 Tutorial: WSO2 API Manager – Extending the API Lifecycle with fine-grained access. But you can also change the flow within a lifecycle (change the state transition events or execution code for each state transition). In other words define what needs to be done when you change the state of an API, or even define your own lifecycle states. You can find more info on: https://docs.wso2.com/display/AM1100/Extending+the+API+Life+Cycle
In this blog we will look into the possibility to notify current subscribers of an API via email when new version has been published.
API Lifecycle
API lifecycle consists of the following:
- a set of lifecycle states
- specific actions for each state transition
- a checklist of items before a state transition occurs
Configuration is registry based, easily extendable as it is defined as a XML configuration.
Default API lifecycle configuration can be found at Extensions > Configure > Lifecycles in the management console. There you can find also Service lifecycle configuration and the difference between the two is that latter concerns artifact lifecycles and it is tied to the Governance Registry that can be installed separately from the API Manager.
Following diagram shows default API lifecycle state transition events:
Create your own lifecycle state and execution code
In order to notify all subscribers of an API that a new version has been published we need to:
- Create a custom executor that will send notification via email
- Add a new state in the API lifecycle configuration
Create a custom executor
When creating a custom executor you need to implement org.wso2.carbon.governance.registry.extensions.interfaces.Execution interface
public interface Execution {
void init(Map parameterMap);
boolean execute(RequestContext context,String currentState,String targetState);
}
All executors are initialized only once and you can pass some parameters from lifecycle configuration using parameter map. In execute() method you will implement your logic and return value should be true if execution succeeded or false otherwise.
In order to send notification email to all subscribers, in short, you need to determine the API based on request context, get all subscribers and fetch their email addresses from the claim value. Then you can send all the emails.
Once you’re done with implementation build a JAR file and place it in the /repository/components/lib folder.
Add a new state in API lifecycle configuration
Using carbon management console go to Extensions > Configure > Lifecycles and edit APILifeCycle.
For this example, we’ve added the following transition execution to the Published state:
<execution forEvent="Notify Subscribers" class="com.yenlo.apim.NotificationExecutor">
<parameter name="host" value="127.0.0.1" />
<parameter name="username" value="noreply@mail.local" />
<parameter name="password" value="P@ssw0rd" />
<parameter name="tls" value="false" />
<parameter name="port" value="55552" />
</execution>
<transition event="Notify Subscribers" target="Notified"/>
These are of course dummy values and should be substituted by values matching your SMTP server. Class attribute value should be set to the fully qualified name of your Execution implementation class.
If you do not have a SMTP server at hand (just want to test or SMTP does not work due to a firewall restrictions) you can use DevNull SMTP. This small and simple Java program will help you test this extension without actually sending emails.
And defined a new Notified state:
<state id="Notified">
<datamodel>
<data name="transitionExecution"
<execution forEvent="Block"
class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
</execution>
<execution forEvent="Deprecate"
class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
</execution>
<execution forEvent="Demote to Created"
class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
</execution>
<execution forEvent="Deploy as a Prototype"
class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
</execution>
</data>
</datamodel>
<transition event="Block" target="Blocked"/>
<transition event="Deploy as a Prototype" target="Prototyped"/>
<transition event="Demote to Created" target="Created"/>
<transition event="Deprecate" target="Deprecated"/>
<transition event="Publish" target="Published"/>
</state>
With these changes we’ve introduced a new API lifecycle state named Notified which is a copy of the default Published state so that after notifying subscribers of a new version API state can be further modified in the same way as if it was just published. By adding a new transition event into the Published state and specifying execution for this event we have enabled the transition from Published to Notified state and our custom Execution implementation will be invoked when this transition occurs.
When you introduce a new transition event to the lifecycle, you also have to add a corresponding entry to the /repository/deployment/server/jaggeryapps/publisher/site/conf/locales/jaggery/locale_default.json file (or relevant file for your language if you’ve localized your API Publisher) in order to view that lifecycle transition event in the Publisher’s Lifecycle tab. For this example we’ve added “notify subscribers” : ” Notify Subscribers” to the locale_default.json file. Note that the key value in this entry should be in lower case and matching your event attribute value from transition definition, otherwise you will see “null” value displayed on Lifecycle tab.
New state in Publisher
Once you’ve made all these changes you can open the API Publisher and check for the new state. It should look like this:
So now when you publish a new version of your API you can also notify all subscribers via email about it. The component we’ve developed could also be used to notify in cases like blocking an API (although since blocking an API is instant that might be a little late) or when an API is deprecated.
You can find the source code of our sample implementation and the complete API lifecycle configuration XML at Bitbucket: https://bitbucket.org/yenlo/notification-executor.
If you have any questions about this post contact us via the comments section of this blog. View also our other WSO2 Tutorials, webinars or white papers for more technical information.
| WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required. |  |
