Skip to main content

Tercen developer’s guide

16 Running Tercen from the CLI

This chapter provides an overview of workflows automation in Tercen using Python and the API. The script uses the Tercen Python client to interact with a local Tercen instance, create a temporary project, import a Git repository, and trigger workflow computations using predefined data.

16.1 Prerequisites

To use the workflow runner script, ensure the following:

  • A local instance of Tercen is running (e.g., via Tercen Studio).
  • The Tercen Python client is installed (tercen package).
  • A GitHub token is available as an environment variable (GITHUB_TOKEN) for repository access, if needed.

16.1.1 Required Python Libraries 

import sys
import string
import random
import os
import uuid
from tercen.client import context as ctx
from tercen.client.factory import TercenClient
from tercen.model.impl import Project, GitProjectTask, InitState, TableStep, TableStepModel, SimpleRelation, StepState, DoneState, RunWorkflowTask, Pair

16.1.2 Configuration Variables

The script uses the following configuration variables:

user = "workflow_runner"
passw = "workflow_runner"
service_uri = "http://tercen:5400"
template_repo = "https://github.com/tercen/dose_response_template"
branch = "main"
tag = ""
git_token = os.environ.get("GITHUB_TOKEN", "")
template_folder = "workflow_tests"
  • user and passw: Credentials for authenticating with the Tercen instance.
  • service_uri: URL of the local Tercen instance.
  • template_repo: GitHub repository containing the workflow template.
  • branch: Git branch to use (e.g., main).
  • tag: Optional Git tag (empty by default).
  • git_token: GitHub personal access token for repository access.
  • template_folder: Folder for workflow tests.

16.2 Script Workflow

The script performs the following steps:

16.2.1 1. Initialize the Tercen Client

The script initializes a connection to the Tercen instance using the provided credentials.

client = TercenClient("http://tercen:5400")
client.userService.connect(user, passw)

16.2.2 2. Create a Temporary Project

A temporary project is created with a randomly generated name to serve as the workspace for the workflow.

project = Project()
project.name = 'WorkflowRunner_' + ''.join(random.choices(string.ascii_uppercase + string.digits, k=4))
project.acl.owner = user
project = client.projectService.create(project)

The project name is prefixed with WorkflowRunner_ followed by a four-character random string.

16.2.3 3. Import a Git Repository

The script sets up and triggers a GitProjectTask to clone the specified repository into the project.

import_task = GitProjectTask()
import_task.owner = user
import_task.state = InitState()

import_task.addMeta("PROJECT_ID", project.id)
import_task.addMeta("PROJECT_REV", project.rev)
import_task.addMeta("GIT_ACTION", "reset/pull")
import_task.addMeta("GIT_PAT", git_token)
import_task.addMeta("GIT_URL", template_repo)
import_task.addMeta("GIT_BRANCH", branch)
import_task.addMeta("GIT_MESSAGE", "")
if tag:
    import_task.addMeta("GIT_TAG", tag)

import_task = client.taskService.create(import_task)
client.taskService.runTask(import_task.id)
importTask = client.taskService.waitDone(import_task.id)

Key metadata includes the project ID, Git URL, branch, and authentication token. The task clones the dose_response_template repository and waits for completion.

16.2.4 4. Trigger Workflow Computation

The script retrieves a predefined workflow, table step, and dataset using hardcoded IDs, then triggers a computation.

project = client.projectService.get("9c44bf7ae873f33e0171dea4fd012375")
workflow_id = "9c44bf7ae873f33e0171dea4fd016344"
step_id = "1e0b619b-b8fa-43c3-aef8-6e0f5d8f80f8"
relation_id = "9c44bf7ae873f33e0171dea4fd015d70"
workflow = client.workflowService.get(workflow_id)
table_step = next((step for step in workflow.steps if step.id == step_id), None)
if not table_step:
    raise ValueError(f"No table step found with ID {step_id}")

The script configures the table step with a SimpleRelation and marks it as complete.

table_step_model = TableStepModel()
simple_rel = SimpleRelation()
simple_rel.id = relation_id
table_step_model.relation = simple_rel
table_step.model = table_step_model

step_state = StepState()
step_state.taskState = DoneState()
table_step.state = step_state

client.workflowService.update(workflow)

A RunWorkflowTask is then created and executed to run the workflow computation.

runTask = RunWorkflowTask()
runTask.state = InitState()
runTask.workflowId = workflow.id
runTask.workflowRev = workflow.rev
runTask.owner = project.acl.owner
runTask.projectId = project.id

runTask = client.taskService.create(obj=runTask)
client.taskService.runTask(taskId=runTask.id)
runTask = client.taskService.waitDone(taskId=runTask.id)

client.workflowService.update(workflow)

16.2.5 5. Next Steps

The script includes suggestions for further exploration:

  • Review the workflow runner’s capabilities.
  • Explore the Tercen Python client unit tests for additional API usage examples.
  • Investigate GitHub Actions for integrating the workflow runner into a CI/CD pipeline.

16.3 Available Tasks

The Tercen platform supports various tasks for workflow and project management, including:

  • CreateGitOperatorTask
  • TestOperatorTask
  • ExportTableTask
  • ExportWorkflowTask
  • ImportWorkflowTask
  • ImportGitWorkflowTask
  • ImportGitDatasetTask
  • RunWebAppTask
  • CSVTask
  • CubeQueryTask
  • RunWorkflowTask
  • RunComputationTask
  • ComputationTask
  • SaveComputationResultTask
  • GlTask
  • GitProjectTask
  • LibraryTask

16.4 Useful Resources

16.5 Notes

  • The script assumes a local Tercen instance is running. For CI/CD integration, refer to Tercen GitHub Actions for starting a local instance.
  • Hardcoded IDs (e.g., workflow_id, step_id) are used for demonstration. In production, these should be dynamically retrieved or passed as parameters.
  • Ensure the GitHub token has appropriate permissions to access the target repository.

This script serves as a foundation for automating Tercen workflows and can be extended for more complex use cases, such as parameterized workflow execution or integration with external systems.