Setting up External Calendars

To set up PSA to use Google Calendar as an external calendar, you must do the following:

• Ask your IT team to set up Google as the authentication provider. This is used to identify relevant users and manage their access.
• Generate Google credentials.
• Configure Google as an authentication provider.

Setting up Google as an Authentication Provider

1. Browse to the Google Cloud Platform https://console.cloud.google.com/.
2. Log in to the Google Cloud Platform using your email and password. If you are a first-time user select the Terms of Service checkbox and click AGREE AND CONTINUE.
3. Contact your IT team to set up a new Google project. To create a new project, navigate to the navigation menu and click IAM & Admin | Create a Project.
   1. Specify the following details:
      1. Enter the project name in the Project name field.
      2. Select the organization name to attach the project to in the Organization drop-down list.
      3. Browse and select the parent organization or folder in the Location field.
   2. Click CREATE. The dashboard opens.
   3. Select the new project from the Select a project drop-down list on the top left side, next to the navigation menu.

4. If you are an existing user and have an existing project, select it from the Select a project drop-down list on the top left side, next to the navigation pane. Contact your IT team to grant you the access to this project to enable APIs.
5. To enable the Google Calendar API in your project, open the navigation menu and click APIs & Services | Enabled APIs & Services. The APIs & Services page opens.
6. Click +Enable APIs and Services. The API Library page opens.
7. In the Search field, type Calendar API and press Enter on the keyboard.
8. Select Google Calendar API. Click Enable. The API/Service Details page opens.

After creating the project and enabling the API, you can now configure the OAuth consent page.

Configuring the OAuth Consent Page and Registering Your App in Google

1. On the APIs & Services page, select the OAuth consent page from the navigation pane.
2. Select the user type as either “Internal” or “External”:
   1. Internal: Select this user type if you are creating the app within your Google Workspace organization. In this case, there is no need to publish and verify the app.
   2. External: Select this user type if you are creating the app outside your Google Workspace organization. Depending on how you configure your OAuth page, you must publish the app in production and submit it for verification.
3. Click CREATE. The App information section opens.
4. In the App information section:
   1. In the App name field, enter the name of your app asking for consent at the time of authorization. The app name can be similar to the Google project name for better usability.
   2. In the User support email field, enter an email where users can contact you regarding their consent. For example, your IT Help desk email.
   3. [Optional] In the App logo field, upload a logo for your app.

5. Under the App domain section, in the Authorized domains, click +ADD DOMAIN and enter force.com in the Authorized domain 1 field. Again, click +ADD DOMAIN and enter salesforce.com in the Authorized domain 2 field.
6. In the Developer contact information section, in the Email addresses field, enter email addresses where Google can notify you about changes in your project.
7. Click SAVE AND CONTINUE.

8. To add the authorization scopes, click ADD OR REMOVE SCOPES.
   1. In the Update selected scopes window in the filter input field, select API and enter Google Calendar API.
   2. Scroll down and select the scope "./auth/calendar", with the user-facing description “See, edit, share and permanently delete all the calendars that you can access using Google Calendar”. This scope is the minimum requirement for this functionality to work.
   3. Click UPDATE.
   4. Click SAVE AND CONTINUE. The app registration summary is displayed.
9. [Optional] To make changes to the app registration, click EDIT.

You have authenticated and registered your app. You must now generate credentials to access your enabled APIs.

Generating Google Credentials: Client ID and Client Secret

1. On the APIs & Services page, select "Credentials" from the navigation pane on the left side.
2. Click + CREATE CREDENTIALS and select "OAuth client ID".
3. On the Create OAuth client ID page, in the Application type drop-down list, select "Web application".
4. In the Name field, enter a name for the web client.
5. Leave the Authorized redirect URls blank to copy the Callback URL generated from the Authorization Provider Setup at the Salesforce end.
6. Click CREATE. The Client ID and Client Secret is created.
7. Copy "Your Client ID" and "Your Client Secret" from the OAuth client created popup window for setting up the Auth. Provider in Salesforce and click OK.

After completing the Google setup and generating the Client ID and Client Secret, you must configure Google as an authentication provider in your Salesforce org.

Configuring Google as an Authentication Provider

You can configure Google as an authentication provider in your Salesforce org from the Auth. Providers Setup page.

1. From Setup, in the Quick Find field, enter Auth. Providers, select "Auth. Providers", and click New.
2. In the Provider Type drop-down list, select "Google". After the selection, the auth. provider fields are displayed.
3. Enter the details in the following fields and leave all other fields blank:
   1. In the Name field, enter a name for the authentication provider.
   2. The URL Suffix field populates automatically as soon as we complete the Name field.
   3. In the Consumer Key field, paste the Google Client ID copied in step 7 of Generate Google Credentials: Client ID and Client Secret section.
   4. Similarly, in the Consumer Secret field, paste the Google Client Secret created in step 7 of Generate Google Credentials: Client ID and Client Secret section.
   5. In the Authorize Endpoint URL field, enter the following URL: https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force
   6. In the Token Endpoint URL field, enter the following URL: https://accounts.google.com/o/oauth2/token
   7. In Default Scopes, enter the following scopes separated by a space:
      1. openid
      2. https://www.googleapis.com/auth/calendar

For example, openid https://www.googleapis.com/auth/calendar

4. Click Save.
5. Copy the Callback URL generated under the Salesforce Configuration section.
6. Navigate to Google setup, in the navigation menu, click APIs & Services | Credentials.
7. On the Credentials page, under OAuth 2.0 Client IDs, click Edit OAuth client.
8. Scroll down to the Authorized redirect URIs section, click +ADD URI and paste the Callback URL in the URIs 1 field.
9. Click SAVE.
10. Navigate to your Salesforce org Auth Provider, which you have created in steps 1 to 4. Use the Test-Only Initialization URL to test the connection. It redirects you to the Google Account login page. Select the account and click Allow to view and edit events on all your calendars.

 After a successful connection, you receive a success response similar to the one below:

Generating Named Credentials

A named credential specifies the URL of a callout endpoint and is used for authentication. In Salesforce, we use an external credential to create a named credential.

Notes:

• We recommend using only the New option for creating named credentials. We do not detail the New Legacy option.
• Use the Named Principal identity type and Per User Principal identity type for PTAs and assignments.
• You can use only the Per User Principal identity type for work events. It is not possible with the Named Principal identity type.
• If you want to use both assignment and work event calendar sync, you can do this using the Per User Principal identity type. Under the Per User Principal identity type, if you are creating assignments or PTAs, you will need Read and Write access to the resource calendars for which you are generating the events. If you do not have this level of security access in the external calendar application, the events will not push, and an app log will be created.

The following table shows the differences between the options in the Named Credential Identity Type drop-down list. Before setting up these identity types, discuss their implications with your security and IT teams.

Named Credential Identity Types

Setup	Named Principal	Per User Principal
Authentication	One user authenticates the whole org.	Each relevant user must authenticate their calendar to be able to push work events, PTAs, and assignments from PSA to a contact's calendar.
Implications for PTAs and assignments	In the contact's calendar, all the events appear to be generated by the same email account. Because of this, we recommend that you have a Certinia PSA and Salesforce licenses, and create a system user, such as psasystem@xyz.com. The authorized user must have sharing access and be able to make changes to events on a contact's calendar to be able to push PTAs and assignments from PSA to the calendar.  Without this access, only records assigned to the authorized user by the authorized user are pushed to the contact's calendar.	The user that is assigning the PTAs, and assignments in PSA is the user that is creating the events in the contact's calendar. Each relevant user must have sharing access and be able to make changes to events on a contact's calendar to be able to push PTAs, and assignments from PSA to the calendar. Without this access, the user can only push self-assigned events to a contact's calendar.
Implications for work events	Work events cannot be pushed to a contact's calendar because the Host field on the work event is set as the logged-in user. PSA attempts to push the work event to the contact's calendar using the logged-in user, which is different from the authenticated user.	The logged-in user is the host of any work event that they create. Any other work events on the work event calendar are read-only.

Creating External Credentials and Named Credentials

To create a named credential using the New Named Credential page, you must create an external credential. External credentials specify an authentication protocol and permission set groups, permission sets, or profiles to use when authenticating to an external system.

1. Create External Credential

   To create an external credential:

   1. From Setup, enter Named Credentials in the Quick Find field, and then select "Named Credentials". The Named Credential page opens.
   2. Click External Credentials | New. The New External Credential window opens.
   3. In the Label field, enter a name for the external credential.
   4. In the Name field, enter a unique name containing underscores to refer to the external credential.
   5. In the Authentication Protocol drop-down list, select "OAuth 2.0".
   6. In the Authentication Flow Type drop-down list, select "Browser Flow".
   7. In the Authentication Provider drop-down list, select the authentication provider name.
   8. Leave the Scope field blank if you have defined it in the specified authentication provider. If you have not defined it, enter the scope.
   9. Click Save. The Named Credentials page opens.
   10. Scroll down to the Principals section and click New.
   11. Select a parameter name and an identity type.
   12. Enter a sequence number. A sequence number specifies the order of principals to apply when there is more than one principal.
   13. In Permission Set Overview | External Credential Principal Access, add the external principal you have just generated to a permission set group or permission set. You must assign this permission set group or permission set to all relevant users.

   14. Click Save.
2. Create Named Credential

   To create a named credential and link it to the external credential:

   1. From Setup, enter Named Credentials in the Quick Find field, and then select "Named Credentials".
   2. Click the Named Credentials tab.
   3. To create a named credential, click New. The New Named Credential window opens.
   4. In the Label field, enter a name for the named credential. For example, named credential google.
   5. In the Name field, enter a unique name containing underscores to refer to the named credential. You can use the same name specified in the Label field. For example, named_credential_google.
   6. In the URL field, enter https://www.googleapis.com.
   7. In the External Credential drop-down list, select the name of the external credential.
   8. Ensure that Generate Authorization Header is selected under Callout Options.
   9. Under the Managed Package Access section, in the Allowed Namespace field enter pse.
   10. Leave the rest of the fields as they are and click Save.
3. Authenticate an External Credential for the Named Principal Identity Type

   To authenticate an external credential for the Named Principal identity type:

   1. Click the External Credentials tab, and then click the external credential name to open the External credential page.
   2. Navigate to the Principals section.
   3. Under Actions, select "Authenticate".
4. Authenticate an External Credential for the Per User Principal Identity Type

   When authenticating external credentials using the Per User Principal identity type, you must add access to it using a permission set group or permission set:

   1. Navigate to an existing permission set group or permission set, or create a new one.
   2. Under External Credential Principal Access, add the per user principal that you have created.
   3. Add Read access to the Salesforce object User External Credentials in the permission set.
   4. Assign this permission set group or permission set to the relevant users or profiles.

   Also ensure that the relevant users follow the steps for Per User Principal authentication:

   1. In the upper right corner, click the profile button.
   2. Click Settings.
   3. In the Quick Find field, enter external credential.
   4. To authenticate the external credential, in the external credential card, click Allow Access.
   5. The authentication flow starts. For example, enter a username and password and click Allow on the consent window.
   6. The external credential is now authenticated, and the external credential card displays a green tick.
   7. [Optional] To revoke authentication on the external credential, click Revoke Access.

When the authentication is done, you must copy the named credential API name and follow the steps in Setting up External Calendars to enable your users to use this functionality.

To set up PSA to use Microsoft Outlook as an external calendar you must do the following:

• Ask your IT team to set up Microsoft as the authentication provider. This is used to identify relevant users and manage their access.
• Generate Microsoft credentials.
• Configure Microsoft as an external calendar service provider.

Registering an Application in Microsoft Entra Admin Center and Generate Outlook Credentials: Client ID and Client Secret

Registering Your Application and Generating a Client ID

To register your application, you must have an Office 365 subscription and access to the Microsoft Entra admin center.

1. Browse to the Microsoft Entra admin center using https://entra.microsoft.com/.
2. Sign in using your developer account Administrator email ID. For example, synctest123@1mwhz4.onmicrosoft.com. The Overview page opens.
3. In the navigation pane, under Identity, expand Applications and click App registrations. The App registrations page opens.
4. Click +New registration. The Register an application page opens.
5. Register your app:
   1. In the Name field, enter a name for your application. For example, Calendar Test.
   2. Under the Supported account types who can use this application section, select "Accounts in any organizational directory (Any Azure AD directory - Multitenant)".
   3. Leave the Redirect URI blank.
6. Click Register. The registered application page opens. The Essentials section displays Application (client) ID and Redirect URIs. Copy the Application (client) ID for Configuring Microsoft as an Authentication Provider
7. In the navigation pane on this page, click API permissions. The API permissions page opens, from where you add the calendar read and write permissions to the app.
8. Under Configured permissions, click +Add a permission. The Request API permissions page opens.
9. Under Microsoft APIs, click Microsoft Graph.
10. Select "Delegated permissions". The permissions are displayed under the Select permissions section:
    1. Under OpenId permissions, select:
       1. offline access
       2. openid
    2. Scroll down to the Calendars section and select:
       1. Calendars.ReadWrite
       2. Calendars.ReadWrite.Shared
    3. Click Add permissions. The permissions are now updated for your application. You can see the permissions listed under the Configured permissions section on the API permissions page.

Generating a Client Secret Credential

To generate a client secret credential:

1. On the API permissions page, in the navigation pane under Manage, click Certificates & secrets. The Certificates & secrets page opens.
2. Click +New client secret. The Add a client secret window opens.
   1. [Optional] In the Description field, enter a description.
   2. In the Expires field, select an expiry date for the client secret.
   3. Click Add. The client secret is generated.
   4. Copy and save the secret's value from the Value column for use in your client application code. This value is not displayed again, so you must save it.

After successfully completing the app registration and generating the Application (client) ID and Client Secret, you must configure Microsoft as an authentication provider in your Salesforce org.

Configuring Microsoft as an Authentication Provider

You can configure Microsoft as an authentication provider in your Salesforce org from the Auth. Providers Setup page.

1. From Setup, in the Quick Find field, enter Auth. Providers, select "Auth. Providers" and click New.
2. In the Provider Type drop-down list, select "Microsoft". After the selection, the auth. provider fields are displayed.
3. Enter the details in the following fields and leave all other fields blank:
   1. In the Name field, enter a name for the authentication provider.
   2. The URL Suffix field populates automatically as soon as we complete the Name field.
   3. In the Consumer Key field, paste the Application (client) ID copied in step 9 in the Setting up External Calendars section.
   4. In the Consumer Secret field, paste the Client Secret value copied in step 2d Setting up External Calendars in the Setting up External Calendars section.
   5. In the Authorize Endpoint URL field, enter the following URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?prompt=consent
   6. In the Token Endpoint URL field, enter the following URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
   7. In Default Scopes, enter the following scopes separated by a space:
      1. openid
      2. offline_access
      3. Calendars.ReadWrite
      4. Calendars.ReadWrite.Shared

For example, openid offline_access Calendars.ReadWrite Calendars.ReadWrite.Shared

4. Click Save.
5. Copy the Callback URL generated under the Salesforce Configuration section.
6. Open the Azure portal. On the Overview page, select "App registration" in the Azure Active Directory menu on the left side.
7. On the App registrations page, under the Owned applications tab, click the registered application link.
8. On the registered application page, under the Essentials section, click Add a Redirect URI link.
9. On the Authentication page, under Platform configurations, click +Add a platform. The Configure platform window opens.
10. In the Configure platform window, under Web applications, select the "Web" card.
11. In the Configure Web window, under Redirect URIs, in the redirect URI field, paste the Callback URL.
12. Click Configure.
13. Navigate to your Salesforce org Auth Provider and use the Test-Only Initialization URL under the Salesforce Configuration section to test the connection. It redirects you to the Microsoft Account login page. Select the account and click Allow to view and edit events on all your calendars.

 After a successful connection, you receive a success response similar to the one below:

Generating Named Credentials

A named credential specifies the URL of a callout endpoint and is used for authentication. In Salesforce, we use an external credential to create a named credential.

Notes:

• We recommend using only the New option for creating named credentials. We do not detail the New Legacy option.
• Use the Named Principal identity type and Per User Principal identity type for PTAs and assignments.
• You can use only the Per User Principal identity type for work events. It is not possible with the Named Principal identity type.
• If you want to use both assignment and work event calendar sync, you can do this using the Per User Principal identity type. Under the Per User Principal identity type, if you are creating assignments or PTAs, you will need Read and Write access to the resource calendars for which you are generating the events. If you do not have this level of security access in the external calendar application, the events will not push, and an app log will be created.

The following table shows the differences between the options in the Named Credential Identity Type drop-down list. Before setting up these identity types, discuss their implications with your security and IT teams.

Named Credential Identity Types

Setup	Named Principal	Per User Principal
Authentication	One user authenticates the whole org.	Each relevant user must authenticate their calendar to be able to push work events, PTAs, and assignments from PSA to a contact's calendar.
Implications for PTAs and assignments	In the contact's calendar, all the events appear to be generated by the same email account. Because of this, we recommend that you have a Certinia PSA and Salesforce licenses, and create a system user, such as psasystem@xyz.com. The authorized user must have sharing access and be able to make changes to events on a contact's calendar to be able to push PTAs and assignments from PSA to the calendar.  Without this access, only records assigned to the authorized user by the authorized user are pushed to the contact's calendar.	The user that is assigning the PTAs, and assignments in PSA is the user that is creating the events in the contact's calendar. Each relevant user must have sharing access and be able to make changes to events on a contact's calendar to be able to push PTAs, and assignments from PSA to the calendar. Without this access, the user can only push self-assigned events to a contact's calendar.sy
Implications for work events	Work events cannot be pushed to a contact's calendar because the Host field on the work event is set as the logged-in user. PSA attempts to push the work event to the contact's calendar using the logged-in user, which is different from the authenticated user.	The logged-in user is the host of any work event that they create. Any other work events on the work event calendar are read-only.

Creating External Credentials and Named Credentials

To create a named credential using the new Named Credential setup page, you must create an external credential. External credentials specify an authentication protocol and permission set groups, permission sets, or profiles to use when authenticating to an external system.

1. Create External Credential

   To create an external credential:

   1. From Setup, enter Named Credentials in the Quick Find field, and then select "Named Credentials". The Named Credential page opens.
   2. Click External Credentials | New. The New External Credential window opens.
   3. In the Label field, enter a name for the external credential.
   4. In the Name field, enter a unique name containing underscores to refer to the external credential.
   5. In the Authentication Protocol, select "OAuth 2.0".
   6. In the Authentication flow type, select "Browser Flow".
   7. In the Authentication Provider drop-down list, select the authentication provider name.
   8. Leave the Scope field blank if you have defined it in the specified authentication provider. If you have not defined it, enter the scope.
   9. Click Save. The Named Credentials page opens.
   10. Scroll down to the Principals section and click New.
   11. Select a parameter name and an identity type.
   12. Enter a sequence number. A sequence number specifies the order of principals to apply when there is more than one principal.
   13. In Permission Set Overview | External Credential Principal Access, add the external principal you have just generated to a permission set group or permission set. You must assign this permission set group or permission set to all relevant users.

   14. Click Save.
2. Create Named Credential

   To create a named credential and link it to the external credential:

   1. From Setup, enter Named Credentials in the Quick Find field, then select "Named Credentials".
   2. Click the Named Credentials tab.
   3. To create a named credential, click New. The New Named Credential window opens.
   4. In the Label field, enter a name for the named credential. For example, named credential outlook.
   5. In the Name field, enter a unique name containing underscores to refer to the named credential. You can use the same name specified in the Label field. For example, named_credential_outlook.
   6. In the URL field, enter https://graph.microsoft.com.
   7. In the External Credential drop-down list, select the name of the external credential.
   8. Ensure that Generate Authorization Header is selected under the Callout Options.
   9. Under the Managed Package Access section, in the Allowed Namespace field enter pse.
   10. Leave the rest of the fields as they are and click Save.
3. Authenticate an External Credential for the Named Principal Identity Type

   To authenticate an external credential for the Named Principal identity type:

   1. Open the External Credentials tab, and now click the external credential name to open the external credential page.
   2. Navigate to the Principals section.
   3. Under Actions, select "Authenticate".
4. Authenticate an External Credential for the Per User Principal Identity Type

   When authenticating external credentials using the Per User Principal identity type, you must add access to it using a permission set group or permission set:

   1. Navigate to an existing permission set group or permission set, or create a new one.
   2. Under External Credential Principal Access, add the per user principal that you have created.
   3. Add Read access to the Salesforce object User External Credentials in the permission set.
   4. Assign this permission set group or permission set to the relevant users or profiles.

   Also ensure that the relevant users follow the steps for Per User Principal authentication:

   1. In the upper right corner, click the profile button.
   2. Click Settings.
   3. In the Quick Find field, enter External Credential.
   4. To authenticate the external credential, in the external credential card, click Allow Access.
   5. The authentication flow starts. For example, enter a username and password and click Allow on the consent window.
   6. The external credential is now authenticated, and the external credential card displays a green tick.
   7. [Optional] To revoke authentication on the external credential, click Revoke Access.

When the authentication is done, you must copy the named credential API name and follow the steps in Setting up External Calendars to enable your users to use this functionality.