This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Calling Admin Services from Apps

WSO2 products are managed internally using SOAP Web services known as admin services. WSO2 products come with a management console UI, which communicates with these admin services to facilitate administration capabilities through the UI.
There can be instances where you want to call back-end Web services directly. For example, in test automation, to minimize the overhead of having to change automation scripts whenever a UI change happens, developers prefer to call the underlying services in scripts. The topics below explain how you can discover and invoke these services from your applications.

Discovering the admin services

By default, the WSDLs of admin services are hidden from consumers. Follow the steps given below to discover them using the OSGi console.

  1. Open the carbon.xml file (from the /conf directory of the respective profile), and set the <HideAdminServiceWSDLs> element to false.

    The location of the /conf directory (for each of the product profiles in WSO2 EI) is as shown below:

    • For the ESB profile: <EI_HOME>/conf/ directory.
    • For the BPS/MB/Analytics profiles: <EI_HOME>/wso2/<profile_name>/conf/ directory.
  2. Start the relevant product profile:

    1. Open a terminal and navigate to the /bin directory.

      The location of the /bin directory (for each of the product profiles in WSO2 EI) is as shown below:

      • For the ESB profile: <EI_HOME>/bin/ directory.
      • For the BPS/MB/Analytics profiles: <EI_HOME>/wso2/<profile_name>/bin/ directory.
    2. Execute the product profile's startup script as explained below.

      In Linux environments

      • For the ESB profile: sh integrator.sh -DosgiConsole

      • For the BPS/MB/Analytics profiles: sh wso2server.sh -DosgiConsole

      In Windows environments

      • For the ESB profile: integrator.bat -DosgiConsole

      • For the BPS/MB/Analytics profiles: wso2server.bat -DosgiConsole

  3. When the server starts, press the Enter/Return key on the keyboard several times to get theOSGI shell in the console.
  4. In the OSGi shell, type the following: osgi> listAdminServices
  5. The admin services for your product profile will be listed on your console. For example, shown below is the list of admin services in the ESB profile of WSO2 EI.

     ESB admin services
    Admin services deployed on this server:
    1. ModuleAdminService, ModuleAdminService, https://localhost:8243/services/ModuleAdminService 
    2. ThemeMgtService, ThemeMgtService, https://localhost:8243/services/ThemeMgtService 
    3. PropertiesAdminService, PropertiesAdminService, https://localhost:8243/services/PropertiesAdminService 
    4. PublishEventMediatorConfigAdmin, PublishEventMediatorConfigAdmin, https://localhost:8243/services/PublishEventMediatorConfigAdmin 
    5. LogViewer, LogViewer, https://localhost:8243/services/LogViewer 
    6. SearchAdminService, SearchAdminService, https://localhost:8243/services/SearchAdminService 
    7. DataServiceAdmin, DataServiceAdmin, https://localhost:8243/services/DataServiceAdmin 
    8. WSDL2CodeService, WSDL2CodeService, https://localhost:8243/services/WSDL2CodeService 
    9. CustomMeteringService, CustomMeteringService, https://localhost:8243/services/CustomMeteringService 
    10. UserAdmin, UserAdmin, https://localhost:8243/services/UserAdmin 
    11. UserStoreConfigAdminService, UserStoreConfigAdminService, https://localhost:8243/services/UserStoreConfigAdminService 
    12. TaskAdmin, TaskAdmin, https://localhost:8243/services/TaskAdmin 
    13. WSDLValidatorService, WSDLValidatorService, https://localhost:8243/services/WSDLValidatorService 
    14. ServerAdmin, ServerAdmin, https://localhost:8243/services/ServerAdmin 
    15. RelationAdminService, RelationAdminService, https://localhost:8243/services/RelationAdminService 
    16. ServiceAdmin, ServiceAdmin, https://localhost:8243/services/ServiceAdmin 
    17. ConfigServiceAdmin, ConfigServiceAdmin, https://localhost:8243/services/ConfigServiceAdmin
    18. WebappAdmin, WebappAdmin, https://localhost:8243/services/WebappAdmin 
    19. EventPublisherAdminService, EventPublisherAdminService, https://localhost:8243/services/EventPublisherAdminService 
    20. EventBrokerService, EventBrokerService, https://localhost:8243/services/EventBrokerService 
    21. StatisticsAdmin, StatisticsAdmin, https://localhost:8243/services/StatisticsAdmin 
    22. KeyStoreAdminService, KeyStoreAdminService, https://localhost:8243/services/KeyStoreAdminService 
    23. MessageProcessorAdminService, MessageProcessorAdminService, https://localhost:8243/services/MessageProcessorAdminService 
    24. DataServiceFileUploader, DataServiceFileUploader, https://localhost:8243/services/DataServiceFileUploader 
    25. ProvisioningAdminService, ProvisioningAdminService, https://localhost:8243/services/ProvisioningAdminService 
    26. MediationSecurityAdminService, MediationSecurityAdminService, https://localhost:8243/services/MediationSecurityAdminService 
    27. ServerRolesManager, ServerRolesManager, https://localhost:8243/services/ServerRolesManager 
    28. LoggedUserInfoAdmin, LoggedUserInfoAdmin, https://localhost:8243/services/LoggedUserInfoAdmin 
    29. TenantMgtAdminService, TenantMgtAdminService, https://localhost:8243/services/TenantMgtAdminService 
    30. CarbonAppUploader, CarbonAppUploader, https://localhost:8243/services/CarbonAppUploader 
    31. CommandMediatorAdmin, CommandMediatorAdmin, https://localhost:8243/services/CommandMediatorAdmin 
    32. ServiceGroupAdmin, ServiceGroupAdmin, https://localhost:8243/services/ServiceGroupAdmin 
    33. DeploymentSynchronizerAdmin, DeploymentSynchronizerAdmin, https://localhost:8243/services/DeploymentSynchronizerAdmin 
    34. EndpointAdmin, EndpointAdmin, https://localhost:8243/services/EndpointAdmin 
    35. MediationLibraryAdminService, MediationLibraryAdminService, https://localhost:8243/services/MediationLibraryAdminService 
    36. UserProfileMgtService, UserProfileMgtService, https://localhost:8243/services/UserProfileMgtService 
    37. OperationAdmin, OperationAdmin, https://localhost:8243/services/OperationAdmin 
    38. Java2WSDLService, Java2WSDLService, https://localhost:8243/services/Java2WSDLService 
    39. LocalEntryAdmin, LocalEntryAdmin, https://localhost:8243/services/LocalEntryAdmin 
    40. MultipleCredentialsUserAdmin, MultipleCredentialsUserAdmin, https://localhost:8243/services/MultipleCredentialsUserAdmin 
    41. RegistryAdminService, RegistryAdminService, https://localhost:8243/services/RegistryAdminService 
    42. DiscoveryAdmin, DiscoveryAdmin, https://localhost:8243/services/DiscoveryAdmin 
    43. FileUploadService, FileUploadService, https://localhost:8243/services/FileUploadService 
    44. InboundAdmin, InboundAdmin, https://localhost:8243/services/InboundAdmin 
    45. TemplateAdminService, TemplateAdminService, https://localhost:8243/services/TemplateAdminService 
    46. CustomUIAdminService, CustomUIAdminService, https://localhost:8243/services/CustomUIAdminService 
    47. MediationLibraryUploader, MediationLibraryUploader, https://localhost:8243/services/MediationLibraryUploader 
    48. LoginStatisticsAdmin, LoginStatisticsAdmin, https://localhost:8243/services/LoginStatisticsAdmin 
    49. LoggingAdmin, LoggingAdmin, https://localhost:8243/services/LoggingAdmin 
    50. EventStreamAdminService, EventStreamAdminService, https://localhost:8243/services/EventStreamAdminService 
    51. NDataSourceAdmin, NDataSourceAdmin, https://localhost:8243/services/NDataSourceAdmin 
    52. RestApiAdmin, RestApiAdmin, https://localhost:8243/services/RestApiAdmin 
    53. SynapseArtifactUploaderAdmin, SynapseArtifactUploaderAdmin, https://localhost:8243/services/SynapseArtifactUploaderAdmin 
    54. PriorityMediationAdmin, PriorityMediationAdmin, https://localhost:8243/services/PriorityMediationAdmin 
    55. ExternalTryitService, ExternalTryitService, https://localhost:8243/services/ExternalTryitService 
    56. ProxyServiceAdmin, ProxyServiceAdmin, https://localhost:8243/services/ProxyServiceAdmin 
    57. ResourceAdminService, ResourceAdminService, https://localhost:8243/services/ResourceAdminService 
    58. ESBNTaskAdmin, ESBNTaskAdmin, https://localhost:8243/services/ESBNTaskAdmin 
    59. RemoteTaskAdmin, RemoteTaskAdmin, https://localhost:8243/services/RemoteTaskAdmin 
    60. SecurityAdminService, SecurityAdminService, https://localhost:8243/services/SecurityAdminService 
    61. ContentSearchAdminService, ContentSearchAdminService, https://localhost:8243/services/ContentSearchAdminService 
    62. MessageStoreAdminService, MessageStoreAdminService, https://localhost:8243/services/MessageStoreAdminService 
    63. FileDownloadService, FileDownloadService, https://localhost:8243/services/FileDownloadService 
    64. ApplicationAdmin, ApplicationAdmin, https://localhost:8243/services/ApplicationAdmin 
    65. DSTaskAdmin, DSTaskAdmin, https://localhost:8243/services/DSTaskAdmin 
    66. TopicManagerAdminService, TopicManagerAdminService, https://localhost:8243/services/TopicManagerAdminService 
    67. SynapseApplicationAdmin, SynapseApplicationAdmin, https://localhost:8243/services/SynapseApplicationAdmin 
    68. UserStoreCountService, UserStoreCountService, https://localhost:8243/services/UserStoreCountService 
    69. SequenceAdminService, SequenceAdminService, https://localhost:8243/services/SequenceAdminService 
    70. STSAdminService, STSAdminService, https://localhost:8243/services/STSAdminService 
    71. FlowsAdminService, FlowsAdminService, https://localhost:8243/services/FlowsAdminService 
    72. RepositoryAdminService, RepositoryAdminService, https://localhost:8243/services/RepositoryAdminService 
    73. EndpointTemplateAdminService, EndpointTemplateAdminService, https://localhost:8243/services/EndpointTemplateAdminService 
    74. ClassMediatorAdmin, ClassMediatorAdmin, https://localhost:8243/services/ClassMediatorAdmin 
  6. Check the list of admin services shown above, and note that the URL of each admin service appears after the admin service's name. See the following example:

    ModuleAdminService, ModuleAdminService, https://localhost:8243/services/ModuleAdminService
  7. To see the service contract of an admin service, select the admin service's URL and then paste it into your browser with ?wsdl at the end. For example, if you want to access the ModuleAdminService of the ESB profile, use the following URL: 

    https://localhost:8243/services/ModuleAdminService?wsdl

    When you are accessing an admin service in the ESB, note that you are using the 8243 port (assuming 0 port offset). However, you should be accessing the admin services via the management console port. The default management console port for each of the profiles in WSO2 EI are as follows:

    • The ESB profile: 9443

    • The BPS profile: 9445

    • The MB profile: 9446
    • The Analytics profile: 9444

    After discovering admin service, you can restart the server without -DosgiConsole.

Invoking an admin service

Admin services are secured using common types of security protocols such as HTTP basic authentication, WS-Security username token, and session-based authentication, to prevent anonymous invocations. For example, the UserAdmin Web service is secured with HTTP basic authentication. To invoke an admin service, you can write your own client program using the Axis2 client API, or you can use an existing tool like SoapUI (4.5.1 or later), or wsdl2java.

Invoking an admin service involves the following steps:

  1. Authenticate yourself and get the session cookie.
  2. Access the back-end service.

Generating a client program to access admin services

The following contents are currently under review!

To generate the stubs, you can write your own client program using the Axis2 client API, or use an existing tool like SoapUI (4.5.1 or later), or wsdl2java.

The wsdl2java tool, which comes with WSO2 products by default, hides all the complexity and presents you with a proxy to the back-end service. The stub generation happens during the project build process within the Maven POM files. It uses the Maven ant run plug-in to execute the wsdl2java tool.

You can also use the Java client program given here to invoke admin services. All dependency JAR files that you need to run this client are found in the /lib directory.

Authenticate the user

The example code below authenticates the user and gets the session cookie:


 import org.apache.axis2.AxisFault;  
 import org.apache.axis2.transport.http.HTTPConstants;  
 import org.wso2.carbon.authenticator.stub.AuthenticationAdminStub;  
 import org.wso2.carbon.authenticator.stub.LoginAuthenticationExceptionException;  
 import org.wso2.carbon.authenticator.stub.LogoutAuthenticationExceptionException;  
 import org.apache.axis2.context.ServiceContext;  
 import java.rmi.RemoteException;  
   
 public class LoginAdminServiceClient {  
   private final String serviceName = "AuthenticationAdmin";  
     private AuthenticationAdminStub authenticationAdminStub;  
     private String endPoint;  
   
     public LoginAdminServiceClient(String backEndUrl) throws AxisFault {  
       this.endPoint = backEndUrl + "/services/" + serviceName;  
       authenticationAdminStub = new AuthenticationAdminStub(endPoint);  
     }  
   
     public String authenticate(String userName, String password) throws RemoteException,  
                                       LoginAuthenticationExceptionException {  
   
       String sessionCookie = null;  
   
       if (authenticationAdminStub.login(userName, password, "localhost")) {  
         System.out.println("Login Successful");  
   
         ServiceContext serviceContext = authenticationAdminStub.  
             _getServiceClient().getLastOperationContext().getServiceContext();  
         sessionCookie = (String) serviceContext.getProperty(HTTPConstants.COOKIE_STRING);  
         System.out.println(sessionCookie);  
       }  
   
       return sessionCookie;  
     }  
   
     public void logOut() throws RemoteException, LogoutAuthenticationExceptionException {  
       authenticationAdminStub.logout();  
     }  
 }

To resolve dependency issues, if any, add the following dependency JARs location to the class path: <PRODUCT_HOME>/repository/components/plugins.

The the AuthenticationAdminStub class requires org.apache.axis2.context.ConfigurationContext as a parameter. You can give a null value there.

Generate the client stubs

After authenticating the user, give the retrieved admin cookie with the service endpoint URL as shown in the sample below. The service management servicenameisServiceAdmin. You can find its URL (e.g., https://localhost:<port>/services/ServiceAdmin) in the service.xml file in the META-INF folder in the respective bundle that you find in the /plugins directory.
 import org.apache.axis2.AxisFault;  
 import org.apache.axis2.client.Options;  
 import org.apache.axis2.client.ServiceClient;  
 import org.wso2.carbon.service.mgt.stub.ServiceAdminStub;  
 import org.wso2.carbon.service.mgt.stub.types.carbon.ServiceMetaDataWrapper;  
 import java.rmi.RemoteException;  
   
 public class ServiceAdminClient {  
   private final String serviceName = "ServiceAdmin";  
   private ServiceAdminStub serviceAdminStub;  
   private String endPoint;  
   
   public ServiceAdminClient(String backEndUrl, String sessionCookie) throws AxisFault {  
     this.endPoint = backEndUrl + "/services/" + serviceName;  
     serviceAdminStub = new ServiceAdminStub(endPoint);  
     //Authenticate Your stub from sessionCooke  
     ServiceClient serviceClient;  
     Options option;  
   
     serviceClient = serviceAdminStub._getServiceClient();  
     option = serviceClient.getOptions();  
     option.setManageSession(true);  
     option.setProperty(org.apache.axis2.transport.http.HTTPConstants.COOKIE_STRING, sessionCookie);  
   }  
   
   public void deleteService(String[] serviceGroup) throws RemoteException {  
     serviceAdminStub.deleteServiceGroups(serviceGroup);  
   
   }  
   
   public ServiceMetaDataWrapper listServices() throws RemoteException {  
     return serviceAdminStub.listServices("ALL", "*", 0);  
   }  
 } 

The following sample code lists the back-end Web services:

 import org.wso2.carbon.authenticator.stub.LoginAuthenticationExceptionException;  
 import org.wso2.carbon.authenticator.stub.LogoutAuthenticationExceptionException;  
 import org.wso2.carbon.service.mgt.stub.types.carbon.ServiceMetaData;  
 import org.wso2.carbon.service.mgt.stub.types.carbon.ServiceMetaDataWrapper;  
   
 import java.rmi.RemoteException;  
   
 public class ListServices {  
   public static void main(String[] args)  
       throws RemoteException, LoginAuthenticationExceptionException,  
           LogoutAuthenticationExceptionException {  
     System.setProperty("javax.net.ssl.trustStore", "$ESB_HOME/repository/resources/security/wso2carbon.jks");  
     System.setProperty("javax.net.ssl.trustStorePassword", "wso2carbon");  
     System.setProperty("javax.net.ssl.trustStoreType", "JKS");  
     String backEndUrl = "https://localhost:9443";  
   
     LoginAdminServiceClient login = new LoginAdminServiceClient(backEndUrl);  
     String session = login.authenticate("admin", "admin");  
     ServiceAdminClient serviceAdminClient = new ServiceAdminClient(backEndUrl, session);  
     ServiceMetaDataWrapper serviceList = serviceAdminClient.listServices();  
     System.out.println("Service Names:");  
     for (ServiceMetaData serviceData : serviceList.getServices()) {  
       System.out.println(serviceData.getName());  
     }  
   
     login.logOut();  
   }  
 }