SharePoint

Overview

SharePoint empowers teamwork with dynamic and productive team sites for every project team, department, and division. Share files, data, news, and resources. Customize your site to streamline your team's work. Collaborate effortlessly and securely with team members inside and outside your organization, across PCs, Macs, and mobile devices.

D3 SOAR is providing REST operations to function with SharePoint.

SharePoint is available for use in:

Known Limitations

See Avoid getting throttled or blocked in SharePoint Online | Microsoft Learn for more information about the rate limits of the SharePoint API.

Connection

To connect to SharePoint from D3 SOAR, please follow this part to collect the required information below:

Permission Requirements

Each endpoint in the SharePoint API requires a certain permission scope. Run the following commands in PowerShell to enable the required permissions. Note: Values surrounded by ankle brackets (<>) are to be replaced with your values.

1. Install the SharePoint module for PowerShell.

Install-Module -Name Microsoft.Online.SharePoint.PowerShell

2. Define the admin user to grant the permissions.

$adminUPN="<AdminUser>@<YourMicrosoftAccount>"

3. Define the organization user grant the permissions.

$orgName="<OrganizationForSharePoint>"

4. Connect to SharePoint online.

$userCredential = Get-Credential -UserName $adminUPN -Message "<PASSWORD>"Connect-SPOService -Url https://$orgName-admin.sharepoint.com $userCredential

5. Allow apps to use Azure Access Control.

$userCredential
set-spotenant -DisableCustomAppAuthentication $false

6. Get auth from site upload file permission.

set-SPOsite -identity https://$orgName.sharepoint.com/sites/{sitename} -DenyAddAndCustomizePages $false

Note: All permissions above are required.

Configuring SharePoint to Work with D3 SOAR

1. Access and log in to your SharePoint environment (https://<Your_Sharepoint_Address>/_layouts/15/sharepoint.aspx) with admin credentials.

2. Once you are logged in, access the following link to generate a Client ID and Client Secret: https://<Your_Sharepoint_Address>/_layouts/15/appregnew.aspx.

   

   1. Click Generate next to the Client Id field to generate the client ID. Store the client ID in a secure location. It will be required to build the integration connection in D3 SOAR.

   2. Click Generate next to the Client Secret field to generate the client Secret. Store the client secret in a secure location. It will be required to build the integration connection in D3 SOAR.

   3. Input a Title for the app (e.g. API Connection).

   4. Input the App Domain (e.g. www.contoso.com). If you are unsure about this field, you may use the provided example. It will not affect the connection app.

   5. Input the Redirect URI (e.g. https://www.contoso.com/default.aspx). If you are unsure about this field, you may use the provided example. It will not affect the connection app.

   6. Click Create.

3. Access the following link to add permissions to the app: https://<Your_SharePoint_Tenant_Name>-admin.sharepoint.com/_layouts/15/appinv.aspx

   

   1. Input the Client Id of your created app into the App Id field, then click Lookup. The other fields will automatically be populated.

   2. Under Permission Request XML, input the following XML.
      <AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" /></AppPermissionRequests>

   3. Click Create.

4. You will be prompted to trust the created API connection. Click Trust It.

   

5. Obtain your app's Tenant ID. Go to https://portal.azure.com/#home and log in with your admin account. Navigate to App registrations, then locate and select your SharePoint tenant name. The Directory (tenant) ID will be displayed under the Essentials section. Store the ID in a secure location, it will be required to establish the connection in D3 SOAR.

   

Configuring D3 SOAR to Work with SharePoint

1. Log in to D3 SOAR.

2. Find the SharePoint integration.

   

   1. Navigate to Configuration on the top header menu.

   2. Click on the Integration icon on the left sidebar.

   3. Type SharePoint in the search box to find the integration, then click it to select it.

   4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.

3. Configure the following fields to create a connection to SharePoint.

   

   1. Connection Name: The desired name for the connection.

   2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

   3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.

   4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

   5. Description (Optional): Add your desired description for the connection.

   6. Configure User Permissions: Defines which users have access to the connection.

   7. Active: Check the tick box to ensure the connection is available for use.

      

   8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
      1. Input the Server URL of your SharePoint server.
      2. Input the saved Tenant ID. See step 5 of Configuring SharePoint to Work with D3 SOAR.
      3. Input the saved Client ID generated on SharePoint. See step 2 of Configuring SharePoint to Work with D3 SOAR.
      4. Input the saved Client Secret generated on SharePoint. See step 2 of Configuring SharePoint to Work with D3 SOAR.

   9. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.

   10. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
       To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

4. Test the connection.

   

   1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

   2. Click OK to close the alert window.

   3. Click + Add to create and add the configured connection.

Commands

SharePoint includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the SharePoint API, please refer to the SharePoint API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring SharePoint to Work with D3 SOAR for details.

Upload File

Uploads a file to SharePoint from D3 SOAR’s database.

Reader Note

• Folder Name and Site Name are required to run this command.

  • The Site Name parameter is referring to the sites on SharePoint. Sites can be viewed and created from the SharePoint home page.

    

  • The input Folder Name must exist in the specified site. You can create a new folder or find your desired folder under the Documents tab of your selected site.

    

File ID and File Source

It is not recommended to use the Test Command feature with the Submit Sample Files command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

1. In D3 SOAR, navigate to Configuration on the top bar menu.

2. Click Utility Commands on the left sidebar menu.

3. Use the search box to find and select the Create a File from input Text Array command.

4. Select the Test tab, then input the required information for the parameters. Click Test Command.
   A D3 File ID will appear in the output data after the file has been successfully created.
   (Note: The D3 File Source of the created file will be Playbook File)

Input

Output

[
  {
      "CheckInComment": "",
      "CheckOutType": 2,
      "ContentTag": "{***-***-***-***-***},10,10",
      "CustomizedPageStatus": 0,
      "ETag": "\"{***-***-***-***-***},10\"",
      "Exists": true,
      "IrmEnabled": false,
      "Length": "2935",
      "Level": 1,
      "LinkingUri": null,
      "LinkingUrl": "",
      "MajorVersion": 1,
      "MinorVersion": 0,
      "Name": "testfolder1",
      "ServerRelativeUrl": "/sites/TestCommunicationSite/testfolder1",
      "TimeCreated": "2022-08-29T21:50:05Z",
      "TimeLastModified": "2022-08-30T19:58:08Z",
      "Title": null,
      "UIVersion": 512,
      "UIVersionLabel": "1.0",
      "UniqueId": "***-***-***-***-***"
  }
]

Successful

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Get Folder

Retrieves folder(s) from the Shared Documents library.

Reader Note

All folders are stored under the system's "/Shared Documents" folder. To retrieve all folders, leave the parameter empty. If you need to access a specific folder, define the Server Relative URL parameter with its folder path. You can obtain the path value from the returned raw data at the path $.Folders[*].Folders[*].ServerRelativeUrl after running this command with no defined parameters.

Please note that the root folder is "/Shared Documents" and cannot be changed. To access a first-level folder, follow the root folder with the folder's name, for example, "/General". To access a subfolder, add the folder name after the parent folder's URL, for example, "/Shared Documents/General/test".

Input

Output

{
    "Exists": true,
    "IsWOPIEnabled": false,
    "ItemCount": 1,
    "Name": "Shared Documents",
    "ProgID": null,
    "ServerRelativeUrl": "/Shared Documents",
    "TimeCreated": "2021-02-28T06:20:15Z",
    "TimeLastModified": "2022-08-31T22:26:43Z",
    "UniqueId": "***-***-***-***-***",
    "WelcomePage": ""
}

Successful

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Successful

Error Handling

If the Return Data is failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.