From c46e721de5e671b816622d49430f35e5204cce0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patricija=20Bre=C4=8Dko?= Date: Tue, 15 Jul 2025 08:59:28 +0200 Subject: [PATCH 1/3] Add docs for configuring state transitions --- docs/metadata-extraction.mdx | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/metadata-extraction.mdx diff --git a/docs/metadata-extraction.mdx b/docs/metadata-extraction.mdx new file mode 100644 index 0000000..82676a1 --- /dev/null +++ b/docs/metadata-extraction.mdx @@ -0,0 +1,88 @@ + ### Configure state transitions + + If an external record type has some concept of states, between which only certain transitions are + possible (for example, to move to the `resolved` status, an issue first has to be `in_testing`), you + can declare these in the metadata too. + + This allows creation of a matching *stage diagram* (a collection of stages and their permitted + transitions) in DevRev, which enables a much simpler import and a closer preservation of the external + data than mapping to DevRev's built-in stages. + + To declare this in the metadata, make sure the status is represented as an enum field, and then + declare the allowed transitions (which you might have to retrieve from an API at runtime, if they + are also customized): + + ```json + { + "fields": { + "status": { + "name": "Status", + "is_required": true, + "type": "enum", + "enum": { + "values": [ + { + "key": "detected", + "name": "Detected" + }, + { + "key": "mitigated", + "name": "Mitigated" + }, + { + "key": "rca_ready", + "name": "RCA Ready" + }, + { + "key": "archived", + "name": "Archived" + } + ] + } + } + }, + "stage_diagram": { + "controlling_field": "status", + "starting_stage": "detected", + "all_transitions_allowed": false, + "stages": { + "detected": { + "transitions_to": ["mitigated", "archived", "rca_ready"], + "state": "new" + }, + "mitigated": { + "transitions_to": ["archived", "detected"], + "state": "work_in_progress" + }, + "rca_ready": { + "transitions_to": ["archived"], + "state": "work_in_progress" + }, + "archived": { + "transitions_to": [], + "state": "completed" + } + }, + "states": { + "new": { + "name": "New" + }, + "work_in_progress": { + "name": "Work in Progress" + }, + "completed": { + "name": "Completed", + "is_end_state": true + } + } + } + } + ``` + + In the above example: + - The status field is the controlling field of the stage diagram. + - If a status field has no explicit transitions but you still want a stage diagram, set `all_transitions_allowed` to `true`, which creates a diagram where all the defined stages can transition to each other. + - External systems may categorize statuses (like Jira's status categories), which can be included in the diagram metadata (`states` in the example). + - The `starting_stage` defines the initial stage for new object instances. This data should always be provided if available, otherwise the starting stage is selected alphabetically. + - The order and human-readable name are taken from the enum values defined on the controlling field. + - If the `states` field is not provided, default DevRev states are used: `open`, `in_progress`, and `closed`. \ No newline at end of file From 72f67d3ad3116d1ce7156b81b98dd42ebc4cacef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patricija=20Bre=C4=8Dko?= Date: Wed, 16 Jul 2025 12:54:19 +0200 Subject: [PATCH 2/3] Update function_invocation and sdk reference docs --- docs/airdrop_sdk_library_documentation.md | 5 ++- docs/function_invocation.mdx | 55 +++-------------------- 2 files changed, 9 insertions(+), 51 deletions(-) diff --git a/docs/airdrop_sdk_library_documentation.md b/docs/airdrop_sdk_library_documentation.md index 17b8259..776d150 100644 --- a/docs/airdrop_sdk_library_documentation.md +++ b/docs/airdrop_sdk_library_documentation.md @@ -363,8 +363,9 @@ Defines the structure of events sent to external extractors from Airdrop platfor Required. An object containing: - _secrets_: An object containing: - - _service_account_token_: A **string** representing the DevRev authentication token for Airdrop platform - - _snap_in_version_id_: A **string** representing the version ID of the snap-in + - _service_account_token_: Required. A **string** representing the DevRev authentication token for Airdrop platform + - _snap_in_version_id_: Required. A **string** representing the version ID of the snap-in + - _snap_in_id_: Required. A **string** representing the snap-in ID. - _payload_ diff --git a/docs/function_invocation.mdx b/docs/function_invocation.mdx index 6c21abf..4f6889d 100644 --- a/docs/function_invocation.mdx +++ b/docs/function_invocation.mdx @@ -1,52 +1,9 @@ -A function can be invoked synchronously or asynchronously. +The function is invoked by the runner.ts file. + +Runner.ts processes events of type "any", which are basically events of type "AirdropEvent" with some additional fields, and passes the events to the function. You can ignore the additional fields. + You need to implement the run method in your function. The run method is called when the function is invoked. The run method signature is defined below: ```typescript -type Context = { - // ID of the dev org for which the function is being invoked. - dev_oid: string; - // ID of the automation/command/snap-kit Action/Event Source for which the function is being invoked. - source_id: string; - // ID of the snap-in as part of which the function is being invoked. - snap_in_id: string; - // ID of the snap-in Version as part of which the function is being invoked. - snap_in_version_id: string; - // ID of the service account. - service_account_id: string; - // This secrets map would contain some secrets which platform would provide to the snap-in. - // `service_account_token`: This is the token of the service account which belongs to this snap-in. This can be used to make API calls to DevRev. - // `actor_session_token`: For commands, and snap-kits, where the user is performing some action, this is the token of the user who is performing the action. - secrets: Record; -}; -type ExecutionMetadata = { - // A unique id for the function invocation. Can be used to filter logs for a particular invocation. - request_id: string; - // Function name as defined in the manifest being invoked. - function_name: string; - // Type of event that triggered the function invocation as defined in manifest. - event_type: string; - // DevRev endpoint to which the function can make API calls. - // Example : "https://api.devrev.ai/" - devrev_endpoint: string; -}; -type InputData = { - // Map of organization inputs and their corresponding values stored in snap-in. - // The values are passed as string and typing needs to be handled by the function - global_values: Record; - // Map of event sources and their corresponding ids stored in snap-in. - // These could be used to schedule events on a schedule based event source. - event_sources: Record; -}; -// Event sent to our app. -type FunctionInput = { - // Actual payload of the event. - payload: Record; - // Context of the function invocation. - context: Context; - // Metadata of the function invocation. - execution_metadata: ExecutionMetadata; - input_data: InputData; -}; -async function run(events: []FunctionInput): any; +async function run(events: []AirdropEvent): void; ``` -As of now, it's safe to assume that only one event is passed to the function at a time. The function can be invoked multiple times for multiple events. -The value returned from the `run` method is passed back in synchronous execution modes, such as commands, snap kit actions, and event source synchronous execution. In asynchronous execution modes, such as automation execution, the return value is ignored. +As of now, it's safe to assume that only one event is passed to the function at a time. The function can be invoked multiple times for multiple events. \ No newline at end of file From 0452bf145de8a25c6bc98f02e36082d0cde74cc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patricija=20Bre=C4=8Dko?= Date: Wed, 16 Jul 2025 13:52:26 +0200 Subject: [PATCH 3/3] Update docs/function_invocation.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/function_invocation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/function_invocation.mdx b/docs/function_invocation.mdx index 4f6889d..87468a7 100644 --- a/docs/function_invocation.mdx +++ b/docs/function_invocation.mdx @@ -1,6 +1,6 @@ The function is invoked by the runner.ts file. -Runner.ts processes events of type "any", which are basically events of type "AirdropEvent" with some additional fields, and passes the events to the function. You can ignore the additional fields. +runner.ts processes events of type "any", which are basically events of type "AirdropEvent" with some additional fields, and passes the events to the function. You can ignore the additional fields. You need to implement the run method in your function. The run method is called when the function is invoked. The run method signature is defined below: ```typescript