The very first action any script should do is to get a RayFlow project. The only requirement is that the script knows
the URL of the RayFlow instance. To get all projects, simply execute the following command:
Get-RayFlowProject -RayFlowServerUrl <RayFlowURL> -All
For example:
Get-RayFlowProject -RayFlowServerUrl http://win-d25fl6tmfav/RayFlow
If you don’t provide credentials, you will be asked for them:
Having to type the credentials each time is not something that you want to use for production. You can define which credentials will be used for the connection and pass them via -Credentials parameter:
$credentials = Get-RayFlowCredentials <Login> <Password>
Get-RayFlowProject -RayFlowServerUrl http://win-d25fl6tmfav/RayFlow -Credentials $credentials
Id Name
-- ----
f164be99-84de-4cea-a7d4-db102c3ac738 Packaging
f1db102c-e84d-4eaf-3cb4-3ac764be9938 Packaging-Test
The list of projects is displayed if you do not provide any parameters. You can also get a specific project by specifying its identifier via ProjectId. Since project identifiers are constant for the lifetime of a project, this can be used to quickly select a project known by you by using its unique identifier, for example:
Get-RayFlowProject -RayFlowServerUrl http://ame2017/RayFlow -ProjectId f164be99-84de-4cea-a7d4-db102c3ac738
Id Name
-- ----
f164be99-84de-4cea-a7d4-db102c3ac738 Packaging
|
Note: The same pattern where: •Providing an identifier gives you a specific entity •And running the command without identifier gives you all items
is used in many places accross RayFlow PowerShell API, for example to get phases and tasks. |
You can also get a project by its name. Be aware that project name is configurable, and unlike the identifier it may change over time. To get a project by its name, provide the -ProjectName parameter, like in the following example:
Get-RayFlowProject -RayFlowServerUrl http://ame2017/RayFlow -ProjectName Packaging
Id Name
-- ----
f164be99-84de-4cea-a7d4-db102c3ac738 Packaging
|
Note: You cannot use both -ProjectName and -ProjectId in the same command. |
Handling Passwords in Non-interactive Apps
It is important to understand implications of using scripting without interactive prompt for the user password. In such cases, there must be a way to provide a password to the Get-RayFlowCredentials command let.
There are three ways how to accomplish this:
•Store the password directly in the script (open text). This is not recommended.
•Store the password in the script in an encrypted form.
•Store the password in a user environment variable of your choice and refer to it in the script. This is the recommended approach.
The second approach does not provide actual security, but has been implemented due to some legacy patterns and practices. To encrypt a password and use it later on in encrypted form:
1.Calculate the encrypted form of your password. This is something you should do once, outside of the actual script. The password can be encrypted by the ConvertTo-RayFlowEncryptedClientPassword command let. Select an encryption key of your choice and remember it, you will need it together with encrypted password in your script.
2.Instead of calling Get-RayFlowCredentials <Login> <Password>, use the following syntax: Get-RayFlowCredentials <Login> -EncryptedTextPassword <EncryptedPassword> -EncryptedTextPasswordKey <EncryptionKey>.
For example, if your password is Start123 and an arbitrary encryption key is MyEncryptionKey123:
Calculated encrypted password:
ConvertTo-RayFlowEncryptedClientPassword -Password Start123 -EncryptionKey MyEncryptionKey123
Fs/XhzIKmqxnLBG0gByD2lyTabfosRP7SUC5jO8g4+M=
Then, in your scripts use the following sample syntax:
$credentials = Get-RayFlowCredentials Admin -EncryptedTextPassword "Fs/XhzIKmqxnLBG0gByD2lyTabfosRP7SUC5jO8g4+M=" -EncryptedTextPasswordKey "MyEncryptionKey123"
Get-RayFlowProject -RayFlowServerUrl http://win-d25fl6tmfav/RayFlow -Credentials $credentials
|
Note: There is no method to decrypt the password from its encrypted form, even with the possession of the encryption key. However, bear in mind that the encryption is not meant to be secure and can be broken by reverse engineering. Thus, the method described in this chapter should be rather classified as obfuscation of passwords, not a real protection. |