A workflow is defined by one Transposit Dev Platform application and implements a functionality end-to-end (E.g. merge a change on Jenkins). A workflow application is broken up into two parts: Input and execute. Let's take a look at these operations.
Input operations (recommended operation name: input_prompt
) return the Slack Block Kit UI you will want to display when a user clicks on a workflow, like in the example below. Make sure to add a parameter (located on the right side) named context
in this operation.
Right now, if the Block Kit JSON is not valid, it will fail silently.
Important: Use the
block_kit_lib
connector to make it easier to form Slack Block Kit UI. You will need to add it as a connector in your workflow application. Under Code > Data connectors, search for Slack Block Kit. Select the "-- None --" operation and save.
Execute operations (recommended operation name: execute
) run when a user clicks the Run button in a workflow modal in Slack. This is where most of the workflow logic is written and most external API calls are made.
An execute operations generally contains code that:
We recommend using a wrapper operation to call your execute operation (recommended operation name: execute_wrapper
). The wrapper operation is used to retrieve user inputted values from context and pass them to execute as parameters.
Example:
api.run("this.execute", {
"context": context,
"param1": my_param_value
})
Make sure to add a parameter (located on the right side) of type object named context
in this operation.
The context
parameter contains the input_prompt
user input and other important information. In the execute
operation, you will find it as params[“context”][“parameters”]
.
The block_kit_lib
also contains a retrieve_text_input
operation to help you retrieve user input. Here's an example that you might have in your execute_wrapper
operation:
context = params["context"]
# retrieve value from input_prompt
# Note: if retrieving multiple values (i.e. multi_static_select, checkboxes)
# be sure to remove '[0]' from the end of the api.run command.
my_param_value = api.run(
"block_kit_lib.retrieve_input", {
"field_name": "my_text_field",
"context": context
})[0]
Use workflow.log.done(slack=output_blocks, metadata={})
to fog results and mark the successful completion of an entire workflow run. For example, in your execute
operation:
output_blocks = api.run("block_kit_lib.markdown_text_section", {
"text": f"Results are: {results}"
})
workflow.log.done(
slack = output_blocks,
metadata = {}
)
There are five types of logs (seen under the Activities in main Transposit site):
See more info about them in the Python operations doc.
Try to at least include a done
type. Some workflows don’t make as much sense to include the full results, like large log responses. Currently, it is only text based, but images are coming soon.
Integrations are how Transposit is able to connect your existing services and APIs together to interactive runbooks.
Authentication for an integration is done in Transposit in the Integrations section in the left sidebar.
You will need to check the box to enable the specific integration and either connect:
For authorizations for workflow applications that don’t require a specific user, you are done here after you connect.
For the second, where workflows are performed by a specific user:
If you want a user to connect to other services as themselves (E.g. so they can post to GitHub as themselves or create a Jira ticket with their credentials), you need to do the following:
Lastly, no matter what authorization type you use, you can go to your Transposit Dev Platform workflow application and add corresponding data connector for the integration. You will be prompted to use an existing auth for the integration, which you will need to confirm.
You can see the existing Transposit Dev Platform environment variables documentation here.
You will create your environment variables first in the Transposit Dev Platform, then when creating a workflow in Mission Control you can specify their values.
Think of environment variables as configuration of a workflow application for a specific workflow. You can have multiple workflows for a single application, but you might want them configured differently. This might be for different services, projects, regions, APIs, clusters, etc.
The code to get an env variable in the Transposit Dev Platform:
env.get("variable_name_here")
This is not commonly needed, but only BaseUrl or Region can be overridden/managed at this time. In order to make use of this new feature, the workflow application needs to have declared that the Region (E.g. AWS Region) or Base URL "can be managed" or "can be overridden." Under Code > your specific data connector > Configuration > Edit:
Note: After you have checked this box, the value for this configuration is set in the Integration section of the main Transposit site, not in the workflow itself.
Most of your debugging with happen by adding print()
statements in Python and viewing them in the Monitor section on the left sidebar in the Transposit Dev Platform.
Note: Some server side errors may be only viewable by the Transposit team at this time, please feel free to reach out to support if you are experiencing an error and don't see anything in the Monitor section.
Currently, there are two ways to return errors to a user:
1. When input_prompt
runs and show the error in the input modal
This case is good for validation on environment variables that does not require an API call.
Example: There is missing environment variable, and you want tell user what is missing and to go update it.
Here’s an example from the GitHub commit log workflow:
blocks = []
repo_name = env.get("gh_repo_name")
if repo_name == None:
message = "Invalid settings, please verify that 'gh_repo_name' is correct."
message += " Values seen for gh_repo_name: " + str(repo_name)
blocks.append(api.run("block_kit_lib.text_section", {"text": message})[0])
return blocks
2. When execute runs and shows in the channel
This case is good for errors that involve API calls. It can also be used for validation.
Example: There is a bad API response and you want to let the user know something is wrong. Since the modal is already closed, you will need to share it in the channel and logs:
workflow.log.fail(message="Restart VM workflow failed", metadata={})
See the catching API errors section below for an example.
Here’s an example from the GitHub commit log workflow:
try:
commits = api.run("this.list_commits", {
"repo": repo_name,
"owner": owner_name
})
except ValueError as ex:
message = "Error from GitHub API: " + str(ex)
workflow.log.fail(
message = f"Error performing an action: {message}",
metadata = {}
)
return {}