Quick Start Guide

WSO2 App Manager provides secure and self-service access to Web and mobile applications through a single-stop app store. It helps IT teams to effectively manage, deploy, and secure business apps, and it helps CIOs, and administrators to measure usage, productivity, and business statistics. The App Store facilitates single sign-on (SSO) to create a seamless user experience (single login to all apps), which reduces help desk and administrative costs.

This guide walks you through the following main use cases of WSO2 App Manager.

Starting WSO2 App Manager

Follow the steps below to start WSO2 App Manager.

1. Download WSO2 App Manager. For more  information on downloading WSO2 AppM, see Downloading the Product.

2. Install Oracle Java SE Development Kit (JDK) version 1.6.24 or later or 1.7.*. For more information on other required prerequisites for WSO2 AppM, see Installation Prerequisites.

3. Set the JAVA_HOME environment variable. For more information on installing WSO2 AppM, see Installing the Product.
4. Using the command line, navigate to the <APPM_HOME>/bin/ directory, and execute the command for your operating system as follows.
   • wso2server.bat (for Windows)
   • wso2server.sh (for Linux)

When the App Manger server is started, you see the message "WSO2 Carbon started in 'n' seconds." It indicates that the server started successfully. To stop the App Manager, simply hit Ctrl-C in the command window. For more information on running WSO2 AppM, see Running the Product.

Creating users

In addition to the common users in enterprises such as the publisher and subscriber, you can create custom users. Given below is the list of users and their roles which you need to create to use this guide. 

 Follow the steps below to create the above users, and assign user roles to them. For more information on users and roles, see User Management.

1. Log in to the management console ( https://<IP_ADDRESS>:9443/carbon ) of the App Manager using admin/admin credentials.

   By default, the admin user is assigned with the internal/creator, internal/publisher, and internal/subscriber roles.

2. Click Users and Roles in the Configure menu.

3. In the User Management screen, click Users.

4. Click Add New User.

5. Enter the username and password, and click Next. 

6. Select the role(s) you want to assign to the user, and click Finish. 

Managing applications

WSO2 App Manager provides a simple Web interface called App Publisher for Web and mobile application creation, publishing, and management. You need a user with the internal/publisher role or the admin role to log in to the App Publisher.

Managing Web applications

WSO2 App Manager facilitates creating, publishing, and managing Web applications.

Deploying a Web Application

Follow the steps below to deploy a Web app in WSO2 AppM.

Step 1 - Creating a Web application

In this guide, you work with a sample Web application (e.g. Plan Your Trip), which you need to host in Apache Tomcat, WSO2 Application Server, or any other app server. Follow the steps below to create a new Web application in the App Publisher.

1. Access the App Publisher using a Web browser (https://<IP_ADDRESS>:9443/publisher).
2. Log in as the creator user you created above, or as the administrator using admin/admin credentials. 

3. Click Add New Web Application.

   Alternatively, you can click the Click Here link to deploy the sample Web apps that are shipped with WSO2 App Manager. For more information on deploying sample Web apps, see Deploying Sample Web Applications.

4. In the Overview screen, enter information as follows. For more information on this section, see Step 1 - Overview.
   
   

   The descriptions of the fields in the above screen are as follows.

   Field	Description	Sample value
   Author	The user who creates the application. The logged in user is automatically applied as the author.	admin
   Name	The name that appears when the app is published.	Plan Your Trip
   Display Name	Name of the app, which is displayed in the App Store.	Plan Your Trip
   Context	Sub context of the Web application. Gateway URL of the Web application will contain this context.	/plan-your-trip
   Version	Version of the Web application. Users can have multiple versions of the same Web application. The version appears in the gateway URL.	1.0.0
   Transports	The transport protocol used. Select http or https.	https
   Web App URL	URL of the Web application. This URL is considered as the landing page of the Web application. Deploy a Web application in Tomcat or any other App Server, start the server, and provide the link of the deployed Web application as the Web app URL.	https://tomcat.apps:8080/plan-your-trip
   Description	A short description, which will be displayed when the app is published.	The Web app for all your travel needs.
   Thumbnail	A thumbnail image for the Web app.	thumbnail.jpg
   Banner	A banner image for the Web app.	banner.jpg
   Tags	Related tags of the Web app.	travel

   When creating a new Web application, you can also add policies, Web application resources, and advanced configurations to it.

5. Click Create. The created Web app will appear in the Web Applications list as follows. 

   

6. Click Submit for Review as shown below, to change the status of the Web app from CREATED to IN-REVIEW. 
   

Step 2 - Publishing a Web application

Follow the steps below to publish a created Web application.

1. Log in as the publisher user you created above, and click on the Plan Your Trip Web application. (Skip this step if you are already logged in as the admin or publisher user).

   Only a user assigned with internal/publisher role or admin role has the privileges to approve publishing a Web application. 

2. Click Approve as shown below, to change the status of the Web app from IN-REVIEW to APPROVED.
   

3. Click Publish as shown below, to change the status of the Web app from APPROVED to PUBLISHED.

   You view the current status as PUBLISHED as shown below.
   

Step 3 - Subscribing to a Web application

The Web applications that you published are available in the App Store. Follow the steps below to subscribe to a Web application using the App Store Web interface.

1. Access the App Store using a Web browser (https://<hostname>:9443/store), and click Sign In.

2. Enter the username of any user with 'internal/subscriber' role and a password (you can use the subscriber user you created above), and click Sign In, to log in to the App Store.

   If you are not an already registered user access the App Store, and click Register to use the self sign-up option to register yourself, and then sign in to the App Store as the registered user.

3. Click on an application to subscribe to it. 
4. Click Subscribe Me. You see a pop-up message if the subscription is successful. Now, you can access and use the app by invoking it as described in the next section.

Step 4 - Invoking a Web application

Follow the steps below to invoke a Web application.

1. Log in to the App Store as the subscriber user you created above, if you are not already logged in. 
2. Click My Subscriptions, to see subscribed applications. 
3. Click on the application which you need to invoke. 
4. Click on the Gateway Endpoint URL, to invoke the Web application as shown below.
   
5. Provide subscriber credentials to sign-in to the application. Now, you are redirected to the Web application. 

Adding application documentation

You can add different types of documents to a Web application. Follow the steps below to add documentation to a Web app using the App Publisher Web interface.

1. Log in to the App Publisher Web interface as the publisher user you created above, if you are not already logged in.
2. Click the Web app to which you want to add documentation.

3. Click Documentation, and then click Add New Document to create the new document.

4. Enter information to create a document for the Web app as shown below.
   

   The descriptions of the field names in the above screen are as follows.

   Field name	Description
   Name	Name of the document. This is mandatory.
   Summary	A short description of the document, which will appear in the App store.
   Document Type	The type of the document. In addition to the available types, you can add a new type. Select Other (specify), and enter the new type.
   Document Source	Whether the document is stored in-line or provided via a URL or a file. The available options are as follows. In-line: documentation is hosted in the App Manager itself. With in-line documentation, you can edit the content directly from the App Publisher interface. URL: if you already have comprehensive documentation managed by an external configuration management system, simply link to those file references (URLs) through the App Manager rather than importing them to the server. File: select and upload a document, which is stored locally on the server.

5. Click Save New Document.  The added document is displayed in the Documentation window of the Web app. If the source type of the document is in-line, click Edit Content to change the content using the embedded editor.

Versioning a Web application

Follow the steps below to create a new version of a Web application.

1. Log in to the App Publisher as the creator user you created above, if you are not already logged in.
2. Click on the Travel Booking Web application, and then click Create New Version.
3. Specify a new version number for New Version in version.major.minor format (for example, 2.0.0), and a New Display Name as shown below. 
   

4. Click Create New Version. The new version appears in the Web Applications list along with the original version.

Tracking usage statistics of a Web application

For instructions on configuring a Web app to track its usage statistics, see Viewing Statistics.

Managing mobile applications

WSO2 App Manager facilitates creating, publishing, and managing mobile applications.

Deploying a mobile application

Follow the steps below to deploy a mobile application in WSO2 AppM.

Step 1 - Creating a mobile application

You can create mobile applications in three different types as Android applications, iOS applications, and Web applications. Follow the steps below to create an Android mobile application named CleanCalc.

1. Log in to the App Publisher (https:/ /<hostname>:9443/publisher) as the creator user you created above.
2. Click Mobile Applications, and click Add New Mobile Application.
3. Select Android for Platform as shown below.
   
4. Select Enterprise for Store Type. The following are the available store types.
   
   • Enterprise - this refers to all apps that have been created by the organization.
   • Public - this refers to publicly available apps (for example, free apps available online).

5. Select the APK file, and click Next. (The APK file size should not exceed 200MB).

   You can download and use the CleanCalc.apk file as an example. (Click View Raw, to download the file.) For more information on the sample which uses this file, see Clean Calc - A Simple Calculator for Android Devices.

6. In the Give application details screen, enter the app details as shown in the example below.

   
   The descriptions of the fields in the above screen are as follows.

   Field	Description
   Title	The name of the app (CleanCalc).
   Description	A summarized description of the app.
   Recent Changes	A summarized description of what is new in this app when compared to its previous version. This is optional.
   Version	Version of the public application. If you have previously entered a different version of this app, enter a unique version number.
   Banner	Image that will appear as the banner of the app.
   Screenshots	Screenshots of the app for users to get an understanding on what the app offers. You can include a maximum of four screenshots.
   Icon file	Image that will be used as the app icon in the App Store. When the App Manager installs a mobile app on a device, the default icon will be used instead of the uploaded icon.

   The recommended image extension for the above images you upload is .png, and the recommended dimensions are as follows:

   • icons: 124px x 124px
   • screenshots: 288px x 512px (landscape), and 512px x 288px (portrait)
   • banners: 705px x 344px

7. Click Create. The created app will appear in the created list of apps as shown below.
   

Step 2 - Publishing a mobile application

Follow the steps below to publish a created mobile application.

1. Log in to the App Publisher as the publisher user you created above, if you are not already logged in. 

2. Click on the CleanCalc mobile application version 1.0. The current status of the application is CREATED. 

3. Click Submit for Review as shown below, to change the status of the app from CREATED to IN-REVIEW.
   

4. Log in as a publisher, and click on the ClearCalc mobile application. (Skip this step if you are already logged in as an admin/publisher user).

   Only a user assigned with internal/publisher role or admin role has the privileges to approve publishing a mobile application. 

5. Click Approve as shown below, to change the status from IN-REVIEW  to APPROVED. 

   

6. Click Publish as shown below, to change the status from APPROVED to PUBLISHED as shown below. 

   

7. Log in to the App Store as subscriber, and click Mobile Applications. You see the published ClearCalc mobile application as shown below.
   

8. Click on the following application icon to see the mobile application details.You view the download URL of the mobile application as shown below.
   

Step 3 - Viewing a mobile app in its catalogue mode

The mobile applications that you published are available in the App Store. By default, App Store is not connected to a Mobile Device Manager (MDM). Therefore, it acts as a catalog. Follow the steps below to view it.

1. Access the App Manager store using the following URL: https://localhost:9443/store/
2. Log in to the store with admin/admin as username and password.
3. Click on the published app to view it in the catalogue mode as shown below.
   

Step 4 - Integrating a Mobile Device Manager (MDM)

After publishing the mobile app, you need to integrate a Mobile Device Manager (MDM) with WSO2 App Manager to install the published mobile application in your mobile device. Follow the steps below to integrate WSO2 App Manager with a MDM.

1. Integrate a mobile device manager with WSO2 AppM. For instructions, see Integrating a Mobile Device Manager.

2. Restart WSO2 App Manager.

Step 5 - Installing a mobile application

 Follow the steps below to install the CleanCalc app you published above on your mobile device.

1. Access the store using the following URL: https://localhost:9443/store/

2. Log in to the store with admin/admin as username and password.
3. Click on the app, and click Install as shown below.
   
   
   
4. Select the device from the displayed list as shown below.
   
   Now, the CleanCalc app will be provisioned to the selected mobile device.