WSO2 API Manager 1.10.0 - API Lifecycle management based on user roles

WSO2 API manager user tasks can be categorized under three main  user roles. They are creator, publisher and subscriber. See Adding User Roles section in the product document for more information. Users with the creator and publisher roles can log in to the API manager publisher application and work on the API creation and management. 

Users with publisher permissions can change the lifecycle states of an api. He can deprecate the api, or block the api or even retire the api. From API Manager 1.10 onward, user can limit this capability and assign their own roles for this lifecycle state management. This way if someone does not want a user with only publisher permission to block an api, he can do it with API Manager 1.10.0 easily using the Custom Lifecycle Inclusion feature.

Scenario

The owner of the api does not want to give every one the permission to put his API in to Blocked state. He wants to assign it to a separate group. 

Steps:

1. Create a new role. 

See Adding User Roles. Here I create a new role "blockrole" for this scenario. You can assign any permission for this. I'll keep that empty since the grouping is done based on the role name.

2. Modify the existing lifecycle.  

For that Log in to API manager management console (https://localhost:9443/carbon) and navigate to 

Home

> Extensions

> Configure

> Lifecycles section and edit 'APILifeCycle' resource. See Extending the API Life Cycle

Update the 'Published' state with the following

      <state id="Published">

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

                        

                  <data name="transitionPermission">

                     <permission forEvent="Block" roles="blockrole" />

                  </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>

Note the newly added data element "transitionPermission" . The newly created role "blockrole" is assign for the event "Block".  

      <data name="transitionPermission">

          <permission forEvent="Block" roles="blockrole" />

      </data>

Test

Now log in to the API manager publisher (I will use the default admin user for this.)  and publish an api. Then go to the Overview section of the api and select the 'Lifecycle' tab and you will notice that the "Block" Operation is not there anymore.

The reason for this is the user admin does not have the role "blockrole". Now Log in the the Management console and assign the role "blockrole" to the admin user refresh the Lifecycle tab in the API manager publisher. You will notice the "Block" button in the tab.

You can extend this feature to provide different roles for different API Lifecycle states.

WSO2 API Manager 1.10.0 - Introducing a custom Lifecycle to an API

WSO2 API Manager 1.10.0 comes with many new features. One of them is the facility to attach custom lifecycle to an API. API manager before 1.10 had only CREATED, PUBLISHED , DEPRECATED, RETIRED , BLOCKED, PROTOTYPED states for an api. With the new version, user can attach more states to an api.

WSO2 api manager uses WSO2 Governance registry Lifecycle features to implement this.  You can get more information about this from the Extending the API Life Cycle section in WSO2 api manager documentation

I'll use this feature to implement a scenario where user sends a notification about  a state change of an api.  this will implement a scenario where user sends an email notification to the business owner of the api when he retires the api.

Main steps:

1. Create a custom executor to handle the custom state change.

When creating a custom executor you have to use org.wso2.carbon.governance.registry.extensions.interfaces.Execution interface for the implementation and implement execute()method


import java.util.Map;
import org.wso2.carbon.governance.registry.extensions.interfaces.Execution;
import org.wso2.carbon.registry.core.jdbc.handlers.RequestContext;

public class CustomExecutor implements Execution {

    String param;

    @Override
    public boolean execute(RequestContext context, String currentState, String targetState) {
        if(something){
            return true;
        } else {
            return false;
        }
    }

    @Override
    public void init(Map arg) {
     param = (String) arg.get("param");

    }
}

For this scenario I created an executor to send email. See MailExecutor.java. You can pass parameters to the executor through the lifecycle.  Refere following property definition in the lifecycle on how this is done (In the next section)

<parameter name="emailUsername" value="xxxxxxxxxx" />

<parameter name="emailPassword" value="xxxxxxxxxx" />

I followed http://crunchify.com/java-mailapi-example-send-an-email-via-gmail-smtp/ when creating the email sender. 

If you are interested in how the default executor works you can refere source code for the default executor org.wso2.carbon.apimgt.impl.executors.APIExecutor in here. 

Once you created the custom executor, build .jar and deploy it in the wso2am-1.10.0/repository/components/lib location. 

I attached the sample custom-executor.zip for the reference

2. Create a custom lifecycle and deploy it.

First log in to Carbon management console and update the lifecycle configuration. Please refer  Extending the API Life Cycle on how to access that resource.

For this I use the default lifecycle and removed the "Deprecated" section and add the following section. Full lifecycle xml can be found in here

   <state id="Deprecated">
        <datamodel>
            <data name="transitionExecution">
                <execution forEvent="Notify Business Owner" class="org.wso2.carbon.apimgt.MailExecutor">
                    <parameter name="emailUsername" value="xxxxxxxxxx" />
                    <parameter name="emailPassword" value="xxxxxxxxxx" />
                </execution>
            </data>
        </datamodel>
        <transition event="Notify Business Owner" target="Notified"/>
    </state>
    <state id="Notified">
        <datamodel>
            <data name="transitionExecution">
                <execution forEvent="Retire"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor"></execution>
            </data>
        </datamodel>
        <transition event="Retire" target="Retired"/>
    </state>

Note that I have used org.wso2.carbon.apimgt.MailExecutor instead of the default executor org.wso2.carbon.apimgt.impl.executors.APIExecutor  and passed the username password parameters in the <execution> section.

Provide valid email username and a password for this property

<parameter name="emailUsername" value="xxxxxxxxxx" />

<parameter name="emailPassword" value="xxxxxxxxxx" />

In this Lifecycle we have introduced a new state "Notified" and provided a transition event "Notify Business Owner" in the Deprecated state.

<transition event="Notify Business Owner" target="Notified"/>

Once user in the Deprecated state, a button will be displayed with the label Notify Business Owner to change the state to Notified

Note: add following entry to the wso2am-1.10.0/repository/deployment/server/jaggeryapps/publisher/site/conf/locales/jaggery/locale_default.json file. The key element is in the lower case. 

 "notify business owner" : "Notify Business Owner"

Test

The scenario is based on sending an email to the business owner of that api regarding API deprecation.

1. Create an API . See Create and Publish an API in the product documentation for more details.
2. Go to the Manage section in the publisher application and fill the Business Information section and save it. business owner email address is used to send the notification.



3. Go to the Overview section of the api and select the lifecycle tab. If you have published the api, It would show a "Deprecate" button. Select it and it would navigate to the newly created state.



Once you click this, User defined as the business owner would get an email