Most Connect workflows have a set of global variables that can be referenced from any domain object. This invocation attribute gives a chance to the invoker to override some of these variables with new values for the duration and in context of this invocation only. As usual, the value can be any xCL expression or xCL string literal (with single quotes). The variable names must comply with formatting rules for a SQL Identifier. That is:

1. Variables names must start with a letter and can only contain alphanumerics or underscores.
2. They are case in-sensitive in Connect, so if you pass “V1” we will use that value where ever there are references for either “V1” or “v1”
3. Properly escaped if other characters are to be used.

onSuccess and onFailure Webhooks

Connect supports steps, pipelines as some of the containers for execution. When one of these is invoked asynchronously, the caller will want to know the current status and also whether the invocation completed successfully or resulted in a failure. Connect supports a pull model for getting the status of an invocation. That is, the caller of an invocation makes subsequent calls to a Connect invocation API to get the latest status.

This works well for a subset of use cases and allows the caller full control of the lifecycle and status gathering and allows the caller to present real time information to their users. For example, using this method, the caller can know exactly which step of a multi-step pipeline is currently being executed. This is extremely useful in giving full transparency into the Connect invocation to those applications that need it.

However, there are other applications that only want to know when an invocation completes (either in success of failure). After starting an invocation asynchronously, these applications may not want to continue polling Connect to get the latest status. They may instead want Connect to call back some API endpoint hosted by the caller when the invocation is complete and perhaps remit some status data.

To accommodate the invocation “callback” or push requirement, we support invocation “onSuccess” and “onFailure” features. The invocation caller is able to supply (at the time of invocation) commands that will be executed base on the final success or failure of the invocation. This is a generic mechanism that can be used to implement webhooks.

• In the above example, the override variables are optional, as are the onSuccess and onFailure attributes.
• Two webhook (callback) functions are available:
  • GetHttp represents a call to a URL using the HTTP method GET. For context, we will add a HTTP header with the URL of the associated invocation. e.g.
    • "Xactly-Connect-Invocation: https://connect-i1.xactlycorp.com/connect/v1/invocations/402881f055360f880155363066260064"
  • PostHttp represents a call to a URL using the POST method and an optional static text body is provided as another parameter.For context, we will add a HTTP header with the URL of the associated invocation. e.g.
    •   "Xactly-Connect-Invocation : https://connect-i1.xactlycorp.com/connect/v1/invocations/402858801553630662600645360f81f0".
  • So in the above example,  the final POST request might look like this

    • POST https://example.com/xactlyNotifyFailed HTTP/1.1 Xactly-Connect-Invocation: https://connect-i1.xactlycorp.com/connect/v1/invocations/402858801553630662600645360f81f0 Content-Type: text/plain; charset="UTF-8" Content-Length: 39 { "myCustomfield" : "myStaticValue" }

• Since the value of onSuccess and onFailure is a xCL command, their value is not limited to “webhook” function calls.
• For example, the value onSuccess or onFailure can be not only calls to some REST service, twillio, slack, etc. but also something like the xCL command ‘send email e_payfile_completed‘.
• We also support another optional parameter externalId that can be supplied at the time of invocation. This is designed to hold the reference ID (or correlation ID) that the caller wants to use to associate the caller’s context to the invocation.
• The invocation service will set the timeout and retry logic when it comes time to call the callback. If the callback can not be successfully made, details of the callback interaction can be found in the last InvocationDetail record in that Invocation object.