Getting Started

Cloud Apps are applications which run inside of the Ex Libris platform. Common use cases for Cloud Apps might include integrating with external systems or data sources, workflow shortcuts or productivity enhancements, and adding brand new functionality not currently supported by the product. Beginning with the 2023-August Alma release, Cloud Apps may be run as widgets on Alma’s dashboard.

This guide is for developers who are interested in building Cloud Apps. End-users and administrators who would like to use Cloud Apps in their institution should refer to the online help and the list of available Cloud Apps.

Cloud Apps are written in Angular (currently version 11) using HTML and TypeScript. They can take advantage of the Cloud Apps API which provides interaction with Alma including access to all of the REST APIs. The Cloud Apps CLI provides a local environment in which you can develop your app.  Once your app is developed, you can deploy it so that it can be discovered and used by others.

The instructions below show how to get started with Ex Libris Cloud Apps. While not required, there are many resources for general Angular development on the web, including on the Angular website.

• Pre-requisites
• Install the CLI
• Create a new app
• Starting with an existing app
• Contributing to an existing app
• FAQs

After you’ve gotten started you can begin exploring the tutorials which provide in-depth guidance for common use cases. You can also check out the frequently asked questions below.

Pre-requisites

• Node JS 10.x or higher (for now up to v16 is supported) is required to install the CLI.
• Visual Studio Code is recommended, although any text editor will do
• Git or Github Desktop
• Ensure Cloud Apps are enabled for your institution in the relevant environment (sandbox or production)

Install the CLI

npm install -g @exlibris/exl-cloudapp-cli

Create a new application

Click below to view a walk-though of creating a new application:
10:28

Create a new directory:

mkdir my-first-cloudapp
cd my-first-cloudapp

Initialize the Cloud App:

eca init

Answer the questions. Use your sandbox URL as the environment. Be sure to use the full URL rather than the short version, including the /institution/44MY_INST, e.g. https://my-inst-psb.alma.exlibrisgroup.com/institution/44MY_INST.

✔ App title:  … My First CloudApp
✔ App description:  … My first CloudApp
✔ Environment URL:  … https://sandbox02-eu.alma.exlibrisgroup.com/institution/01MYINST
✔ Run dev server on port:  … 4200

Using config:
{
  env: 'https://sandbox02-eu.alma.exlibrisgroup.com/institution/01MYINST',
  port: 4200
}

The following files and folders were created:
.gitignore
.ng
.vscode
cloudapp
config.json
manifest.json
manifest.schema.json
package.json 

Done.

Start your application:

eca start

The application will build and open your browser. Log into your Alma environment. Click the Cloud Apps icon to open your the pane and your app.

Congratulations! You’ve installed and started your first Cloud App! Now you can view the tutorial on Exploring the sample app and review the style guide for help with your app’s design. And when you’re ready, you can follow the instructions to publish your app.

Starting with an Existing Application

Click below to view a walk-though of starting with an existing application:
4:55
If you wish to start with an existing application and develop it locally, perform the following steps:

Git clone the repository and enter the directory. (If you don’t yet have Git installed, see the section below.) For example, to clone the Cloud App Tutorials repository, type the following:

git clone https://github.com/{REPOSITORY_NAME}
cd alma-csv-user-load

Initialize the application

eca init

Add the configuration for your environment:

Existing app detected. 
✔ Do you want to reconfigure this existing app? … yes

✔ Environment URL:  … https://na01-psb.alma.exlibrisgroup.com/institution/MY_INST
✔ Run dev server on port:  … 4200

Using config:
{
  env: 'https://na01-psb.alma.exlibrisgroup.com/institution/MY_INST',
  port: 4200
}

Configuration created for existing app.

Start the application and log in.

eca start

Installing Github Desktop

The easiest way to get started with Git is by using Github for Desktop. The Github for Desktop website includes instructions for installing the client for Windows or Mac, as well as instructions for cloning a repository to your local workstation.

Contributing to an Existing Application

All Cloud Apps are stored in Github repositories, so you can contribute to an app using the standard Github workflows. The steps for contributing to an app include:

• Clone the repository locally
• Make your changes to the app
• Fork the repository and commit your changes
• Create a pull request for the owner of the original repository

Click below to view a walk-though of contributing to an existing application:
7:34

Frequently Asked Questions

I’m currently developing an app and I need support, what should I do?

You can turn to the Cloud Apps forum to ask a question. The forum is monitored by Ex Libris staff and by members of the community.

Can I make sure that the app I’m developing will be available only to my institution?

In order to realize the benefits of community apps, all Cloud Apps are available to any institution when published. This “force multiplier” will enable institutions to benefit from the work done by others.

Is there a process of ‘confirming’ the app by Ex Libris before they go live?

When a Cloud App is first published in the App Center, it undergoes a manual review process to ensure it works as described and that it doesn’t use any libraries which are flagged as having critical security issues. For more information on the deploying process, see the documentation.

If a vulnerability is reported in an update to a Cloud App published by the developer/publisher, we will:

1. Disable the Cloud App, removing it from the list of available Cloud Apps.
2. Notify the developer.
3. Work with the developer to resolve the issue, if help is requested.
4. Republish the Cloud App once fixed.

Who owns the intellectual property for Cloud Apps developed by the community?

Any contributions to the App Center and the Developer Network, including Cloud Apps, are subject to the Developer Network Terms of Use. Under those Terms, Ex Libris does not assert ownership over Developer Code and Apps (including Cloud Apps) independently developed and contributed by the community. Community developers specify the open source license under which they wish to license Cloud Apps, although Ex Libris encourages use of the New BSD license. For more information please refer to the Terms of Use.

Who maintains Cloud Apps after they are released?

Ex Libris commits to maintaining backwards compatibility for the Cloud App framework, such that updates to Alma will not break existing Cloud Apps. Cloud Apps are open source and maintained by the community so that adding features or fixing bugs can leverage the power of the collective. Cloud Apps developers are encouraged to specify a help page in the manifest which provides information about how to request support, for example via issues in the Github repository. For Cloud Apps developed by Ex Libris, users may open a support case for help with the Cloud App.

When are technology updates applied to the Cloud Apps SDK?

Ex Libris commits to updating the Cloud App SDK to keep current with the included libraries and underlying technology. This is presently being done twice a year. Apps don’t have to be updated to continue to work, but developers who wish to update their toolset and apps will have the opportunity to do so.

Can I also develop a Cloud App for Esploro, Leganto and the other Ex Libris cloud solutions?

Cloud Apps work on the Ex Libris higher-ed platform, so apps can be developed for Alma, Primo VE back-office, Esploro, Leganto, Rialto, and Rapido. If you’re interested in developing an app for a product other than Alma, please reach out in the forum.