Learn how to use the CLI to create, manage, and test SaaS connectors in this guide.
You can use SaaS connectors to serve as bridges between your IdentityNow (IDN) tenant and other source systems without the use of a Virtual Appliance (VA). For more information about the SaaS connectors, refer to the SaaS Connectivity guide.
connectors command is a CLI interface for the SaaS Connectivity platform. The CLI is the best way to create, manage, and test SaaS connectors within your tenant.
To create, manage, and test SaaS connectors with the CLI, you can run these commands:
- Init project
- Create connector
- Upload connector
- Invoke command
- List connectors
- Update connector
- Validate connector
- Delete connector
- Manage tags
- Get logs
To initialize a connector project, run this command:
sail conn init [connectorProjectName]
This command creates a folder named
connectorProjectName in your working directory. The folder includes all the files necessary to create a connector. For more information about initiating a connector project, refer to the Create new project section of the SaaS Connectivity documentation.
To create a connector entry in your IDN tenant, run this command:
sail conn create [connectorAlias]
This command registers your connector and gives it a unique ID. For more information about creating a connector in your tenant, refer to the Create connector in your org section of the SaaS Connectivity documentation.
To upload a connector to your IDN tenant, run
npm run pack-zip in the project directory to package the connector into a zip file. Then run this command:
sail conn upload -c [connectorID | connectorAlias] -f connector.zip
You must package the project files before you upload them. For more information about how to package and upload connectors, refer to the Create and upload connector bundle section of the SaaS Connectivity documentation.
To test connector commands, like
entitlement-list, run this command:
sail conn invoke [command] -c [connectorID | connectorAlias] -p [config.json] -v [version]
For more information about the different available connector commands, refer to Connector Commands.
The entitlement commands require an additional flag (
-t [entitlementType]), like this example:
sail conn invoke entitlement-list -t [entitlementType] -c [connectorID | connectorAlias] -p [config.json] -v [version]
For more information about invoking commands, refer to the Test your connector in IdentityNow section of the SaaS Connectivity documentation.
To get a list of connectors in your tenant, run this command:
sail conn list
To change a connector's alias, run this command:
sail conn update -c [connectorID] -a [newConnectorAlias]
Validate a connector
You can use the CLI to validate your connector's behavior. The validate command runs integration tests against your connector to ensure all the basic functionality works.
To validate a connector's behavior, run this command:
sail conn validate -c [connectorID]
You can pass in a
-r flag to run the command as read-only, or you can run a full suite of read/write tests.
To delete a connector, run this command:
sail conn delete -c [connectorID]
You can use tags to create multiple instances of your connector that can be used in IDN. The
latest tag is created by default and is the primary instance, typically used for production purposes. Tags are similar to branches in a version control system, like git or CVS. You can create a tag for actively developing the connector, or for any other purpose you want.
A common pattern is to create a
development tag on a connector from a specific version, like the latest version.
sail conn tags create -c [connectorID | connectorAlias] -n [tagName] -v [version]
As the connector is developed and the version number increases, update the
development tag to point to the latest version. Doing so leaves the
latest tag on a stable version while you make changes to your connector on the unstable
sail conn tags update -c [connectorID | connectorAlias] -n [tagName] -v [version]
You can test the connector in IDN by selecting the connector instance with the
development tag. The CLI will use the version you point to with the update command.
To see a connector's tags and the versions they point to, run this command:
sail conn tags list -c [connectorID | connectorAlias]
When you are satisfied with the changes you made to the
develop tag, you can point your
latest tag to the new stable version.
To get all logs for all connectors, run these logging commands:
To get a dump of logs, run this command:
sail conn logs
To get the output of logs in realtime, run this command:
sail conn logs tail
To filter the logs to a specific connector, use a utility like
grep, like how it's used in this example:
sail conn logs | grep 'connector version 29'
To get detailed logging statistics on each connector, run this command:
sail conn stats
For more information about connector logging, refer to Logging.