Important

You are browsing upcoming documentation for version 6.1 of OroCommerce, scheduled for release in 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

OroConnector Add-in for Microsoft 365

Note

OroConnector Add-in for Microsoft 365 is available for Enterprise Edition only.

The OroConnector add-in is a valuable tool for users of the Enterprise Oro applications. It allows users to interact with Oro applications from within Outlook through an Outlook add-in. The OroConnector eliminates the need for time-consuming switching between applications, streamlining workflow processes, and improving productivity. Its seamless integration with your email client makes it a game-changer for Oro users, providing a more convenient and streamlined workflow.

Requirements

Ensure you have the following installed on your system before proceeding:

• Node.js (v14+ recommended)

• pnpm (package manager for Node.js) – Install via:

npm install -g pnpm

Set Up the Project

Set Up the Project Manually

1. Clone the MS365 Mailbox add-in repository code to your project folder (for Enterprise customers only).

2. Install node_modules:

pnpm i

3. Add a new .env file and set up environment variables following the example in the .env.example file.

4. Run the following command to generate a manifest file:

pnpm run generate-manifest

5. Run the following command to create a build folder:

pnpm run build

6. Deploy dist folder on [your-addin-domain] (for example on Azure server).

Set Up Individual Local Environment

1. Generate certificates for local environment.

   • Install office-addin-dev-certs lib:

   npm i -g office-addin-dev-certs
   

   • Generate certificates:

   office-addin-dev-certs install
   

2. Open your Get add-ins window.

3. Navigate to Add-Ins for Outlook > My add-ins > Custom Addins > + Add a custom add-in > Add from file.

4. Choose the generated manifest file.

5. Run the following command:

pnpm run dev

6. Open your Outlook client. Open any email and find the OroConnector add-in.

Configure the OAuth Application

To create a new OAuth application in Oro:

Navigate to System > User Management > OAuth Applications in your Oro application. Create a new OAuth application with the following settings:

• Grant Type: Authorization Code

• Redirect URL: Enter the required URL in the https://[your-addin-domain].com/grant-access-token-success format. For local setup it should be: https://localhost:3000/grant-access-token-success.

Once saved, the system will generate Client ID and Client Secret for the OAuth application. Update your .env file with the generated credentials, where:

VITE_APP_CLIENT_ID = Client ID
VITE_APP_CLIENT_SECRET = Client Secret

Note

For more details on OAuth application configuration, refer to the related documentation.

Deploy Production and Publish on the Internal Marketplace

1. Log in to Azure Service.

2. Navigate to Applications > App registrations and click + New registration to create a new registration.

3. Fill in the app name, choose a supported account type, and select the Single-page application (SPA) option from the dropdown menu under Redirect URI. Click Register.

4. The system will generate Application (client) ID and Directory (tenant) ID for your application. Update your .env file with the generated credentials, where:

VITE_APP_AZURE_CLIENT_ID: Application (client) ID
VITE_APP_AZURE_TENANT_ID: Directory (tenant) ID

5. Navigate to the API permissions subsection and click + Add a permission.

6. Click Microsoft Graph > Delegated permissions and select the following permissions:

   • Mail > Mail.Read

   • Mail > Mail.ReadBasic

   • OpenId permissions > Openid

   • OpenId permissions > Profile

   • OpenId permissions > Email

   • User > User.Read

7. Click Add permissions to save the request.

8. Navigate to Applications > Enterprise applications in the main menu, then Manage > All applications in the submenu. Search by your application name (from Step 3) via the search field and click it.

9. Go to Users and groups submenu and click the + Add users/group button.

10. On the Add Assignment page, click None Selected under Users to add all required users.

11. Choose the users or groups to be added to your application and click Select.

12. Click Assign to save the list.

Set Up Add-in to Your Organization

1. Create an OAuth Application.

2. Follow the Set Up the Project Manually flow.

3. Navigate to MS Admin Panel.

4. Go to Settings > Integrated Apps in the menu to the left.

5. Click Upload custom apps.

6. For App type select Office Add-in and provide the URL to your manifest file. Click Next.

7. On the Users step, select users with whom you want to share the OroConnector Add-in. Click Next.

8. Complete the details on the Deployment step and click Finish Deployment.

9. The OroConnector Add-in should now be available at the bottom of the Integrated Apps page.

Connect

Once OroConnector has been installed in your mail client, a new icon will appear in the side panel, indicating that the add-in is ready for use.

To connect the add-in to your Oro application:

1. Open the OroConnector add-in by clicking on the Oro icon.

2. Click Connect.

3. Provide valid Oro credentials to log in to your Oro application.

   

4. Click Grant to allow the connector to access information from the Oro application.

   

Manage OroConnector Menu

The connector’s menu offers the following actions:

About	Read more information about the connector.
Disconnect	End the connection with the connector.
Refresh	Update the connector.
Manage Add-in	Access the connector’s settings. This option is only available to the organization’s administrator who installed the connector.

Search & Context

Once you have completed the setup process, OroConnector is available for you to start your search for the necessary information and add or remove context from the add-in.

In Oro applications, context is a piece of information relevant to a particular user, task, or process within the application. When an OroConnector user opens an email thread in their mail client, they can see Oro entities related to that particular email and retrieve the latest context of the conversation. Context search is performed by the From/To/CC/BCC fields of the email being viewed.

By default, the following data is passed from your Oro application to the connector and vice versa:

• Accounts

• Contacts

• Customer users

• Leads

• Opportunities

• Orders

• Users

• Customers

• Tasks

• Cases

• Requests for quotes.

To begin your search, type a query into the search bar and click Enter. If the search returns many entities, click Load More to view all available search results.

Hint

OroConnector will also give you prompts if there is an association with an entity, for example Could Be Related To or In Context Of.

Manage Context

Click on the desired entity from the search results to view its details. Here, you can perform the following actions:

• Open.

  To view an entity you found in the OroConnector in the Oro application, click Open. You will be redirected to the view page of this entity on the Oro side.

  

• Add Context.

  You can connect any relevant entities to an email thread as context. When the connector and Oro application are synchronized, you can easily view the added context on both the email and Oro application side. You can add multiple entities as necessary to provide additional context to the email.

  To add an entity as context, click Add Context on its details page.

• Remove Context.

  Removing context in the OroConnector removes it on the Oro application side as well. To disconnect entities from the email thread as its context, click Remove Context on the details page of the entity.