Salesforce CLI And API Setup
Since Cloudaware is built on force.com, address Salesforce CLI which is a powerful command line interface that simplifies development and build automation when working with your Salesforce instance.
Install Salesforce CLI application
1. Download and install Salesforce CLI application for your OS using this link.
2. Open Terminal (or Windows Command Prompt) and run the command
sfdx to make sure the application was successfully installed.
Create a Private Key and Self-signed Digital Certificate
The JWT-based authorization flow requires a digital certificate and a private key used to sign the certificate. You upload the digital certificate to the custom connected app that is also required for JWT-based authorization. This process produces two files:
server.key - the private key. You specify this file when you authorize an org with the
server.crt - the digital certification. You upload this file when you create the connected app required by the JWT-based flow.
1. If necessary, install OpenSSL on your computer. To check whether OpenSSL is installed, run this command:
2. In Terminal create a directory to store the generated files and change to the directory:
3. Generate a private key and store it in a file called server.key:
openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048
openssl rsa -passin pass:xxxx -in server.pass.key -out server.key
xxxx - a password containing 4 characters minimum. Newer versions of Linux Open SSL are more demanding in terms of password requirements.
You can delete the file server.pass.key as you will no longer need it.
4. Generate a certificate signing request using the server.key file. Store the certificate signing request in a file called server.csr. Enter the information about your company when prompted.
openssl req -new -key server.key -out server.csr
5. Generate a self-signed digital certificate from the server.key and server.csr files. Store the certificate in a file called server.crt.
openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt
Create a Connected App in Your Salesforce Org
1. Log in to your Cloudaware account.
2. Open the main menu under your username. Go to Setup → section ‘Build' on the left → under 'Create' select Apps → Connected Apps → New.
3. Enter a meaningful connected app name and your email address.
4. In 'API (Enable OAuth Settings)' check the box Enable OAuth Settings.
5. For the Callback URL paste http://localhost:1717/OauthRedirect.
6. Check the box Use digital signatures. Click Choose File and upload the server.crt file that contains your digital certificate.
7. In 'Selected OAuth Scopes' add the following OAuth scopes:
Access and manage your data (api)
Perform requests on your behalf at any time (refresh_token, offline_access)
Provide access to your data via the Web (web)
8. Click Save → Continue.
9. Review Connected App details. Click Manage.
10. Click Edit Policies. Under 'OAuth Policies' select 'Admin approved users are pre-authorized' in Permitted Users. Click OK in the popup message.
11. Click Save.
12. Go back to the section 'Build' on the left → under 'Create' select Apps → select the created app. Under 'Profiles' click Manage Profiles to select profiles of those users who will have access to the app. CloudAware Collector Only and CloudAware Administrator should be selected by default. Click Save.
13. Optional: to allow all users access the app using their credentials in CLI, select the app → Edit policies → select 'All users may self-authorize' in the section 'OAuth Policies'.
To authorize user access in an already created app, contact the application creator to request a certificate.
Authorize a Salesforce Org for Use with Salesforce CLI
1. Open Terminal and run the following command (without single quotes):
sfdx force:auth:jwt:grant -u ‘text’ -f ‘text’ -i ‘text’ -a ‘text’
-u - authentication username (Setup → under the section 'Administer' on the left select Manage Users → Users → click the user → copy username)
-f - path to a file containing the private key generated earlier
-i - consumer key of the Salesforce connected app created earlier (Setup → the section 'Build' on the left → under 'Create' select Apps → select the app → copy the value from 'Consumer Key')
-a - sets an alias for the authenticated org (simple string)
You have successfully authorized your Salesforce org for use with the Salesforce CLI.
Execute a Sample SOQL Query
Note that you must use API names to run SOQL queries against Cloudaware objects and fields. To locate API names, go to Setup → under the section 'Create' select Objects → select an object in question.
Let's execute a sample SOQL query that will return AWS EC2 instances that are not deleted from AWS with Accounts, Private IPs and Public IPs. Use the sample query below replacing the value of -u parameter by -a value set before (without single quotes):
sfdx force:data:soql:query -q "Select CA10__account__r.Name, CA10__instanceId__c, CA10__privateIpAddress__c, CA10__publicIpAddress__c from CA10__CaAwsInstance__c where CA10__disappearanceTime__c =null" -u ‘text’
More information on Salesforce CLI is available here.
Setting Up API
1. Get your Access Token using Salesforce CLI:
sfdx force:org:display -u orgAlias
This is your authorization bearer token. Make curl and rest API calls using this token.
2. Make note of your Instance URL. You can see examples here.
3. Here is a Cloudaware-specific example to retrieve the list of IP addresses:
curl https://cloudaware-0000.cloudforce.com/services/data/v20.0/query/?q=SELECT+CA10__privateIpAddress__c%2C+CA10__associationPublicIp__c+from+CA10__CaAwsNetworkInterface__c -H 'Authorization: Bearer 00D1U00000130CD/!AQwAQN7gCP78KDezrjUpFMsEIOTsTEItsL53UkLa5ZvrU6bENuT2Jj5oSWzKGD4IopBsrX0p1pv0wRczXK.'
If you encounter any errors, make sure to:
Escape ! in Access Token with / slash.
Use single quotes around -H value
Use URL encoded URL
More information about other API calls is available in Salesforce documentation on Working with Records and Working with Searches and Queries.
Loading Custom Data To CMDB Using CLI
Let's assume we have a 2-column dataset made up of EC2 Instance ID and a custom attribute called ''Demo Version'':
Using CLI, we will need to extract instanceID and Salesforce ID in order to create a Salesforce-side dataset that will look like this:
sfdx force:data:soql:query -q "Select Id, CA10__instanceID__c CA10__CaAwsInstance__c where CA10__disappearanceTime__c =null" -u your SFDC username
If you are not sure how to create a custom field on an existing object such as EC2 Instance or Physical Server, follow the instructions here.
CMDB CURRENT DATA
We will use sort and merge commands to create a final dataset that will be used to upload the merged dataset. In this merged dataset, records are matched by instanceID but the actual instanceID does not need to be re-imported.
sfdx force:data:bulk:upsert -s EC2_Instances -f ./path/to/file.csv -i Salesforce ID