Salesforce

Connect Salesforce to your preprocessing pipeline, and use the Unstructured Ingest CLI or the Unstructured Ingest Python library to batch process all your documents and store structured outputs locally on your filesystem.

The requirements are as follows.

• A Salesforce account. Create an account.

• Your Salesforce username.

• The Salesforce categories (objects) that you want to access, specified as a comma-separated list. Available categories include Account, Campaign, Case, EmailMessage, and Lead.

• The OAuth consumer key (client ID) for the target Salesforce connected app in the account.

• The contents of the private key (PEM) for the certificate that is associated for the Salesforce connected app. The PEM must be expressed as a single-line string without line breaks. To print this single-line string without line breaks, suitable for copying, you can run one of the following commands from your Terminal or Command Prompt. In this command, replace <path-to-private-key-file> with the path to the .pem file.

  For macOS or Linux:

• The Salesforce categories (objects) that you want to access, specified as a comma-separated list. Available categories include Account, Campaign, Case, EmailMessage, and Lead.

• The OAuth consumer key (client ID) for the Salesforce connected app.

  1. If you do not already have a connected app, you will first need a certificate for the connected app that you will create later. If you do not already have a certificate, see Certificates and Keys, for example to generate a self-signed certificate and to download the resulting .crt file.

  2. To create the connected app, follow the steps in Configure Basic Connected App Settings and Enable OAuth Settings for API Integration to create create and configure the app to use the JWT OAuth flow. The minimum fields to set for the app are:

     • Connected App Name
     • API Name
     • Contact Email
     • Check Enable OAuth Settings
     • Callback URL - Can be set to https://localhost if you have no special requirements for additional authentication for this app outside of Unstructured.
     • Check Use digital signatures, and
     • Selected OAuth Scopes - Select Manage user data via APIs (api) (recommended), or Full access (full).

  3. Get the consumer key (client ID) for the app.

  4. Get the private key for the app.

• The private key (.pem) file for the certificate (.crt) file. To generate the private key file, you can use a utility such as openssel, as follows:

  openssl x509 -in MyCertificate.crt -out MyCertificate.pem -outform PEM
  

  To ensure maximum compatibility across Unstructured service offerings, you should give the private key information to Unstructured as a single-line string that contains the contents of the downloaded private key file (and not the prviate key file itself).
  To print this single-line string without line breaks, suitable for copying, you can run one of the following commands from your Terminal or Command Prompt. In this command, replace <path-to-downloaded-key-file> with the path to the private key file that you generated by following the preceding instructions.

  • For macOS or Linux:

    awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <path-to-private-key-file>
    

  • For Windows:

    (Get-Content -Path "<path-to-private-key-file>" -Raw).Replace("`r`n", "\n")
    

To get your Salesforce username, do the following:

1. Log in to your Salesforce account.
2. In the top navigation bar, click the Quick Settings (gear) icon, and then click Open Advanced Setup.
3. In the search box, search for and go to Users.
4. Note the Name value (not the User Name value) for your user.

If you do not already have a Salesforce connected app, to create one, start by creating or getting the certificate (.crt) and private key (.pem) files that you will associate with the connected app. If you do not have the certificate and private key, you can use your local machine to create your own private key and self-signed certificate, if your organization allows, by running the following commands, one command at a time:

openssl genrsa -out MyPrivateKey.pem -traditional
openssl req -new -key MyPrivateKey.pem -out MyCertificateSigningRequest.csr
openssl x509 -req -in MyCertificateSigningRequest.csr -signkey MyPrivateKey.pem -out MyCertificate.crt -days 365

Be sure to store these generated files in a secure location.

To create a Salesforce connected app, do the following:

1. Log in to your Salesforce account.

2. In the top navigation bar, click the Quick Settings (gear) icon, and then click Open Advanced Setup.

3. In the search box, search for and go to App Manager.

4. Click New Connected App.

5. With Create a Connected App selected, click Continue.

6. At a minimum, fill in the following, and then click Save:

   • Connected App Name
   • API Name (can be same as Connected App Name, but do not use spaces or punctuation)
   • Contact Email
   • Check Enable OAuth Settings.
   • For Callback URL, entering http://localhost is okay if you won’t be using this connected app for other special authentication scenarios.
   • Check Use Digital Signatures. Click Choose File, and browse to and select your certificate (.crt) file.
   • For Selected OAuth Scopes, add Manage user data via APIs (api) (recommended) or Full access (full).

To get the Salesforce connected app’s consumer key, do the following:

1. Log in to your Salesforce account.
2. In the top navigation bar, click the Quick Settings (gear) icon, and then click Open Advanced Setup.
3. In the search box, search for and go to App Manager.
4. In the list of apps, click the arrow next to the target connected app, and click View.
5. Click Manage Consumer Details.
6. Complete the on-screen security verification.
7. Note the Consumer Key value.

The Salesforce connector dependencies:

pip install "unstructured-ingest[salesforce]"

You might also need to install additional dependencies, depending on your needs. Learn more.

The following environment variables:

• SALESFORCE_USERNAME - The Salesforce username that has access to the required Salesforce categories, represented by --username (CLI) or username (Python).
• SALESFORCE_CONSUMER_KEY - The consumer key (client ID) for the Salesforce connected app, represented by --consumer-key (CLI) or consumer_key (Python).
• SALESFORCE_PRIVATE_KEY - The contents of the private key (PEM) associated with the consumer key for the Salesforce connected app, represented by --private-key (CLI) or private_key (Python), or
• SALESFORCE_PRIVATE_KEY_PATH - The local path to the (PEM) associated with the consumer key for the Salesforce connected app, represented by --private-key-path (CLI) or private_key_path (Python).

These environment variables:

• UNSTRUCTURED_API_KEY - Your Unstructured API key value.
• UNSTRUCTURED_API_URL - Your Unstructured API URL.

Now call the Unstructured Ingest CLI or the Unstructured Ingest Python library. The destination connector can be any of the ones supported. This example uses the local destination connector: