Integrating your web application

Introduction

You can integrate web application into Aurora by placing that application into IFrame. If needed, application can have access to current user context.

The module we'll use to provide the integration is found at:

https://github.com/afterlogic/aurora-module-webclient-iframe-app

It allows you to place an application into IFrame, provides link for this app in main menu, enables a separate tab for it in admin area and, depending on configuration, may add a tab for it to user account settings.

Installation and configuration

The module is installed according to the standard procedure described at Adding modules documentation page.

By default, the module operates in "No authentication" mode. In module configuration tab under admin area, you need to provide application name and URL:

IFrame app IMG 1

For every user account, it's possible to disable or enable the use of the application:

IFrame app IMG 2

Authentication

Additionally, the application can have current user context passed into it by providing auth token, so the application can get access to user account credentials, be it Aurora ones or some custom credentials specified for particular user account:

IFrame app IMG 3

Let's suppose the application requires login and password of current user. Those aren't passed into application directly, though; only authentication token is sent through. However, with the use of Aurora Web API, it's possible to retrieve user account credentials.

Assuming that External App URL was set to http://mydomain.com/myapp/index.php, the application can obtain account details with the following code in that index.php file:

$authToken = ( isset($_REQUEST["authToken"]) ? $_REQUEST["authToken"] : "" );

$postData = array(
      'Module' => 'Core',
      'Method' => 'GetAuthenticatedAccount',
      'AuthToken' => $authToken
);

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'http://mydomain.com/cloud/index.php?/Api/',
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $postData,
  CURLOPT_SSL_VERIFYPEER => false,
  CURLOPT_RETURNTRANSFER => true
));
$resp = curl_exec($curl);
$result = json_decode($resp);

if ( isset($result->Result) && isset ($result->Result->Password) ) {
   echo "Password is available";
/*
   Credentials are available as:
   $result->Result->Login
   $result->Result->Password
*/
}
else
{
   echo "Password is NOT available";
}

Note that in the above code, it doesn't matter whether auth token is passed via GET or POST, it would work either way.

The code deals with account credentials of Aurora users. But what if the application you need to integrate uses its own login/password combinations for existing users? This case is supported as well, and you can configure the module so that login/password are either supplied by users themselves, or entered by administrator for each of the accounts.

This approach can be implemented with a minimal modification of the above code:

$postData = array(
      'Module' => 'IframeAppWebclient',
      'Method' => 'GetCredentials',
      'AuthToken' => $authToken
);

Forking

The above assumes that you're simply installing the module the way it is, performing its configuration and using it on your installation. There might be cases, however, when you need to create a modification (fork) of the module. For example, if you need to integrate two different web applications into the same Aurora installation, you cannot reuse the same module twice. Instead, you would need to create a copy of the module, set it up in a separate repository, and rename a few entries throughout the module files, the changes are listed below.

During the development (especially on its initial stage) you would probably wish to, rather then dealing with creating a fork repository, have a separate copy of the module residing under modules directory next to the original module. Upon creating such a clone, you would need to rebuild static files as explained here.

  1. Module directory

The module itself needs to be renamed from IframeAppWebclient into the custom name.

  1. composer.json

In this file, you'll need to alter the lines:

{
    "name": "afterlogic/aurora-module-webclient-iframe-app",
...
        "dist":{
               "url":"https://github.com/afterlogic/aurora-module-webclient-iframe-app/archive/master.zip",
...
    "extra": {
        "installer-name": "IframeAppWebclient"   

so that they reflect new module name and its download location.

  1. module.php

To avoid conflict with other instances of this module or its forks, you need to rename class found here:

class IframeAppWebclientModule extends AApiModule
  1. templates/MainView.html
<div class="screen IframeApp" style="display: none;">

While technically CSS class name affects nothing, it's a good practice to have HTML container renamed according to your module name.

  1. classes/enum.php

Enumerations found here are presented by two classes:

class EIframeAppAuthMode extends AEnumeration
...
class EIframeAppTokenMode extends AEnumeration

You'll need to replace all the occurences throughout both PHP and JavaScript files according to your custom module naming.

In PHP code, the names start with capital E - while in JavaScript, it is omitted, for example:

Enums.IframeAppAuthMode
  1. Language files

While it's not required, you may wish to adjust text constants found in language files under i18n directory.