5.2 Remote Application Overview

This section provides a conceptual overview about the interoperability between OpenText Vibe and remote applications. If you prefer to learn by doing, you might want to skip this section and begin with Creating a Remote Application.

Use the following very high-level steps as an overview for setting up a customization based on a remote application:

  1. A site administrator registers a remote application, specifying a name and a URL for the application (for more information, see Registering a Remote Application).

  2. After using configuration or designer tools to include HTML from a remote application, a page in Vibe performs an HTTP POST operation to the application’s URL and provides user-context information.

  3. As an option, the remote application can use Web services (SOAP) to obtain Vibe data needed to generate its section of the page.

    For more information about Web services, see Section 2.0, Web Services Overview.

  4. The remote application responds, providing its HTML to the Vibe code that is drawing the page.

    Because Vibe has already begun to draw the page, providing structuring HTML tags (such as html, title, head, and body), the remote application should not specify those tags.

In Vibe, a remote application is treated as a principal; examples of other principals are users and groups. Vibe treats the application like a user, and users are subject to access control.

When Vibe makes a request of the remote application, it provides the user identifier for the user currently viewing the page, and it provides a security token. Depending upon the type of Vibe page that incorporates HTML from the remote application, the security token can be session-based (valid until the user signs out) or request-based (invalid immediately after the remote application responds to the request). In most cases, Vibe uses a combination of the registration information for the remote application, rights assigned to the user currently viewing the page, and rights granted to the remote application itself.

There are several ways to apply HTML generated from remote applications:

  • As an accessory (session-based token)

  • As any portion of a custom form or view (session-based token)

  • As a consequence of a workflow state change (request-based token)

  • As a call from a tag within a custom JSP file (session-based token)

For more information, see the following subsections:

5.2.1 Processing Flow for a Remote Accessory

This section describes the flow of information when someone configures an accessory to use HTML from a remote application to provide its content. Consider the numbers in this graphic and the descriptions that follow it:

Figure 5-1 Conceptual Diagram for an Accessory Calling a Remote Application

  1. The enclosing rectangle in the graphic represents a workspace or folder page.

    Vibe draws the page until it encounters the accessory.

  2. The enclosed rectangle represents an accessory that is configured to use HTML generated from a remote application.

  3. Vibe calls the remote application by using the HTTP POST method, and it provides the user ID of the person viewing the page and a security token.

    The gray portion of the diagram indicates that control has been passed to the remote application, which might be located on a server machine separate from the one running OpenText Vibe.

  4. The rectangle in the gray area represents the remote application.

    The remote application can access databases external to Vibe as part of its process for constructing the HTML needed to generate the accessory. The remote application can run in any environment that can generate an HTML response (for example, using PHP or Pearl scripts in its application environment).

  5. As an option, the remote application can use the Vibe user ID and security token to log into the Vibe Web services and make calls, which can gather Vibe data in preparation for generating the HTML for the accessory.

  6. This rectangle represents Vibe Web services.

    In the graphic, both Web services and the Vibe user interface have access to information in the Vibe database.

After the remote application responds by returning HTML for the accessory, Vibe adds the HTML to the output stream and finishes drawing the page. Then, Vibe revokes the security token so that it can no longer be used.

5.2.2 Processing Flow for a Remote Form

This section describes the flow of information when someone uses the Vibe designers to specify that a remote application provides the HTML for the form used to create an entry. Consider the numbers in this graphic and the descriptions that follow it:

Figure 5-2 Conceptual Model for an Add-Entry Form Generated Remotely

  1. The enclosing rectangle represents the add-entry page.

  2. The enclosed rectangle represents the form used to add an entry.

  3. Vibe does an HTTP POST to the remote application, sending the folder ID of the enclosing folder, the user ID of the person currently viewing the add-entry page, and a session-level security token.

  4. The remote application builds the HTML needed to construct the form to be displayed on the Vibe page. The URL specified to the action element in the form tag points to the remote application.

  5. The remote application can use the user ID and security token to log into Vibe Web services, which can gather data used to construct the form.

  6. This rectangle represents the Vibe Web services.

After the remote application responds by returning HTML for the form, Vibe adds the HTML to the output stream and finishes drawing the page. The user completes and then submits the form. Information on the form goes directly to the remote application, which then uses the folder ID, user ID, and security token to make Web services calls, which, in turn, create a new entry in the folder based on the information provided in the form.

When the user logs out, Vibe revokes the security token.

5.2.3 Setting Access Control for Remote Applications

Understanding Access Control Settings for Remote Applications

As mentioned, Vibe treats a remote application as a OpenText Vibe user, which allows for the application of access control. However, for non-workflow uses of remote applications, Vibe considers these factors when determining access control:

  • Rights granted to the user currently viewing the page that contains HTML from the remote application.

  • Rights granted to the remote application by the owner of the containing binder (workspace or folder).

  • The Trusted designation, which a Site Administrator can grant to a remote application upon registration.

Vibe considers the role of the user viewing the page and the role assigned to the remote application, and Vibe grants the less powerful role to the application. For example, if the user viewing the page has the role of Visitor, and if the workspace or folder owner places the remote application in the role of Participant, the application has the rights associated with a Visitor. As another example, if the user is a Site Administrator, and if the application is a Participant, the application has the rights associated with a Participant.

When the site administer selects the Trusted check box while registering a remote application, then Vibe disregards any access control applied to the application and uses only the access control granted to the user viewing the page.

Finally, if Vibe calls a remote application as the result of a workflow state change, access control is determined by settings in the workflow definition, which can result in the application having the rights of either the entry owner or the folder owner.

Setting Access Controls on a Remote Application

Unless you are certain that an application is trusted (for example, an application that you maintain and run on the same server machine as OpenText Vibe), you should strongly consider placing access controls on the remote application itself. For example, if the site administrator uses the access-control tools to place the remote application into the Participant role in the top Workspace, all workspaces and folders that inherit access control automatically apply the same restrictions on the remote application. Then, if a site administrator views a page calling the remote application, the application is restricted to the rights granted to a Participant instead of those granted to a Site Administrator.

If you do not make any attempt to restrict the rights of a remote application, the remote application has the same rights as the user viewing the page that calls the application. For example, if a site administrator views the page, the remote application can use Site Administrator rights to do anything in Vibe using Web services calls.

To set access controls on a remote application:

  1. Log in to the Vibe site as the Vibe administrator.

  2. Click the Administration icon in the upper-right corner of the page.

    The Administration page is displayed.

  3. Under System, click Access Control for Zone Administration Functions.

    The Configure Access Control page is displayed.

  4. In the provided table, click Add an Application.

  5. In the Add an Application field, start typing the name of the remote application for which you want to set access controls. When the remote application appears in the drop-down list, select it.

  6. Click the Add a role link at the top of the table.

  7. From the drop-down list, select the role that you want to associate to the remote application.

    Vibe adds a new column for the new role.

  8. In the row of the remote application, select the check box that is located in the role column that you want to assign to the remote application.

  9. Click Save Changes.

5.2.4 Reviewing Supporting Source Code

To learn more details about the interaction between OpenText Vibe and a remote application, you can look at example source code by downloading the Kablink Vibe code base from the Open Source Community page.

After downloading the Kablink Vibe sources, review this code:

  • SOAP wrappers for objects: These wrappers are located within the Kablink Vibe source code in /ssf/samples/wsclient/src/org/kablink/teaming/samples/wsclient/TeamingServiceClientWithStub.java.

    For more information about Web services and SOAP wrappers, see Section 2.0, Web Services Overview.

  • Passed information: To see details about the information passed between Kablink Vibe and a remote application, see /ssf/main/src/org/kablink/teaming/remoteapplication/impl/RemoteApplicationManagerImpl.java.