Develop and manage OPUS Actions

Use a clear and descriptive name that identifies the purpose of an OPUS Action. Use a consistent naming structure to make related OPUS Actions easier to identify and manage, especially when multiple OPUS Actions use the same event.

For example:

• updateStatusOnInvoiceApproval

• validateProductNameOnCreate

Keep the name concise. Use the Description field to provide additional information about the Action's purpose.

An OPUS Action uses a JavaScript function that receives the execution context through the ctx object.

A basic OPUS Action uses the following structure:

function execute(ctx) {
    ctx.log.info('Processing Action');

    return {
        success: true,
        response: '',
        errorString: ''
    };
}
execute

The action returns the following values:

• success – Indicates whether the action succeeded.

• response – Contains response information.

• errorString – Contains error information when processing fails.

Use the ctx object to access runtime information and APIs available to the action.

Tip

• Keep each OPUS Action focused on a specific business responsibility. Smaller actions are easier to test, troubleshoot, and reuse.

The ctx object provides runtime information and APIs to an OPUS Action.

Use the following properties to access event information and perform the required action logic.

The event payload contains information supplied by the event that triggered the OPUS Action.

Access the event payload through:

ctx.opusEventPayload

The payload structure depends on the configured event:

• A POST_TRANSITION payload typically represents the object after the workflow transition.

• A POST_OPERATION payload represents information returned by the completed operation.

Do not assume that every event provides the same payload structure. Inspect the payload before using specific fields.

For example:

function execute(ctx) {
    ctx.log.debug(
        JSON.stringify(ctx.opusEventPayload)
    );

    return {
        success: true,
        response: '',
        errorString: ''
    };
}
execute

Use ctx.api.gql.execute(...) to call supported GraphQL APIs from an OPUS Action.

Use GraphQL APIs to:

• Add data in another OPUS app.

• Edit related records.

• Perform cross-app automation.

For example:

var gqlResponse = ctx.api.gql.execute(
    ctx,
    `mutation {
        ...
    }`,
    null,
    null
);

Some API calls might require routing or business-object context that differs from the event context.

Create header overrides using:

var headersOverride = ctx.api.newHeadersOverride();

Supported values might include:

• processNetworkId

• partnerNetworkNodeId

• businessObject

• baseObjectType

For example:

var headersOverride = ctx.api.newHeadersOverride();
headersOverride.processNetworkId = ctx.envVars.targetProcessNetwork;
headersOverride.businessObject = 'PurchaseOrder';

Use ctx.api.sendEvent(...) to send an event from an OPUS Action.

Use the following structure:

ctx.api.sendEvent( ctx, eventName, applicationName, requestPayload, headersOverride )

Use this method when downstream processing is event-driven rather than handled through a direct API call.

For example:

function execute(ctx) {
    var response = ctx.api.sendEvent(
        ctx,
        'target-event',
        'target-application',
        JSON.stringify({
            id: 'example-id'
        }),
        null
    );

    return {
        success: response.success,
        response: response.response,
        errorString: response.errorString
    };
}
execute

Use ctx.api.agent.invoke(...) to explicitly invoke the configured agent from an OPUS Action.

For example:

function execute(ctx) { var response = ctx.api.agent.invoke( ctx, 'Validate Product Name' ); ctx.log.info(JSON.stringify(response)); return response; } execute

In this example, Validate Product Name is the name of the Objective for the Agent.

Tip

• An agent binding does not automatically invoke the agent. The JavaScript must explicitly call the Agent API.

Multiple OPUS Actions can use the same OPUS event.

For example, the same event can trigger:

• One action that edits related data.

• Another action that invokes an agent.

• Another action that sends information to another app.

Each OPUS Action must independently match its configured binding. Configure multiple actions for the same event and binding.

Tip

• Keep each OPUS Action focused on a specific business responsibility. This makes related actions easier to test and troubleshoot.

When multiple matching OPUS Actions use the same Event, OPUS executes them by binding level in the following order:

• SOLUTION

• PROCESS_NETWORK

• AGENT

For example, consider an event with two matching Solution-bound Actions, one Process Network-bound Action, and one Agent-bound Action. The Solution Actions execute first. The Process Network Action executes next, followed by the Agent Action.

Actions that use the same binding execute in parallel. Their execution order is not guaranteed.

Tip

• Do not design actions that depend on a specific execution order between actions using the same binding.

An unhandled error in an OPUS Action might prevent remaining actions associated with the same event from executing. Use appropriate error handling and logging when multiple actions depend on the same event.

For a POST_OPERATION event, the underlying business operation completes before the OPUS Action executes. If the action subsequently fails, the completed business operation remains successful. The action failure does not roll back the business operation.

Tips

• Check downstream API responses for failures.

• Use logging to diagnose action failures.

• Test related actions that use the same event.

• Do not rely on a specific execution order for actions using the same binding.