Microsoft Office 365 connector
Microsoft Office 365 connector is used for connecting BMC Helix Digital Workplace Catalog with the Microsoft 365 third-party system, and performing some actions in Office 365.
This topic describes the capabilities of Microsoft Office 365 connector, how to configure this connector, and provides a reference for how to use the Microsoft Office 365 workflow actions.
External account requirements
- Before you start building workflows that use Office 365 actions, you must have:
- A registered account in Microsoft Azure. To register for an account, go to the
Microsoft Azure signup page
. - A registered account in Microsoft 365. To register for an account, go to
Create Microsoft 365 account
.
- Your Microsoft Azure account associated with the Microsoft Office 365 account. For details about how to associate these accounts, see
To associate an existing Azure subscription with the Office 365 account
.
- A registered application to be used for integration. For details about how to register an application, see
Quickstart: Register an application with the Microsoft identity platform
.
- A registered account in Microsoft Azure. To register for an account, go to the
Microsoft Azure signup page
You must set up the following permissions for the registered application in Azure Portal. To set up these permissions, in Azure Portal, under Azure Active Directory, select App registrations, then select the registered application, then select API permissions, then select Add a permission. Then, in the Microsoft APIs tab, select Microsoft Graph, then select Delegated or Application permissions type, and then select the permissions.
Type of permission
Permission Description Delegated
Directory > Directory.Read.All Read directory data Delegated
Mail > Mail.Send Send mail as a user Delegated User > User.ReadWrite Read and write access to the user's profile Delegated User > User.ReadWrite.All Read and write access to all users' profiles Application Directory > Directory.Read.All Read directory data Application
Mail > Mail.Send Send mail as a user Application User > User.ReadWrite.All Read and write access to all users' profiles Find the externalServiceId:
Login to https://portal.azure.com
.Select Azure Active Directory > Licenses to open the Licenses - Overview screen.
- Under Essentials, select your product to open the Licensed users list.
The alphanumeric externalServiceId is displayed afterskuId/in the browser path.
Configuration parameters for the Microsoft Office 365 connector
Before you can use the Microsoft Office 365 connector to import the catalog or resource mapping, or use the connector in workflows, you must configure a connection, as described in Configuring service connectors. The following table describes the parameters required to create a connection:
| Parameter | Examples | Description |
|---|---|---|
| Client ID | 9c6ef4a4-045f-4124-afbb-5aefyfc45eb1 | This value is generated by your Azure account. |
| Client Secret | 5sFUedFu3rM+OfBDg3TKLHcYOC8OMwOuxRvuHb9XfbI | This value is generated by your Azure account. |
| Username | <userName>@<domainName> | The name of a registered Microsoft 365 user account. |
| Password | <userPassword> | The password of the registered Microsoft 365 user account. |
Authentication Code | Not applicable | This parameter is required if the connection cannot be configured successfully by using the Username and Password parameters. |
| Tenant | <domainName> | The domain of the email address. |
| Redirect URL | http://<autoGeneratedValue> | This value is generated by your Azure account. |
| Trust Self-Signed Certificates |
| Not applicable. |
Catalog import capabilities
With the Microsoft Office 365 connector, you can import services from Microsoft Office 365 as services in BMC Helix Digital Workplace Catalog. For details about how to import the catalog, see Importing service catalog items from external systems.
You must import Microsoft Office 365 catalog to BMC Helix Digital Workplace Catalog so that you can build workflows that include any of the following actions:
- Create Office 365 User
- Is Office 365 License Available
- Get Office 365 Available License Count
Resource mapping capabilities
You can map data sets to populate a list of answers in the service questionnaire with a data set. For more information, see Creating selection menus for question responses.
You can map data only from the Country Codes data set. This data set is required for the Usage Location parameter, which is required for the Create Office 365 User action.
Workflow actions available through the Office 365 connector
The following table provides an overview of all Office 365 connector actions:
| Action category | Action | Description | Input parameters | Possible output |
|---|---|---|---|---|
| Actions with accounts | Assign Office 365 License To Existing User | Assigns an existing Office 365 license to an existing user. | Assign Office 365 License To Existing User input parameters | Assign Office 365 License To Existing User output parameters |
Create Office 365 User | Creates an Office 365 user account. Notes:
| Create Office 365 User input parameters | Create Office 365 User output parameters | |
Is Office 365 License Available | Checks if Office 365 license is available for a selected account. Note: The workflow that uses this action must be attached to the Create Office User 365 User [Microsoft Office Developer] imported service. | Is Office 365 License Available input parameters |
| |
Get Office 365 Available License Count | Returns a count of available Office 365 licenses for a selected account. Note: The workflow that uses this action must be attached to the Create Office User 365 User [Microsoft Office Developer] imported service. | Get Office 365 Available License Count input parameters | Number of available licenses | |
Delete Office 365 User | Deletes an existing Office 365 user account. | Delete Office 365 User | No output Note: If the queried user is not found, no exception is thrown. | |
Office 365 Users With Licences Report | Returns a list of users with an Office 365 license. | Office 365 Users With License Report input parameters | ||
Office 365 Users Without Licenses Report | Returns a list of users without an Office 365 license. | Office 365 Users Without License Report input parameters | Office 365 Users Without License Report output parameters | |
| Actions that send notifications about events | Send Office 365 Created User Email Notification | Sends an email notification when an Office 365 user account is created. Use this action to confirm a successful Create Office 365 User operation. | Send Office 365 Created User Email Notification input parameters | No output |
Send Azure Storage Creation Email | Sends an email notification when an Azure storage is created. Use this action in combination with the Create Storage Account Service operation. | Send Azure Storage Creation Email | No output | |
Send Keys For Azure Storage Email | Sends an email with keys for Azure generated when the Azure storage account is created. Use this action in combination with the Create Storage Account Service action. | Send Keys For Azure Storage Email | No output | |
Send Regenerated Keys For Azure Storage Email | Sends an email with regenerated keys for Azure storage. Use this action in combination with the Regenerate Storage Key action. | Send Regenerated Keys for Azure Storage Email | No output | |
Send Aws Instance Creation Email | Sends an email notification when Amazon Web Services storage is created. Use this action in combination with the Launch EC2 Instances action. | Send Aws Instance Creation Email | No output | |
Send Virtual Machine Creation Email | Sends an email notification when a virtual machine is created in Microsoft Azure. Use this action in combination with the Create Vm action. | Send Virtual Machine Creation Email | No output | |
Send Status Virtual Machine Email | Sends an email about the status of a virtual machine in Microsoft Azure. Use this action in combination with the Status Vm action. | Send Status Virtual Machine Email | No output |
Default service actions
The Microsoft Office 365 connector provides the following Day 2 predefined service action: Delete Office 365 User. This action is available for end users who requested creation of an Office 365 user. For more details about Day 2 service actions, see Setting up the My Stuff page.
Example 1: Workflow for a service that generates a report about users with and without licenses
The following workflow generates reports about users with and without licenses. Both of these reports are sent to the Dashboard of BMC Helix Digital Workplace Catalog through the Send In App Notification action.
For configuration details about this service, save the attached Office 365 Users With Licenses Report.zip, and import it to your environment.
Example 2: Building a service that creates an account in Microsoft Office 365
The following video (6:37 min) shows how a catalog administrator builds a service in BMC Helix Digital Workplace Catalog. End users can request this service when they need to create a user account in an external Microsoft Office 365 system:
Input and output parameters for actions
Assign Office 365 License to Existing User input parameters
| Validation | Parameter name | Data type | Example | Description |
|---|---|---|---|---|
| Required | Connection Id | String | Connection > Connection ID | The default Connection ID of this connector. |
| Required | Service Id | String | Process context > Service > External Service ID | The ID of the imported external service request definition. |
| Required | User Principal Name (UPN) | String | Process input > Text variable | UPN of the user to whom the Office 365 license should be assigned. |
Assign Office 365 License to Existing User output parameters
The returned object contains the following Output parameters that can be used in later workflow steps:
| Parameter name | Data type | Example | Description |
|---|---|---|---|
| Assigned Licenses | Array | | A list of available licenses. |
| Assigned Plans | Array | | A list of available assigned plans that contain details about a service, such as service name, service plan ID, capability status, and assigned time stamp. |
| Display Name | String | "displayName":"Allen Allbrook" | Account name of the user who was deleted in Microsoft Office 365. |
| Object Id | String | "objectId":"fc3477bc-30f4-4bcf-a39a-0d24165e2376" | ID of the object in Microsoft Office 365. |
| Provisioned Plans | Array | "provisionedPlans":[] | A list of provisioned plans. |
| Usage Location | String | "usageLocation":"AM" | Location of the user to be created in Microsoft Office Active Directory is the two-letter
ISO 3166-1 alpha-2
|
| User Principal Name (UPN) | String | "userPrincipalName":"Allen@BMC1016.onmicrosoft.com" | The name of a system user in the following format: <user name>@<associated domain name of the user> |
Create Office 365 User input parameters
| Validation | Parameter name | Data type | Example | Description |
|---|---|---|---|---|
| Required | Connection Id | String | Connection > Connection ID | The default Connection ID of this connector. |
| Required | Service Id | String | Process context > Service > External Service ID | The ID of the imported external service request definition. |
| Required | Display Name | String | Process context > Requested By User > Full Name or Process context > Requested For User > Full Name | An account name of the user to be created in Microsoft Office 365. Note: The account display name must be associated with the requester or requested-for user. |
| Required | Mail Nickname | String | Process context > Requested By User > Login Name or Process context > Requested For User > Login Name | A mail nickname for the user to be created in Microsoft Office 365. |
| Required | Password | String | Process input > Text variable | Password of the user to be created in Microsoft Office 365. Note: The password must have at least eight characters and contain at least two of the following options:
|
| Required | Usage Location | String | Process input > Text variable | Location parameter of the user to be created in Microsoft Office 365. The question that you create for the user must be mapped to Country Codes data set that exists in the Microsoft Office 365 connector. |
Create Office 365 User output parameters
The returned object contains the following Output parameters that can be used in later workflow steps:
| Parameter name | Data type | Example | Description |
|---|---|---|---|
| Assigned Licenses | Array | | A list of available licenses. |
| Assigned Plans | Array | | A list of available assigned plans that contain details about a service, such as service name, service plan ID, capability status, and assigned time stamp. |
| Display Name | String | "displayName":"Allen Allbrook" | Account name of the user who was deleted in Microsoft Office 365. |
| Object Id | String | "objectId":"fc3477bc-30f4-4bcf-a39a-0d24165e2376" | ID of the object in Microsoft Office 365. |
| Provisioned Plans | Array | "provisionedPlans":[] | A list of provisioned plans. |
| Usage Location | String | "usageLocation":"AM" | Location of the user to be created in Microsoft Office Active Directory is the two-letter
ISO 3166-1 alpha-2
|
| User Principal Name (UPN) | String | "userPrincipalName":"Allen@BMC1016.onmicrosoft.com" | The name of a system user in the following format: <user name>@<associated domain name of the user> |
Office 365 License input parameters
The Is Office 365 License Available and Get Office 365 Available License Count actions use the same input parameters, which are described in the following table:
| Validation | Parameter name | Data type | Example | Description |
|---|---|---|---|---|
| Required | Connection Id | String | Connection > Connection ID | The default connection ID of this connector. |
| Required | Service Id | String | Process context > External Service ID | ID of the imported external service request definition. |
Delete Office 365 User input parameters
| Validation | Parameter name | Data type | Example | Description |
|---|---|---|---|---|
| Required | Connection Id | String | Connection > Connection ID | The default connection ID of this connector. |
| Required | User Principal Name (UPN) | String | Process input > Text variable | UPN of the user to be deleted. |
Office 365 Users Licenses Report input parameters
Office 365 Users With Licenses Report and Office 365 Users Without Licenses Report actions have a single input parameter, which is described in the following table:
| Validation | Parameter name | Data type | Example | Description |
|---|---|---|---|---|
| Required | Connection Id | String | Connection > Connection ID | The default connection ID of this connector. |
Office 365 Users Licenses Report output parameters
Office 365 Users With Licenses Report and Office 365 Users Without Licenses Report actions return the same output parameters, which are described in the following table:
| Parameter name | Data type | Description |
|---|---|---|
| Description | String | Description of the report. |
| Title | String | Title of the report. |
| Users | Array | List of users with licenses or list of users without licenses. |
For an example of the notification text, see Licenses report.
Send Office 365 Created User Email Notification input parameters
| Validation | Parameter name | Description |
|---|---|---|
| Required | Connection Id | Connection ID of the Microsoft Office 365 connector. |
| Required | Recipient | User who will be notified that the user was created. |
| Required | User Email | Email of the created user. |
For an example of the notification text, see Create Office 365 User notification.
Send Azure Email input parameters
The Send Azure Storage Creation Email, Send Keys For Azure Storage Email, and Send Regenerated Keys For Azure Storage Email actions have the same input parameters parameters, which are described in the following table:
| Validation | Parameter name | Description |
|---|---|---|
| Required | Connection Id | Connection ID of Microsoft Azure connector. |
| Required | Recipient | Email address of the user who will receive the email with the regenerated keys. |
| Required | Storage Account | Account generated for Azure storage. |
| Required | Key 1 | Private access key for Storage Account. |
| Required | Key 2 | Private access key for Storage Account. |
Send AWS Instance Creation Email input parameters
| Validation | Parameter name | Description |
|---|---|---|
| Required | Connection Id | Connection ID of the AWS connector. |
| Required | Recipient | Email address of the user who receives the email about the creation of the AWS instance. |
| Required | Login | Login to the AWS instance. |
| Required | Private Key | Generated private key attachment. |
| Required | Connection details | Connection details of the AWS instance. |
Send Virtual Machine Creation Email input parameters
| Validation | Parameter name | Description |
|---|---|---|
| Required | Connection Id | Connection ID of the Microsoft Azure connector. |
| Required | Recipient | Email address of the user who will receive the email about creation of the virtual machine. |
| Required | Ip | IP address of the virtual machine that was created. |
| Required | Login | User login to the virtual machine. |
| Required | Password | User password to the virtual machine. |
Send Status Virtual Machine Email input parameters
| Validation | Input parameter | Description |
|---|---|---|
| Required | Connection Id | Connection ID of the Microsoft Azure connector. |
| Required | Recipient | Email address of the user who will receive the email about status of the virtual machine. |
| Required | Ip | IP address of the virtual machine. |
| Required | Status | Status the virtual machine that was created. |
Reference screenshots
This section includes helpful screenshots about information referenced in this topic.
Country Codes data set
The following screenshot shows how to map a process input question with the Country Codes data set.
For more details about how to create selection menus for question responses in the Question Designer, see Creating selection menus for question responses.
Create New Office 365 User notification text
The following screenshot shows the notification text that is sent when a new user is created in Microsoft Office 365.
Office 365 Users Licenses Report notification text
The following code blocks show JSON output generated from the Office 365 Users With Licenses Report and Office 365 Users Without Licenses Report actions.
{
"description": "Shows all users in tenant that have at least one assigned license.",
"title": "Users with licenses",
"users": [{
"displayName": "Demo",
"email": "Demo@BMC1016.onmicrosoft.com",
"assignedServicePlans": [{
"name": "ProcessSimple",
"status": "Enabled"
},
{
"name": "TeamspaceAPI",
"status": "Enabled"
},
{
"name": "ProjectWorkManagement",
"status": "Enabled"
},
{
"name": "SharePoint",
"status": "Enabled"
},
{
"name": "MicrosoftStream",
"status": "Enabled"
},
{
"name": "PowerAppsService",
"status": "Enabled"
},
{
"name": "To-Do",
"status": "Enabled"
},
{
"name": "MicrosoftOffice",
"status": "Enabled"
},
{
"name": "SharePoint",
"status": "Enabled"
},
{
"name": "exchange",
"status": "Enabled"
},
{
"name": "OfficeForms",
"status": "Enabled"
},
{
"name": "Sway",
"status": "Enabled"
},
{
"name": "MicrosoftCommunicationsOnline",
"status": "Enabled"
}
],
"provisionedServicePlans": [{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "MicrosoftCommunicationsOnline"
},
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "exchange"
},
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "SharePoint"
},
{
"capabilityStatus": "Enabled",
"provisioningStatus": "Success",
"service": "SharePoint"
]
}{"description":"Shows all users in tenant that does not have any licenses.",
"title":"Users without licenses",
"users":[]
}Required licensing
SaaS subscribers who use BMC Helix ITSM or BMC Helix Virtual Agent Basic service are entitled to this feature.
Comments
Unable to setup O365 Connector.... The provided link talks about how the Microsoft 365 connector has to be setup. We understand that there are predecessors to the steps mentioned on providing access permissions. We find that these permissions are missing on the website or a link at least describing on what has to be done. Based on my earlier experience with other applications as an Azure Admin, I'm able to figure out this has to be provided under the Graph API permissions however the permission name and description are not provided. If we search on the permissions page we would need the Permission name and not the description, which makes it difficult to search 40 odd permissions and its time consuming. Request this document to be updated with the correct steps with the pre-requisites for coming on to the permissions. Example, having to login to Azure Portal > Under Azure AD > Enterprise App > API permissions. This kind of detailing is required to help us understand if this is required for the BMC connector.
Hello, Gaurav Wadhwa
Thank you for this feedback and detailed requirements. Please give us a few days to talk to our R&D team and update the docs with the required information.
Thanks,
Aaditi
Log in or register to comment.