4D NetKit is a built-in 4D component that allows you to interact with third-party web services and their APIs, such as Microsoft Graph.

• OAuth2Provider class
  • New OAuth2 provider
  • OAuth2ProviderObject.getToken()
• Office365 class
  • New Office365 provider
  • Office365.mail.append()
  • Office365.mail.copy()
  • Office365.mail.createFolder()
  • Office365.mail.delete()
  • Office365.mail.deleteFolder()
  • Office365.mail.getFolder()
  • Office365.mail.getFolderList()
  • Office365.mail.getMail()
  • Office365.mail.getMails()
  • Office365.mail.move()
  • Office365.mail.renameFolder()
  • Office365.mail.reply()
  • Office365.mail.send()
  • Well-known folder names
  • "Microsoft" mail object properties
  • Status object
  • Office365.user.get()
  • Office365.user.getCurrent()
  • Office365.user.list()
• Tutorial : Authenticate to the Microsoft Graph API in service mode
• (Archived) Tutorial : Authenticate to the Microsoft Graph API in signedIn mode (4D NetKit), then send an email (SMTP Transporter class)

Warning: Shared objects are not supported by the 4D NetKit API.

The OAuth2Provider class allows you to request authentication tokens to third-party web services providers in order to use their APIs in your application. This is done in two steps:

1. Using the New OAuth2 provider component method, you instantiate an object of the OAuth2Provider class that holds authentication information.
2. You call the OAuth2ProviderObject.getToken() class function to retrieve a token from the web service provider.

Here's a diagram of the authorization process:

This class can be instantiated in two ways:

• by calling the New OAuth2 provider method
• by calling the cs.NetKit.OAuth2Provider.new() function

New OAuth2 provider( paramObj : Object ) : cs.NetKit.OAuth2Provider

New OAuth2 provider instantiates an object of the OAuth2Provider class.

In paramObj, pass an object that contains authentication information.

The available properties of paramObj are:

The returned object's properties correspond to those of the paramObj object passed as a parameter.

OAuth2ProviderObject.getToken() : Object

.getToken() returns an object that contains a token property (as defined by the IETF), as well as optional additional information returned by the server:

If the value of token is empty, the command sends a request for a new token.

If the token has expired:

• If the token object has the refresh_token property, the command sends a new request to refresh the token and returns it.
• If the token object does not have the refresh_token property, the command automatically sends a request for a new token.

When requesting access on behalf of a user ("signedIn" mode) the command opens a web browser to request authorization.

In "signedIn" mode, when .getToken() is called, a web server included in 4D NetKit starts automatically on the port specified in the redirectURI parameter to intercept the provider's authorization response and display it in the browser.

The Office365 class allows you to call the Microsoft Graph API to:

• get information from Office365 applications, such as user information
• create, move or send emails

This can be done after a valid token request, (see OAuth2Provider object).

The Office365 class can be instantiated in two ways:

• by calling the New Office365 provider method
• by calling the cs.NetKit.Office365.new() function

New Office365 provider( paramObj : Object { ; options : Object } ) : cs.NetKit.Office365

New Office365 provider instantiates an object of the Office365 class.

In paramObj, pass an OAuth2Provider object.

In options, you can pass an object that specifies the following options:

The returned Office365 object contains the following properties:

To create the OAuth2 connection object and an Office365 object:

var $oAuth2: cs.NetKit.OAuth2Provider
var $office365 : cs.NetKit.Office365

$oAuth2:=New OAuth2 provider($param)
$office365:=New Office365 provider($oAuth2;New object("mailType"; "Microsoft"))

Office365.mail.append( email : Object ; folderId : Text) : Object

Office365.mail.append() creates a draft email in the folderId folder.

In email, pass the email to create. It must be of the Microsoft mail object type.

The method returns a status object.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

$status:=$office365.mail.append($draft; $folder.id)

Office365.mail.copy( mailId : Text ; folderId : Text) : Object

Office365.mail.copy() copies the mailId email to the folderId folder within the user's mailbox.

The method returns a status object.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

To copy an email from a folder to another:

$status:=$office365.mail.copy($mailId; $folderId)

Office365.mail.createFolder( name : Text { ; isHidden : Boolean { ; parentFolderId : Text } }) : Object

Office365.mail.getFolder() creates a new folder named name and returns its ID in the status object.

By default, the new folder is not hidden. Pass True in the isHidden parameter to create a hidden folder. This property cannot be changed afterwards. Find more information in Hidden mail folders on the Microsoft web site.

By default, the new folder is created at the root folder of the mailbox. If you want to create it within an existing folder, pass its id in the parentFolderId parameter.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a status object.

You want to create a "Backup" mail folder at the root of your mailbox and move an email to this folder:

// Creates a new folder on the root
$status:=$office365.mail.createFolder("Backup")
If($status.success=True)
	$folderId:=$status.id
		// Moves your email in the new folder
	$status:=$office365.mail.move($mailId; $folderId)
End if

Office365.mail.delete( mailId : Text ) : Object

Office365.mail.delete() deletes the mailId email.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a status object.

Note: You may not be able to delete items in the recoverable items deletions folder (for more information, see the Microsoft's documentation website).

You want to delete all mails in the $mails collection:

For each($mail;$mails)
	$office365.mail.delete($mail.id)
End for each

Office365.mail.deleteFolder( folderId : Text ) : Object

Office365.mail.deleteFolder() deletes the folderId mail folder.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a status object.

$status:=$office365.mail.deleteFolder($folderId)

Office365.mail.getFolder( folderId : Text ) : Object

Office365.mail.getFolder() allows you to get a mailFolder object from its folderId.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a mailFolder object containing the following properties (additional information can be returned by the server):

Office365.mail.getFolderList( options : Object ) : Object

Office365.mail.getFolderList() allows you to get a mail folder collection of the signed-in user.

In options, pass an object to define the folders to get. The available properties for that object are (all properties are optional):

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a status object containing the following properties:

The method returns an empty collection in the folders property if:

• no folders are found at the defined location
• an error is thrown

You want to :

//get the mail folder collection under the root folder (in $result.folders)
var $result : Object
$result:=$office365.mail.getFolderList()

//get the mail subfolder collection under the 9th folder
var $subfolders : Collection
$subfolders:=$office365.mail.getFolderList($result.folders[8].id)

Office365.mail.getMail( mailId : Text { ; options : Object } ) : Object
Office365.mail.getMail( mailId : Text { ; options : Object } ) : Blob

Office365.mail.getMail() allows you to get a single mail from its mailId.

By default, the mail is returned with its original format, as defined in the mail.type property of the provider. However, you can convert it to any type using the mailType property of the options parameter.

You can also select the preferred format of the body and uniqueBody properties of the returned mail using the contentType property of the options parameter.

The data type of the function result depends on the mail type:

If an error occurs, the function returns Null and an error is generated.

See also Microsoft's documentation website.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

Download a specific email:

$mail:=$office.mail.getMail($mailId)

Office365.mail.getMails( options : Object ) : Object

Office365.mail.getMails() allows you to get messages in the signed-in user's mailbox (for detailed information, please refer to the Microsoft's documentation website).

This method returns mail bodies in HTML format only.

In options, pass an object to define the mails to get. The available properties for that object are (all properties are optional):

The method returns a status object containing the following properties:

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

You want to retrieve all the mails present in the Inbox folder, using its well-known folder name:

$param:=new object
$param.folderId:="inbox"

$mails:=$office365.mail.getMails($param)

Office365.mail.move( mailId : Text ; folderId : Text) : Object

Office365.mail.move() moves the mailId email to the folderId folder. It actually creates a new copy of the email in the destination folder and removes the original email from its source folder.

The method returns a status object.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

To move an email from a folder to another:

$status:=$office365.mail.move($mailId; $folderId)

Office365.mail.renameFolder( folderId : Text ; name : Text ) : Object

Office365.mail.renameFolder() renames the folderId mail folder with the provided name.

Note that the renamed folder ID is different from the folderId. You can get it in the returned status object.

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

The method returns a status object.

You want to rename the the "Backup" folder to "Backup_old":

$status:=$office365.mail.renameFolder($folderId; "Backup_old")

Office365.mail.reply( reply : Object ; mailId : Text { ; replyAll : Boolean } ) : Object

Office365.mail.reply() replies to the sender of mailId message and, optionnally, to all recipients of the message.

Note: Some mails, like drafts, cannot be replied.

If you pass False in replyAll and if the original message specifies a recipient in the replyTo property, the reply is sent to the recipients in replyTo and not to the recipient in the from property.

The method returns a status object

One of the following permissions is required to call this API. For more information, including how to choose permissions, see the Permissions section on the Microsoft documentation.

To reply to an email and create a conversation:

$reply:=New object
// Text that will be send as reply
$reply.comment:="Thank you for your message"
$status:=$office365.mail.reply($reply; $mails.mailId)

Office365.mail.send( email : Text ) : Object
Office365.mail.send( email : Object ) : Object
Office365.mail.send( email : Blob ) : Object

Office365.mail.send() sends an email using the MIME or JSON formats.

In email, pass the email to be sent. Possible types:

• Text or Blob: the email is sent using the MIME format
• Object: the email is sent using the JSON format, in accordance with either:
  • the Microsoft mail object properties
  • the 4D email object format, which follows the JMAP specification

The data type passed in email must be compatible with the Office365.mail.type property. In the following example, since the mail type is Microsoft, $email must be an object. For the list of available properties, see Microsoft mail object's properties:

$Office365:=New Office365 provider($token; New object("mailType"; "Microsoft"))
$status:=$Office365.mail.send($email)

To avoid authentication errors, make sure your application asks for permission to send emails through the Microsoft Graph API. See Permissions.

The method returns a status object.

Outlook creates certain folders for users by default. Instead of using the corresponding folder id value, for convenience, you can use the well-known folder name when accessing these folders. Well-known names work regardless of the locale of the user's mailbox. For example, you can get the Drafts folder using its well-known name "draft". For more information, please refer to the Microsoft Office documentation.

When you send an email with the "Microsoft" mail type, you must pass an object to Office365.mail.send(). The available properties for that object are:

In general, the timeZone property can be set to any of the time zones currently supported by Windows, as well as the additional time zones supported by the calendar API:

• Default time zones
• Additional time zones

Send an email with an attachment, on behalf of a Microsoft 365 user:

var $oAuth2 : cs.NetKit.OAuth2Provider
var $token; $param; $email; $status : Object

// Set up authentication
$param:=New object()
$param.name:="Microsoft"
$param.permission:="signedIn"
$param.clientId:="your-client-id" // Replace with your client ID
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
// Ask permission to send emails on behalf of the Microsoft user
$param.scope:="https://graph.microsoft.com/Mail.Send"  

$oAuth2:=New OAuth2 provider($param)

$token:=$oAuth2.getToken()

// Create the email, specify the sender and the recipient
$email:=New object()
$email.from:=New object("emailAddress"; New object("address"; "[email protected]")) // Replace with sender's email
$email.toRecipients:=New collection(New object("emailAddress"; New object("address"; "[email protected]")))
$email.body:=New object()
$email.body.content:="Hello, World!"
$email.body.contentType:="html"
$email.subject:="Hello, World!"

// Create a text file and attach it to the email
var $attachment : Object
var $attachmentText : Text

$attachmentText:="Simple text file"
BASE64 ENCODE($attachmentText)
$attachment:=New object
$attachment["@odata.type"]:="#microsoft.graph.fileAttachment"
$attachment.name:="attachment.txt"
$attachment.contentBytes:=$attachmentText
$email.attachments:=New collection($attachment)

// Send the email
$Office365:=New Office365 provider($token; New object("mailType"; "Microsoft"))
$status:=$Office365.mail.send($email)

Several Office368.mail functions return a standard **status object**, containing the following properties:

Basically, you can test the success and statusText properties of this object to know if the function was correctly executed.

When an error occurs during the execution of an Office368.mail function:

• if the function returns a **status object**, the error is handled by the status object and no error is thrown,
• if the function does not return a status object, an error is thrown that you can intercept with a project method installed with ON ERR CALL.

Office365.user.get( id : Text { ; select : Text }) : Object
Office365.user.get( userPrincipalName : Text { ; select : Text }) : Object

Office365.user.get() returns information on the user whose ID matches the id parameter, or whose User Principal Name (UPN) matches the userPrincipalName parameter.

The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. By convention, it should correspond to the user's email name.

If the ID or UPN is not found or connection fails, the command returns an object with Null as a value and throws an error.

In select, you can pass a string that contains a specific set of properties you want to retrieve. Each property must be separated by a comma (,). If the select parameter is omitted, the function returns an object with a predefined set of properties (see below).

The list of available properties is available on Microsoft's documentation website.

By default, if the select parameter is omitted, the command returns an object with the following properties:

Otherwise, the object contains the properties specified in the select parameter.

For more details on user information, see Microsoft's documentation website.

Office365.user.getCurrent({select : Text}) : Object

Office365.user.getCurrent() returns information on the current user. In this case, it requires a signed-in user, and therefore a delegated permission.

The command returns a Null object if the session is not a sign-in session.

In select, pass a string that contains a set of properties you want to retrieve. Each property must be separated by a comma (,).

By default, if the select parameter is not defined, the command returns an object with a default set of properties (see the property table).

To retrieve information from the current user:

var $userInfo; $params : Object
var $oAuth2 : cs.NetKit.OAuth2Provider
var $Office365 : cs.NetKit.Office365

// Set up parameters: 
$params:=New object
$params.name:="Microsoft"
$params.permission:="signedIn"
$params.clientId:="your-client-id" // Replace with your Microsoft identity platform client ID
$params.redirectURI:="http://127.0.0.1:50993/authorize/"
$param.scope:="https://graph.microsoft.com/.default"

$oAuth2:=New Oauth2 provider($params) //Creates an OAuth2Provider Object

$Office365:=New Office365 provider($oAuth2) // Creates an Office365 object

// Return the properties specified in the parameter.
$userInfo:=$Office365.user.getCurrent("id,userPrincipalName,\
principalName,displayName,givenName,mail") 

Office365.user.list({options: Object}) : Object

Office365.user.list() returns a list of Office365 users.

In options, you can pass an object to specify additional search options. The following table groups the available search options:

The returned object holds a collection of users as well as status properties and functions that allow you to navigate between different pages of results.

By default, each user object in the collection has the default set of properties listed in the Office365.user.get() function. This set of properties can be customized using the select parameter.

var $oAuth2 : cs.NetKit.OAuth2Provider
$Office365 : cs.NetKit.Office365
$userInfo; $params; $userList; $userList2; $userList3; $userList4 : Object
var $col : Collection

// Set up parameters: 
$params:=New object
$params.name:="Microsoft"
$params.permission:="signedIn"
$params.clientId:="your-client-id" // Replace with your Microsoft identity platform client ID
$params.redirectURI:="http://127.0.0.1:50993/authorize/"
$params.scope:="https://graph.microsoft.com/.default"

// Create an OAuth2Provider Object
$oAuth2:=New OAuth2 provider($params) 

// Create an Office365 object
$Office365:=New Office365 provider($oAuth2) 

// Return a list with the first 100 users
$informationList1:=$Office365.user.list() 

// Return a list of users whose displayName is Jean
$userList2:=$Office365.user.list(New object("filter"; "startswith(displayName,'Jean')"))

// return a list of users whose display names contain "F" and arrange it in descending order.
$userList3:=$Office365.user.list(New object("search"; "\"displayName:F\""; "orderBy"; "displayName desc"; "select"; "displayName"))

// Create a list filled with all the userPrincipalName 
$userList4:=$Office365.user.list(New object("select"; "userPrincipalName"))
$col:=New collection
Repeat 
    $col.combine($userList4.users)
Until (Not($userList4.next()))

Establish a connection to the Microsoft Graph API in service mode.

• You have registered an application with the Microsoft identity platform and obtained your application ID (also called client ID) and client secret.

Here, the term "application" does not refer to an application built in 4D. It refers to an entry point you create on the Azure portal. You use the generated client ID to tell your 4D application to trust the Microsoft identity platform.

Once you have your client ID and client secret, you're ready to establish a connection to your Azure application.

1. Open your 4D application, create a method and insert the following code:

var $oAuth2 : cs.NetKit.OAuth2Provider
var $token : Object

$param:=New object()
$param.name:="Microsoft"
$param.permission:="service"

$param.clientId:="your-client-id" // Replace with your Microsoft identity platform client ID
$param.clientSecret:="your-client-secret" // Replace with your client secret
$param.tenant:="your-tenant-id" // Replace with your tenant ID
$param.tokenURI:="https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token/" //Replace ID
$param.scope:="https://graph.microsoft.com/.default"

$oAuth2:=New OAuth2 provider($param)

$token:=$oAuth2.getToken()

2. Execute the method to establish the connection.

This tutorial has been archived. We recommend using the Office365.mail.send() method to send emails.

Establish a connection to the Microsoft Graph API in signedIn mode, and send an email using the SMTP Transporter class.

In this example, we get access on behalf of a user.

• You have registered an application with the Microsoft identity platform and obtained your application ID (also called client ID).

Here, the term "application" does not refer to an application built in 4D. It refers to an entry point you create on the Azure portal. You use the generated client ID to tell your 4D application to trust the Microsoft identity platform.

• You have a Microsoft e-mail account. For example, you signed up for an e-mail account with Microsoft's webmail services designated domains (@hotmail.com, @outlook.com, etc.).

Once you have your client ID, you're ready to establish a connection to your Azure application and send an email:

1. Open your 4D application, create a method and insert the following code:

var $token; $param; $email : Object
var $oAuth2 : cs.NetKit.OAuth2Provider
var $address : Text

// Configure authentication


$param:=New object
$param.name:="Microsoft"
$param.permission:="signedIn"
$param.clientId:="your-client-id" // Replace with your Microsoft identity platform client ID
$param.redirectURI:="http://127.0.0.1:50993/authorize/"
$param.scope:="https://outlook.office.com/SMTP.Send" // Get consent for sending an smtp email

// Instantiate an object of the OAuth2Provider class
$oAuth2:=New OAuth2 provider($param)

// Request a token using the class function

// Send a token request and start the a web server on the port specified in $param.redirectURI 
//to intercept the authorization response
$token:=$oAuth2.getToken() 

// Set the email address for SMTP configuration 
$address:= "[email protected]" // Replace with your Microsoft email account address

// Set the email's content and metadata
$email:=New object
$email.subject:="My first mail"
$email.from:=$address
$email.to:="[email protected]" // Replace with the recipient's email address
$email.textBody:="Test mail \r\n This is just a test e-mail \r\n Please ignore it"

// Configure the SMTP connection
$parameters:=New object
$parameters.accessTokenOAuth2:=$token
$parameters.authenticationMode:=SMTP authentication OAUTH2
$parameters.host:="smtp.office365.com"
$parameters.user:=$address

// Send the email 

$smtp:=SMTP New transporter($parameters)
$statusSend:=$smtp.send($email)

2. Execute the method. Your browser opens a page that allows you to authenticate.

3. Log in to your Microsoft Outlook account and check that you've received the email.