A common ask from teams evaluating Sigma is migrating their IBM Cognos Analytics footprint — usually to trade a server-administered, report-centric platform for a live-query workspace their analysts can actually drive. The conversion itself is often the thing that stalls the project.

The typical Cognos-to-Sigma migration loop is rebuild-the-data-module-by-hand, rewrite every Cognos expression and calculated measure as a Sigma formula, recreate each report's visualizations and layout, then eyeball the numbers and hope nothing drifted in the translation. Done on a single report it's tedious. Across a real Cognos estate — typically dozens of reports reading from shared packages and data modules — it's the reason migration projects slip.

This QuickStart walks through a Claude Code skill called cognos-to-sigma that automates the loop.

Point it at a Cognos report; it discovers the report's visualizations and the data module or package behind them via the Cognos REST API. It translates each visualization's expression into a Sigma formula, builds a Sigma data model from the warehouse tables the data module points at, mirrors the report layout on Sigma's grid, and runs a parity pass comparing Sigma's results against the live warehouse. It surfaces a punch list of anything it couldn't auto-translate — instead of silently producing a broken workbook.

What else this enables

A pure lift-and-shift is the floor, not the ceiling. The same skill family supports three follow-on moves that turn a migration into an upgrade:

Sample dashboard

For the demonstration, we'll convert a dashboard called Commerce Dashboard — 6 visualizations built on a data module that reads from Snowflake. You'll see the discovery artifacts each phase produces, the converter's breakdown of how each Cognos expression mapped to a Sigma formula, the parity report against the live warehouse, and the resulting Sigma data model and workbook landed in your org — along with the gap list of items to hand-polish.

Target Audience

Sigma SEs, technical CSMs, and migration partners running Cognos-to-Sigma conversions — or scoping a batch migration with the companion cognos-assessment skill.

Prerequisites

Sigma Free Trial

Footer

cognos-to-sigma is one of two skills that ship together as a single repo (cloned in the next section). Most of this QuickStart focuses on the converter — but knowing where the assessment skill fits avoids dead ends later when scoping a batch migration.

Skill

Role

When to reach for it

cognos-assessment

Scoping

Auditing a Cognos instance before committing to a conversion plan. Emits a per-report complexity readout (visualization-type mix, expression convertibility, data module vs package flags, join complexity, filter/parameter complexity), usage signal from Cognos's activity API, and a value/cost-ranked migration shortlist that cognos-to-sigma can consume. Read-only — only GETs against the Cognos API.

cognos-to-sigma

Conversion

The subject of this QuickStart. Converts a single Cognos report (or a batch via shortlist) to a Sigma data model and matching workbook with verified row-level parity.

Here's how the two skills connect in a full migration — cognos-assessment hands the converter a ranked shortlist, and cognos-to-sigma produces the Sigma workbooks with a verified parity report:

Which skill for your situation

Not every migration needs both skills. Use the table below to map your scenario to the smallest set that fits.

In this QuickStart we're in the first row — one Cognos dashboard whose data module reads directly from the same Snowflake warehouse Sigma will connect to.

Your situation

Skill(s) to use

One report to migrate, warehouse already in Sigma

cognos-to-sigma only

Need to scope your full estate first

cognos-assessment → cognos-to-sigma

Unknown data model complexity

Start with cognos-assessment to surface custom-SQL and multi-fact flags before committing

Batch migration from a shortlist

cognos-assessment produces the shortlist; cognos-to-sigma consumes it

Footer

First we need to clone the skill's GitHub repository, configure Cognos REST credentials, and capture your Sigma credentials.

The two skills live in sigmacomputing/quickstarts-public under cognos-migration-skills/.

From a terminal, run each command below one at a time so you can confirm each step before moving on.

Step 1: Create a local folder for the clone

mkdir -p ~/quickstarts-public

Step 2: Move into the new folder

cd ~/quickstarts-public

Step 3: Clone the repo without pulling any files yet

git clone --filter=blob:none --sparse https://github.com/sigmacomputing/quickstarts-public.git .

Step 4: Fill in only the cognos-migration-skills folder

git sparse-checkout set cognos-migration-skills

Step 5: Symlink cognos-to-sigma into the Claude skills folder

ln -s ~/quickstarts-public/cognos-migration-skills/cognos-to-sigma ~/.claude/skills/cognos-to-sigma

Step 6: Symlink cognos-assessment

ln -s ~/quickstarts-public/cognos-migration-skills/cognos-assessment ~/.claude/skills/cognos-assessment

Steps 5 and 6 should return with no error.

divider

Step 7: Add your Sigma API credentials.
 The Cognos skill uses bootstrap.sh.

Because bootstrap.sh is non-interactive, write your Sigma API credentials directly to the shared env file it reads:

cat >> ~/.sigma-migration/env <<'EOF'
export SIGMA_BASE_URL='https://api.us-a.aws.sigmacomputing.com'
export SIGMA_CLIENT_ID='{your-client-id}'
export SIGMA_CLIENT_SECRET='{your-client-secret}'
EOF

Get SIGMA_CLIENT_ID and SIGMA_CLIENT_SECRET from Sigma under Administration > Developer Access > Create New Client Credentials (requires Admin role).

For information, see: Generate Sigma API client credentials

SIGMA_BASE_URL must match your Sigma deployment region. The value shown (https://api.us-a.aws.sigmacomputing.com) covers AWS US. To find the correct URL for your instance, see: Supported regions, data platforms, and features

divider

Step 8: Configure Cognos credentials.
 The skill authenticates to Cognos using a CA API key — a durable, headless credential that doesn't require a browser session.

8a. Generate a CA API key.

In your Cognos instance, open the user menu (top-right) and select Profile. Under the API keys section, select Create key, give it a name (e.g., sigma-migration), and copy the generated key value — it is only shown once.

8b. Set the Cognos env vars.

export COG_INSTANCE="https://{your-cognos-host}"
export COG_APIKEY="{your-ca-api-key}"

COG_INSTANCE is the base URL of your Cognos instance — the part before /api/v1 or /bi. It appears in your browser address bar when you're logged in (e.g., https://us3.ca.analytics.ibm.com).

8c. Establish the session.

eval "$(bash ~/.claude/skills/cognos-to-sigma/scripts/cognos-apikey-session.sh)"

No return is expected.

8d. Smoke-test the connection.

cog_get "/session"

A successful response returns a JSON object containing "isAnonymous":false — confirming the skill can reach Cognos and the API key is valid:

divider

Step 9: Run the environment bootstrap.
 This single command verifies that all runtime dependencies are in place (Ruby, Python 3, Node.js), installs any that are missing without requiring admin access, and writes the sentinel file the skill gates on before starting. Run it once per machine:

SIGMA_SKIP_CRED_SMOKE=1 bash ~/.claude/skills/cognos-to-sigma/scripts/bootstrap.sh

A successful run ends with:

bootstrap: COMPLETE — doctor green; sentinel written to ~/.sigma-migration/bootstrap.json.

If a runtime dependency fails to install, follow the message's suggestion (usually a Homebrew install) and rerun.

divider

Step 10: Verify Claude Code can invoke the skill.
 Type claude in your terminal to start Claude Code, then invoke the skill:

claude

/cognos-to-sigma

Claude should start reading the reference files and ask what dashboard you want to convert.

Pause at this prompt — we'll hand it everything in one shot via the kickoff prompt in the Run the Conversion section later.

Footer

Cognos tables don't appear in the data module editor

The Snowflake JDBC URL must include the database, warehouse, and schema as query parameters. Without them, Cognos connects but shows no assets. Verify your JDBC URL includes:

jdbc:snowflake://{account}.snowflakecomputing.com/?db=QUICKSTARTS&warehouse=COMPUTE_WH&schema=COGNOS_ECOMMERCE

Note the ? separator before the first parameter, & between parameters, and .snowflakecomputing.com in the account hostname (the hostname alone without that suffix will fail to resolve).

Snowflake signon fails in Cognos

Personal Snowflake accounts provisioned through SSO (Okta, Google) cannot authenticate via JDBC — only password-based accounts work. Create a dedicated Snowflake user for Cognos:

CREATE USER COGNOS_USER PASSWORD='{your-password}' DEFAULT_ROLE=SIGMA_SERVICE_ROLE;
GRANT ROLE SIGMA_SERVICE_ROLE TO USER COGNOS_USER;

Use COGNOS_USER and its password in the Cognos User ID and password signon dialog.

Logged into Cognos but can't create content

The Cognos Subscription administrator role manages users and billing — it does not grant a product seat. Check License user in addition to Subscription administrator under your user profile to enable content creation and API access.

Bootstrap credential smoke test fails

The bootstrap credential check can return a false failure even when the credentials are valid (for example, when the Sigma API endpoint resolves differently in the bootstrap probe than it does for the skill). Bypass it — the credentials are checked again during the actual token mint:

SIGMA_SKIP_CRED_SMOKE=1 bash ~/.claude/skills/cognos-to-sigma/scripts/bootstrap.sh

Validate the credentials directly if you want to confirm them before running the skill:

curl -s -X POST \
  -H "Authorization: Basic $(printf '%s:%s' "$SIGMA_CLIENT_ID" "$SIGMA_CLIENT_SECRET" | base64 | tr -d '\n')" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  "${SIGMA_BASE_URL}/v2/auth/token"

A response containing access_token confirms the credentials are valid.

cog_get smoke test returns HTTP 400 "Invalid id format"

The /content/.public_folders/items path is a /bi/v1 alias that doesn't exist in the /api/v1 surface the API key session uses. Use /session instead:

cog_get "/session"

A response containing "isAnonymous":false confirms the session is established and ready.

Footer

The demo uses four tables loaded into Snowflake — the same ecommerce dataset used across the migration skill family. Both Cognos and Sigma will query these tables directly, which is what makes the parity check meaningful.

Run the following script in Snowflake. It creates the schema, stages the source files from S3, loads the tables, and grants read access to the Sigma service role.

USE ROLE ACCOUNTADMIN;
USE WAREHOUSE COMPUTE_WH;

CREATE DATABASE IF NOT EXISTS QUICKSTARTS;
CREATE SCHEMA  IF NOT EXISTS QUICKSTARTS.COGNOS_ECOMMERCE;
USE SCHEMA QUICKSTARTS.COGNOS_ECOMMERCE;

CREATE OR REPLACE FILE FORMAT COGNOS_csv_format
  TYPE = CSV
  FIELD_DELIMITER = ','
  FIELD_OPTIONALLY_ENCLOSED_BY = '"'
  NULL_IF = ('', 'NULL')
  EMPTY_FIELD_AS_NULL = TRUE
  PARSE_HEADER = TRUE;

CREATE OR REPLACE STAGE COGNOS_ecommerce_stage
  URL = 's3://sigma-quickstarts-main/Cognos/'
  FILE_FORMAT = COGNOS_csv_format;

CREATE OR REPLACE TABLE BRAND (
  "Brand ID" NUMBER,
  "Brand"    VARCHAR
);

CREATE OR REPLACE TABLE CATEGORY (
  "Category ID" NUMBER,
  "Category"    VARCHAR
);

CREATE OR REPLACE TABLE COUNTRY (
  "Country ID" NUMBER,
  "Country"    VARCHAR
);

CREATE OR REPLACE TABLE COMMERCE (
  "Visit ID"    NUMBER,
  "Date"        DATE,
  "Brand ID"    NUMBER,
  "Category ID" NUMBER,
  "Country ID"  NUMBER,
  "Revenue"     FLOAT,
  "Quantity"    NUMBER,
  "Cost"        FLOAT,
  "Age Range"   VARCHAR,
  "Gender"      VARCHAR,
  "Condition"   VARCHAR
);

COPY INTO BRAND    FROM @COGNOS_ecommerce_stage/BRAND.csv    MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;
COPY INTO CATEGORY FROM @COGNOS_ecommerce_stage/CATEGORY.csv MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;
COPY INTO COUNTRY  FROM @COGNOS_ecommerce_stage/COUNTRY.csv  MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;
COPY INTO COMMERCE FROM @COGNOS_ecommerce_stage/COMMERCE.csv MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;

SELECT 'BRAND'    AS TBL_NAME, COUNT(*) AS ROW_COUNT FROM BRAND
UNION ALL
SELECT 'CATEGORY', COUNT(*) FROM CATEGORY
UNION ALL
SELECT 'COUNTRY',  COUNT(*) FROM COUNTRY
UNION ALL
SELECT 'COMMERCE', COUNT(*) FROM COMMERCE;

SELECT
  ROUND(SUM("Revenue"), 3) AS TOTAL_REVENUE,
  SUM("Quantity")          AS TOTAL_QUANTITY
FROM COMMERCE;

GRANT USAGE  ON DATABASE QUICKSTARTS                                  TO ROLE SIGMA_SERVICE_ROLE;
GRANT USAGE  ON SCHEMA   QUICKSTARTS.COGNOS_ECOMMERCE                 TO ROLE SIGMA_SERVICE_ROLE;
GRANT SELECT ON ALL    TABLES IN SCHEMA QUICKSTARTS.COGNOS_ECOMMERCE  TO ROLE SIGMA_SERVICE_ROLE;
GRANT SELECT ON FUTURE TABLES IN SCHEMA QUICKSTARTS.COGNOS_ECOMMERCE  TO ROLE SIGMA_SERVICE_ROLE;

The final two queries confirm the load. Expected results: 613,002 rows in COMMERCE, total revenue 39,759,625.515, total quantity 91,206.

Footer

With the Snowflake data in place, build the source dashboard in Cognos Analytics. This is the content the skill will discover and convert to Sigma.

The dashboard has six panels — two KPI tiles and four charts — built on a star-schema data module that reads from the four tables loaded in the previous section.

Create the data module

  1. In Cognos Analytics, select New > Data module.
  2. Under Select sources, choose Data servers and schemas and select the Snowflake connection you configured.
  3. Navigate to QUICKSTARTS > COGNOS_ECOMMERCE and select all four tables: BRAND, CATEGORY, COMMERCE, and COUNTRY. Select OK.
  4. In the data module editor, create the star-schema relationships — COMMERCE is the fact table:
    • COMMERCE."Brand ID" → BRAND."Brand ID"
    • COMMERCE."Category ID" → CATEGORY."Category ID"
    • COMMERCE."Country ID" → COUNTRY."Country ID"

  1. Add a calculated column for year. In the module tree, right-click COMMERCE and select Calculation. Name it Year and enter the expression:
year(Date_)
  1. Save the data module as eCommerce Data Module.

Build the dashboard

  1. Select New > Dashboard.
  2. When prompted for a source, select eCommerce Data Module.
  3. Choose a blank template. Rename the default tab to Commerce.
  4. Build the six panels below. For each, drag fields from the data panel onto the canvas and set the visualization type and field assignments from the toolbar.

Panel 1 — Revenue KPI

Panel 2 — Quantity KPI

Panel 3 — Revenue by Country

Panel 4 — Quantity by Category

Panel 5 — Revenue by Category

Panel 6 — Revenue by YEAR

  1. Save the dashboard as Commerce Dashboard.

The completed dashboard should show Revenue 39.8M and Quantity 91.2K with country, category, and year breakdowns matching the screenshot in the Overview:

Footer

The skill lands workbooks in a Sigma folder. Create a dedicated folder now so the output is organized from the start.

In Sigma, navigate to Home and create a new folder named Cognos Migration. Copy the folder's ID from the URL — you'll pass it to the skill in the next section.

The folder ID appears in the URL after /folder/:

https://app.sigmacomputing.com/{your-org}/folder/{your-folder-id}

Footer

With credentials configured and the demo dashboard built, run the converter. Open Claude Code and invoke the skill with the kickoff prompt below — substituting your dashboard ID, connection ID, and folder ID.

Select option 4. Something else:

Find your Cognos dashboard ID

Open the Commerce Dashboard in Cognos and copy the content ID from the browser URL — it is the long alphanumeric value that begins with i (e.g., i20CF97EDA4FC43498424E42A24835D16).

Kickoff prompt

Replace the placeholder values before running:

Run /cognos-to-sigma on the following. Walk every phase in SKILL.md end-to-end and stop only if a hard gate fails.

Cognos
- COG_INSTANCE and COG_APIKEY are already exported in this shell (run Step 8 first)
- Dashboard ID: {your-dashboard-id}

Warehouse — same on both sides
- Cognos reads from Snowflake via data module — database QUICKSTARTS, schema COGNOS_ECOMMERCE
- Sigma reads from Snowflake — same schema QUICKSTARTS.COGNOS_ECOMMERCE

Sigma
- SIGMA_API_TOKEN = mint from ~/.sigma-migration/env
- SIGMA_CONNECTION_ID: {your-snowflake-connection-id}
- SIGMA_FOLDER_ID: {your-folder-id}

Options
- Name prefix: Cognos Demo
- Auto-approve mid-pipeline questions: yes
- Parity: data should match exactly since both sides read from the same warehouse. Report any deltas.

Don't declare GREEN until the parity gate passes and the visual-QA loop passes.

The skill runs through five phases: Discover → Translate → Build → Verify → Report. Each phase emits a progress summary — watch for any WARN or MANUAL flags, which land on the gap list rather than stopping the run.

Footer

When the skill completes, it prints a migration summary — the count of visualizations converted, any items flagged for manual review, and the parity result:

The Sigma workbook

Open the workbook in your Sigma folder and compare it against the source Cognos dashboard. The layout mirrors the source, and each visualization is backed by the translated formula.

The Sigma data model

The skill also creates a data model in the same folder — the tables, joins, and calculated columns derived from the Cognos data module.

The gap list

Any visualization or expression the skill couldn't auto-translate lands in the gap list — with the source expression, the reason it was flagged, and a suggested Sigma equivalent where one exists. Work through the list to finish the migration.

Footer

We converted a Cognos dashboard to a verified Sigma workbook without rebuilding the data model by hand. The credential setup and kickoff prompt you used here work for any Cognos dashboard on a paid instance — same pattern, different content ID.

The part of the migration that usually takes days is the data module — mapping query subjects to warehouse tables, carrying over joins, translating Cognos expressions to Sigma formulas. The skill handles that automatically and surfaces anything it couldn't convert on the gap list, so you know exactly what needs a manual pass before calling it done.

The parity gate provides proof. Because Sigma and Cognos both query the same Snowflake tables, any number mismatch is a translation error — not a data difference. GREEN means the migration is done. Short of GREEN, the gap list tells you why.

When you're ready to scale, run cognos-assessment across the full estate first. It ranks each artifact by migration complexity against what the converter can actually handle, so you can shortlist the high-value, low-effort content before committing to a full run.

Additional Resource Links

Blog
Community
Help Center
QuickStarts

Be sure to check out all the latest developments at Sigma's First Friday Feature page!

   

Footer