gaia synergy
Documentation

Link your Salesforce Net Zero Cloud org

Install the Gaïa package, prepare an integration user, generate its security token and connect it in Gaïa.

Gaïa pushes the data extracted from your invoices to Salesforce Net Zero Cloud. This guide takes about 15 minutes and needs a Salesforce administrator.

Before you start

  • A Salesforce org with Net Zero Cloud, and an administrator account in it
  • The Gaïa package installation link (sent by the Gaïa team)
  • A Gaïa account, signed in to the web app

1. Install the Gaïa package

Open the installation link from the Gaïa team while signed in to Salesforce as an administrator, choose who gets access (Install for Admins Only is enough), and complete the installation.

The package adds the objects Gaïa writes invoice data to, and a permission set for the integration user.

2. Prepare an integration user

Use a dedicated Salesforce user for Gaïa rather than a person's account, so the connection doesn't break when someone leaves or changes their password.

  1. In Setup → Users → New User, create the user (e.g. gaia.integration@yourcompany.com) with a Salesforce license.
  2. Give it a profile with the API Enabled permission.
  3. On the user, open Permission Set Assignments → Edit Assignments and add the Gaïa permission set from the package.
  4. Log in once as this user and set its password.

3. Find your instance URL

In Setup → My Domain, copy the Current My Domain URL. It looks like https://yourcompany.my.salesforce.com.

You can also paste the address from your browser while using Salesforce, like https://yourcompany.lightning.force.com/lightning/page/home: Gaïa converts it to the .my.salesforce.com login URL.

4. Generate the security token

Gaïa connects to Salesforce from AWS servers that don't have a fixed IP address, so Salesforce asks for a security token in addition to the password.

  1. Log in to Salesforce as the integration user (each user has their own token).
  2. Click the avatar (top right) → Settings.
  3. In My Personal Information, select Reset My Security Token, then Reset Security Token.
  4. Salesforce emails the new token to the integration user's address.

Or open the page directly, replacing yourcompany with your My Domain name:

  • Lightning Experience: https://yourcompany.lightning.force.com/lightning/settings/personal/ResetApiToken/home
  • Salesforce Classic: https://yourcompany.my.salesforce.com/_ui/system/security/ResetApiTokenEdit

Official guide: Reset Your Security Token (Salesforce Help)

Note: changing the user's password also resets the token. When that happens, generate a new one and update the credentials in Gaïa (step 6).

The option is missing or the page is empty?

The user's profile has Login IP Ranges, so Salesforce hides the token reset. Open the Classic link above, which usually explains why. Gaïa connects from AWS without a fixed IP, so it can't be added to those ranges:

  1. In Setup → Users, open the integration user and note its profile.
  2. In Setup → Profiles, open that profile → Login IP Ranges, and delete the ranges (or clone the profile without them and assign the clone to the integration user only).
  3. Log in again as the integration user: Reset My Security Token now appears.

5. Link the org in Gaïa

  1. In the Gaïa web app, open Salesforce NZC → + Create.
  2. Enter the instance URL (step 3), the integration user's username and password, and the security token (step 4).
  3. Click 1. Test connection. Gaïa signs in to Salesforce and confirms the user and org.
  4. Click 2. Save. The password and token are stored encrypted in AWS Secrets Manager.
  5. In the table, click the power icon to Activate the link. Gaïa pushes invoices to the active org.

6. Update the credentials later

After a password change or a new token, click the edit icon on the link, enter the new password and token, test, then save. The instance URL and username stay the same.

Troubleshooting

INVALID_LOGIN

The username, password or token is wrong. If the password changed recently, the token was reset too: generate a new one (step 4). Setup → Login History shows the exact reason for each failed attempt.

"Reset My Security Token" is missing or the page is empty

The integration user's profile has login IP ranges. Remove them for that profile (step 4).

LOGIN_MUST_USE_SECURITY_TOKEN

The security token is missing. Add it in the form (step 4).

API_DISABLED_FOR_ORG or "API is not enabled for this user"

The integration user's profile needs the API Enabled permission, and your Salesforce edition must include API access.

"Use your https://<domain>.my.salesforce.com URL"

Use your My Domain URL (step 3). Addresses ending in .lightning.force.com are converted automatically; other domains aren't accepted.

Invoices aren't pushed

Check that the link is active, and that the integration user has the Gaïa permission set (step 2).

Still stuck? Write to contact@gaia-synergy.io.