/
Pulse Migration Package CLI Utility Guide

Pulse Migration Package CLI Utility Guide

Execute Pulse Migration Package via Script (CLI Utility)

This page describes a Node.js-based command-line utility that imports Pulse migration packages and, optionally, executes them against a target environment/service. It is suitable for non-interactive pipelines and repeatable deployment workflows.

Useful when you need to: run imports unattended, enforce consistent parameters across environments, and integrate package deployment steps into CI/CD.

Overview

The utility automates Pulse UI actions using Playwright to perform two modes:

  • Import-only: Uploads a migration package into Pulse without executing it.

  • Import + Execute: Imports the package and triggers execution for a specified environment and service.

Future maintenance may replace UI automation with direct Pulse API calls once suitable endpoints are standardized.

Prerequisites

  • Node.js v14 or later installed on the machine executing the script.

  • npm available to install project dependencies.

  • Network connectivity from the execution host to the Pulse web application URL.

  • Pulse permissions to import and (if enabled) execute migration packages for the target environment and service.

Download and Installation

  1. Download the latest utility zip

  2. If the file name ends with .zip.txt, rename it to end with .zip.

  3. Extract the archive to a working directory on the execution host.

  4. From the extracted folder, install dependencies:

  5. Run npm install to fetch Node.js modules, including Playwright.

Configuration

Set behavior through environment variables or a local configuration mechanism used by the utility.

  • PULSE_AUTHENTICATION_TYPE: WIN_SSO, AUTO or BASIC. Determines how the utility authenticates with Pulse.

  • ALLOW_EXECUTION: true or false. Controls whether the package is only imported or also executed after import.

Usage

Import-only

When ALLOW_EXECUTION=false, provide a single argument: the path to the package file (.zip).

node index.js C:/packages/your-package.zip

The utility authenticates to Pulse and uploads the package for later execution via the UI or another automated step.

Import + Execute

When ALLOW_EXECUTION=true, provide four arguments in order:

  1. TARGET_ENVIRONMENT: Pulse environment name/label.

  2. TARGET_SERVICE_NAME: TM1 service (instance) name.

  3. PULSE_PACKAGE_NAME: Display name of the migration package in Pulse.

  4. PULSE_PACKAGE_FILE: Filesystem path to the .zip package file.

node index.js <TARGET_ENVIRONMENT> <TARGET_SERVICE_NAME> <PULSE_PACKAGE_NAME> <PULSE_PACKAGE_FILE>

On success, the utility will authenticate, import the package, locate the environment and service, and trigger execution.

Parameter Reference

Parameter

Type / Example

When Required

Notes

Parameter

Type / Example

When Required

Notes

PULSE_AUTHENTICATION_TYPE

Enum (WIN_SSO | AUTO | BASIC)

Always

Determines login mechanism used by Playwright automation.

ALLOW_EXECUTION

Boolean (true | false)

Always

Controls mode: import-only vs import + execute.

<TARGET_ENVIRONMENT>

String (e.g., DEV)

Required if ALLOW_EXECUTION=true

Must exactly match the environment label in Pulse.

<TARGET_SERVICE_NAME>

String (e.g., PlanningSample)

Required if ALLOW_EXECUTION=true

TM1 instance name as registered in Pulse.

<PULSE_PACKAGE_NAME>

String (e.g., CoreUpdate_1.4.2)

Required if ALLOW_EXECUTION=true

Display name shown in the Pulse package list.

<PULSE_PACKAGE_FILE>

Path (e.g., C:/packages/pkg.zip)

Always

Must be accessible to the execution host; used for import in both modes.

Logging and Troubleshooting

  • Console output: The utility logs high-level steps (authenticate, import, execute). Capture stdout/stderr in your pipeline for diagnostics.

  • Playwright traces: Enable Playwright tracing or headed mode if UI element selection fails due to Pulse UI differences or latency.

  • Permissions: Verify the Pulse account can import and execute on the target environment/service if you see authorization errors.

  • Package validity: Ensure the .zip is a valid Pulse migration package created/exported from a compatible Pulse version.

Security Considerations

  • Credentials handling: For BASIC or AUTO modes that require credentials, store secrets in your CI/CD secret store and pass via environment variables rather than command-line arguments.

  • Windows SSO: When using WIN_SSO, ensure the execution context (service account or signed-in user) has appropriate AD and Pulse permissions.

  • Least privilege: Grant only the minimum roles in Pulse necessary to import/execute packages for the intended environments.

Maintenance Notes

  • Playwright dependency: The current implementation drives the Pulse web UI. Keep Playwright browsers updated via npm and review selectors if Pulse UI changes.

  • Potential API approach: A future iteration may replace UI automation with direct Pulse API calls for import and execution to reduce fragility and external dependencies.

Related Links