API Functions

The Liquit.Initialize function allows you to connect to the Application Workspace. It determines the version of the targeted Application Workspace zone. Then the Application Workspace API translates the API calls to the correct syntax/endpoints.

Request parameters

The first parameter is the Application Workspace zone, for which you need to specify a string containing the URL to which you want to connect.

The following extra options are available for the API as the second parameter:

Example

Liquit.Initialize('https://workspace.recastsoftware.com', {
  version: '3.0',
  relogin: function () { console.log('Session has expired'); },
  token: null
});

The Liquit.GetSources function allows you to retrieve the identity sources known in the Application Workspace, as well as to determine the authentication method required by them.

Request parameters

Example

Liquit.GetSources(
    (result ) => {
    
        //The result parameter will contain the identity source information.
        console.log(result);
        
    }
);

The Liquit.Login function allows you to connect to the Application Workspace API with provided credentials. You can specify the identity source, username and password required to authenticate to the Application Workspace.

Request parameters

You need to specify at least a username and password to authenticate to the Application Workspace.

The following parameters are available for the API:

Example

Liquit.Login({
    identitySource: 'LOCAL',
    username : 'admin',
    password: 'password',
    callback: function (token, fault) {
    
        // Check if the request failed.
        if (fault != null) {
            alert('Error ' + fault.code + ': ' + fault.message);
            return;
        }
        
        // Call Liquit.Applications.List API to retrieve all available applications for the logged-in user.
    
    }
});

The Liquit.SSO function allows a user to connect to the Application Workspace API with previously authenticated credentials that are stored in the user's web browser. It also detects whether or not a user is already authenticated to an OAuth 2 provider configured in Application Workspace.
Within it, you can specify a username or identity source required to authenticate to Application Workspace and it can be either a Microsoft Entra ID (Azure AD) or an AD FS setup.
This can be useful in scenarios where multiple OAuth2 providers are configured and used by the user.

Request parameters

Example

Liquit.SSO({
  username: 'admin@recastsoftware.com',
  identitySource: 'Microsoft Entra ID',
  popUp: false,
  token:null //Exchange token
}, function(token, fault) {

  // Check if authentication failed.
  if (fault != null) {
    alert('Error ' + fault.code + ': ' + fault.message);
    return;
  }
 
  //Do Application Workspace stuff here

});

The Logout function allows you to disconnect from the Application Workspace and the provided identity source. It is possible to select whether or not only the Application Workspace session should be terminated.

Request parameters

The following parameters are available for the API:

Example

Liquit.Logout({

  // If excludeAction is set to false, the logout function will also log you out from the selected identity source. The default value is true.
  excludeAction: false,

  // If popUp is set to true, a popup window will be used to execute the logout action. If set to false, an iframe will be used.
  popUp:true

}, function (feedback) {

  // The feedback parameter is only available for Application Workspace Server 3.3 and later
  if (feedback == false) {
    console.log('Logout in progress')
  }
  if (feedback == true) {
    console.log('Logout executed.')
  }

});

The Liquit.Agent.SelectFile function lets you utilize the Agent to select a local file. The Agent needs to be running to use this function.
You can check if the Agent is running by using the following variable:

Liquit.Workspace.Agent.Enabled

Usage and example

By default, the Agent will return the path where the selected file is available.

Liquit.Agent.SelectFile(
    function (result) {
     //result.path will be the path to the selected file
    console.log(result);
});

The Liquit.Applications.Launch function is used to launch applications from the Application Workspace API. The applications return a callback reporting on their status: if the application has been launched successfully or not, or a status update on the progress. The update on the progress comes especially in handy when running installations or distributions.

Return parameters

The status callback property can be as follows:

The details property is available only when an application has failed to launch. It reports the exact reason why an application failed to launch.

The progress property is available only when an application is in progress. It reports the progress in percentage (0-100).

Example

// Launch application by ID with callback returning progress information.
Liquit.Applications.Launch(id, null, function (e) {

	console.log(e);

	// *** e.state ***
	// Can be one of the following values:
	//
	// * 'success': The application has been successfully launched.
	// * 'inprogress': The application is being installed. Check the progress property to see how far along the installation is.
	// * 'failure': The application has failed to start. See the details property for more information about the error.
	//
	// *** e.progress ***
	// Gives an estimated percentage of the installation progress.
	//
	// *** e.details ***
	// Gives additional information about the failure to launch the application.
	// This is structured with a 'code' field and a 'message' field describing the error.
	//

	// Application started
	if (e.state == 'success')
		alert('application started');

	// Failed to start application.
	else if (e.state == 'failure')
		alert('application failed to start: ' + e.details.code + ': ' + e.details.message);

});

The Liquit.Applications.List function returns all applications that are available to the user. Whenever an application has been made available in the Application Workspace it will be listed in the response of this function. The Application Workspace API autodetects whether or not the Agent is available and adjusts its response according to it. For example, a local application will not be enabled when the Agent is not running.

Request parameters

Return parameters

The following properties are returned:

Example

Below you will find a small example of code to render the applications and their respective icons.

// Do Liquit API calls...
Liquit.Applications.List({

  sort:0

},function (fault, result) {

  // Check if the request failed.
  if (fault != null) {
    alert('Error ' + fault.code + ': ' + fault.message);
    return;
  }

  for (var i = 0; i < result.length; i++) {
    
    $('body').append(
      $('<div>')
        .attr({
          id: result[i].id
        })
        .addClass('app')
        .toggleClass('disabled', !result[i].enabled)
        .on('click', function (e) {

          // Get target html element.
          var target = $(e.currentTarget);

          // Verify application is disabled
          if (target.hasClass('disabled')) {
            alert('Application is disabled');
            return;
          }

          // Launch application by ID with callback returning progress information.
          Liquit.Applications.Launch(target.attr('id'), null, function (e) {

            console.log(e);

            // *** e.state ***
            // Can be one of the following values:
            //
            // * 'success': The application has been successfully launched.
            // * 'inprogress': The application is being installed. Check the progress property to see how far along the installation is.
            // * 'failure': The application has failed to start. See the details property for more information about the error.
            //
            // *** e.progress ***
            // Gives an estimated percentage of the installation progress.
            //
            // *** e.details ***
            // Gives additional information about the failure to launch the application.
            // This is structured with a 'code' field and a 'message' field describing the error.
            //

            // Application started
            if (e.state == 'success')
              alert('application started');

            // Failed to start application.
            else if (e.state == 'failure')
              alert('application failed to start: ' + e.details.code + ': ' + e.details.message);

          });

        })
        .append(
          $('<img>')
            .addClass('icon')
            .attr({
              src: result[i].icon
            })
            .toggle(result[i].icon != null),
          $('<span>')
            .addClass('title')
            .text(result[i].name)
        )
    );

  }

});

The Liquit.Applications.Create function lets the end-user add a personal application of their own. This can be a local application or a URL the user wants to save to their workspace.
By default, the Liquit.Application.Create API will return the ID of the freshly created personal application. When the request fails, an error will be returned in the fault object of the response. This can be because an application with the same name already exists.

Request parameters

Based on the type, the following parameters are available:

Example

var type = 'url';
var name = 'friendlyName';
var path = 'https://www.recastsoftware.com';
var icon = $('.icon')[0].files;

Liquit.Applications.Create({
  type: type,
  name: name,
  url: path,
  icon: file
}, function (fault, result) {
  console.log(fault, result);
});

The Liquit.Applications.Favorite function adds an application to the favorites list of the end-user. This function requires the ID of the application you want to add to the favorites list.

Usage and example

You need to specify at least the values shown in the example below:

Liquit.Applications.Favorite(

  // The id of the application you want to favorite or unfavorite.
  '00000000-0000-0000-0000-000000000000', 
  
  // True adds the application to the favorites, false removes the application from the favorites.
  true, 

  // Callback which either returns an error or the result of the API call.
  function (fault, result) {
    console.log(result);
  }

);

The Liquit.Applications.Get function returns the properties of a personal application. This function is not available for packages assigned to the user via the Application Workspace interface.
By default, the Liquit.Applications.Get API returns information about the entity triggered by the personal app, and its corresponding settings. To acquire information on the application, you need to supply its ID and its source information.

Request parameters

The following parameters are available for the API:

Return parameters

The following properties are returned:

Example

Below you will find a small example of code to fetch a personal application and its starting information.

// Do Application Workspace API calls...
Liquit.Applications.Get({
    id: id,
    source: {
        id: sourceId,
        type: 'Team'
    }
}, function(fault, result) {
    console.log({
        fault: fault,
        result: result
    });
});
                               

The Liquit.Applications.Move function changes the position of an application. This determines the order of the applications shown if no explicit sorting options are used in the Liquit.Applications.List function.

Usage and example

You need to specify at least the ID of the targeted application and the target position:

Liquit.Applications.Move(

  // The id of the application you want to move.
  '00000000-0000-0000-0000-000000000000', 

  // The target position.
  0,

  // Callback that will return a fault object when something goes wrong.
  function (fault, result) {
    console.log(result);
  }

);

The Liquit.Applications.Remove function removes an application from the Application Workspace.

Example

You need to specify at least the ID of the application you want to remove as shown in the example below:

Liquit.Applications.Remove(

  // The id of the application you want to remove from the workspace.
  '00000000-0000-0000-0000-000000000000',

  // The callback function that provides feedback.
  function (fault, result) {
    console.log(result);
  }
  
);

The Liquit.Applications.Update function updates a personal application.
By default, the Liquit.Application.Update API returns the ID of the freshly created personal application. When the request fails, an error is returned in the fault object of the response. This can can happen for example because an application with the same name already exists.

Request parameters

Based on the type of application, the following options are available:

Example

var type = 'url';
var name = 'friendlyName';
var path = 'https://www.recastsoftware.com';
var icon = $('.icon')[0].files;

Liquit.Applications.Update('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' , {
  type: type,
  name: name,
  url: path,
  icon: file
}, function (fault, result) {
  console.log(fault, result);
});

The Liquit.Catalog.List function returns all applications available in the user's catalog. Whenever an application is made available in the Catalog, it is listed in the response of this function.

Request parameters

The following parameters are available for the API:

Return parameters

Example

Liquit.Catalog.List({
    media: true,
    license: true,
    reviews: true,
    faq: true
        }, function (fault, result) {

        // Check if the request failed.
        if (fault != null) {
            alert('Error ' + fault.code + ': ' + fault.message);
            return;
	    }

	    // The result object will contain an array of all catalog items.
        console.log(result);
});

The Liquit.Catalog.Get function returns all information on an application in the user catalog. Whenever an application has been made available in the Catalog it will be available in the response of this function.

Request parameters

The following parameters are available for the API:

Return parameters

The following properties are returned:

Example

				var id = '00000000-0000-0000-0000-000000000000';
				// Catalog get
				Liquit.Catalog.Get({
					id:id,
					media: true,
					license: true,
					reviews: true,
					faq: true
				}, function (fault, result) {
					console.log(result)
				});

The Liquit.Categories.List function returns all categories available to the user. Categories can be assigned to applications and help organize them. To get insight into the assigned categories, see Liquit.Application.List or Liquit.Application.Get.

Return parameters

The API call returns an array with all the categories assigned to the user. Each category will have the following properties.

Example

Liquit.Categories.List(function (result) {

	    // The result object will contain an array of all categories.
        console.log(result);
});

The Liquit.Catalog.Request function is used to request applications from catalog. All applicable applications return a callback reporting on the status of the application, this can be either the application has been requested successfully or indicate approval from an approver is equired.

Return parameters

The status callback property can be as follows:

Liquit.Catalog.Request(id, function (e) {
// e = null
// the requested application has been approved and the application becomes available in the workspace right away

// e = “Pending”

// The requested application needs approval before becoming available in the workspace.

});

The Liquit.Settings.List function returns all user and portal settings available. Some properties are read-only; for more details, see the list with all properties.

Usage

Every setting has at least four different properties:

• id - The identifier of the setting (e.g. “portal.animations” identifies whether or not animations are enabled)
• force - Reflects whether or not an administrator has locked a user setting in Application Workspace > Manage > User Settings.
• inherited - This property reflects whether or not the value is inherited or if it is modified
• value - Returns the value of the setting.

Example

Liquit.Settings.List(function (fault, result) {
  
  // Check if the request failed.
  if (fault != null) {
    alert('Error ' + fault.code + ': ' + fault.message);
    return;
  }
  
  // The result object contains an array with all the settings.
  console.log(result)
  
  // Build a table with all the available settings and their values.
  var table = $('<table>')
  .append(
    $('<tr>').append(
      $('<td>')
      .text('Setting id'),
      $('<td>')
      .text('Value'),
      $('<td>')
      .text('Force'),
      $('<td>')
      .text('Inherited')
    )
  );
  
  // Loop through result.
  for (var i in result)
    table.append(
      $('<tr>').append(
        $('<td>').text(result[i].id),
        $('<td>').text(result[i].value),
        $('<td>').text(result[i].force),
        $('<td>').text(result[i].inherited)
      )
    )
  
  table.appendTo($('body'));

});

The Liquit.Settings.Update function enables you to update a setting to a new value. Some properties are read-only; for more details, see the list with all properties.

Usage

To update a setting you need to at least specify the ID of the setting and the value. It is possible to update more than one setting at a time.

Example

Liquit.Settings.Update(
  
  // The array with the settings you want to adjust.
  [
    {
    
      // The id of the setting you want to adjust.
      id: 'portal.background.color',
    
      // The value you want to assign to the property.
      value: '000'
      
    },
    {
      id: 'portal.text.shadow',
      value:false
    }
  ],
  
  // Callback.
  function (fault, result) {

    // If an error occurs, the fault object will return an error and an error message.
    console.log(fault);

    // Returns the result of the API call when connected to Application Workspace 3.0 and later. Application Workspace 2.x APIs will return null
    console.log(result);
    
  }

);

The Liquit.Contexts.List function returns all contexts that are available to the user.

Return parameters

The following properties are available:

Example

Liquit.Contexts.List(function (fault, result) {

        // Check if the request failed.
        if (fault != null) {
            alert('Error ' + fault.code + ': ' + fault.message);
            return;
	    }

	    // The result object will contain an array of all contexts
        console.log(result);
});

The Liquit.Tags.List function returns all tags available to the user. Tags can be assigned to applications and help organize applications. To get insight into the assigned tags, see Liquit.Application.List or Liquit.Application.Get.

Return parameters

The API call returns an array with all the tags assigned to the user. These are available because they are assigned to applications that in turn are assigned to the user. Each tag will have the following properties.

Example

Liquit.Tags.List(function (result) {

	    // The result object will contain an array of all tags.
        console.log(result);
});