To be able to view archived records within Salesforce, we must connect the archive viewer API token to your organization. This can be done in two ways: automatically through Gearset or manually by a Salesforce admin.
What is the Archive Viewer API token?
The archive viewer API token is a special key which grants users access to view records in your archive. It is imperative that this key is kept secure and is not shared with anyone and once created in this setup step, you cannot view the token again.
In a sense, the API token is a password to your archive so it should be treated with the same level of security. If you ever suspect unauthorized access to your archive, this token can be revoked at any time in Access Token Management.
Gearset will never ask for your archive viewer API token and you should never share it with anyone.
Automatically connecting your archive
We recommend connecting the archive viewer API token automatically. This uses the Salesforce Connect API to add your API token securely to an External Credential (which was included in the Archive Viewer metadata).
Using the Connect API to automatically connect your archive does not use a metadata deployment so will not appear in your "Deployment history" within Gearset - API tokens cannot be deployed as metadata. Instead, an audit log of this action will be found in the "History" tab of your archive.
During the initial setup of the Archive Viewer, upon reaching the Connect Api key step, first ensure that Connect automatically is selected and then click Create and connect token in Salesforce.
A success message should appear, showing that your token has been created and connected in Salesforce automatically.
The API token has now been created and added to your Salesforce organization, and you can now move on to the next step of the archive viewer setup. The secret is made available to copy should you want to add it to a secure password vault for safe keeping but this should not be shared with anyone. This is the only time you will have access to the token.
If you receive a warning stating that your token was not automatically connected, then you will need to follow the manual steps to add your token.
Connecting your archive manually
Adding the archive viewer API token manually requires access to External Credentials within Salesforce. If you have access, then create the API token and follow these steps:
Step 1: From Setup, search for Named credentials.
Step 2: Navigate to the tab for External credentials and then Gearset Archive Viewer.
This is the credential that is used when we communicate with the archive. To add the API token, we must add an authentication parameter to the Gearset Archive Viewer Principal.
Step 3: Scroll down to the "Principals" section. Click on the dropdown and press Edit.
Step 4: Click Add to create an Authentication Parameter.
Step 5: Set the name to be ApiKey and the value to be the token you just created in the Archive Viewer setup.
Step 6: Clicking Save will update the principal and connect the API token so that the archive can be accessed.
Troubleshooting connection issues
Problems connecting the Archive Viewer API token may be due to the reasons below. If your issue is not found here, please contact our support team and they'll be happy to help.
I cannot access external credentials
To be able to connect the Archive Viewer API token, you must have access to edit External Credentials within Salesforce. These credentials state external services that you connect to - in this case it's connecting to your archive in Gearset. If you don't have access to these, ask your Salesforce admin to give you the Manage Named Credentials permission or ask them to follow the manual setup steps.
I cannot find the Gearset Archive Viewer external credential
If the Gearset Archive Viewer credential does not exist under external credentials, then you will need to deploy, or re-deploy, the Archive Viewer metadata to your org. To do this for the first time, follow these steps (LINK).
Gearset could not reach your Salesforce organisation
On very rare occasions, an error occurs where Gearset cannot access the Salesforce servers. Either try the steps to connect the token manually or try again later.