Prerequisites

• Access to the Configuration > General parameters (DC035) menu.
• Access to the Document (DC010) menu.
• Microsoft Entra ID user with Global Admin privilege.
• SoftExpert Document user with the "View", "Edit", and "Save locally" controls allowed in the security list of the document.
• SoftExpert Suite user with the Microsoft account e-mail that has access to the registered tenant.
• Allow original file download in the view mode parameter checked in the General section of the Configuration > General parameters (DC035) menu.
• Document in the "Revision" or "Indexing" step.

Introduction

The Document component allows for using Microsoft OneDrive to edit and view electronic files during the revision or indexing step.

When this resource is used, files are opened directly through Office 365 applications (Word, Excel, PowerPoint, etc.) and, once the revision is completed, they are automatically stored again in the Document component.

To enable this feature, it is necessary to integrate the Microsoft 365 API with SoftExpert Document, ensuring that the electronic files can be edited later with the Office pack.

Below, see the procedures you need to perform in order to use this resource.

Creating a site in your company's SharePoint

1. Access SharePoint.

2. Log in with your Microsoft work account.

3. Access the SharePoint admin center: https://[your-domain]-admin.sharepoint.com.

4. In the left side menu, expand Sites and click on Active sites.

5. In the action bar above the site list, click on + Create.

6. Choose the desired site type for the team.

7. Set up the site by filling in the following fields:

• Site name: enter the name of your site. Suggestion: SoftExpert Document.
• Description (optional): describe the site's purpose. Suggestion: "Site intended for integration with SoftExpert Document".
• Privacy: private.
• Site address (URL): SharePoint automatically generates the site's address (URL), but it is possible to adjust it, if you wish. Take note of the final URL path, as it will be used later in the Graph Explorer query to obtain the site's ID.

8. Add the site's owners and members (or skip this step and add them later).

9. Click on Finish.

Setting up the Microsoft 365 API

Part 1: Initial app registration

1. Access the Microsoft Entra portal.

2. In the side panel, go to Identity > Applications > App registrations.

3. Select the New registration option.

4. Fill in the fields that will be displayed:

• Name: SoftExpert Document
• Supported account types: select the Accounts in this organizational directory only option.
• Redirect URL (optional): select the Web option and fill in the field next to it with http://localhost.

5. Click on Register.

Part 2: Basic configuration and ID collection

1. On the "Overview" screen that will be shown, copy the following values and keep them somewhere safe, as they will be used later:

• Application ID (client)
• Directory ID (tenant)

2. In the Manage section of the side panel, click on Branding and Properties.

3. Fill in the Home page URL field with http://localhost and click on Save.

4. Still in the Manage section, click on Owners.

5. If your user (or the appropriate service user) does not appear on the list, select the Add owners option, locate and select the intended user, and click on the Select button.

Part 3: API permission configuration

1. From the side panel, in the Manage section, click on API permissions.

2. Click on the Microsoft Graph User.Read permission. It will be displayed by default as granted.

3. In the panel that will be displayed, click on the Remove permission option and confirm the deletion.

4. Back to the "API permissions" main screen, click on Add a permission.

5. In the side panel, click on Microsoft Graph.

6. Choose the Application permissions option.

7. In the search box, type Sites.Selected.

8. Check the Sites.Selected option and click on the Add permissions button.

9. After adding the permission, click on the Grant admin consent for [Your Directory] button and confirm the action.

Part 4: Client secret creation

1. From the side panel, in the Manage section, click on Certificates and secrets.

2. In the Client secrets tab, click on New client secret.

3. In the panel that will be displayed, fill in these fields:

• Description: enter a value such as “DC035” or “SoftExpertDocument_Secret”.
• Expires on: select the 24 months option (or the desired period).

4. Click on Add.

5. The secret will be shown on the list. Copy the content of the Value column and keep it somewhere safe, as it will be used later.

Obtaining the site's ID

Part 1: Preparation - Authenticating in Graph Explorer

1. Access Graph Explorer.

2. In the upper-right corner, click on the Sign in icon and authenticate yourself with your administrator account (Global Admin or SharePoint Admin).

3. Upon logging in, before opening the permissions, type a site-related URL in the query bar so that the correct permissions are displayed. To consent to Sites.Read.All, use: https://graph.microsoft.com/v1.0/sites/root

4. Click on the Modify permissions tab and, in the Sites.Read.All row, click on Consent. This permission is required to find the site in Part 2.

5. Next, to consent to the Sites.FullControl.All permission, enter the permissions URL in the bar (you may keep {siteId} as a placeholder just to load the list): https://graph.microsoft.com/v1.0/sites/{siteId}/permissions. Open the Modify permissions tab again: now Sites.FullControl.All will be displayed. Click on Consent in that row. This permission is required to grant access to your application in Part 3.

6. In the Microsoft pop-up windows generated when you click on Consent, confirm the permission for "Graph Explorer".

7. Graph Explorer is ready to be used.

Part 2: Obtaining the site's ID (GET request)

1. Check if the HTTP method is set to GET (it is usually the default option).

2. In the main query bar, enter the URL in the format below, replacing the placeholders: https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}

• {hostname}: your company's host in SharePoint. Example: yourcompany.sharepoint.com.
• {site-path}: the portion that appears after the domain in your site's URL, exactly as shown in the browser. It is usually sites/SiteName.

3. Click on Run query.

4. The Response preview window below will display a JSON. Copy the entire value of the id field and save it somewhere. The value must follow this pattern: yourcompany.sharepoint.com,xxxx-xxxx-xxxx,yyyy-yyyy-yyyy.

Part 3: Granting permission to your application (POST request)

1. Change the HTTP method from GET to POST.

2. In the query bar, enter the new URL, replacing the {siteId} value with the recently copied ID: https://graph.microsoft.com/v1.0/sites/{siteId}/permissions

3. Below the query bar, click on the Request Headers tab.

4. Fill in the fields that will be displayed:

• In the Key field, type: Content-Type
• In the Value field, type: application/json

5. Click on Add.

6. Click on the Request Body tab next to it.

7. Paste the following JSON into the text editor, replacing the placeholders with the data of the application created in the previous tab:

{
  "roles": ["write"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "<client-id-of-your-app>",
        "displayName": "<name-of-your-app>"
      }
    }
  ]
}

• <client-id-of-your-app>: replace it with the "Application ID (client)" saved earlier.
• <name-of-your-app>: replace it with the name of your application. Example: “SoftExpert Document”.

8. Check that everything is correct (POST URL, Request Header, and Request Body) and click on Run query.

9. If all goes well, the 201 Created status will be shown, along with the JSON for the permission that has just been created, in the response window.

Setting up the integration in the Document component

1. Access the Configuration > General parameters (DC035) menu and go to the Microsoft 365 section.

2. Check the Enable editing with Microsoft 365 option.

3. Fill in the necessary fields:

4. Check the Convert to PDF using Microsoft 365 option, if you wish. With this option checked, the system will use the integration with Microsoft 365 to convert the electronic files of documents to PDF, provided that PDF publishing is configured in the document category.

Using Microsoft 365 to edit and view electronic files

1. Access the Document (DC010) menu.

2. Locate and place the mouse cursor over the document.

3. Expand the more options button and click on Open electronic file.

4. If there is more than one electronic file associated with the document, select the one you want to view in the list that will be displayed.

Conclusion

Thus, Microsoft 365 has been successfully integrated, and electronic files can now be edited and viewed with the Office package.