Updated snap-in template and documentation.

devrev-snapin-template.plain

@@ -18,6 +18,7 @@
 - The Snap-In should use The Airdrop SDK Library version "1.5.1" for handling data extraction and loading, pushing data, event-driven actions, state management, and artifact handling.
   - The documentation for the The Airdrop SDK Library is provided in the resource [airdrop_sdk_library_documentation.md](docs/airdrop_sdk_library_documentation.md).
   - Please note that 'processTask' function **only** executes task if 'processTask' function is called from a worker thread. Therefore 'processTask' function should be called from a worker thread spawned using 'Spawn' class.
+  - If the worker is written in TypeScript, it must referenced with a .ts extension, not .js.
 
 - Use snake_case for JSON keys.
 
@@ -53,6 +54,10 @@
 
 # The TypeScript Node.js application boilerplate
 
+***Non-Functional Requirements:***
+
+- Details on how The Function must be invoked are provided in the resource [Function Invocation](docs/function_invocation.mdx).
+
 ***Functional Requirements:***
 
 - Implement The Function that only checks if The Function can be invoked.

docs/airdrop_sdk_library_documentation.md

@@ -390,6 +390,8 @@ Defines the structure of events sent to external extractors from Airdrop platfor
 
   Required. An object containing:
 
+  - _function_name_: A **string** representing the name of the the function that is being invoked.
+
   - _devrev_endpoint_: A **string** representing the DevRev endpoint URL
 
 - _input_data_

docs/function_invocation.mdx

@@ -0,0 +1,61 @@
+A function can be invoked synchronously or asynchronously.
+
+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<string, string>;
+};
+
+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 need to be handled by the function
+    global_values: Record<string, string>;
+    // 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<string, string>;
+};
+
+// Event sent to our app.
+type FunctionInput = {
+    // Actual payload of the event.
+    payload: Record<string, any>;
+    // Context of the function invocation.
+    context: Context;
+    // Metadata of the function invocation.
+    execution_metadata: ExecutionMetadata;
+    input_data: InputData;
+};
+
+async function run(events: []FunctionInput): any;
+
+```
+
+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.

docs/mapping-reasons.mdx

@@ -0,0 +1,56 @@
+Airdrop uses transformation methods to map data from one data model to another. 
+These methods operate at the individual field level, transforming data field-by-field rather than entire records at once. 
+Each transformation method has specific requirements regarding the field types and data formats it can work with. 
+If the source data field does not meet these requirements for a particular transformation method, that mapping option is not available for selection during the mapping configuration process.
+
+There are several reasons why some mappings might be unavailable:
+
+1. A common reason is mismatch of types. For example, if a DevRev field is expected to be `rich_text`, 
+but the field is set as `text` mapping to some fields is unavailable. 
+2. Only references can be mapped to references. Ensure that source system fields are correctly 
+mapped to reference fields in DevRev.
+3. Support for the `struct` type is limited. Marking a field as a struct in the metadata schema will 
+make it unavailable for mapping outside of using the custom jq transformation method. 
+4. Links are supported only on works and conversations.
+
+## Transformation methods
+The following tables outline the available transformation methods categorized by their applicable field types:
+
+### Custom fields transformation methods
+
+| Method | Description | Requirements |
+|--------|-------------|-------------|
+| `make_constrained_simple_value` | Propagates validation constraints from the external system and enforces those in DevRev | - |
+| `make_enum` | Produces an enum field | External field must be of type enum |
+| `make_uenum` | Produces an enum field | External field must be of type enum |
+| `reference_custom_field` | Produces a reference field | External field must be of type reference |
+
+### Metadata extraction transformation methods
+
+| Method | Description | Requirements |
+|--------|-------------|-------------|
+| `make_custom_stages` | Makes custom stages | Requires stage diagram data in the domain metadata |
+| `map_enum` | Produces an enum field | External field must be of type enum |
+| `map_roles` | Maps permission roles from external to DevRev format | - |
+| `use_as_array_value` | Produces an array field | External field must be a scalar (single-value) |
+| `use_devrev_record` | Enables use of a fixed reference to something in DevRev | DON should be of the right type |
+| `use_directly` | Identity operator that returns exactly the input | External field must be of the same type as the DevRev field; if external field is an array, internal field must also be an array |
+| `use_fixed_value` | Produces a fixed value in DevRev | Only available for boolean or enum DevRev fields |
+
+### Custom and stock fields transformation methods
+
+| Method | Description | Requirements |
+|--------|-------------|-------------|
+| `use_rich_text` | Produces a rich text field | External field must be of type `rich_text` |
+
+### Constructed custom fields transformation methods
+
+| Method | Description | Requirements |
+|--------|-------------|-------------|
+| `construct_text_field` | Produces a text field | External field must be of type text |
+
+### Universal transformation method
+
+| Method | Description | Requirements |
+|--------|-------------|-------------|
+| `use_raw_jq` | Enables the use of `jq` to transform data | Can be used on all fields, but should be used sparingly, only if no other transformation method is available |