Import
Each Sysl file defines a Module. However a large system defined in a single file is hard to manage. The import keyword allows one file to include the contents of another file, merging the two modules together. This allows a large system to be split across many simple files.
An import statement merges the contents of another Sysl Module into the current one.
For example, given some Sysl file server.sysl:
Server: Login: ... Register: ...... and some client.sysl with an import:
import server
Client: Login: Server <- LoginThe resulting model in client.sysl will include both the Server and Client apps.
Once a Module is imported, it doesn't matter where it came from. It can be local or remote, with any directory structure or filename.
Imported files can even be non-Sysl files, if Sysl knows how to import them. For example, you can import a .json file containing an OpenAPI spec, and it will be automatically converted to Sysl.
If the imported file is a .sysl file, you can omit the .sysl extension from the import location.
Local relative file#
Imagine that you have server.sysl, client.sysl and deps.sysl files structured as below:
.├── server.sysl├── client.sysl└── deps └── deps.syslTo import both server.sysl and deps.sysl files in client.sysl:
import serverimport deps/deps
Client: Login: Server <- Login Dep: Deps <- DepServer: Login: ... Register: ...Deps: Dep: ...The resulting model in client.sysl will include three apps: Server, Client and Deps.
Local absolute file#
If the imported are in the same project but outside of current folder, you must have at least a common root directory and import /path/from/root.
All Sysl commands accept the --root option to specify this root directory from which paths are resolved. Run sysl help for more details.
<root-dir>├── clients│ └── client.sysl└── servers └── server.syslServer: Login: ... Register: ...import /servers/server
Client: Login: Server <- LoginRemote file#
Sysl supports importing Sysl files from any Git repository.
The location for a remote import starts with //, and omits the blob/main/ path segment you may see in GitHub. For example, to import the Sysl bank demo, you would import //github.com/anz-bank/sysl/demo/bank/bank.sysl
Server: Login: ... Register: ...import //github.com/foo/bar/servers/server
Client: Login: Server <- LoginWhen importing remote files from private repos, Sysl supports multiple authentication methods.
SSH Agent
If you have an SSH agent to connect to GitHub, Sysl will use that to fetch remote files.
For GitHub repositories, generate a new SSH key and add it to your GitHub account if you haven't yet. Also make sure it's added to ssh-agent.
Tokens
Git repo hosting services provide access to individual files via API if you provide an API token. If you set the SYSL_TOKENS environment variable, Sysl will use the token you specify for the domain of the remote import.
On GitHub, this token is a personal access token.
The SYSL_TOKENS value is a comma-separated list of domain:token pairs. For example:
export SYSL_TOKENS="github.com:<GITHUB-PAT>,gitlab.com:<GITLAB-TOKEN>"SSH keys
Sysl can connect directly to GitHub using the SSH private key you've registered with GitHub. Tell it where to find your key with the SYSL_SSH_KEYS environment variable.
SYSL_SSH_KEYS is a comma-separated list of domain:key-path:key-passphrase triples. If your key doesn't have a passphrase, you can leave that part empty. For example:
export SYSL_SSH_KEYS="github.com:<github-key-path>:<github-key-passphrase>,gitlab.com:<gitlab-key-path>:<gitlab-key-passphrase>"Non-Sysl file#
To import a non-Sysl file, include the file extension and use as AppName to give a name to the imported application.
For example, import a Swagger file like so:
import foreign_import_swagger.yaml as Foreign :: AppRefer to the sysl import command for all supported non-Sysl types. (Note that not all of them can be imported with the import keyword.)