Quick-Start & Installation

Always back up your data and test in a sandbox environment.

• Before you begin, we strongly recommend familiarizing yourself with your target API. Use cURL, Postman, or some other tool to verify your API settings in advance of entering anything into the tool. In some cases, a browser may work to verify a simple, unprotected API. Take this example: https://jsonplaceholder.typicode.com/users – you can see the APIs JSON “response” plainly.
  • Note: for this app, you will likely be using POST, PUT, PATCH, or DELETE api methods – you will need cURL or postman to test those APIs
• However, no API can be synced without first adding the https://api-domain to Salesforce Setup > Remote Site Settings. Please add your external endpoints before doing anything else. You only need to add the https:// and the domain, unless you want to further restrict access to the external domain
• The same can be said for Salesforce Setup > Named Credentials – you should set up and test your named credentials in advance of mapping an API.  Setting up named credentials can be tricky. We have some tips further in the documentation.
• Always use https:// for all of your endpoints otherwise you may leak PII, credentials, or other sensitive data 
• Install the managed package into your sandbox environment first ( we don’t recommend testing on production )
• The package will install itself along with a number of demos – the demos are safe to preview and run ( they won’t update any external API – in fact they will throw errors if you try, but you can modify the configs to test them for real )
• In Setup > Lightning App Builder, click on “New” to create a new lightning app page.
• Click: App Page then hit the next button, type a label like “Export Data, CSV, & Sync Admin” click next
• Choose “One Region” for the style of app page, and click Finish
• Drag the sfPLUGINS_Export_Command_Center aura widget to the Add Components Here Section and click Save in the top right of the screen
  

• Click the Activation button
• Activate for system adminstrators only ( or use custom profiles and permissions to further control access to this page )

• Click on Lightning Experience at the top of this screen and choose an app to display the App on, click Add Page To App, or customize as you wish.

• Click Save. 
• Assuming that you assigned the lightning page to the profile of the user you are logged in as: visit your object page and click on a record to see the record detail. ( You may need to create a dummy record if the object has no rows ) 
• Go back to Salesforce and refresh your app page, you should now see the app as a tab at the top of your screen.
• Click on the app which will look something like: 

• And click on the Login button 

• The default username and password is: syncManagerAdmin and sfPluginsAdminPass
• Once logged in, click on Configuration Options and change the username and password.
• The login screen has a “Forgot Username and/or Password” button – using this button will email the password to all system admins
• Click on API Preview or Manage API Sync Options – and you will see the pre-installed demo APIs
  • none of them are active on installation and you will not be able to sync them until they are set to active through Manage API Sync Options – see mapping and sync options for more info
• From here:
  • You can browse your APIs 
  • Preview Sync Results
  • Start a sync and see the results  
• Before you proceed, you might want to Export the Demos that come packaged with the app, in case you want to use them again later.
  • In Sync Manager, click on Manage API Sync Options 
  • Click Import/Export Sync Options
  • Click Export Sync options on the following screen
  • Save the export to a safe location, keeping in mind that exports may contain sensitive data

Troubleshooting the App:

Always back up your data and test in a sandbox environment.

• Sync does not appear in Sync One API dropdown – refresh the page – there are some cases in which the dropdown does not populate after re-logging into the app, uploading, or upgrading.
• See the in-app documentation for more troubleshooting tips
• Always test your connection credentials with Postman or cURL before entering the credentials into Salesforce – this will tell you whether or not your target API is behaving as expected
• Remote Site Settings – found under Setup, these settings are required to access API endpoints from within Salesforce. Please make sure that you add https://yourDomain to remote site settings before connecting to any APIs
• Named Credentials – some APIs will use Salesforce named credentials to authenticate and make subsequent calls to a protected API. Named credentials can be tricky to set up and there are many resources through Google that can help you connect. In almost all cases, if you can access your target API through cURL ( through a regular internet connection ) or Postman, you can likely do so from the sfPlugins app via named credentials. Please be aware of any VPN or other factors that may affect cURL results.
• When all else fails you can log a support ticket ( 2 hours free with purchase of an app ) having tried all of the above
  • For support requests, please be ready to provide the following:
    • A sandbox with the app installed and your test configuration
    • Sample API Mock data and export of your Sync Options ( please be aware of any PII or sensitive data )
    • Ideally we would be able to connect to your target API and test from both Mock and live data, from our servers ( where we have detailed logging capability ) and your Sandbox environment

Troubleshooting Named Credentials:

In some cases, you may find that your API is returning an authorization error, when you least expect it:

This is usually caused by the settings of the API or App that you are connecting to. Oauth authorization tokens have a lifetime, or a validity period ranging from hours, to weeks, to effectively infinite. When the token expires, you will need to go into Settings > Named Credentials > External Credentials > Permission Set Mappings > Actions > Authenticate and re-authorize the app.

Many providers pride some form of refresh_token ( in Salesforce this is a scope that can be added to a connected app, and the external credential should reference it was well, for Salesforce example of scopes would be refresh_token full offline_access openid api )

In the case of Salesforce, specifying the refresh_token scope in your external credentials, authorization provider, and the connected app on the target org should allow Named Credentials to refresh the auth token automatically, on your behalf. In practice, this doesn’t always work and you will need to follow the steps above to resolve the issue.

* Scopes and their names vary by API – refer to the API documentation for supported scopes and scope names. if your target API supports refresh instead of refresh_token ( for example ) you will need to specify that in your authorization provider and external credential.

Usage Terms:

This application is provided by the copyright holders and contributors “as is” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, consequential or similar damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this application, even if advised of the possibility of such damage.

Subject to the foregoing, and appropriate licensing and permission from the copyright holder, this application may be: distributed, transmitted, used, or otherwise exploited by salesforce.com or its affiliates, any customer or partner of salesforce.com or its affiliates, or any developer of applications that interface with the salesforce.com application, for any purpose, commercial or non-commercial, related to use of the salesforce.com application, and in any way, including by methods that have not yet been invented or conceived.

Always test data manipulation thoroughly in sandbox and backup your data regularly, and also before using in production.This app is to be used at the customer’s sole discretion and risk.

Additional support is available from sfplugins.com at an hourly rate.

The app is licensed in yearly increments, whether the app is used in whole or part of the year. All sales are final.