Skip to main content

Registering and Configuring Graph API

JAMS supports Microsoft Graph API for use with email notifications. You can also specify a Graph API connection in various places within the application for sending and receiving emails, including:

  • Connection Store - Store the Graph API connection information that can be reused in multiple Jobs.
  • JAMS PowerShell cmdlets
  • Mail Triggers - Run a Job based on an incoming email
  • Notifications - Send an email after an event
  • Reports - Send a report as an email
  • Workflow Jobs - Via the GraphAPISession activity

Configuring JAMS as an Application in the Azure Portal​

To use Graph API, you will need to configure JAMS as an application in Azure Portal before you can configure JAMS. Ensure you have configured the following:

  • Grant the application the appropriate Microsoft Graph API permissions. In JAMS, Graph API uses the Open Authorization (OAuth) client credentials flow to authenticate in Microsoft Azure.
  • To send emails and execute MailWatch Jobs, ensure the Mail.Read, Mail.ReadWrite, and Mail.Send permissions have been added in the Microsoft Graph API permissions. The Mail.ReadWrite is required for MailWatch Jobs.

As part of this process, you need to save the following information from Azure Portal because it is needed for configuration in JAMS:

  • Azure Directory (Tenant) ID
  • Azure Application (Client) ID
  • Azure Client Secret Value

The Client Secret can expire, so configure this as appropriate for your security preferences. When it expires, generate a new Client Secret and update the JAMS Credential as mentioned in the section below.

After you complete the configuration in the Azure Portal, complete the steps in the sections below within JAMS.

Configuring JAMS​

After you complete the configuration in the Azure Portal, you must:

  1. Create the Credentials
  2. Create the Connection Store item

Creating Credentials​

You need two Credentials in JAMS when working with Graph API:

  • A Credential is used to store the Client ID and Secret Value Key. You can use the Logon As field for the Client ID and the password for the Secret Value Key.
  • A Credential is used to save the mailbox information. You can use the Logon As field for the email address to monitor.

See Credentials for more information on creating a Credential.

Creating a Graph API Connection Store​

To use Graph API in JAMS, you need to create a Connection Store item. This will store the connection information, so you can reuse it in multiple places within JAMS. The Connection Store item is used when a MailServer needs to be specified. You will need:

  • The Tenant Id from the Azure Portal.
  • A Credential that contains the Client ID and Client Secret Value.
  • A Credential to save the mailbox information.

See Connections to Mail Servers for more information.

Using Graph API in Specific Features​

You can use Graph API in various places in JAMS. The sections below are optional based on how you use Graph API in your environment.

Using PowerShell Scripts using JAMS cmdlets​

If you are using the JAMS PowerShell cmdlets, you can use Graph API with a new cmdlet named Connect-JGraph. The PowerShell cmdlet has a JAMSConnection argument that should be updated to use the Graph API Connection Store object.

Example: Getting an email based on the subject

Import-Module JAMS
$cred = Get-JAMSCredential -Username GraphAPI_ConnectionCredential -Server localhost 
$conn = Get-JAMSAgent GraphAPI_Connection -server localhost
$mailServer = Connect-JGraph -JAMSConnection $conn -Credential $cred
$mailHeader = Get-JMailHeader -Subject "MailMessage_Subject" -Unread
$mailMessage = Get-JMailMessage -MailServer $mailServer -InputObject $mailHeader[0]

Using Mail Triggers​

If you use Mail Watch Jobs, you can update them to use the Graph API Connection Store object. These are Schedule Items that are added to a Job by using the Run this Job | based on an email option, and they run a Job based on a received/monitored email.

To use Graph API, you need to add the Graph API Connection Store item that you created to the Mail Server field and any email information, such as To Address, From Address, or Subject. See Triggers for more information.

Using Notifications​

You can have an email sent to an address if a specified event occurs. For example, if a Job is set to a Runaway status and it has an event flag or finishes in failure, you can have an email sent to alert someone to review the Job in the Monitor. These are configured in the JAMS Desktop Client.

Using Reports​

You can use JAMS to create and send a report as an email. Use the JAMS Reports Execution Method to create a Job that creates a Report. You can then add the Schedule Item to have the report sent as an email. These are configured in the JAMS Desktop Client.

Using Workflow Jobs​

You can use Graph API within Workflow Jobs from the JAMS Desktop Client. To use Graph API, use the GraphAPISession activity has the main container to hold your other Mail Server Session Workflow Activities. This allows all activities within the GraphAPISession activity to inherit the mail server properties from the Connection Store item. If you add an activity, such as ForEachMailMessage, outside the GraphAPISession activity, a red icon and error message is displayed.