Managing Microsoft Exchange Groups from BMC Helix Digital Workplace requests by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template to manage Microsoft Exchange groups via a BMC Helix Digital Workplace request. To use the integration template with the values defined out of the box, you update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities: 

After you deploy the integration template, when a request is created in BMC Helix Digital Workplace, the corresponding action is performed on the Microsoft Exchange mail list. 

BMC Helix Digital Workplace to Microsoft Exchange data flow

The following image gives an overview of the data flow for creating a Microsoft Exchange mail list from a BMC Helix Digital Workplace service request:

The following image gives an overview of the data flow for updating a Microsoft Exchange mail list from a BMC Helix Digital Workplace service request:

Before you begin

You require the following items to successfully set up and use this integration: 

Limitations

• Only unified groups are supported.
• You can only add existing Microsoft Exchange users to a mailing group.

Task 1: To add the BMC Helix iPaaS connector to BMC Digital Workplace Catalog

1. Log in to BMC Digital Workplace Catalog.
2. Select Services > Connectors.
3. Click New Connection and complete the following fields:
   • Connection Name—Enter Helix Integration Platform.
   • Connector—Select  REST.
4. Open the connector and add a URL to your BMC Helix iPaaS Cloud Studio instance.

Task 2: To import the required service request to BMC Digital Workplace Catalog

1. Download the Create Microsoft Exchange Group from BMC Helix DWP Request Update 2022-07-01 project file to your system from the BMC Helix iPaaS page on the Electronic Product Distribution site.

   This compressed package contains the following files:

   • Sync DWP Service Request to Exchange.json—Contains the BMC Helix iPaaS Cloud Studio project Create Microsoft Exchange Group from BMC Helix DWP Request.

   • ServiceExport_DWP_Exchange.zip—Contains the BMC Digital Workplace service Call Helix Integration Platform API.

     Important

     Your ability to access product pages on the EPD website is determined by the license your company purchased.

2. Log in to BMC Digital Workplace Catalog.
3. Select Services > Services.

4. Click Import From File to navigate to the location where you extracted the Create Microsoft Exchange Group from BMC Helix DWP Request Update 2022-07-01.zip file you downloaded.

5. Select the ServiceExport_DWP_Exchange.zip file.

6. Verify that the Call Helix Integration Platform API is displayed in the list.

Task 3: To set up the BMC Digital Workplace service request

1. Log in to BMC Digital Workplace Catalog.
2. Select Services > Services.

3. Select  MailListExchangeService and select Actions > Open or double-click the service name.

4. To view the Workflows & Questions, next to Workflow,  click Edit.

5. To update the workflow, in the Request section, next to Workflow, click Edit .
   

    Click here to view the detailed process

   

6. Add values for the following input parameters.

   Important

   The security fields must be populated according to the authentication mechanism used with BMC Helix iPaaS. To view the selected security profile, log in to BMC Helix iPaaS and select API Manager > My APIs , and select Security Profiles from the list. For more information, see Security profiles .

   Input parameter	Description
   Jitterbit Security Profile Type	The authentication method used. For example, type "APIKEY" if you use API key based authentication.
   Jitterbit Security Profile Basic Auth Token	If you are using the basic authentication method, type the authentication token.
   Jitterbit Security Profile ApiKey Name	If you are using API authentication, type the name of the API key.
   Jitterbit Security Profile ApiKey Value	If you are using API authentication, type the value of the API key.
   Jitterbit URI	Path for the BMC Helix iPaaS environment and project. For example, BMCDevEnv1/DWP_Service_To_Exchange_v2
   Jitterbit method	The API method used. For example, POST.
   Action Index	Specifies the sequence number of operation to be performed. This value is populated based on mapping provided for the option selected in the BMC Helix Digital Workplace request.
   sb-context	Type 'context' to set it to the BMC Digital Workplace context.

7. After you update the values, click Close.

8. To add the questions for the Service Request, in the Request section, next to Questions , click Add.
9. Select DWP Service Request to MS Exchange, and click Save.
10. To exit Workflows & Questions, click Save, and then click Close.

Task 4: To authenticate and authorize BMC Helix iPaaS to use the application credentials to access Microsoft Exchange

BMC Helix iPaaS uses Microsoft Graph APIs. The application does not call the API on behalf of a user but by using its own credentials. This requires the application to use the OAuth 2.0 client grant flow to get access tokens from Azure Active Directory (AD). You must configure a service and use the OAuth client credentials grant flow to get an access token to use Microsoft Graph APIs. 

To register your app and get the access tokens from Azure AD, perform the following steps:

1. Log in to the  Azure portal .
2. From the Azure services, select Azure Active Directory.
3. From the left navigation menu, select App Registrations.
4. On the App Registrations page, click + New Registration and add the following information:
   • Name —Add a unique name for your application. 
   • Supported Account Types —Select Accounts in this organizational directory only (Single tenant).
   • Redirect URI—From the list, select Web , and enter the BMC Helix iPaaS URI. 
5. Click Register.
   The application details page is displayed.
6. To add app permissions, from the left navigation menu, select API Permissions.
7. On the Configured permissions page, click + Add a Permission, and then select Microsoft Graph.
8. Select Application Permissions and add all the available permissions under Group, Group members, and User permissions groups.
9. To enable the permissions you added, click Request Admin Consent. 
   Permissions are enabled after an administrator confirms the permissions. 
10. To generate the secret key, from the left navigation menu, select Certificates & Secrets. 
11. Under Client Secrets , select + New client secret.
12. When the system prompts for the details, add a Description and select the validity of the secret. 
    The secret ID is generated for the application under Client secrets.
13. Copy the secret ID and save the value. 
    This value is required when adding the project variables for Microsoft Exchange in BMC Helix iPaaS.

Task 5: To download and import the integration template project file

1. Download the Create Microsoft Exchange Group from BMC Helix DWP Request Update 2022-07-01 project file to your system from the BMC Helix iPaaS page on the Electronic Product Distribution site.

   This compressed package contains the following files:

   • Sync DWP Service Request to Exchange.json—Contains the BMC Helix iPaaS Cloud Studio project Create Microsoft Exchange Group from BMC Helix DWP Request.

   • ServiceExport_DWP_Exchange.zip—Contains the BMC Digital Workplace service Call Helix Integration Platform API.

     Important

     Your ability to access product pages on the EPD website is determined by the license your company purchased.

2. As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio. 

3. On the projects page, click Import.

4. Click Browse and then select the Create Microsoft Exchange Group from BMC Helix DWP Request.json file extracted from the product file you downloaded. 
   The Project Name and Organization fields are automatically populated depending on the values defined. 
5. From the Environment list, select the environment to which you want to import this integration template, and click Import.
   The project opens after the integration template is imported. 
6. To open the project file at a later time, select the environment where the integration templates are available, select the Create Microsoft Exchange Group from BMC Helix DWP Request project and click View/Edit.

Step 6: To update the project variables for the integration template

1. Next to the Environment name, click the ellipsis ... and select Project Variables.
2. Update the following project variables:

   • Access points and authentication details for Microsoft Exchange and BMC Helix iPaaS applications

     Project variable	Value
     Microsoft Exchange
     Exchange_Client_Id	Enter the OAUTH API endpoint ID generated in Microsoft Identity platform in Task 4 .
     Exchange_Client_Secret	Enter the OAUTH API endpoint client secret generated in Microsoft Identity platform in Task 4 .
     Exchange_Tenant_Id	Enter Tenant ID for the user created in Microsoft Identity platform.
     BMC Helix iPaaS
     BHIP_Url	Enter the URL to access BMC Helix iPaaS.
     BHIP_User	Enter the user ID to access BMC Helix iPaaS.
     BHIP_User_Password	Enter the password of the user ID to access BMC Helix iPaaS.

   • API variables

     Project variables	Value
     BHIP_API_Name	Enter the name for the Webhook API that is created in Microsoft Exchange to use with the Sync DWP Request To Exchange workflow. By default, this value is set to DWP_Service_To_Exchange.
     BHIP_API_Method	Enter the RestAPI method that is used by the Webhook API. This value is added to the BMC Helix iPaaS Jitterbit API. Valid values include: POST (Default) GET PUT DELETE
     BHIP_API_Security_Profile_Type	Enter the Security Profile type that defines the authentication type to be used by the Webhook API. This value is added in the BMC Helix iPaaS Jitterbit API. Valid values include: BASIC (Default) ANONYMOUS APIKEY Enter comma separated values to select multiple profile types; for example, APIKEY,BASIC. Important: For profile types supported by the source application, the security profiles are automatically created by the integration template when you enable the integration.  BMC Helix iPaaS does not support OAuth authentication for this application.
     BHIP_API_Security_Profile_Name_Suffix	Enter the suffix to be added to the name of security profiles created.
     BHIP_API_Security_Profile_BASIC_Auth_Username	For the BASIC security profile type, enter the username to be used to create the security profile. This username is used for authentication by the BMC Helix iPaaS Jitterbit API and the Webhook API.
     BHIP_API_Security_Profile_BASIC_Auth_Password	For the BASIC security profile type, enter the password for the security profile created.  This password is used for authentication by the BMC Helix iPaaS Jitterbit API and the Webhook API.
     BHIP_API_Security_Profile_ApiKey_Name	For the APIKEY security profile type, enter the name of the APIKEY to set on the security profile. This APIKEY is used for authentication by the BMC Helix iPaaS Jitterbit API and the Webhook API.
     BHIP_API_TimeOut	Enter an API timeout value, in seconds. The minimum value must range between 30 and 180. By default, the value is set to 90.

   • Email notification configurations

     Project variable	Value
     BHIP_SMTP_Hostname	Enter the SMTP host details for email configuration.
     BHIP_To_Email_Address	Enter the email address to which you want to send the notification emails.
     BHIP_From_Email_Address	Enter the email address from which the notification emails should be sent.
     BHIP_Email_Summary	To disable email notifications for successful operations, set the value to false. By default, this value is set to true.  This value defines if notification emails with a summary log should be sent when the workflow is successful.
     BHIP_Email_Enabled	If you want to disable email notifications, update the default value to false. By default, the value is set to true.  This value defines if notification emails should be sent when an error occurs during the operation activities.
     BHIP_Email_On_Success	To disable email notifications for successful operations, set the value to false. By default, this value is set to true.  This value defines if emails should be sent if workflow is successful.
     BHIP_Email_Data_Error	To disable email notifications for errors, set the value to false. By default, this value is set to true.  This value defines if data error logs should be sent through emails if an error occurs during the operation activities.

Task 7: To deploy and enable the project

After you enable the integration, when a service request is created in BMC Helix Digital Workplace, the corresponding action of creating a mailing group, adding an existing user to a mailing group or removing an existing user from a mailing group is executed.

(Optional) Task 8: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

1. In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.

2. Open the API created for the integration. The API name is the value defined in the BHIP_API_Name project variable.

3. Select Enable Debug Mode Until: and set it for the required date and time.

4. Save and publish the API.

Workflows included in the integration template

The integration template includes workflows for the basic configuration and each integration use case. The following tables describe the operations defined in each workflow. 

Enable Integration

This workflow defines the operations required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Sync DWP request to Exchange

This workflow defines the operations to create a mailing group and add or remove users from an existing mailing group in Microsoft Exchange. The following operations are included in this workflow: