Use this Python script to automatically create workflow instances and complete steps programmatically.
Use case: Create a new employee onboarding workflow, automatically complete the first step by, for example, automatically filling in personal details, and advance to the next step.
The script creates an instance with process_id and tags. The name is created automatically as per Next Matter settings.
List of form fields ( with input data required for the step to complete)
If successful, shows a completion message.
Copy
Ask AI
# Next Matter API Key (Replace with actual API Key)API_KEY = "API_KEY_VALUE"# Workfow and Step IDs (Replace with actual values)PROCESS_ID = "WORKFLOW_ID_VALUE"STEP_ID = "STEP_ID_VALUE"# Next Matter API Base URLBASE_URL = "https://core.nextmatter.com/api/"# Headers for authenticationHEADERS = { "Authorization": f"Api-Key {API_KEY}", "Content-Type": "application/json"}def create_instance(process_id: str, tags: list = None): """ Creates a new instance of a Next Matter workflow. The name of the instance will be automatically created by Next Matter. :param process_id: ID of the workflow to create an instance for. :param tags: Optional list of tags to assign to the instance. :return: Instance ID and Instance URL if successful, None otherwise. https://help.nextmatter.com/reference/instances_create """ url = f"{BASE_URL}instances/" payload = { "process": f"https://core.nextmatter.com/api/processes/{process_id}/" } if tags: payload["tags"] = tags response = requests.post(url, json=payload, headers=HEADERS) if response.status_code == 201: instance_data = response.json() print(f"✅ Instance created successfully: {instance_data['id']}") return instance_data["id"], instance_data["url"] else: print(f"❌ Error creating instance: {response.text}") return None, Nonedef complete_step(instance_id: str, step_id: int, actions: list): """ Completes a step in a given Next Matter instance. :param instance_url: URL of the instance where the step should be completed. :param step_id: ID of the step to be completed. :param actions: List of form fields (each containing an action_id and input_object). :return: API response data. https://help.nextmatter.com/reference/instances_complete_step """ url = f"{BASE_URL}instances/{instance_id}/complete_step/" payload = { "step_id": step_id, "actions": actions } response = requests.post(url, json=payload, headers=HEADERS) if response.status_code == 200: print("✅ Step completed successfully.") return response.json() else: print(f"❌ Error completing step: {response.text}") return Noneif __name__ == "__main__": # Example usage instance_id, instance_url = create_instance(PROCESS_ID, instance_name="Test Instance") if instance_url: # Modify the form field list according to your workflow's requirements actions = [ { "action_id": 123456, # Replace with actual action ID "input_object": {"inputValue": "Value 1"} # Key (i.e. inputValue) depends on the type of form field }, { "action_id": 789012, # Replace with actual action ID "input_object": {"itemSelected": "Value 2"} } ] complete_step(str(instance_id), STEP_ID, actions)
Use case: Find all workflow instances that completed within a specific time frame.
You can use this API call to get filtered instances of a workflow. In the example below, we’re filtering for all instances with a maximum total runtime of 50 seconds.
