Page tree
Skip to end of metadata
Go to start of metadata

Salesforce Integration

This article describes how to set up Salesforce synchronization in your Agiloft knowledgebase. Synchronization between Salesforce and  Agiloft allows you to integrate and update your data in real-time between both systems. If you already use Salesforce to manage marketing, sales, service, or other content, it's much easier to sync content between both systems than to manually re-enter existing data in  Agiloft. Similarly, if you already have data in Agiloft and want to transfer that data to Salesforce, syncing the data saves both time and effort, and it ensures data in both systems is kept up to date.

All Salesforce tables are supported in  Agiloft, including both standard tables and custom tables. For a given table, you can choose to sync some, all, or none of the fields.

To view a video tutorial on Salesforce syncing, click here.

Prerequisites

  • Have a working email account ready to use as a login and to receive notifications.
  • Create a Salesforce developer account using your email account.
  • Obtain your Salesforce security token after creating a Salesforce account. In Salesforce, click your user icon in the top right and go to Settings > My Personal Information > Reset Security Token. The security token is sent to your account's email address. For more information, see Reset Your Security Token.
  • Ensure that all fields you want to sync with Salesforce have been added to the knowledgebase.

Before proceeding with the setup, you might also want to review the tables and fields in Salesforce that already contain or will contain your data. To do so, click the dots in the top left of the Sales Console to open the App Launcher. In the App Launcher, select the app that contains your data or most closely suits your integration purpose. In Salesforce, apps are containers that hold the tables you can map to  Agiloft with your integration. From the app page, you can then select a table and create a test record to see fields in that table.

Considerations for Syncing Contracts

To sync the Contracts table from  Agiloft to Salesforce, you need to sync both the Contracts and Companies tables. Before you begin the steps in the Configure Synchronization section below, take these steps to prepare the Companies table:

  1. Go to Setup Companies and go to the Fields tab.
  2. Create a new Text or Short Text field.
  3. Name the field Salesforce Account ID, or something similar. This field will receive the account ID from Salesforce.
  4. Go to the Options tab and make the field required. If you want to prevent companies from sharing a Salesforce ID, make this field unique.
  5. Click Finish.

Now, prepare the Contracts table:

  1. Go to Setup Contracts and go to the Fields tab.
  2. Edit the linked field set from the Companies table and add the new Salesforce Account ID to the set.
  3. Enforce populating the Salesforce Account ID field. As part of a linked set, you can't require this specific field be set. Instead, you can do one or both of the following:
    • Set up a Validate Action to prevent saving when the Salesforce Account ID is empty.
    • Edit the linked field set, go to the Mapping tab, select "Allow entries not in source table," and then make the Salesforce Account ID field required. You might also want to create a rule that triggers when the Salesforce Account ID changes, and then executes a Linked Record Action to copy the new Salesforce account number.

As you complete the steps in the Configure Synchronization section, make sure to map both the Account ID and the Account Name from Salesforce to fields in the Companies table. Also make sure the Account ID is mapped in the Relation Mapping settings. When you test your synchronization, check that the Salesforce Account ID is populated in both tables.

Configure Synchronization

Follow these steps to configure synchronization between  Agiloft and Salesforce.

  1. In your Agiloft knowledgebase, select Setup > Sync > New > External Sync.

  2. On the General tab:
    1. Set External System Type to Salesforce. Leave the default Third-party ESA (HTTP) option selected.
    2. Set up Directions and Conflicts according to your system requirements. These settings are treated as the default for this sync, but you can configure individual tables to have different directions on the Mapping tab in step 4.

    3. If desired, set up personal synchronization options or API calls.

    4. Click Next.

  3. On the ESA Settings tab, select a login option:

    • Oauth 2.0: Enter the Redirect URI, Key, and Secret values you used for your Google OAuth 2.0 SSO integration. Then, click Verify Credentials to make sure the authorization is working.

    • Login/Password: Enter https://login.salesforce.com/services/Soap/u/33.0 in the Salesforce WSDL Endpoint field. If you receive an error, follow the SOAP API Developer Guide to identify the current endpoint. Then, enter your Salesforce account email login. In the Password field, use the following format: salesforcepasswordSECURITYTOKEN. For example, SfP4s5w[]rdSECURITYTOKEN.

  4. On the Mapping tab, map the objects in the Agiloft KB with the external Salesforce system. To map an object:

    1. Locate the  Agiloft table in the list and then select the corresponding Salesforce table from the drop-down menu. 

    2. Click Map. The Field Mapping wizard opens. On the Field Mapping tab:

      1. In the Record Modification Timestamp Field, select a field that provides the timestamp in each system to indicate the latest version of the record. If you set the table to Synchronize in the System Update Type in the next step, the timestamp field is compared between systems to determine which record's values are synced to the other system.

      2. For System Update Type, choose the sync direction for the table. You can choose a different sync direction for the table than you chose for the overall sync on the General tab, but you can't contradict the General tab setting. For example, if you chose to Update Agiloft Only on the General tab, you can't choose the Export option here to send data to Salesforce.
        • Synchronize: Updates records in both systems based on the timestamp field.
        • Export: Updates records in Salesforce to match field values in  Agiloft.
        • Import: Updates records in  Agiloft to match field values in Salesforce.
      3. In Allowed Operations, choose which sync operations are allowed during the sync.
      4. Determine how the record ID is generated during the sync. This can be done by Salesforce or   Agiloft. If you generate record IDs with  Agiloft, you must also specify a prefix and a table column to store the generated IDs.
      5. For each Salesforce field you want to sync, click Map.
      6. Select the corresponding  Agiloft field, and then choose whether the field value is updated in  Agiloft, Salesforce, or both systems. Update options are disabled if the sync direction does not permit them. For fields with multiple choice values, complete the dialog box that opens to map individual choice fields.

        Use this to map links to single fields, but not if you want to map a complete linked set. Linked sets should be mapped in step 5 below, on the Relation Mapping tab.

      7. Use the Identifying column to select fields to identify matching records between the systems. If you want to match records only when all the Identifying fields match, select the "Use strict match for identification" option. Otherwise, the system first attempts to identify matches by all fields, and if no match is found, it then narrows down the Identifying fields one at a time until a match is found.
      8. Click Next.
      9. On the Filters tab, if you need to prevent records created or updated in one system from being synced to the other, create a saved search to filter the desired records.
      10. Click Finish. The Field Mapping wizard closes.
    3. Repeat the previous steps for each table and set of fields you want to sync, and click Next when complete.
  5. On the Relation Mapping tab, you need to explicitly match any linked field relationships across mapped tables that you did not select on the Mapping tab. In general, it's best to use the Mapping tab for links to single fields, or linked sets where only one of the fields in the set will be synced. For linked sets, use Relation Mapping to connect the complete set with the appropriate Salesforce entity.

    1. Set any linked field relations between mapped tables. Linked relationships between Salesforce tables must be preserved with corresponding links in Agiloft or you cannot save the sync configuration. See the second bullet of the Additional Notes section below for more information.

    2. Choose whether the field values are updated in  Agiloft, Salesforce, or both systems.
    3. Click Next.
  6. On the Running tab, choose whether synchronization is initiated manually, via actions and rules, or via Salesforce. For more discussion of these options, see Automate Synchronization.

    To run a sync manually, go to a table's action bar and select Actions > Sync > Run [Configuration Name]

  7. On the Export tab, customize any export settings related to the sync configuration. This allows you to transfer your sync configuration to another KB, if desired.
  8. Click Finish.

Additional Notes

Before attempting to sync with Salesforce, check the configuration of the  Agiloft fields you mapped:

  • Make sure linked fields are mapped only once, either on the Mapping tab or the Relation Mapping tab. In general, it's best to use the Mapping tab for links to single fields, or linked sets where only one of the fields in the set will be synced. For linked sets, use Relation Mapping to connect the complete set with the appropriate Salesforce entity.

  • For each linked field being synced, edit the field, go to the Mapping tab, and select "Allow entries not in source table."

    Example

    In Salesforce, the Contracts to Accounts relationship is required. For any contract in the Contracts table, you must create a link to the Accounts table specifying the relevant account. In  Agiloft, this relationship is instead a link from the Contracts table to the Companies table, but the link is not required for a given contract. If you're syncing the Contracts table, you need to go to the Contracts table in Agiloft and configure the linked set to the Company table to be required. You can do this on the Options tab of the Linked Field wizard by changing the "Require the user to choose record(s) to be imported?" option to Yes.

  • For all fields being synced, edit the field, go to the Options tab, and confirm the field does not require unique values.

These are necessary for the sync to save values from Salesforce that differ from  Agiloft values. The following fields are common changes in the out-of-the-box knowledgebase:

    • Lead Table: The Company / Location Name field should not require a unique value.
    • Company and Person Table: The linked field set to the Locations table should use the "Allow entries not in source table" option. 

Automate Synchronization

Use the following steps to set up a time-based rule to automate the sync process.

  1. Navigate to Setup > Sync and edit your Salesforce sync configuration.
  2. Click Next twice, and then click the Running tab.
  3. Make sure the "By Actions (Rules/Workflow)" option is selected and click Finish.
  4. Navigate to Setup > Rules and click New. The Rule wizard opens.
  5. On the General tab, enter a name and select the table you're syncing.
  6. On the Rule Type tab, select the "At selected time intervals" option.
  7. On the Condition tab, select the "Run once per scheduled time interval" option.
  8. On the Schedule tab, apply the rule however often you want the sync to occur.
  9. On the Action tab, click Create Sync Action. The Sync action wizard opens.
    1. Enter an action name.
    2. Click the lookup icon for the External System ID field and select your sync configuration.
    3. Click Finish. The Sync action wizard closes.
  10. Click Finish in the Rule wizard.

The sync operates for all tables mapped in the sync configuration, regardless of which table contains the rule. If you need to sync some tables separately, create a separate Salesforce sync configuration for each table and use them in different Sync actions and rules. However, be careful with multiple Salesforce syncs so that you don't create conflicts with existing mappings.

Manage Attachments

If you intend to synchronize attached file fields with Salesforce and need to ensure that changes are automatically reflected in Agiloft, you need to enter code in the Salesforce developer account. The code automatically updates the Last Modified field of the containing record whenever the attached file is changed in the Salesforce account, which ensures the latest version of the attachment is synced. 

Because the sync creates a new version of the file whenever a change is made, in Agiloft you need to ensure that the field has Enable Versioning set to Yes on the Options tab of the Field wizard. Otherwise, changes from Salesforce to  Agiloft are only compared to the first sync.

  1. Click the gear icon in the top right of the Salesforce interface and select Developer Console.
  2. Go to File > New > Apex Trigger
  3. Enter a name and select Attachment for the sObject field.
  4. Click Submit.
  5. In the console, enter the following code, customizing it to use your set of synchronized tables:

    trigger Attachment_Trigger on Attachment (after insert, before delete, after update) {
        Attachment file;
        String[] tableNames = new String[]{'Account','Asset'}; //Add tables based on your sync mapping.
            
            try {
                if(Trigger.isInsert || Trigger.isUpdate) {
                    file = Trigger.new[0];
                }
                if(Trigger.isDelete) {
                    file = Trigger.old[0];
                }
                System.debug('Attachment file: ' + file);
                Attachment parentDetails = [SELECT ParentId, Parent.Type FROM Attachment Where Id = :file.Id];
                System.debug('Parent Type of attachment file: ' + parentDetails.Parent.Type);
                for(String tableName : tableNames) {
                    if(tableName.equalsIgnoreCase(parentDetails.Parent.Type)) {
                        Sobject parentTable = Database.query('SELECT Id, Description FROM ' + parentDetails.Parent.Type + ' where Id=\''+parentDetails.ParentId+'\'');
                        parentTable.put('Description', parentTable.get('Description'));
                        update parentTable;                  
                    }
                }
            } catch (Exception e) {
                System.debug('Exception in attachment_trigger: ' + e);
            }       
    }
  6. Go to File > Save to save the code.