This article describes how to use an On Behalf Of (OBO) pattern to perform operations on behalf of a Symphony end user.

Overview

In conjunction with the Symphony URI, which launches the Symphony desktop client, the OBO pattern can be used for building click-to-chat integrations with third-party or in-house systems, such as a trading platform, a research management system, or a CRM.

The pattern is comprised of an authentication sequence and a series of OBO-compatible endpoints that allow an app to take actions on behalf of the user in context, including:

• Initiate connection requests to and determine connection status with other users
• Get the presence state of other connected users
• Initiate IMs and MIMs with other users
• Send messages and attachments
• Set the context user's own presence

OBO use cases differ from bot use cases in that activities are performed as if end users had initiated actions directly from within Symphony themselves.

Getting Started

1. Create an application manifest bundle file for the OBO app.
2. Set the required permissions.
3. Authenticate.
4. Invoke OBO-enabled endpoints.

OBO App Permissions

OBO integrations can be built either by enterprises to integrate with internal systems or partners who want to create workflow integrations with their applications.

To use the endpoints above, OBO apps must be assigned the appropriate permissions from the list below:

OBO Apps and Authentication

On Behalf Of integrations are apps that must be enabled for customer pods and installed for specific users. Similar to Symphony's Extension API Apps, OBO apps are surfaced in the Symphony Admin Portal, where company admins can choose to enable them for their pod.

OBO apps are specified by an appId and a certificate (similar to those used for REST API Bot Authentication), which has a common name that matches the apps name. This certificate must be trusted on the customer's pod, which can be done in the Admin Portal > Manage Certificates section.

For OBO apps, authentication is a two-fold process:

1. The app itself must be authenticated using its certificate. The app authenticates only if it is enabled for the pod and its certificate is trusted. Upon successful OBO app authentication, the app receives an app sessionToken.
2. The app must request to authenticate on behalf of a particular user, using its app sessionToken. The app authenticates only if it is installed for the user and its app sessionToken is valid. Upon successful OBO user authentication, the app receives the user's sessionToken.

Once the app has obtained the user's sessionToken, it can make REST API calls with this sessionToken to perform activities on behalf of the session user.

OBO-Enabled Endpoints

See OBO-Enabled Endpoints for a list of endpoints that have been enabled for OBO.

OBO Pod and Agent Paths

OBO integrations can be built either by enterprises to integrate with internal systems or partners who want to create workflow integrations with their applications.

📘

Customer Prerequisite

To build and use OBO integrations, customers (that is, end users) must have the required Symphony API infrastructure. Specifically, they must have the Agent component that allows for encryption and decryption of messages sent via the API.

When an app calls an OBO endpoint to authenticate or to perform an operation, the app must use the paths corresponding to the user whom the app intends to act on behalf of.

Enterprise developers should know (or can obtain through internal channels) the paths for their infrastructure (pod/Agent) and can call the OBO endpoints with these paths prespecified.

For partners building apps for use by multiple customers, these paths are unique to each customer and are provided to the partner by Symphony via a callback when the app has been enabled for the customer's pod.

As part of provisioning a partner's app, Symphony asks the partner to supply a callback URL and an application key.

This callback URL is invoked when the partner's app is enabled by a customer or a customer's Agent is registered with their pod (a rare event but possible, for example, if a customer changed their Agent address after the app was enabled).

Symphony invokes the callback URL, returning the base URLs the partner should use for OBO requests.

POST https://<callback url>
X-API-KEY: <apiKey>
 
{
  "appId": "appId",
  "companyId": "companyId",
  "eventType": "eventType", // "appEnabled" or "agentRegistered"
  "payload": {
     "agentUrl": "agentUrl", // This field will only be returned if there is an Agent registered with the pod
     "podUrl": "podUrl",
     "sessionAuthUrl": "sessionAuthUrl"
   }
}

🚧

Partner Agent Access

Symphony's customers can have their encryption/decryption infrastructure (Key Manager and Agent) either hosted in-cloud by Symphony or on-premise. Partner applications can be either cloud-based or on-premise (on the user's desktop). Partner applications can perform OBO message sending only if they have access to the customer's Agent. The following three scenarios are supported:

• The customer's Symphony KM and Agent and the partner's application are all on-premise.
• The customer's Symphony KM and Agent are in-cloud, and the partner's application is cloud-based.
• The customer's Symphony KM and Agent are in-cloud, and the partner's application is on the user's desktop.

in a future release, Symphony plans to support the case in which the customer's Symphony KM and Agent are on-premise and the partner's application is in-cloud.