This documentation supports the 21.3 version of BMC Helix Digital Workplace Advanced.To view an earlier version, select the version from the Product version menu.

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.


Related topics

Service-connector-overview

Service-connector-capabilities

Workflow-designer-elements-overview

External account requirements

  1. Before you start building workflows that use Office 365 actions, you must have:

  2. 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

  3. Find the externalServiceId:
    2. Select Azure Active Directory > Licenses to open the Licenses - Overview screen.
    3. Under Essentials, select your product to open the Licensed users list.
      The alphanumeric externalServiceId is displayed after skuId/ 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. 

Click here to view the procedure used to generate the authentication code.
  1. Copy the following URL into any text editor:
    https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=Client_id&redirect_uri=Credirect_uri
  2. Replace Client_id and Credirect_uri with values from your Azure account.
  3. Log in to Microsoft 365 with your Microsoft 365 user login and password.
  4. In the address bar of the window in which you are logged in as an Microsoft 365 user, delete the URL that is displayed.
  5. Copy the edited string from the text editor, and paste it into the address bar of the window with Microsoft 365. 
    A long string is returned in the browser address bar.
  6. Copy the string from the address bar into a text editor.

  7. Copy the authentication code from the obtained string:
    http://o365conn.com/?code=authentication_code&session_state=state

    The authentication code begins right after code=, and ends up right before &session_state.

    Tip

    Use the obtained authentication code token for configuring the Office 365 connector within 30 minutes of the time it is generated.

    Regenerate the authentication code when you restart your BMC Helix Digital Workplace Catalog server.

  8. Copy the authentication code, and paste it into the Authentication Code field.

Tenant

<domainName>

The domain of the email address. 

Redirect URL

http://<autoGeneratedValue>

This value is generated by your Azure account.

Trust Self-Signed Certificates

  • False
  • True

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.

Create Office 365 User

Creates an Office 365 user account.

Notes:

  1. The workflow that uses this action must to be attached to the Create Office User 365 User [Microsoft Office Developer] imported service.
  2. The questionnaire attached to the service that uses this workflow must contain a question that uses data from the Country Codes data set.

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.

  • True
  • False

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.

Number of available licenses

Delete Office 365 User

Deletes an existing Office 365 user account.


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 Without Licenses Report

Returns a list of users without an Office 365 license.

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.

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.

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.

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.

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.

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.

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.

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.

WorkflowLicensesReport.png

Click here to view the JSON of this workflow.

Failed to execute the [code] macro. Cause: [RuntimeError: maximum recursion depth exceeded (Java StackOverflowError)]. Click on this message for details.

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:

icon_play.png https://youtu.be/8f9rLyjZob8

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

"assignedLicenses": [{
"disabledPlans": [],
"skuId": "189a915c-fe4f-4ffa-bde4-85b9628d07a0"
}]

A list of available licenses.

Assigned Plans

Array

{
"assignedPlans": [{
"service": "To-Do",
"servicePlanId": "3fb82609-8c27-4f7b-bd51-30634711ee67",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "OfficeForms",
"servicePlanId": "e212cbc7-0961-4c40-9825-01117710dcb1",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftStream",
"servicePlanId": "6c6042f5-6f01-4d67-b8c1-eb99d36eed3e",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "ProcessSimple",
"servicePlanId": "76846ad7-7776-4c40-a281-a386362dd1b9",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "PowerAppsService",
"servicePlanId": "c68f8d98-5534-41c8-bf36-22fa496fa792",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "TeamspaceAPI",
"servicePlanId": "57ff2da0-773e-42df-b2af-ffb7a2317929",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "ProjectWorkManagement",
"servicePlanId": "b737dad2-2f6c-4c65-90e3-ca563267e8b9",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "Sway",
"servicePlanId": "a23b959c-7ce8-4e57-9140-b90eb88a9e97",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftOffice",
"servicePlanId": "43de0ff5-c92c-492b-9116-175376d08c38",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftCommunicationsOnline",
"servicePlanId": "0feaeb32-d00e-4d66-bd5a-43b5b83db82c",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "exchange",
"servicePlanId": "efb87545-963c-4e0d-99df-69c6916d9eb0",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "SharePoint",
"servicePlanId": "527f7cdd-0e86-4c47-b879-f5fd357a3ac6",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "SharePoint",
"servicePlanId": "a361d6e2-509e-4e25-a8ad-950060064ef4",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

}
]

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 code of a country.

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:

  • Uppercase letters
  • Lowercase letters
  • Numbers
  • Symbols

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

"assignedLicenses": [{
"disabledPlans": [],
"skuId": "189a915c-fe4f-4ffa-bde4-85b9628d07a0"
}]

A list of available licenses.

Assigned Plans

Array

{
"assignedPlans": [{
"service": "To-Do",
"servicePlanId": "3fb82609-8c27-4f7b-bd51-30634711ee67",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "OfficeForms",
"servicePlanId": "e212cbc7-0961-4c40-9825-01117710dcb1",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftStream",
"servicePlanId": "6c6042f5-6f01-4d67-b8c1-eb99d36eed3e",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "ProcessSimple",
"servicePlanId": "76846ad7-7776-4c40-a281-a386362dd1b9",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "PowerAppsService",
"servicePlanId": "c68f8d98-5534-41c8-bf36-22fa496fa792",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "TeamspaceAPI",
"servicePlanId": "57ff2da0-773e-42df-b2af-ffb7a2317929",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "ProjectWorkManagement",
"servicePlanId": "b737dad2-2f6c-4c65-90e3-ca563267e8b9",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "Sway",
"servicePlanId": "a23b959c-7ce8-4e57-9140-b90eb88a9e97",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftOffice",
"servicePlanId": "43de0ff5-c92c-492b-9116-175376d08c38",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "MicrosoftCommunicationsOnline",
"servicePlanId": "0feaeb32-d00e-4d66-bd5a-43b5b83db82c",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "exchange",
"servicePlanId": "efb87545-963c-4e0d-99df-69c6916d9eb0",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "SharePoint",
"servicePlanId": "527f7cdd-0e86-4c47-b879-f5fd357a3ac6",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

},
{
"service": "SharePoint",
"servicePlanId": "a361d6e2-509e-4e25-a8ad-950060064ef4",
"capabilityStatus": "Enabled",
"assignedTimestamp": "2018-01-29T13:40:22.5310464Z"

}
]

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 code of a country.

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.  

map to data set.png

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.

NotificationText.png

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.

With licenses report
{
"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"
]
}


Without licenses report
{"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.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*