Programmatically create new workspaces and get them operational by adding SSO settings, inviting users, creating integrations, workflows, step runners, and more. This allows quick and secure onboarding, control over workspace resources, and easy division of organizational setup and team automation.
Enable automatic workspace creation for your organization by contacting Torq support. Only users with the Owner role can create new workspaces once enabled.
Creating a New Workspace in Torq
Follow the steps below to create a new workspace and access token. Use the access token to populate the new workspace with users, integrations, workflows, claim mappings, runners, etc.
Initiate a New Workspace: Utilize the Create a workspace step, optionally specifying a workspace_name through the on-demand trigger to customize the new workspace's name. Access the parameter value by using:
{{ $.event.workspace_name }}
Copy SSO Configurations: Opt to replicate the IdP configuration from your current workspace to the new one by setting the Copy SSO config parameter to true.
Secure API Credentials: Post-creation, the step's output will provide an API key, including a client ID and secret for the new workspace. The initiator is added as an Owner.
Configuring SSO Settings
For new workspaces requiring SSO setup:
Enable SSO Copying: In the Create a workspace step, ensure the Copy SSO config is true to duplicate existing SSO settings.
Transfer Claim Mappings: Duplicate or create unique claim mappings for the new workspace by listing the current workspace's mappings and using a loop for replication or customization.
Inviting Users
Expand workspace collaboration by adding users automatically:
Prepare User List: Incorporate a JSON parameter in the workflow trigger to get a list of users to invite to the new workspace and the role each user will get.
Send Invitations: Iterate over the user list in a Loop, employing the Invite a new user step to issue email invitations for the specified roles.
Create Integrations
Establish essential integrations within the new workspace:
Create Integrations: Apply the Create an integration step, selecting the appropriate vendor and detailing required parameters for each integration, ensuring sensitive credentials are securely managed.
You can use
$.integrations.<integration name>.<parameter>to access the credentials used for the selected type of integration in the current workspace. The credentials can also be saved as workspace secrets, retrieved from an external vault, and more.To keep integration credentials private, toggle Discard data in the step Execution Options to Yes.
Automate Integration Setup: Utilize the generated access token to authenticate the integration setup, catering to specific needs like webhook URL dissemination for trigger-based integrations. Click the three-dot menu next to the Torq integration field and select Set values separately. Provide the access token for the new workspace (generated in a previous step).
Implementing Step Runners
Ensure the successful execution of workflows imported to the new workspace that contain steps utilizing a self-hoster runner.
Define Step Runners: Add a JSON parameter to the workflow trigger to get a predefined list of step runners, specifying their platforms.
Retrieve Step Runners: Loop through the list provided and create them with the Create Step Runner step. The step outputs will include the step runner install commands.
Involve Users: You can send the install commands to a user to deploy them.
Importing Workflows
To make existing workflows available in the new workspace:
Select Workflows for Import: Use a JSON parameter to identify which workflows to copy from a user.
Retrieve All Workflows:
Loop over the JSON list provided by the user.
Use the List workflows step with the Workflow name optional parameter to get the workflow ID.
Use the Retrieve a workflow step to get the ID of the current workflow revision.
Use the Retrieve a revision step to get the content of the workflow revision in. a YAML format.
Use the Import a workflow step to import the YAML to the new workspace.
Publish and Tag: For each imported workflow you have the option to use the Publish a workflow step to publish the workflow within the new workspace. You can check whether the workflow is published in the current workspace by using the Retrieve a workflow step and checking whether the
current_revision_idis the same as thepublished_revision_id.Add tags to the workflow in the new workspace using the Add a tag step (using the new workspace credentials).
