Provide stepMetadata to steps through IntegrationStepExecutionContext

Fix stepMetadata field placement and propagate

Clearly there needs to be a better test for this...

Add a test to ensure stepMetadata reaches execution handler

Author: aiwilliams

packages/integration-sdk-cli/src/__tests__/cli.test.ts

@@ -509,6 +509,11 @@ describe('collect/visualize integration', () => {
   });
 });
 
+test('custom context and config types', async () => {
+  loadProjectStructure('typeScriptCustomConfigsProject');
+  await createCli().parseAsync(['node', 'j1-integration', 'collect']);
+});
+
 describe('document', () => {
   test('loads the integration with entities and relationships and writes documentation results', async () => {
     await documentCommandSnapshotTest('docsInstanceWithRelationships');

packages/integration-sdk-core/src/types/context.ts

@@ -1,6 +1,7 @@
 import { IntegrationInstance, IntegrationInstanceConfig } from './instance';
 import { JobState } from './jobState';
 import { IntegrationLogger } from './logger';
+import { StepMetadata } from './step';
 
 export type Execution = {
   startedOn: number;
@@ -24,7 +25,7 @@ export interface ExecutionContext {
  * `IntegrationInstanceConfig`, containing dynamic values perhaps calculated
  * based on the instance config.
  */
-export type IntegrationExecutionConfig = object;
+export type IntegrationExecutionConfig = Record<string, any>;
 
 /**
  * @param TInstanceConfig the integration specific type of the `instance.config`
@@ -51,6 +52,7 @@ export type IntegrationExecutionContext<
 
 export type StepExecutionContext = ExecutionContext & {
   jobState: JobState;
+  stepMetadata: StepMetadata;
 };
 
 /**

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptCustomConfigsProject/.env

@@ -0,0 +1 @@
+MY_INSTANCE_CONFIG_FIELD=myInstanceConfigFieldValue

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptCustomConfigsProject/.gitignore

@@ -0,0 +1 @@
+.j1-integration

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptCustomConfigsProject/src/config.ts

@@ -0,0 +1,45 @@
+import {
+  IntegrationExecutionConfig,
+  IntegrationExecutionContext,
+  IntegrationInstanceConfig,
+  IntegrationStepExecutionContext,
+} from '@jupiterone/integration-sdk-core';
+
+export interface CustomInstanceConfig extends IntegrationInstanceConfig {
+  myInstanceConfigField: string;
+}
+
+export interface CustomExecutionConfig extends IntegrationExecutionConfig {
+  myExecutionConfigField: string;
+}
+
+export type CustomExecutionContext = IntegrationExecutionContext<
+  CustomInstanceConfig,
+  CustomExecutionConfig
+>;
+
+export interface CustomStepExecutionContext
+  extends IntegrationStepExecutionContext<
+    CustomInstanceConfig,
+    CustomExecutionConfig
+  > {
+  myStepExecutionContextField: string;
+}
+
+export function validateInvocation(context: CustomExecutionContext) {
+  if (
+    context.instance.config.myInstanceConfigField !==
+    'myInstanceConfigFieldValue'
+  )
+    throw new Error('Invalid instance config');
+}
+
+export function loadExecutionConfig(options: {
+  config: CustomInstanceConfig;
+}): CustomExecutionConfig {
+  if (options.config.myInstanceConfigField !== 'myInstanceConfigFieldValue')
+    throw new Error('Invalid instance config');
+  return {
+    myExecutionConfigField: 'myExecutionConfigFieldValue',
+  };
+}

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptCustomConfigsProject/src/index.ts

@@ -0,0 +1,23 @@
+import { IntegrationInvocationConfig } from '@jupiterone/integration-sdk-core';
+import {
+  CustomExecutionConfig,
+  CustomInstanceConfig,
+  loadExecutionConfig,
+  validateInvocation,
+} from './config';
+import step from './steps';
+
+export const invocationConfig: IntegrationInvocationConfig<
+  CustomInstanceConfig,
+  CustomExecutionConfig
+> = {
+  instanceConfigFields: {
+    myInstanceConfigField: {
+      mask: true,
+      type: 'string',
+    },
+  },
+  integrationSteps: [step],
+  validateInvocation,
+  loadExecutionConfig,
+};

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptCustomConfigsProject/src/steps.ts

@@ -0,0 +1,70 @@
+import {
+  createIntegrationEntity,
+  IntegrationStep,
+} from '@jupiterone/integration-sdk-core';
+import {
+  CustomExecutionConfig,
+  CustomInstanceConfig,
+  CustomStepExecutionContext,
+} from './config';
+
+const stepId = 'step-id';
+const stepName = 'Step Name';
+const entities = [
+  {
+    resourceName: 'The Account',
+    _type: 'my_account',
+    _class: 'Account',
+  },
+];
+const relationships = [];
+
+const step: IntegrationStep<CustomInstanceConfig, CustomExecutionConfig> = {
+  id: stepId,
+  name: stepName,
+  entities,
+  relationships,
+
+  executionHandler: async (context: CustomStepExecutionContext) => {
+    const { instance, jobState, executionConfig, stepMetadata } = context;
+
+    if (
+      context.myStepExecutionContextField != 'myStepExecutionContextFieldValue'
+    )
+      throw new Error('Invalid step execution context');
+
+    if (
+      executionConfig.myExecutionConfigField !== 'myExecutionConfigFieldValue'
+    )
+      throw new Error('Invalid execution config');
+
+    if (instance.config.myInstanceConfigField !== 'myInstanceConfigFieldValue')
+      throw new Error('Invalid instance config');
+
+    if (stepMetadata.id != stepId) throw new Error('Invalid step metadata');
+    if (stepMetadata.name != stepName) throw new Error('Invalid step metadata');
+    if (stepMetadata.entities != entities)
+      throw new Error('Invalid step metadata');
+    if (stepMetadata.relationships != relationships)
+      throw new Error('Invalid step metadata');
+
+    await jobState.addEntities([
+      createIntegrationEntity({
+        entityData: {
+          source: {
+            id: '1234',
+            name: instance.config.myInstanceConfigField,
+            description: executionConfig.myExecutionConfigField,
+          },
+          assign: {
+            _key: 'account:1234',
+            _type: 'my_account',
+            _class: 'Account',
+          },
+        },
+      }),
+    ]);
+  },
+};
+
+export default step;

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptIntegrationProject/src/index.ts

@@ -3,8 +3,9 @@ import fetchUsers from './steps/fetchUsers';
 
 import validateInvocation from './validateInvocation';
 import getStepStartStates from './getStepStartStates';
+import { IntegrationInvocationConfig } from '@jupiterone/integration-sdk-core';
 
-export const invocationConfig = {
+export const invocationConfig: IntegrationInvocationConfig = {
   instanceConfigFields: {
     myConfig: {
       mask: true,

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptIntegrationProject/src/steps/fetchUsers.ts

@@ -1,7 +1,7 @@
 import {
-  IntegrationStepExecutionContext,
-  createIntegrationEntity,
   createDirectRelationship,
+  createIntegrationEntity,
+  IntegrationStepExecutionContext,
   Step,
   StepExecutionContext,
 } from '@jupiterone/integration-sdk-core';
@@ -25,9 +25,7 @@ const fetchUsersStep: Step<StepExecutionContext> = {
       targetType: 'my_user',
     },
   ],
-  executionHandler: async ({
-    jobState,
-  }: IntegrationStepExecutionContext<{}>) => {
+  executionHandler: async ({ jobState }: IntegrationStepExecutionContext) => {
     await jobState.addEntities([
       createIntegrationEntity({
         entityData: {

packages/integration-sdk-private-test-utils/__fixtures__/typeScriptIntegrationProject/src/validateInvocation.ts

@@ -1,3 +1,7 @@
-export default function validateInvocation() {
-  return 'loaded';
+import { IntegrationExecutionContext } from '@jupiterone/integration-sdk-core';
+
+export default function validateInvocation(
+  _context: IntegrationExecutionContext,
+) {
+  // no problem-o
 }