Workflow Steps

The Step Listing

Workflows are represented as a series of steps (see ‘Getting Started 3. Connecting Steps’ from the examples library).  Step headers in blue are initiators, and are executed first when the workflow is run.  

Step headers in green are dependant steps and may or may not be executed depending on the specific routing logic built into the workflow.

Step headers in red are steps which have produced errors when executed.  These can happen for a variety of reasons, including omitted required values, data type mismatches (ie, a string instead of an integer), or a failure to find an appropriate route in from the Conditions & Routes section.

Step headers in red also display a ‘view response’ link on the right-hand side.  This can be clicked to bring up a window which shows what the API service is responding with.  This can be very helpful in debugging. Also, turning on Debug Mode can show the full logical pathway of the ACP Workflow.

A new step can be added by using the ‘Add New Step’ form at the top of the screen.  Select the connector you want to use, then the API Endpoint Family, then the specific API Endpoint you are interested in.  

Steps can be removed from a Workflow by clicking the ‘x’ button on the far right of their entry.

Steps can be re-ordered by using the arrow buttons on the left of their entry.

The output section is required cannot be removed.  An ACP workflow must have at least one step in addition to the output section.

Anatomy of a Step

Clicking on any step header will expand the step to a long list of step details, separated into sections.

The first section is ‘General Options,’ and it contains a field where you can add a description of what the step is trying to accomplish.  You can also customize the name of the step, and there is a ‘test step’ button which will attempt to run this single API call in isolation.  This is useful for debugging.

The second section is ‘iteration options,’ which deals with how to loop over array responses.  This section will be covered in more detail later.

The third section is for ‘Required Inputs.’  These are the variables that must be set for the API call to proceed.  This section is not always present, as not all API calls have required parameters.

The fourth section is for ‘Optional Inputs,’ which are those parameters that the API call might make use of which are not explicitly required.  Some APIs are flexible and allow you to add additional optional parameters. To allow for this, the ‘add input’ button will allow you to define an additional optional input to complete the API call.

Both types of inputs have a small green ‘?’ next to their name which will supply help text as to what that parameter does.  For more details, see the official API documentation for the API service you are using.

Both types of inputs can be customized with the following states:

1. Omitted.  The default state.  This parameter will not be sent with the API call.
2. Default value.  This parameter will be set to some constant, defined here.
3. User given.  This parameter will be supplied by the user executing the ACP Workflow.
4. Workflow link.  The input for this parameter is the output of another step.  This will be described in greater detail later.
5. Iteration.  This parameter becomes available when the Iteration Options section is configured.  Inputs set to ‘iteration’ are populated with the iterated run number, starting from zero.  This will be described in greater detail in its own section.
6. Function.  The input of this parameter will be supplied by the output of a javascript function.  This will be described in greater detail later.

If there are no optional inputs for a given API call, the entire section is hidden.

After the ‘output’ section appears after the ‘optional inputs section.  This section shows an example return of the API endpoint, for use in establishing Workflow Links.

The ‘Sub Steps’ section describes how to iterate over an array of return objects, similar to the ‘iteration options’ previously.  This will be described in more detail later.

Lastly, the ‘Conditions & Routes’ section describes the flow-control by which the ACP system chooses what step is next.  The logic involved is complicated and receives its own section later in this document.

Links Between Steps

Setting a Required Input or an Optional Input to be a ‘workflow link’ will indicate that this parameter is to be taken from the results of a previous step.  The result can come from any previous step so long as it has run.  

When the ‘workflow link’ option is selected the form expands to gather the necessary information.  The middle drop-down selects what step you will be taking this information from. Once a step is selected, the rightmost ‘property’ box accepts the name of a parameter.

For example, if you are referencing a ProVision Resource GET call you can specify ‘id’ or ‘name’ here to feed in the associated value to this parameter.

If the step you are referencing returns an array of items, you can specify which item in the array you reference by way of the syntax ‘index.property’.  For example, if an API call returns an array of 3 objects, and you want to reference the id of the last one, you would put ‘2.id’ in the ‘property’ field.

A simple example of using the ‘workflow link’ parameter can be found in the ACP examples library as ‘Getting Started 3. Connecting Steps.’  

Another example can be found in ‘Getting Started 9. Working with Arrays.’  The Output area contains a reference to ‘2’, which indicates the entire 3rd object returned by the ProVision Get Resources query.

User Inputs

Setting a Required or Optional Input to ‘user given’ indicates that this parameter is a required input from the user who executes this workflow.  This parameter must be supplied for the workflow to run, regardless of whether the step where it is introduced is ever executed.

When the ‘user given’ option is selected the form changes to show an additional field where this variable can be named.  These variable names are global in scope, and the same name used multiple times will refer to the same variable, and will be requested from the user only once.  For example if your variable is ‘customer_name’ and it is used in three separate steps, the workflow will only request ‘customer_name’ once and use it in all three instances.

Conditions and Routing

The ‘Conditions & Routes’ section examines the data returned as the result of a workflow step and decides which step is next.  The workflow creator can define an unlimited number of separate conditions leading to different next steps, and each condition can consist of an unlimited number of individual comparisons.

The “add condition” button in the upper-left is used to create a new condition.  Each Conditions & Routes section can have an unlimited number of routes defined. Individual routes can be removed by clicking the trashcan icon at the right, and the route can be renamed by clicking on the existing name in the header.

At the bottom of every Conditions & Routes section is a “Route” section which dictates which step the workflow will be directed to if these conditions are met.

Each routing section is evaluated in order, from top to bottom, until a match is found.  Once a match is found the system proceeds to the indicated step without evaluating further conditions.  Multiple matches are not checked for. If no next-route is found, the workflow errors, possiblly triggering a rollback.

Initially each condition consists of a single comparison clause.  All comparison clauses consist of a ‘left value,’ which indicates source data, an ‘operator,’ which defines the nature of the comparison, and a ‘right value,’ which denotes the comparison data.

Both the ‘left value’ and the ‘right value’ areas can accept data from a variety of sources.  The options are:

1. http code:  uses the HTTP code returned by the API call in the step.
2. body:  accesses some value in the body of the API request.  Parameters are accessed by name, and arrays are accessed by “$index.parameter” as elsewhere.  (ex: the name of the first object in an array would be ‘0.name’)
3. default value:  a static, default value defined by the workflow creator
4. user given:  a value which must be supplied when the workflow is invoked
5. workflow link:  a reference to data obtained in a previous step
6. function:  indicates that the data for this field is the output of a data-processing function.  These functions are described in greater detail later in this document.

The ‘operators’ are largely self-explanatory boolean comparators, but a few require special syntax:

1. The operators IN and NOT IN accept comma-separated arrays (ex: one,two,three) for their values.  See “Getting Started 8. Compound Branching Conditions” for examples.
2. NULL, NOT NULL, TRUE, and FALSE do not require a right-hand value.
3. BETWEEN and NOT BETWEEN accept a tuple with the format “minvalue,maxvalue” (ex: ‘200,299’ for valid HTTP codes).
4. We should get Tony to talk a bit on what happens using numerical operators on strings.

The add-clause button (the plus symbol) and the remove-clause button (the minus symbol) on the far right allow you to join individual clauses into a compound clause, like “if A or B” or “if A and B and C”.  Once clicked, the add clause button creates a new clause below the last existing clause.  

At the far right of each comparison clause is a drop down that dictates how this and the next clause are to be joined.  The drop-down contains two operators, AND and OR, which join the two conditions as advertised.

Output

The Output area is always the final section in every workflow and determines what data is returned to the user when the workflow is invoked.  The workflow can be configured to return individual fields, entire arrays, individual members of arrays, and the entire body return from the executed steps.

The “add parameter” button allows you to populate the Output area with individual return parameters.  There is no limit on how many parameters can be returned by a single workflow.  

Each Output parameter consists of a number of parts:  the parameter name, the parameter type, and the type details.  Each parameter requires a distinct name. This is the name used in the return payload.  

The parameter types field is similar to those in the Optional and Required Parameters section.  You can define a parameter to draw its data either from a workflow link, a function, user given data, or a javascript function.  These functions are more fully described in the Optional and Required Parameters section.

Parameters can be removed by clicking the trashcan on the right.

Execution, the Results Area, and Debugging

Workflows can be run using the blue “Execute” button in the far upper right.  When a Workflow is executed, the system scans the Workflow’s structure to determine what information is required from the user as inputs and presents a modal screen requesting it.  Once this data is supplied, the screen scrolls to the Results area at the very bottom of the Step List and displays the results.

The Results section is broken into three sections:  Status, Stepwise Debugging, and the Raw Output. These sections can be navigated between by clicking on their names (in blue) just below the Results header.  The current section is underlined.

The Status screen shows the broad results of the Workflow.  If the workflow executed successfully the amount of time it consumed will be displayed in green.  

If the workflow encountered an error and halted, this error will be shown in red.

The output box below the response shows the data that has been returned by the Workflow.  In the case of a successful execution, this will be the data described in the Workflow’s Output section.  In the case of an error it will return a JSON debugging structure which contains an error message and a summary of what calls were executed.

If Debug Mode (see the section “Rollback Mode and Debug Mode” in this documentation) is enabled then the Steps and Raw Output sections are available.  These areas provide additional information on how to diagnose issues with ACP Workflows.

The Steps section shows the list of ACP Steps and lists the HTTP code returned at each step. If a step is not run, the HTTP code is listed as “HTTP N/A.”  Clicking on each step displays the variable values that were used in the execution of that step, as well as the output that was returned and the next step taken by the system.  This can be used to trace the flow of data throughout a workflow to determine where an issue occured.

The Raw Output section displays the raw JSON returned by the ACP system.  The details of this area are beyond the scope of this document, but this data can provide additional insight into the behavior of the Workflow.  

Workflow URL and External Execution

Once saved, every Workflow is assigned a distinct URL which can be used to execute it remotely by POST’ing data to it.  This URL can be found by navigating to the header area of the Workflow and clicking on the ‘More options’ drop-down below the description area.

Then select the ‘Workflow Info’ option.  

A modal window appears which displays the Workflow URL and the user-given variables required for the Workflow to run.

Export

Workflows can be exported in JSON format by navigating to the header area of the Workflow and clicking the ‘More options’ drop-down below the description area.  

Then select the ‘Export as JSON’ option.  

The Workflow JSON will be downloaded through the browser.  This exported JSON can be saved as a backup, shared with coworkers, or sent to 6connect Support for assistance.

Initiator Conditions

The 6connect ACP system uses “initiator conditions” as a sort of pre-routing system to determine, based on user-given data, which step is executed first.  This is particularly useful for data unification processes. For example, a Workflow can be configured to accept both a Customer Name or a Customer Id, but if a Customer Name is provided to start at a step which looks up the Customer Id before proceeding to the main work.  

The Initiator Editor can be accessed by scrolling to the top of a workflow and clicking ‘More options’, followed by ‘initiator conditions.’  

The Initiator Editor consists of a series of conditions blocks identical to those found in the Conditions and Routing sections on each individual step.  The “add condition” button can be used to include an arbitrary number of initiator conditions. Each individual condition can describe the relation between any number of variables using the same tools available in the routing section of individual steps.

When the workflow is executed each condition is evaluated against the user-given data, from top to bottom, in order.  One a matching condition is found the Workflow immediately proceeds to the indicated step.

Iteration Options

Each Step has an “Iteration Options” section which can be used to execute a single step multiple times.

Each iteration cycle will execute the step with identical inputs, with the exception of any variables defined with the ‘iteration’ type.  These variables will be supplied with data derived from the specific iteration cycle.

The Iteration Variable field in the Iteration Options section accepts the normal set of ACP variable types.  If supplied with a simple numerical value (ex: 5), the step will iterate that number of times. If supplied with a JSON array (ex: [ { id: 123}, {id : 321 } ] ), the step will repeat once for every member of the array.

Once a Step’s Iteration Variable is changed from “omitted,” each input in the Required Inputs section and the Optional Input gains access to the “iteration” data type.  If selected, this means that this input will be supplied with data from the iteration cycle.  

In the case of simple numeric iteration the data supplied will the iteration count, starting from zero.  

In the case of a more complicated JSON structure (ex: [ { id: 123}, {id : 321 } ] ), the entire object will be provided to the variable.  If only part of the structure is required, it can be accessed using the same semantics used to navigate JSON trees elsewhere. In the above example “{id: 123}” will be passed to the input by default, but if the input is configured with “id”, then only the value “123” will be passed in.  Likewise, if the object contained an array, then “2.id” will select the third item’s “id” parameter.

Javascript Functions

While many API automation tasks can be completed by invoking endpoints in order and passing identifiers from one service to another, many tasks will require some data processing to correctly accomplish their goals.  To assist in this ACP offers the ability to include user-written Javascript functions to handle these data manipulation tasks.

The Javascript Functions Management screen can be accessed from the left-hand menu by clicking on the pages icon, below User Management and above Generic Connectors.  

The Javascript Functions Management screen contains a listing of all the Javascript Functions currently known by the system.  When Workflows are exported, all used Javascript Functions are packaged in the Export bundle. When Workflows are imported, these packaged Functions are automatically included in the listing of Javascript Functions.

Each Javascript Function has a name, an optional category, and a description.  The Management screen contains boxes to search for a given Function by name and to filter by category.  Click on an existing Function name to edit the Function.

New Javascript Functions can be defined by hitting the ‘Add Function’ button at the top of the screen.

This opens up a short window where you can give a name to the new function, provide a description, assign it a category, and provide the code.  All Javascript Functions take the following form:

return function() {

    return "Hello World;"

}

Each Function can accept an unlimited number of arguments and produces exactly one return value.  Each Function can be of unlimited length and contain whatever logic is required to accomplish the Function’s goals.

All internal Javascript functions are available, but no Javascript extensions or libraries.

Javascript Functions are used wherever a variable is required in an ACP Workflow.  They can be used to transform Required or Optional Input data, or in Conditions & Routing blocks, or anywhere else a variable type box is displayed.  

To use a particular Javascript Function, open the variable type drop-down and pick ‘function.’  Click the ‘select function’ box to bring up the Function Picker.

The Function Picker allows you to filter the list of known Functions by name and category.  Choose a function by clicking on it from the Function Listing on the left.

Once you have selected a Function the next step is to supply it with inputs.  Click the “add argument” button to add the correct number of inputs for this Function.  These arguments will be passed to the Function in-order from top to bottom when the Function is executed.  Each argument comes with its own variable type picker and can consist of user-given data, workflow links, or default values.  

Save the configuration by clicking the ‘add’ button at the bottom of the screen.

This variable will be now be populated with the results of the function whenever this step is run.

Sub-Steps

Each Workflow Step has an optional Sub-steps section.  This area is initially empty, but can be populated with sub-steps to create a Workflow within a Workflow.  This Inner Workflow will be executed once for each item produced by the parent Step. For example, if the parent Step produces an array of five objects, then the Inner Workflow in the Sub-steps section will be executed five times, once for each object.

The Sub-steps section is executed after the parent call, but before the data is passed to the Conditions & Routes section.

The Sub-steps section is initially empty.  The “add substep” button enables this area and navigates to a new screen which focuses exclusively on this inner Workflow.  The “back to parent” button returns to the parent Step.

The Sub-step edit screen is very similar to the normal Workflow Step editing area.  You can add individual Sub-steps, each invoking an endpoint of configured API service, connected by Conditions & Routes sections and utilizing data provided by previous Steps from both inside and outside the Sub-step area.  It works exactly like a complete Workflow, only self-contained and dedicated to manipulating the data result of a parent Step.

In general, all the rules which apply to the normal Steps of a Workflow apply to Sub-steps.

One major difference is that a series of Sub-steps does not have an “Output,” but instead has a new field in its General Options field titled “Write output in parent scope.”  This field substitutes for an Output area and allows the user to specify where to put the output of this call.  NEED EXAMPLES FROM TONY

Each Inner Workflow can have, if needed, Sub-steps of is own, creating an Inner-Inner Workflow.  There is no limit to how many Workflows deep this can go.

Generic Connectors

The Generic Connector system is designed to allow ACP to support API-providing systems which do not have a predefined built-in connector.  For example, there may be a network appliance which offers an API that ACP does not natively support. In this case the user can employ a Generic Connector to manually define the API endpoints offered by this appliance and then integrate its functions with an ACP workflow as normal.

The Generic Connector section can be found by clicking on the graph icon on the left-hand navigation bar.

This brings up the main Generic Connectors List screen.

The Generic Connectors List screen.  From this screen you can edit or delete existing Generic Connectors.

Clicking on ‘Add Connector’ brings up a form which allows the user to name the new connector, add a short description, and pick the authentication type and communications protocol this connector will employ.

Authentication methods currently supported are “HTTP Basic”, “vCenter”, and “None.”

The only communications protocol currently supported is “HTTP.”

Completing the form and clicking the ‘add’ button will add the Generic Connector to the connectors list.  

Endpoints can be added to a Generic Connector by clicking on the ‘edit’ icon to the right of each Connector’s name.  This brings up a screen which displays a form for adding new Endpoints above the list for managing existing Endpoints.

The General Options area is where the information necessary to properly execute the API action is defined.  There are several fields:

Unique call name:  the name for this endpoint within ACP.

Endpoint http method:  the HTTP header for accessing this endpoint (GET, POST, etc).

Endpoint pathname:  the path of this API action.  Note: the connector configuration modal on each ACP Workflow will ask you for the location of the API service.  This pathname is the path to be used *after* the location of the service is defined. For example, if an API endpoint is “https://127.0.0.1/services/action1/”, the connector location will be defined as “https://127.0.0.1/services” and the endpoint pathname will be “/action1/”.  

Endpoint family name:  ACP organizes API endpoints into families for easier lookups.  This field allows you to define what family this endpoint falls into.  Families are automatically created from the contents of this field.

Friendly endpoint name:  a more user-friendly name for this endpoint.  

Endpoint description:  a short description of what this endpoint does.

Rollback call:  the unique call name which will be invoked if this call fails and rollbacks are enabled.  Optional.

Use this call to test credentials:  When the user is filling out the connector’s location and authentication details in a Workflow the ‘test’ button does a quick call to a specified endpoint to verify the credentials are working.  This toggle defines whether or not this endpoint is appropriate for this test.

Content-type header:  The content-type header sent to the API service by the HTTP protocol.  

Once a Generic Connector has been defined it can be selected from the Connectors section of any Workflow.

Workflows Executing Workflows

ACP ships with a self-referential “acp” connector type which is designed to include API calls generated by the ACP system itself.  This connector type can be found from the general list of connector types on the Connectors modal.

This functionality is extremely useful as it allows the user to extend simple workflows into more advanced ones in an intuitive fashion.

For example, imagine a situation where a Workflow integrates between some 3rd party billing software and customer information stored in 6connect ProVision.  A simple workflow might accept user credentials (user names, account numbers, etc) and then verify them with ProVision, the billing software, or both. This simple workflow would return the user object on success, but an error on failure.

On its own this doesn’t seem to do much, but this Workflow can be used as the first step of all subsequent Workflows, drastically cutting down on the clutter and overhead as well as allowing for easy single-point for maintenance in case of shifts in the underlying technologies.  

By creating simple workflows for very focused tasks one can build up a library of increasingly more complex combinations, allowing for very powerful results to be achieved in a compact space.