Add aws generate runbook link action (#1563)

rSnapkoOpenOps · Copilot · MarceloRGonc · web-flow · commit 3885cbeb33e0 · 2025-11-05T14:02:45.000+01:00
Part of OPS-2931. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Marcelo Gonçalves <marcelo@openops.com>
diff --git a/packages/blocks/aws/src/index.ts b/packages/blocks/aws/src/index.ts
@@ -23,6 +23,7 @@ import { rdsDeleteInstanceAction } from './lib/actions/rds/rds-delete-instance-a
 import { rdsDeleteSnapshotAction } from './lib/actions/rds/rds-delete-snapshot-action';
 import { rdsGetInstancesAction } from './lib/actions/rds/rds-describe-instances-action';
 import { rdsGetSnapshotsAction } from './lib/actions/rds/rds-describe-snapshots-action';
+import { ssmGenerateRunbookLinkAction } from './lib/actions/ssm/ssm-generate-runbook-link-action';
 
 export const aws = createBlock({
   displayName: 'AWS',
@@ -53,6 +54,7 @@ export const aws = createBlock({
     rdsCreateSnapshotAction,
     rdsDeleteSnapshotAction,
     addTagsAction,
+    ssmGenerateRunbookLinkAction,
     awsCliAction,
   ],
   triggers: [],
diff --git a/packages/blocks/aws/src/lib/actions/ssm/ssm-generate-runbook-link-action.ts b/packages/blocks/aws/src/lib/actions/ssm/ssm-generate-runbook-link-action.ts
@@ -0,0 +1,69 @@
+import { createAction, Property } from '@openops/blocks-framework';
+import {
+  amazonAuth,
+  DocumentOwner,
+  generateBaseSSMRunbookExecutionLink,
+  generateSSMRunbookExecutionParams,
+  runbookNameProperty,
+  runbookParametersProperty,
+  runbookVersionProperty,
+} from '@openops/common';
+import { RiskLevel } from '@openops/shared';
+
+export const ssmGenerateRunbookLinkAction = createAction({
+  auth: amazonAuth,
+  name: 'ssm_generate_runbook_execution_link',
+  description:
+    'Generate an AWS Console link to execute an SSM Automation Runbook',
+  displayName: 'Generate Runbook Execution Link',
+  isWriteAction: false,
+  riskLevel: RiskLevel.LOW,
+  props: {
+    region: Property.ShortText({
+      displayName: 'Region',
+      description: 'AWS region (defaults to the region from authentication).',
+      required: false,
+    }),
+    owner: Property.StaticDropdown({
+      displayName: 'Owner',
+      description: 'Source/owner of the runbook (Automation document).',
+      required: true,
+      options: {
+        options: [
+          { label: 'Owned by Amazon', value: DocumentOwner.Amazon },
+          { label: 'Owned by me', value: DocumentOwner.Self },
+          { label: 'Shared with me', value: DocumentOwner.Private },
+          { label: 'Public', value: DocumentOwner.Public },
+          { label: 'Third Party', value: DocumentOwner.ThirdParty },
+          { label: 'All runbooks', value: DocumentOwner.All },
+        ],
+      },
+      defaultValue: DocumentOwner.Private,
+    }),
+    runbook: runbookNameProperty,
+    version: runbookVersionProperty,
+    parameters: runbookParametersProperty,
+  },
+  async run({ propsValue, auth }) {
+    const { runbook, version, parameters, region } = propsValue;
+    const awsRegion = region || auth.defaultRegion;
+
+    if (!runbook) {
+      throw new Error('Runbook is required');
+    }
+
+    const base = generateBaseSSMRunbookExecutionLink(
+      awsRegion,
+      runbook,
+      version,
+    );
+
+    const fragment = generateSSMRunbookExecutionParams(
+      (parameters as Record<string, unknown>) || {},
+    );
+
+    return {
+      link: `${base}${fragment}`,
+    };
+  },
+});
diff --git a/packages/blocks/aws/test/index.test.ts b/packages/blocks/aws/test/index.test.ts
@@ -21,7 +21,7 @@ describe('block declaration tests', () => {
   });
 
   test('should return block with correct number of actions', () => {
-    expect(Object.keys(aws.actions()).length).toBe(22);
+    expect(Object.keys(aws.actions()).length).toBe(23);
     expect(aws.actions()).toMatchObject({
       ebs_get_volumes: {
         name: 'ebs_get_volumes',
@@ -103,6 +103,10 @@ describe('block declaration tests', () => {
         name: 'ec2_get_instances',
         requireAuth: true,
       },
+      ssm_generate_runbook_execution_link: {
+        name: 'ssm_generate_runbook_execution_link',
+        requireAuth: true,
+      },
       aws_cli: {
         name: 'aws_cli',
         requireAuth: true,
diff --git a/packages/blocks/aws/test/ssm/ssm-generate-runbook-link-action.test.ts b/packages/blocks/aws/test/ssm/ssm-generate-runbook-link-action.test.ts
@@ -0,0 +1,146 @@
+import { ssmGenerateRunbookLinkAction } from '../../src/lib/actions/ssm/ssm-generate-runbook-link-action';
+
+type RunResult = { link: string };
+
+describe('ssmGenerateRunbookLinkAction.run', () => {
+  const auth = {
+    ...jest.requireActual('@openops/blocks-framework'),
+    defaultRegion: 'us-west-2',
+  };
+
+  test('generates base link using auth.defaultRegion when region is not provided', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth,
+      propsValue: {
+        runbook: 'AWS-RestartEC2Instance',
+      },
+    };
+
+    const result = (await ssmGenerateRunbookLinkAction.run(ctx)) as RunResult;
+
+    expect(result.link).toBe(
+      'https://us-west-2.console.aws.amazon.com/systems-manager/automation/execute/AWS-RestartEC2Instance?region=us-west-2',
+    );
+  });
+
+  test('honors explicit region override', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth: { defaultRegion: 'us-east-1' },
+      propsValue: {
+        runbook: 'My-Runbook',
+        region: 'eu-central-1',
+      },
+    };
+
+    const result = (await ssmGenerateRunbookLinkAction.run(ctx)) as RunResult;
+
+    expect(result.link).toBe(
+      'https://eu-central-1.console.aws.amazon.com/systems-manager/automation/execute/My-Runbook?region=eu-central-1',
+    );
+  });
+
+  test('includes documentVersion when provided', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth: { defaultRegion: 'ap-south-1' },
+      propsValue: {
+        runbook: 'My-Runbook',
+        version: '3',
+      },
+    };
+
+    const result = (await ssmGenerateRunbookLinkAction.run(ctx)) as RunResult;
+
+    expect(result.link).toBe(
+      'https://ap-south-1.console.aws.amazon.com/systems-manager/automation/execute/My-Runbook?region=ap-south-1&documentVersion=3',
+    );
+  });
+
+  test('encodes parameters of various types and omits empty values', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth: { defaultRegion: 'us-west-1' },
+      propsValue: {
+        runbook: 'Param-Runbook',
+        parameters: {
+          s: 'hello world',
+          n: 42,
+          b: true,
+          arrPrimitives: [1, 'a', true, null, undefined],
+          arrObjects: [{ a: 1 }, { b: 2 }],
+          obj: { key: 'value' },
+          emptyStr: '',
+          nothing: undefined,
+          nothing2: null,
+        },
+      },
+    };
+
+    const result = (await ssmGenerateRunbookLinkAction.run(ctx)) as RunResult;
+
+    expect(
+      result.link.startsWith(
+        'https://us-west-1.console.aws.amazon.com/systems-manager/automation/execute/Param-Runbook?region=us-west-1#',
+      ),
+    ).toBe(true);
+
+    const fragment = result.link.split('#')[1] as string;
+    expect(fragment).toBeDefined();
+
+    const expectedParts = [
+      's=hello%20world',
+      'n=42',
+      'b=true',
+      'arrPrimitives=%5B1%2C%22a%22%2Ctrue%2Cnull%2Cnull%5D',
+      'arrObjects=%5B%7B%22a%22%3A1%7D%2C%7B%22b%22%3A2%7D%5D',
+      'obj=%7B%22key%22%3A%22value%22%7D',
+    ];
+
+    const actualParts = fragment.split('&');
+
+    for (const forbidden of ['emptyStr', 'nothing', 'nothing2']) {
+      expect(
+        actualParts.some((part) =>
+          part.startsWith(`${encodeURIComponent(forbidden)}=`),
+        ),
+      ).toBe(false);
+    }
+
+    for (const part of expectedParts) {
+      expect(actualParts).toContain(part);
+    }
+  });
+
+  test('encodes special characters in param keys and values', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth: { defaultRegion: 'eu-west-3' },
+      propsValue: {
+        runbook: 'RB',
+        parameters: {
+          'key with space': 'value/with?special&chars',
+        },
+      },
+    };
+
+    const result = (await ssmGenerateRunbookLinkAction.run(ctx)) as RunResult;
+
+    expect(result.link).toBe(
+      'https://eu-west-3.console.aws.amazon.com/systems-manager/automation/execute/RB?region=eu-west-3#key%20with%20space=value%2Fwith%3Fspecial%26chars',
+    );
+  });
+
+  test('throws when runbook is missing', async () => {
+    const ctx = {
+      ...jest.requireActual('@openops/blocks-framework'),
+      auth: { defaultRegion: 'us-east-2' },
+      propsValue: {},
+    };
+
+    await expect(ssmGenerateRunbookLinkAction.run(ctx)).rejects.toThrow(
+      'Runbook is required',
+    );
+  });
+});
diff --git a/packages/openops/src/index.ts b/packages/openops/src/index.ts
@@ -22,6 +22,11 @@ export * from './lib/aws/rds/rds-delete-instance';
 export * from './lib/aws/rds/rds-delete-snapshot';
 export * from './lib/aws/rds/rds-describe';
 export * from './lib/aws/regions';
+export * from './lib/aws/ssm/document-owner';
+export * from './lib/aws/ssm/generate-ssm-runbook-execution-link';
+export * from './lib/aws/ssm/runbook-name-property';
+export * from './lib/aws/ssm/runbook-parameters-property';
+export * from './lib/aws/ssm/runbook-version-property';
 export * from './lib/aws/sts-common';
 export * from './lib/aws/tags/tag-resources';
 export * from './lib/aws/tags/tags';
diff --git a/packages/openops/src/lib/aws/ssm/generate-ssm-runbook-execution-link.ts b/packages/openops/src/lib/aws/ssm/generate-ssm-runbook-execution-link.ts
@@ -0,0 +1,53 @@
+const encodeParamValue = (value: unknown): string | undefined => {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === 'string') {
+    return encodeURIComponent(value);
+  }
+
+  if (Array.isArray(value)) {
+    const allPrimitives = value.every(
+      (v) =>
+        typeof v === 'string' ||
+        typeof v === 'number' ||
+        typeof v === 'boolean',
+    );
+
+    if (allPrimitives) {
+      const joined = value.map((v) => String(v)).join(', ');
+      return encodeURIComponent(joined);
+    }
+
+    return encodeURIComponent(JSON.stringify(value));
+  }
+
+  return encodeURIComponent(JSON.stringify(value));
+};
+
+export const generateBaseSSMRunbookExecutionLink = (
+  region: string,
+  runbookName: string,
+  version?: string,
+) => {
+  return `https://${region}.console.aws.amazon.com/systems-manager/automation/execute/${encodeURIComponent(
+    runbookName,
+  )}?region=${encodeURIComponent(region)}${
+    version ? `&documentVersion=${encodeURIComponent(version)}` : ''
+  }`;
+};
+
+export const generateSSMRunbookExecutionParams = (
+  parameters: Record<string, unknown>,
+) => {
+  const entries = Object.entries(parameters);
+
+  const hashParts: string[] = [];
+  for (const [key, value] of entries) {
+    const encodedValue = encodeParamValue(value);
+    if (encodedValue) {
+      hashParts.push(`${encodeURIComponent(key)}=${encodedValue}`);
+    }
+  }
+
+  return hashParts.length ? `#${hashParts.join('&')}` : '';
+};
diff --git a/packages/openops/test/aws/ssm/generate-ssm-runbook-execution-link.test.ts b/packages/openops/test/aws/ssm/generate-ssm-runbook-execution-link.test.ts
