getUserInfo

Validates CRM credentials and returns the stable identity App Connect should store for the connected CRM user.

Signature

async function getUserInfo({
  authHeader,
  tokenUrl,
  apiUrl,
  hostname,
  platform,
  username,
  callbackUri,
  query,
  proxyId,
  proxyConfig,
  userEmail,
  data,
  additionalInfo,
  apiKey
}) {
  return {
    successful: true,
    platformUserInfo: {
      id: '123-myCRM',
      name: 'Jane Smith',
      timezoneName: 'America/Los_Angeles',
      timezoneOffset: -7,
      platformAdditionalInfo: {}
    },
    returnMessage: {
      messageType: 'success',
      message: 'Connected.',
      ttl: 1000
    }
  };
}

The runtime passes different fields depending on auth mode. OAuth flows include OAuth callback context. API-key flows include apiKey and additionalInfo.

Input

Field	Used in	Description
authHeader	Both	Prepared CRM auth header.
hostname	Both	CRM hostname selected or entered during setup.
platform	Both	Platform name.
additionalInfo	API key	Auth-page fields from auth.apiKey.page.content[]. Managed-auth values are resolved before this method is called.
apiKey	API key	Final API key value after managed-auth resolution.
tokenUrl, apiUrl, username, callbackUri, query, data	OAuth	OAuth callback metadata and token response data.
proxyId, proxyConfig, userEmail	Both/proxy	Proxy and user context when available.

Return

Field	Required	Description
successful	Yes	true when credentials are valid and user info was loaded.
platformUserInfo.id	Yes	Stable CRM user ID. Include the platform suffix if the raw CRM ID may collide with another connector.
platformUserInfo.name	Yes	Display name shown after connection.
platformUserInfo.timezoneName	Optional	Time zone name used by logging formatters.
platformUserInfo.timezoneOffset	Optional	Offset used by logging formatters. Existing connectors may use hours or minute-style offsets; keep your connector consistent with its date logic.
platformUserInfo.platformAdditionalInfo	Optional	Extra values stored with the user and available later as user.platformAdditionalInfo. Do not store secrets unless required.
platformUserInfo.overridingHostname	Optional	Hostname core should persist instead of the setup hostname.
platformUserInfo.overridingApiKey	Optional	API key core should persist instead of the submitted API key.
returnMessage	Optional	UI feedback.

When successful is false, return returnMessage so the client can tell the user what failed.

Reference

Template

const axios = require('axios');

// For params, if OAuth, then accessToken, refreshToken, tokenExpiry; If apiKey, then apiKey
// ------------
// - additionalInfo: contains custom additional fields on auth page (eg. username and password for redtail)
// ------------
// Optional input params:
// - oauth: tokenUrl, apiUrl, hostname
// - apiKey: hostname
async function getUserInfo({ authHeader, additionalInfo }) {
    try {
        //--------------------------------------
        //--- TODO: Add CRM API call here ------
        //--------------------------------------
        // const userInfoResponse = await axios.get('https://api.crm.com/user/me', {
        //     headers: {
        //         'Authorization': authHeader
        //     }
        // });
        const mockUserInfoResponse = {
            data: {
                id: 'testUserId',
                name: 'Test User',
                time_zone: 'America/Los_Angeles',
                time_zone_offset: 0
            }
        }

        const id = mockUserInfoResponse.data.id;
        const name = mockUserInfoResponse.data.name;
        const timezoneName = mockUserInfoResponse.data.time_zone ?? ''; // Optional. Whether or not you want to log with regards to the user's timezone
        const timezoneOffset = mockUserInfoResponse.data.time_zone_offset ?? null; // Optional. Whether or not you want to log with regards to the user's timezone. It will need to be converted to a format that CRM platform uses,
        return {
            successful: true,
            platformUserInfo: {
                id,
                name,
                timezoneName,
                timezoneOffset,
                platformAdditionalInfo: {}  // this should save whatever extra info you want to save against the user
            },
            returnMessage: {
                messageType: 'success',
                message: 'Connected to TestCRM.',
                ttl: 1000
            }
        };
    }
    catch (e) {
        return {
            successful: false,
            returnMessage: {
                messageType: 'warning',
                message: 'Could not load user information',
                details: [
                    {
                        title: 'Details',
                        items: [
                            {
                                id: '1',
                                type: 'text',
                                text: `TestCRM was unable to fetch information for the currently logged in user. Please check your permissions in TestCRM and make sure you have permission to access and read user information.`
                            }
                        ]
                    }
                ],
                ttl: 3000
            }
        }
    }
    //---------------------------------------------------------------------------------------------------
    //--- CHECK: Open db.sqlite (might need to install certain viewer) to check if user info is saved ---
    //---------------------------------------------------------------------------------------------------
}

module.exports = getUserInfo;