migrate-k2-nintex

Assess and migrate K2 / Nintex K2 applications to Mendix — SmartObjects to domain models, SmartForms to pages, K2 workflows to microflows and Mendix workflows. Use when analysing or converting a K2 ap

SKILL.md

GitHub
<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines section
29-37 When to Use This Skill
38-91 Understanding K2 Application Architecture
92-128 Export and Package Options
129-288 Migration Strategy
289-341 Assessment Workflow
342-407 Migration Execution Order
408-456 Common Challenges and Solutions
457-480 Pre-Migration Checklist
481-492 Investigation Tips
493-500 Related Skills
<!-- /skill-index -->

K2/Nintex to Mendix Migration Skill

This skill provides comprehensive guidance for assessing and migrating K2 (now Nintex K2) applications to Mendix using MDL (Mendix Definition Language).

When to Use This Skill

Use this skill when:

  • Analyzing K2/Nintex applications for migration to Mendix
  • Converting SmartObjects to Mendix domain models
  • Mapping SmartForms Views to Mendix pages
  • Translating K2 Workflows to Mendix microflows or workflows
  • Planning a migration strategy for legacy K2 systems

Understanding K2 Application Architecture

K2 applications are fundamentally different from Mendix in how they're stored and structured.

K2 Storage Model

Key Difference: K2 applications are server-side/database-stored, not file-based like Mendix. All K2 project elements and data are saved into the K2 database, not as files. This is one of the key challenges for migration.

Aspect K2/Nintex Mendix
Storage Server database .mpr file (SQLite)
Versioning Server-managed Git-based (MPR v2)
Export format .kspx package .mpk package
Project file No single file .mpr project file

K2 Artifact Types

A K2 application is composed of several artifact types:

SmartObjects

Middle layer between data providers (SQL, SAP, SharePoint) and data consumers (forms, workflows, reports). They abstract data from LOB systems.

SmartObject Type Description Mendix Mapping
SmartBox Stores data in K2's own database Persistable Entity
SQL Connector Connects to SQL Server tables External Database Connector
SAP Connector Connects to SAP systems OData/REST Integration
SharePoint Connector Connects to SharePoint lists REST Client
Service Object Exposes services/methods Microflow/Java Action

SmartForms

Browser-based forms composed of Views and Forms:

SmartForms Element Description Mendix Mapping
View Reusable collection of controls + rules bound to SmartObjects Snippet or Page Section
Form Container for views, accessible via URL Page
Control UI element (text, date, dropdown, etc.) Widget
Rule Event-driven logic ("when button clicked, execute method") Nanoflow or Microflow

Workflows

Process definitions with steps, tasks, branching logic:

Workflow Element Description Mendix Mapping
Workflow Full process definition Workflow or Microflow chain
Activity Individual step in workflow Microflow activity or User Task
Task Human task requiring user action User Task
Destination Rule Routing logic for tasks Decision (microflow)
Datafield Workflow data variable Parameter or Variable

Export and Package Options

There's no single "project file" like Mendix's .mpr. Your options for extracting K2 app definitions:

1. K2 Package (.kspx)

The K2 Package and Deployment tool packages K2 artifacts (SmartObjects, forms, views, workflows) into a single file with a .kspx extension. This is the primary mechanism for moving apps between environments.

How to export:

K2 Management Site → Solutions → Package → export

2. Legacy Project Files

Older K2 Studio / K2 for Visual Studio projects used:

File Type Extension Contents
Project file .k2proj Project structure and references
Workflow definition .kprx Workflow definition
SmartObject definition .sodx SmartObject schema

3. K2 APIs

SmartObject Runtime API and management APIs can be used programmatically to extract definitions:

// Example: Programmatic SmartObject extraction
using SourceCode.SmartObjects.Client;

SmartObjectClientServer server = new SmartObjectClientServer();
server.CreateConnection();
SmartObject so = server.GetSmartObject("CustomerSO");
// Extract properties, methods, etc.

Migration Strategy

For a K2 → Mendix migration, approach it in layers:

Layer 1: Data Model (SmartObjects → Entities)

SmartObject Type Migration Approach
SmartBox SmartObjects Direct translation to Mendix persistable entities
SQL Connector SmartObjects Options: (a) Import data to Mendix, (b) External Database Connector
Service SmartObjects Microflows that call external services

Example MDL:

mdl 1;
-- SmartBox SmartObject "Customer" → Mendix Entity
create persistent entity CRM.Customer (
  CustomerCode: string(50),
  CustomerName: string(200),
  Email: string(200),
  Phone: string(50),
  IsActive: boolean default true,
  CreatedDate: autocreateddate
);

-- SmartBox SmartObject "Order" → Mendix Entity
create persistent entity CRM.Order (
  OrderNumber: string(50),
  OrderDate: datetime,
  status: CRM.OrderStatus,  -- Enumeration
  TotalAmount: decimal
);

-- SmartObject relationship → Association
create association CRM.Order_Customer
from CRM.Order to CRM.Customer
type reference;

Layer 2: UI (SmartForms → Pages)

SmartForms Views map to Mendix pages/snippets. The rules system (event-driven, "when X happens, do Y") maps well to Mendix's nanoflow/microflow-on-events pattern.

SmartForms Control Mendix Widget
Text Box TEXTBOX
Text Area TEXTAREA
Drop-down List COMBOBOX
Date Picker DATEPICKER
Check Box CHECKBOX
Radio Button RADIOBUTTONS
Data Label DYNAMICTEXT
Button ACTIONBUTTON
List View LISTVIEW or DATAGRID
Subview SNIPPETCALL
Tab Control Tab container pattern

SmartForms Rules to Mendix Events

SmartForms Rule Mendix Implementation
When Control is Clicked Button action microflow/nanoflow
When View is Initialized Page data source microflow
When Control Value Changes OnChange nanoflow
When Data Loads Data source microflow
Execute SmartObject Method Microflow calling entity operations
Transfer Data Variable assignment in microflow
Show/Hide Control Conditional visibility
Enable/Disable Control Editable expression

Example MDL (SmartForm View → Mendix Page):

mdl 1;
create page CRM.Customer_Edit
(
  params: ( $Customer: CRM.Customer ),
  title: 'Edit Customer',
  layout: Atlas_Core.PopupLayout
)
{
  dataview dvCustomer (datasource: $Customer) {
    -- Text Box controls
    textbox txtCode (label: 'Customer Code', attribute: CustomerCode)
    textbox txtName (label: 'Customer Name', attribute: CustomerName)
    textbox txtEmail (label: 'Email', attribute: Email)
    textbox txtPhone (label: 'Phone', attribute: Phone)

    -- Check Box control
    checkbox chkActive (label: 'Active', attribute: IsActive)

    -- Button bar (SmartForms action buttons)
    footer {
      actionbutton btnSave (caption: 'Save', action: save changes, buttonstyle: primary)
      actionbutton btnCancel (caption: 'Cancel', action: cancel changes)
    }
  }
};

Layer 3: Process (Workflows → Microflows/Workflows)

K2 Workflows translate to Mendix microflows or the Workflow module:

K2 Workflow Element Mendix Mapping
Start Microflow start / Workflow start
Task (human) User Task activity
Reference (call SmartObject) Microflow activities (Create, Change, Retrieve)
Decision Decision (split/merge)
Send Email Email activity
Generate Document Generate document microflow
Web Service Call REST/Web service call
Script Java action or expressions
End End event / Microflow return
Escalation Scheduled event or timer
Destination Rule Microflow logic for task assignment

Task Allocation Mapping

K2 Destination Rule Mendix User Task
Specific User User by association
Role XPath targeting user role
Manager Microflow calculating manager
Queue First user from filtered list

Example MDL (K2 Task → Mendix Microflow):

mdl 1;
-- K2 Task "Review Order" → Mendix microflow for task handling
create microflow CRM.ACT_Order_SubmitForReview ($Order: CRM.Order)
begin
  -- Update status (like K2 "Set Status")
  change $Order (status = CRM.OrderStatus.PendingReview);
  commit $Order;

  -- Show page for review (like K2 "Task" with form)
  show page CRM.Order_Review (Order = $Order);
end;

-- K2 Decision "Order > $5000?" → Mendix microflow with decision
create microflow CRM.ACT_Order_ProcessApproval ($Order: CRM.Order)
returns boolean as $Approved
begin
  declare $Approved boolean = false;

  if $Order/TotalAmount > 5000 then
    -- Route to manager (K2 Destination Rule equivalent)
    call microflow CRM.ACT_Order_SubmitForManagerReview (Order = $Order);
  else
    -- Auto-approve (K2 "Go To" equivalent)
    change $Order (status = CRM.OrderStatus.Approved);
    commit $Order;
    set $Approved = true;
  end if;

  return $Approved;
end;

Assessment Workflow

When assessing a K2 application for migration:

Step 1: Inventory SmartObjects

Export SmartObject definitions and categorize:

| SmartObject Name | type | data source | entity count | Mendix mapping |
|------------------|------|-------------|--------------|----------------|
| CustomerSO | SmartBox | K2 DB | single | CRM.Customer entity |
| OrderSO | SmartBox | K2 DB | single | CRM.Order entity |
| EmployeeSO | sql | HR database | single | Integration or import |
| SAPOrderSO | SAP | SAP ERP | multiple | odata service |

Step 2: Inventory SmartForms

Document all forms and views:

| Form Name | views Used | SmartObjects | Mendix mapping |
|-----------|------------|--------------|----------------|
| Customer Entry | CustomerView, AddressView | CustomerSO, AddressSO | Customer_Edit page |
| Order Dashboard | OrderListView, FilterView | OrderSO | Order_Overview page |
| Order Entry | OrderHeaderView, LineItemsView | OrderSO, OrderLineSO | Order_Edit page |

Step 3: Inventory Workflows

Document all workflows and their complexity:

| workflow Name | Tasks | Activities | Complexity | Mendix mapping |
|---------------|-------|------------|------------|----------------|
| Order Approval | 3 | 12 | Medium | microflow chain |
| New Employee Onboarding | 8 | 25 | High | workflow module |
| Leave request | 2 | 6 | Low | microflows only |

Step 4: Map Rules and Logic

Extract business rules from SmartForms rules and workflow logic:

| rule ID | Location | description | Mendix Implementation |
|---------|----------|-------------|----------------------|
| R-001 | CustomerView | Email format validation | validation microflow |
| R-002 | OrderWorkflow | Orders > $5000 need manager approval | decision in microflow |
| R-003 | LineItemsView | Auto-calculate line total | on-change nanoflow |

Migration Execution Order

Execute migration in this order to manage dependencies:

Phase 1: Domain Model

-- 1. Enumerations first (no dependencies)
create enumeration CRM.OrderStatus (
  Pending 'Pending',
  Approved 'Approved',
  Rejected 'Rejected',
  Completed 'Completed'
);

-- 2. Entities (may reference enumerations)
create persistent entity CRM.Customer (...);
create persistent entity CRM.Order (...);

-- 3. Associations (reference entities)
create association CRM.Order_Customer from CRM.Order to CRM.Customer type reference;

Phase 2: Business Logic (Microflows)

-- Core CRUD microflows
create microflow CRM.ACT_Customer_Save ($Customer: CRM.Customer)
begin
  -- Validation (from SmartForms rules)
  if $Customer/Email = empty then
    validation feedback $Customer/Email message 'Email is required';
    return false;
  end if;

  commit $Customer;
  return true;
end;

-- Workflow logic
create microflow CRM.ACT_Order_Submit ($Order: CRM.Order)
begin
  -- Workflow start logic
  ...
end;

Phase 3: Pages

-- Overview pages
create page CRM.Customer_Overview (...);

-- Edit pages (can reference microflows from Phase 2)
create page CRM.Customer_Edit (...);

Phase 4: Security

mdl 1;
-- Module roles matching K2 roles
create module role CRM.Manager description 'Can approve orders and manage customers';
create module role CRM.User description 'Can create and edit own records';

-- Access rules
grant create, delete, read *, write * on entity CRM.Order to CRM.Manager;
grant create, read *, write * on entity CRM.Order to CRM.User where [System.owner = '[%CurrentUser%]'];

Common Challenges and Solutions

Challenge 1: Server-Side Storage

Problem: K2 stores everything in a database, no single project file.

Solution: Use K2 Package (.kspx) export or K2 APIs to extract definitions. Work with K2 administrators to get comprehensive exports.

Challenge 2: SmartObject Connectors

Problem: SmartObjects may connect to external systems (SQL, SAP, SharePoint).

Solutions:

Connector Type Mendix Options
SQL Direct External Database Connector or data migration
SAP SAP BAPI Connector, OData, or REST
SharePoint REST integration via Microsoft Graph API
Web Service REST/SOAP consumption

Challenge 3: Complex Rules

Problem: SmartForms rules are event-driven and can be deeply nested.

Solution: Map each rule to appropriate Mendix mechanism:

event-based UI logic → nanoflows
validation → validation microflows + validation feedback
data manipulation → microflows
Complex calculations → microflow expressions

Challenge 4: Workflow Participants

Problem: K2 uses destination rules for task assignment that may be complex.

Solution: Implement participant logic in microflows:

mdl 1;
-- K2 Destination Rule "Route to Manager" → Mendix microflow
create microflow CRM.SUB_GetManager ($Employee: HR.Employee)
returns HR.Employee as $Manager
begin
  retrieve $Manager from HR.Employee
    where [HR.Employee_Reports = $Employee];
  return $Manager;
end;

Pre-Migration Checklist

Before starting migration:

  • Obtain K2 Package (.kspx) export for all artifacts
  • Get SmartObject documentation or extract via APIs
  • Document all SmartForms views and their rules
  • Map workflow steps and decision logic
  • Identify external system integrations (SQL, SAP, SharePoint)
  • Understand K2 security/role model
  • Plan for data migration (SmartBox data → Mendix entities)

During migration:

  • Create entities in dependency order
  • Create enumerations before entities that use them
  • Create microflows before pages that reference them
  • Test validation rules thoroughly
  • Verify workflow logic paths

After migration:

  • Run mxcli check script.mdl -p app.mpr --references
  • Open in Mendix Studio Pro to verify
  • Test all workflow scenarios
  • Validate data migration completeness

Investigation Tips

If you have access to K2:

  1. K2 Management Site: Export packages and view SmartObject schemas
  2. K2 Designer: View SmartForms rules in detail
  3. K2 Workspace: Examine workflow definitions
  4. SQL Server: Query K2 database for SmartBox data and metadata
  5. K2 API: Programmatically extract definitions for automation

If you have a .kspx file, it can potentially be parsed (it's a ZIP-based format) to extract XML definitions of the artifacts inside.

Related Skills