Carbon Apps, or CAR Files are a deployable package consisting of WSO2 Product related artifacts. These artifacts can range from Synapse Sequences, Proxy Services, Registry items, to Dashboard Server Gadgets, Dashboards, Siddhi Execution Plans, to Tasks like Purging, NTask etc. For example, to group a set of artifacts to be deployed on WSO2 ESB, a CAR file can be used that has some Synapse Sequences, Proxy Services, APIs, and Endpoints. In essence, it’s a compressed Zip file with a different extension.

A Carbon App can be deployed on a WSO2 Server using different methods, however all those methods end up copying the CAR file to <CARBON_HOME>/repository/deployment/server/carbonapps folder. A continuous watcher that checks for content changes inside this folder would decompress the CAR file and execute respective deployers based on the artifact type (defined in the meta file artifact.xml).

So, if the target server is a localhost, it’s just a simple matter of copying the CAR file to the above location. However, things get a little complicated when the target server doesn’t provide shell access.

WSO2 Carbon exposes a set of administrative services that act as a SOAP based API to interact with the particular WSO2 Server. If the OSGi Console is enabled (by setting osgiConsole System Property), the total list of admin services can be displayed by issuing listAdminServices command on the OSGi prompt. For example, the list of admin services exposed in an ESB 4.9.0 server can be found out as follows.

./wso2server.sh -DosgiConsole 
JAVA_HOME environment variable is set to /home/chamilad/dev/java/jdk1.8.0_77
CARBON_HOME environment variable is set to /home/chamilad/dev/wso2esb-4.9.0
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256m; support was removed in 8.0
OSGi console has been enabled with options: -console
osgi> [2016-09-16 01:00:45,715]  INFO - CarbonCoreActivator Starting WSO2 Carbon...
[2016-09-16 01:00:45,718]  INFO - CarbonCoreActivator Operating System : Linux 4.4.0-36-generic, amd64
[2016-09-16 01:00:45,718]  INFO - CarbonCoreActivator Java Home        : /home/chamilad/dev/java/jdk1.8.0_77/jre
[2016-09-16 01:00:45,718]  INFO - CarbonCoreActivator Java Version     : 1.8.0_77
....
....
....
....
....
[2016-09-16 01:01:06,987]  INFO - CarbonUIServiceComponent Mgt Console URL  : https://172.17.0.1:9443/carbon/

[Press ENTER]
osgi> 
osgi> 
osgi> listAdminServices
Admin services deployed on this server:
1. ModuleAdminService, ModuleAdminService, https://chamilad-ubuntu:8243/services/ModuleAdminService 
2. TracerAdmin, TracerAdmin, https://chamilad-ubuntu:8243/services/TracerAdmin 
3. InboundAdmin, InboundAdmin, https://chamilad-ubuntu:8243/services/InboundAdmin 
4. TemplateAdminService, TemplateAdminService, https://chamilad-ubuntu:8243/services/TemplateAdminService 
5. CustomUIAdminService, CustomUIAdminService, https://chamilad-ubuntu:8243/services/CustomUIAdminService 
6. ThemeMgtService, ThemeMgtService, https://chamilad-ubuntu:8243/services/ThemeMgtService 
7. MediationLibraryUploader, MediationLibraryUploader, https://chamilad-ubuntu:8243/services/MediationLibraryUploader 
8. ListMetadataService, ListMetadataService, https://chamilad-ubuntu:8243/services/ListMetadataService 
9. LoginStatisticsAdmin, LoginStatisticsAdmin, https://chamilad-ubuntu:8243/services/LoginStatisticsAdmin 
10. PropertiesAdminService, PropertiesAdminService, https://chamilad-ubuntu:8243/services/PropertiesAdminService 
11. PublishEventMediatorConfigAdmin, PublishEventMediatorConfigAdmin, https://chamilad-ubuntu:8243/services/PublishEventMediatorConfigAdmin 
12. LoggingAdmin, LoggingAdmin, https://chamilad-ubuntu:8243/services/LoggingAdmin 
13. LogViewer, LogViewer, https://chamilad-ubuntu:8243/services/LogViewer 
14. NDataSourceAdmin, NDataSourceAdmin, https://chamilad-ubuntu:8243/services/NDataSourceAdmin 
15. SearchAdminService, SearchAdminService, https://chamilad-ubuntu:8243/services/SearchAdminService 
16. RestApiAdmin, RestApiAdmin, https://chamilad-ubuntu:8243/services/RestApiAdmin 
17. WSDL2CodeService, WSDL2CodeService, https://chamilad-ubuntu:8243/services/WSDL2CodeService 
18. BAMMediatorConfigAdmin, BAMMediatorConfigAdmin, https://chamilad-ubuntu:8243/services/BAMMediatorConfigAdmin 
19. CustomMeteringService, CustomMeteringService, https://chamilad-ubuntu:8243/services/CustomMeteringService 
20. UserAdmin, UserAdmin, https://chamilad-ubuntu:8243/services/UserAdmin 
21. UserStoreConfigAdminService, UserStoreConfigAdminService, https://chamilad-ubuntu:8243/services/UserStoreConfigAdminService 
22. TaskAdmin, TaskAdmin, https://chamilad-ubuntu:8243/services/TaskAdmin 
23. CGAgentAdminService, CGAgentAdminService, https://chamilad-ubuntu:8243/services/CGAgentAdminService 
24. WSDLValidatorService, WSDLValidatorService, https://chamilad-ubuntu:8243/services/WSDLValidatorService 
25. SynapseArtifactUploaderAdmin, SynapseArtifactUploaderAdmin, https://chamilad-ubuntu:8243/services/SynapseArtifactUploaderAdmin 
26. ServerAdmin, ServerAdmin, https://chamilad-ubuntu:8243/services/ServerAdmin 
27. MediationTracerService, MediationTracerService, https://chamilad-ubuntu:8243/services/MediationTracerService 
28. RelationAdminService, RelationAdminService, https://chamilad-ubuntu:8243/services/RelationAdminService 
29. ServiceAdmin, ServiceAdmin, https://chamilad-ubuntu:8243/services/ServiceAdmin 
30. PriorityMediationAdmin, PriorityMediationAdmin, https://chamilad-ubuntu:8243/services/PriorityMediationAdmin 
31. ExternalTryitService, ExternalTryitService, https://chamilad-ubuntu:8243/services/ExternalTryitService 
32. ConfigServiceAdmin, ConfigServiceAdmin, https://chamilad-ubuntu:8243/services/ConfigServiceAdmin 
33. ProxyServiceAdmin, ProxyServiceAdmin, https://chamilad-ubuntu:8243/services/ProxyServiceAdmin 
34. ResourceAdminService, ResourceAdminService, https://chamilad-ubuntu:8243/services/ResourceAdminService 
35. EventBrokerService, EventBrokerService, https://chamilad-ubuntu:8243/services/EventBrokerService 
36. StatisticsAdmin, StatisticsAdmin, https://chamilad-ubuntu:8243/services/StatisticsAdmin 
37. KeyStoreAdminService, KeyStoreAdminService, https://chamilad-ubuntu:8243/services/KeyStoreAdminService 
38. MessageProcessorAdminService, MessageProcessorAdminService, https://chamilad-ubuntu:8243/services/MessageProcessorAdminService 
39. ESBNTaskAdmin, ESBNTaskAdmin, https://chamilad-ubuntu:8243/services/ESBNTaskAdmin 
40. ProvisioningAdminService, ProvisioningAdminService, https://chamilad-ubuntu:8243/services/ProvisioningAdminService 
41. MediationSecurityAdminService, MediationSecurityAdminService, https://chamilad-ubuntu:8243/services/MediationSecurityAdminService 
42. RemoteTaskAdmin, RemoteTaskAdmin, https://chamilad-ubuntu:8243/services/RemoteTaskAdmin 
43. ServerRolesManager, ServerRolesManager, https://chamilad-ubuntu:8243/services/ServerRolesManager 
44. SecurityAdminService, SecurityAdminService, https://chamilad-ubuntu:8243/services/SecurityAdminService 
45. ContentSearchAdminService, ContentSearchAdminService, https://chamilad-ubuntu:8243/services/ContentSearchAdminService 
46. InfoAdminService, InfoAdminService, https://chamilad-ubuntu:8243/services/InfoAdminService 
47. ManageGenericArtifactService, ManageGenericArtifactService, https://chamilad-ubuntu:8243/services/ManageGenericArtifactService 
48. LoggedUserInfoAdmin, LoggedUserInfoAdmin, https://chamilad-ubuntu:8243/services/LoggedUserInfoAdmin 
49. MessageStoreAdminService, MessageStoreAdminService, https://chamilad-ubuntu:8243/services/MessageStoreAdminService 
50. TenantMgtAdminService, TenantMgtAdminService, https://chamilad-ubuntu:8243/services/TenantMgtAdminService 
51. CarbonAppUploader, CarbonAppUploader, https://chamilad-ubuntu:8243/services/CarbonAppUploader 52. FileDownloadService, FileDownloadService, https://chamilad-ubuntu:8243/services/FileDownloadService 
53. CommandMediatorAdmin, CommandMediatorAdmin, https://chamilad-ubuntu:8243/services/CommandMediatorAdmin 
54. ServiceGroupAdmin, ServiceGroupAdmin, https://chamilad-ubuntu:8243/services/ServiceGroupAdmin 
55. MediationStatisticsAdmin, MediationStatisticsAdmin, https://chamilad-ubuntu:8243/services/MediationStatisticsAdmin 
56. DeploymentSynchronizerAdmin, DeploymentSynchronizerAdmin, https://chamilad-ubuntu:8243/services/DeploymentSynchronizerAdmin 
57. ApplicationAdmin, ApplicationAdmin, https://chamilad-ubuntu:8243/services/ApplicationAdmin 
58. EndpointAdmin, EndpointAdmin, https://chamilad-ubuntu:8243/services/EndpointAdmin 
59. MediationStatPublisherAdmin, MediationStatPublisherAdmin, https://chamilad-ubuntu:8243/services/MediationStatPublisherAdmin 
60. MediationLibraryAdminService, MediationLibraryAdminService, https://chamilad-ubuntu:8243/services/MediationLibraryAdminService 
61. TopicManagerAdminService, TopicManagerAdminService, https://chamilad-ubuntu:8243/services/TopicManagerAdminService 
62. SynapseApplicationAdmin, SynapseApplicationAdmin, https://chamilad-ubuntu:8243/services/SynapseApplicationAdmin 
63. OperationAdmin, OperationAdmin, https://chamilad-ubuntu:8243/services/OperationAdmin 
64. Java2WSDLService, Java2WSDLService, https://chamilad-ubuntu:8243/services/Java2WSDLService 
65. LocalEntryAdmin, LocalEntryAdmin, https://chamilad-ubuntu:8243/services/LocalEntryAdmin 
66. ThrottleAdminService, ThrottleAdminService, https://chamilad-ubuntu:8243/services/ThrottleAdminService 
67. MultipleCredentialsUserAdmin, MultipleCredentialsUserAdmin, https://chamilad-ubuntu:8243/services/MultipleCredentialsUserAdmin 
68. SequenceAdminService, SequenceAdminService, https://chamilad-ubuntu:8243/services/SequenceAdminService 
69. STSAdminService, STSAdminService, https://chamilad-ubuntu:8243/services/STSAdminService 
70. FlowsAdminService, FlowsAdminService, https://chamilad-ubuntu:8243/services/FlowsAdminService 
71. RepositoryAdminService, RepositoryAdminService, https://chamilad-ubuntu:8243/services/RepositoryAdminService 
72. RegistryAdminService, RegistryAdminService, https://chamilad-ubuntu:8243/services/RegistryAdminService 
73. EndpointTemplateAdminService, EndpointTemplateAdminService, https://chamilad-ubuntu:8243/services/EndpointTemplateAdminService 
74. WSDLToolService, WSDLToolService, https://chamilad-ubuntu:8243/services/WSDLToolService 
75. DiscoveryAdmin, DiscoveryAdmin, https://chamilad-ubuntu:8243/services/DiscoveryAdmin 
76. FileUploadService, FileUploadService, https://chamilad-ubuntu:8243/services/FileUploadService 
77. ClassMediatorAdmin, ClassMediatorAdmin, https://chamilad-ubuntu:8243/services/ClassMediatorAdmin

Although all admin services are listed here, some of those are not exposed by default, and some do not have authorization parameters set. Therefore, those are blocked from being accessed. If these need to be desperately accessed follow {future blog post} steps.

Getting back to the topic, one of the admin services in this list is of interest to us. Using the service CarbonAppUploader, CAR files can be uploaded to the respective server. Let’s try this scenario using SoapUI for WSO2 ESB 4.9.0.

Service Definition

To call the CarbonAppUploader admin service, we have to create the clients from its WSDL. By default, the WSDLs of the admin services are hidden. If you don’t have any control over the server in question, or it cannot be restarted for reasons of service disruption, I’ve added the WSDL as a Gist. After downloading, replace server-host-or-ip with the hostname or the IP address of the ESB server.

If you have some control over the server, where you can restart the ESB server, you can directly obtain the WSDL from the server. First disable the setting that hides the WSDLs by default, by setting HideAdminServiceWSDLs to false in <CARBON_HOME>/repository/conf/carbon.xml.

<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>

After this you will able to obtain the WSDL of a service by appending ?wsdl to the end of the Service URL. For example, the WSDL of the CarbonAppUpload service of a locally run ESB server will be at the following location.

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

Notice the port mentioned in the above URL, 8243, and in the resulting WSDL, is different from the port that I have included in the WSDL in the Gist above? This is to do with the difference between the Servlet ports and the Synapse Mediation ports. Because Synapse accepts mediation through (by default) port 8243, the WSDL is shown on it. However the admin services are available through the Servlet port, 9443.

SoapUI Requests

Having obtained the WSDL, let’s proceed to create a SoapUI request from it.

Open SoapUI and create a new SOAP Project (File -> New SOAP Project). Provide the WSDL file (or the above ?wsdl URL). Check Create Requests so that SoapUI will create sample requests for the operations in the WSDL.

Click Ok and you will see the set of operations (in CarbonAppUploader, there is one operation, uploadApp) created in the SoapUI Project view.

Open Request1 under CarbonAppUploaderSoap11Binding.uploadApp and you will see the already created Soap Envelope with ? as a placeholder for values. For the uploadApp operation three inputs are needed.

  1. dataHandler — Base64 binary encoded file content
  2. fileName — File name of the CAR file
  3. fileType — File compression, only the value “jar” is supported

The port confusion comes in to play again. If you loaded the WSDL from the remote URL with 8243, you will have to change the port in the request from 8243 to 9443.

Attaching the CAR File

We need to serialize the CAR file as a base64 encoded string and add it in the SOAP request. SoapUI provides this functionality as Attachments.

On the request, click on Attachments, and then add CAR file as an attachment. Navigate to the CAR file and select it. Select No to cache the attachment, as I found it to sometimes upload the file in an incomplete manner.

Copy the value in the ContentID. This, along with the cid: prefix, has to be added as the dataHandler in the request.

After the attachment is done, the request will look like the following.

In addition to adding the attachment, MTOM has to be enabled in the request. This has to be done through setting Enable MTOM to true in the request properties.

Authentication

Click on Auth tab and add basic authentication to the request.

Upload the CAR File

We are all done now. What’s left is to just go ahead and make the SOAP request. The file will be uploaded, and a response will be returned, with the status of the upload. After a maximum of one minute, the Carbon App will be processed and the artifacts will be deployed.


Written on September 17, 2016 by chamila de alwis.

Originally published on Medium