Order Cancel Flow

The Order Cancel Flow facilitates the processing of order cancellation plans within Omnitron. The flow retrieves a list of cancellation plans that match a specific cancellation plan status configured by the user in the flow settings. The flow operates only in an inbound mode.

Inbound order cancel flow means that the flow triggers itself at specific intervals set by the user, such as once every minute, every 1 hour, every day at midnight, every 5th day of a month, etc., to fetch eligible cancellation plans from Omnitron. It processes these plans based on the configured cancellation plan status, ensuring the correct actions are taken for each plan.

This process ensures reliable and efficient handling of order cancellations within the system, maintaining consistency and accuracy for cancellation data in Omnitron.

Order Cancel Flow Types​

• Inbound Flow: Indicates that the flow will read data from the Omnitron. A cron schedule is set up to ensure it runs, for example, every 5 minutes.

Flow Steps​

• Login Step: Handles logging into Omnitron and (if configured) the ERP system. If an error occurs during this step, the details are logged.

• Get Data From Omnitron Step: Queries are made to the Omnitron system to fetch cancellation plans matching the user-defined cancellation plan status, cancellation plan type and channel filters.

• Script Step (Optional): Transformation operations on each cancellation plan object are performed using Python, if required.

• Mapping Step (Optional): Transformation operations on each cancellation plan object are performed using the Jolt Transform library. Further details can be found at the Jolt Transform website.

• Write Data to ERP Step: The transformed cancellation plan information is sent to the ERP system.

• Custom Response Script Step: The Write Data to ERP step's input data and the ERP response for each cancellation plan are provided to a Python script one by one to check if ERP requests are successful, extra data such as sales channel of the cancellation plan or how many rejected cancellation plans does the order have etc. are provided via attributes.

• Write Data to Omnitron Step: For each successfully processed cancellation plan, the relevant updates are made in Omnitron based on the result of the Write Data to ERP Step.

• Post Script Step: Runs after the Write Data to Omnitron Step if every prior step is successful.

Detailed Flow Designer Settings​

Configuration Card​

• Omnitron API Settings

  • Domain URL: Omnitron's domain URL, Example: https://demo.omnitron.akinon.net/.

Get Data From Omnitron​

Omnitron is queried for cancellation plans matching settings in this step.

Channel Type: Specify the type of channel from which cancellation plans should be fetched. This field is required to filter the cancellation plans by the appropriate channel type.

Cancel Type: Select the type of cancellation plan to retrieve from Omnitron. Options include:

• Cancel: Fetch only cancellations.

• Refund: Fetch only refunds.

• All: Fetch both cancellations and refunds.

Cancel Status: Select the status of the cancellation plans to fetch from Omnitron. Options include:

• Waiting: Fetch cancellation plans that are awaiting processing.

• Confirmed: Fetch cancellation plans that have been confirmed.

• Completed: Fetch cancellation plans that have been fully processed. (completed type cancel status task runs with modified date filter changing based on last query time, as a result failed executions can not be retried automatically)

• Confirmation Waiting: Fetch cancellation plans awaiting confirmation.

• Order Transaction: Fetch cancellation plans associated with specific ‘return’ type Omnitron payment transactions which have no integration mapping value. For successful jobs, an omnitron integration mapping is created marking the successful delivery. All cancellation plans retrieved with this option are also considered “completed”. This option can substitute the “Completed” status for delivering fully processed cancellation plans on sales channels where Omnitron manages return transactions. When used instead of the “completed” option, cancellation plans that couldn’t be delivered to ERP by any failure can be automatically retried in the next execution, unlike the “completed” option.

Channel ID: Enter the IDs of the channels from which to fetch cancellation plans. If specifying multiple channel IDs, separate them with commas (e.g., 1,2,3). This field is, optionally, used to narrow the scope of the data to specific channels when left empty the flow will run for all omnitron channels. Channel id’s can be retrieved from Omnitron, Sales Channels screens.

Based on the above settings following query strings are used:

If cancel status is set as Waiting, Confirmed, Completed or Confirmation Waiting:

/api/v1/cancellation_plans/?status=<cancellation plan status>&sort=modified_date&limit=5&channel_type=<omnitron channel type>&modified_date__gt=2022-10-20+16:08:20.943282&channel_id__in=<omnitron channel ids>

If cancel status is set as Order Transaction:

/api/v1/order_transactions/?transaction_type=refund&related_cancellation_plan__plan_type=<cancellation plan type>&order__channel__channel_type=<omnitron channel type>&order__channel__in=<omnitron cannel ids>&mapping__isnull=true&sort=modified_date&limit=5&modified_date__gt=2024-08-22T06:15:45.000000

For Order Transaction type flows the above query is used for listing cancellation plans after listing orders for each order transaction a query is made to /api/v1/cancellation_plans to fetch related cancellation plan data.

Script Card (Optional)​

This is a base script that can be updated to enable script functionality within the process step.

Scripts can read incoming data from the inputStream, where the variable input_text contains a JSON string. This string should be parsed using Python's json library. Any outgoing data is written using the outputStream.write() method after converting the relevant Python object back into a JSON string.

Additionally, the script allows for the use of attributes, which provide supplementary information tied to the current execution process. These attributes can be freely accessed or modified throughout the script. For example, the get_attribute() function is used to read attribute values, while the session.putAttribute() method is used to write new string attribute values. Each attribute consists of a key-value pair, where the key uniquely identifies the attribute, and the value can be referenced in subsequent steps.

Attributes with keys starting with the prefix log.will be automatically logged at the end of the execution if a log file is generated, ensuring that important information is captured and available for later review.

Example Script:

import json
import traceback
from java.nio.charset import StandardCharsets
from org.apache.commons.io import IOUtils
from org.apache.nifi.processor.io import StreamCallback

def get_attribute(flow_file, attr_name):
   all_var = flow_file.getAttribute("allVar")
   if all_var:
       all_attributes = json.loads(all_var)
       return all_attributes.get(attr_name, None)
   return flow_file.getAttribute(attr_name)

class TransformCallback(StreamCallback):
   def __init__(self, flowFile):
       self.flowFile = flowFile
       self.omnitronToken = get_attribute(flowFile, "token.omnitron")
       self.erpToken = get_attribute(flowFile, "token.erp")

   def process(self, inputStream, outputStream):
       input_text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)
       input_obj = json.loads(input_text)

       # Transform content
       output_obj = self.transform(input_obj)

       # Write output content
       outputStream.write(bytearray(json.dumps(output_obj, indent=4).encode('utf-8')))
      
   def transform(self, output_obj):
       # Transform content
       return output_obj

flowFile = session.get()
if flowFile != None:
   try:
       flowFile = session.write(flowFile, TransformCallback(flowFile))
       # Finish by transferring the FlowFile to an output relationship
       session.transfer(flowFile, REL_SUCCESS)
   except:
       var = traceback.format_exc()
       session.putAttribute(flowFile, 'log.script.error', str(var))
       session.transfer(flowFile, REL_FAILURE)
   session.commit()

Script Testing: The ERP response is placed in the input field, and the script's result along with the written attributes can be viewed in the result field. When the test script is run, attributes like log.script.error will appear under the "attributes" section in the result panel and should be referenced if any exceptions occur during execution. The script's output content will be found under the result_data value.

The “+ Add Attributes” button can be used to simulate incoming, readable, attributes for the script. This feature is useful when an attribute value is read and used in the script. Note that attributes added through the button are only for testing purposes and will not be saved in the flow information—they will be removed when the page is refreshed.

Example Input: Example input can be constructed using the endpoints written in Read Data From Omnitron, the input will be a cancellation plan object, not an array of objects.

Mapping Card (Optional)​

Details can be found at the Jolt Transform website. The flow expects the following output to be a cancellation request object for each order, as the input will also be a cancellation plan of one order. Integrator uses the output of this mapping step as the body of the ERP request, therefore there is no expected data structure; the output structure of the mapping step is fully dependent on ERP requirements.

Mapping Testing: The result from the script or the response of the Omnitron request for cancellation plan data, if the script step is not used, is placed in the input field and the result of the mapping is viewed in the result field.

Write Data to Omnitron​

The finalized data from Script and/or Mapping steps is sent to ERP using configuration entered in this step. A successful request must respond with 2xx HTTP status codes.

Next State: Select the next status for the cancellation or refund after it has been successfully reported to the ERP system. Options include:

• Approved: Mark the cancellation or refund as approved.

• Confirmation Waiting: Set the status to indicate it is awaiting confirmation.

• Completed: Mark the cancellation or refund as fully processed.

• Confirmed: Mark the cancellation or refund as confirmed.

For flows with "order_transaction" or "completed" cancellation statuses (set in Read Data From Omnitron card), the "Next State" setting is ignored.

Cancellation API URL: Provide the URL endpoint for the ERP system's cancellation API. This URL will be used to send cancellation or refund requests to the ERP system.

HTTP Method: Specify the HTTP method to use for communicating with the ERP system. Options include:

• POST: Send the data using the POST method.

• GET: Update data using the GET method.

• PUT: Send data using the PUT method.

• PATCH: Send data using the PATCH method.

Custom Response Setting: Choose whether to enable custom response handling.

• True: Enable custom scripting for handling responses from the ERP system.

• False: Disable custom response handling, using default behavior instead.

Custom Response Script​

The Custom Response Script is a user-configurable template designed to process and evaluate the ERP system's response for each cancellation or refund request. It provides flexibility for users to customize the logic based on their specific requirements while maintaining default functionality. Below is the default script provided as a template in the flow and a description of its core features and customizable aspects:

import json
import traceback
from java.nio.charset import StandardCharsets
from org.apache.nifi.processor.io import StreamCallback
from org.apache.commons.io import IOUtils


class TransformCallback(StreamCallback):
    def __init__(self, flowFile):
        self.flowFile = flowFile
        # erp_response code is response status from ERP
        self.erp_response_code = flowFile.getAttribute("invokehttp.status.code")
        # relation information;
        # continue = process will be to continue result with approved or confirmation_waiting
        # failure = process will be result with the rejected
        # do_nothing = process will be nothing, and it will be trying again in to next batch
        # auth_fail = that means if response is authorization fail, it will be requested for new token and try again to send.
        self.relation = 'continue'

    def process(self, inputStream, outputStream):
        input_text = IOUtils.toString(inputStream, StandardCharsets.UTF_8)

        response_status = self.erp_response_code
        output_obj = json.loads(input_text)
        #erp response_body : output_obj.get(" log.erp.response.body")
        #erp request_body : output_obj.get(" log.erp.request.body")

        #useful attributes
        #channel_id = self.flowFile.getAttribute("channel_type")
        #rejected_count = int(self.flowFile.getAttribute("rejected_count") or 0)


        if response_status in ('401', '403'):
            self.relation = 'auth_fail'
        if not response_status.startswith('2') and response_status not in ('401', '403'):
            self.relation = 'failure'
        # Write output content
        outputStream.write(bytearray(json.dumps(output_obj).encode('utf-8')))


flowFile = session.get()
if flowFile is not None:
    try:
        content = TransformCallback(flowFile)
        flowFile = session.write(flowFile, content)
        session.putAttribute(flowFile, 'relation', str(content.relation))
        # Finish by transferring the FlowFile to an output relationship
        session.transfer(flowFile, REL_SUCCESS)
    except:
        var = traceback.format_exc()
        session.putAttribute(flowFile, 'log.custom.response.script_error', str(var))
        session.transfer(flowFile, REL_FAILURE)
    session.commit()

• The script retrieves the ERP response status code (invokehttp.status.code) to evaluate the result of the request.

  • The relation attribute is added to the FlowFile to indicate the next action.

    • Relation Definitions:

      1. continue: The cancellation or refund will proceed with the next state (e.g., approved or confirmation waiting).

      2. failure: The cancellation or refund is marked as rejected and will not proceed.

      3. do_nothing: The cancellation or refund will not be further processed in this batch and will be retried later, except for “completed” status tasks.

      4. auth_fail: Indicates an authorization failure, prompting a new token request and retry.

  • Default Attributes Available For Use:

    • invokehttp.status.code: ERP HTTP status code.

    • channel_type: The channel associated with the request (if applicable).

    • rejected_count: Tracks how many rejected cancellation plans the current order has.

  • Output:

    • relation attribute must be added to flowFile.

    • The FlowFile is transferred to the appropriate relationship (REL_SUCCESS or REL_FAILURE) based on the processing outcome.

If the ERP request is successful and the custom response script result is "continue," Omnitron will automatically update the Omnitron order by using different API endpoints, depending on the "Next State" settings:

• Approved: /api/v1/orders/{order_pk}/cancellation_approved_order/

• Conformation Waiting or Confirmed: /api/v1/cancellation_plans/{cancellation.pk}/update_status/

• Order Transaction: /api/v1/order_transactions/{order_transaction.pk}/create_mapping/

Post Script (Optional)​

This script runs with the “request_data” and “response_data” from the ERP write request after the Write Data to Omnitron step, if the Write Data to ERP step is successful and the cancellation is approved.

This script is optional, and its output is not used. It can be used for additional tasks after the order is updated in Omnitron, such as updating CRM services or performing other actions.