Synapse Server Controller Web API

The Synapse Controller Web API manages enforcing the RBAC, starting, cancelling, and recording/fetching Plan status. For information about configuration, see Controller/Node Setup.

Executing Plans

The Synapse Controller URI is: http://{host:port}/synapse/execute. For detailed method invocation information, see the Swagger URI at: http://{host:port}/swagger/

Verb	URI	Description
get	/synapse/execute/hello	Returns "Hello, World!" Does not invoke RBAC or DAL, but does require authentication.
get	/synapse/execute/hello/whoami	Returns a string of the authenticated user context. Does not invoke RBAC or DAL.
get	/synapse/execute/{planUniqueName}/item	Returns a Plan by PlanUniqueName.
get	/synapse/execute/{planUniqueName}/help	Returns Plan Dynamic Parameter information by PlanUniqueName.
get	/synapse/execute	Returns a list of Plans.
get	/synapse/execute/{planUniqueName}	Returns a list of Plan Instance Ids.
get	/synapse/execute/{planUniqueName}/start	Execute a Plan using the URI querystring for dynamic parameters. Returns planInstanceId.
post	/synapse/execute/{planUniqueName}/start	Execute a Plan with an http post, where dynamic parameters are specified in the http body. Returns planInstanceId.
get	/synapse/execute/{planUniqueName}/start/sync	Execute a Plan using the URI querystring for dynamic parameters and polls for completion at the server. Includes an embedded call to `/part/` and, by default, returns `Actions[0]:Result:ExitData`. See Synchronous Execution below for more information.
post	/synapse/execute/{planUniqueName}/start/sync	Execute a Plan with an http post, where dynamic parameters are specified in the http body and polls for completion at the server. Includes an embedded call to `/part/` and, by default, returns `Actions[0]:Result:ExitData`. See Synchronous Execution below for more information.
delete	/synapse/execute/{planUniqueName}/{planInstanceId}	Cancel a Plan by planInstanceId.
get	/synapse/execute/{planUniqueName}/{planInstanceId}	Get the status of a Plan by planInstanceId.
post	/synapse/execute/{planUniqueName}/{planInstanceId}	Update the status of the entire Plan, by planInstanceId.
post	/synapse/execute/{planUniqueName}/{planInstanceId}/action	Update the status of an individual Action within a Plan, by planInstanceId.
get	/synapse/execute/{planUniqueName}/{planInstanceId}/part	Select an individual element from within a Plan, specifying the desired return data serialization format. See details on the Part Interface below.
post	/synapse/execute/{planUniqueName}/{planInstanceId}/part	Select one or more individual elements from within a Plan, specifying the desired return data serialization format. See details on the Part Interface below.

Synchronous and Asynchronous Execution Models

Synapse supports two execution models: sync and async. These should not be confused with async/await threading patterns as implemented by client consumers - rather, the models refer to the behavior of the Controller when initiating a Plan.

Synchronous Execution

When executing under the sync interface, the Controller will monitor the Plan for completion and return a subset of the ResultPlan when complete. "Complete" is defined as a Plan Status value of Complete/Success (integer 128) or greater (see below for StatusType detail). Sync execution is most appropriate for short-running Plans where maintaining an open HTTP connection is acceptable.

Sync Execution Options

Parameter	Type	Required	Default	Description
`planUniqueName`	string	yes	none	The unique name of the Plan to execute.
`dryRun`	boolean	no	`false`	Indicates whether to execute the Plan in a "test" mode.
`requestNumber`	string	no	none	Optional self-provided tracking number for this current Plan execution.
`path`	string	no	`Actions[0]:Result:ExitData`	The subsection of the ResultPlan to return when the Plan completes. See Path Syntax for details.
`serializationType`	SerializationType	no	`SerializationType.Json`	Takes the output from `path` above and validates it can be parsed according to the SerializationType and returns it as such.
`setContentType`	boolean	no	`true`	Optionally sets the HTTP Response header for `Content-Type` to match the SerializationType.
`pollingIntervalSeconds`	int	no	1	Specifies time interval, in seconds, for how often the Controller polls for Plan completion.
`timeoutSeconds`	int	no	120	Specifies the time interval, in seconds, for how long the Controller will continues polling for Plan completion. If the timeout elapses the Controller will throw a timeout exception but that does not affect Plan execution - you may continue to poll for status manually following a timeout.
`nodeRootUrl`	string	no	none	Optional value to override the default Node for Plan execution. Specify as `http://{host:port}/synapse/node`.

Example GET/POST

Notes:

Parameters specified below for clarity, see above for required/default values.
GET/POST URLs are the same, but Plan Dynamic Parameters are managed differently per method. See Dynamic Parameters below for details.

http://localhost:20000/synapse/execute/samplePs1/start/sync?dryRun=false&requestNumber=1234&path=Actions%5B0%5D%3AResult%3AExitData&serializationType=Json&setContentType=true&pollingIntervalSeconds=2&timeoutSeconds=20

StatusType Values

StatusType values are part of the Synapse Core project. The values below are current as of the last update to this documentation, but for the most recent values, please check the SynapseProject GitHub page.

namespace Synapse.Core
{
    public enum StatusType
    {
        None = 0,
        New = 1,
        Initializing = 2,
        Running = 4,
        Waiting = 8,
        Cancelling = 16,
        Zombie = 32,
        Complete = 128,
        Success = 128,
        CompletedWithErrors = 256,
        SuccessWithErrors = 256,
        Failed = 512,
        Cancelled = 1024,
        Tombstoned = 2048,
        Any = 16383
    }
}

Path Syntax

Selecting Plan elements requires a rooted path, expressed as shown below. If an element is part of a list, use a index specifier.

element:element:element:etc.
element[index]:element:element[index]:element:etc.

Examples:

Result:BranchStatus #returns Plan.Result.Status
Actions[0]:Result:ExitData #returns Plan.Actions[0]:Result:ExitData

SerializationType Values

StatusType values are part of the Synapse Core project. The values below are current as of the last update to this documentation, but for the most recent values, please check the SynapseProject GitHub page.

namespace Synapse.Core
{
    public enum SerializationType
    {
        Yaml = 0,
        Xml = 1,
        Json = 2,
        Html = 3,
        Unspecified = 4
    }
}

YAML/JSON/XML will attempt to parse the element data into the specified format before returning it. "Unspecified" will return the data, as-is.

Asynchronous Execution

When executing under the async interface, the Controller will immediately return a plan instance Id back to the caller and close the HTTP connection. To know when the Plan has completed, create a manual poller (example) and use the API endpoints for status as shown below. Asynchronous execution is most appropriate for long-running Plans where maintaining an open HTTP connection is inappropriate. When using async execution, you will need to manually poll for Plan completion via the planInstanceId, which may be accomplished through two interface options, as described below.

Async Execution Options

Parameter	Type	Required	Default	Description
`planUniqueName`	string	yes	none	The unique name of the Plan to execute.
`dryRun`	boolean	no	`false`	Indicates whether to execute the Plan in a "test" mode.
`requestNumber`	string	no	none	Optional self-provided tracking number for this current Plan execution.
`nodeRootUrl`	string	no	none	Optional value to override the default Node for Plan execution. Specify as `http://{host:port}/synapse/node`.

Example GET/POST

Notes:

Parameters specified below for clarity, see above for required/default values.
GET/POST URLs are the same, but Plan Dynamic Parameters are managed differently per method. See Dynamic Parameters below for details.

http://localhost:20000/synapse/execute/samplePs1/start?dryRun=false&requestNumber=1234

Example Manual Poller, c-sharp

public static StatusType GetStatus(string planName, long id, int pollingIntervalSeconds = 1, int timeoutSeconds = 120)
{
    //ensure valid values
    pollingIntervalSeconds = pollingIntervalSeconds < 1 ? 1 : pollingIntervalSeconds;
    timeoutSeconds = timeoutSeconds < 1 ? 120 : timeoutSeconds;

    int c = 0;
    StatusType status = StatusType.New;
    while( c < timeoutSeconds )
    {
        Thread.Sleep( pollingIntervalSeconds * 1000 );
        //pseudo-code: status = fetch from whole ResultPlan or part interface
        c = status < StatusType.Success ? c + 1 : int.MaxValue;
    }

    return status;
}

Example Manual Poller, PowerShell

Getting Plan Status with PlanInstanceId

When manually fetching Plan status, you may choose to retrieve the entire ResultPlan or a specified subsection via the \part interface.

Getting the Entire ResultPlan

One way to fetch Status is via getting the entire ResultPlan. When polling, the ResultPlan will not contain status for every Action until the Plan Status is >= Complete. To retrieve the ResultPlan, execute an HTTP GET to:

/synapse/execute/{planUniqueName}/{planInstanceId}

Then, parse the Plan and get the Plan.Result.Status.

Getting Subsections of the ResultPlan with the `/part` Interface

The Synapse Controller /part interface is designed to allow selection of one or more individual Plan elements, serialized into a specific format. This is useful when seeking efficiency of data interrogation or when serializing data to a specific format. This capability is embedded in Synchronous Plan execution and is the method by which data is returned.

Parameter	Type	Required	Default	Description
`path`	string	yes	`Actions[0]:Result:ExitData`	The subsection of the ResultPlan to return when the Plan completes. See Path Syntax for details.
`serializationType`	SerializationType	no	`SerializationType.Json`	Takes the output from `path` above and validates it can be parsed according to the SerializationType and returns it as such.
`setContentType`	boolean	no	`true`	Optionally sets the HTTP Response header for `Content-Type` to match the SerializationType.

Example GET

Notes:

Parameters specified below for clarity, see above for required/default values.
Unlike Synchronous Plan execution, Path is required in the /part interface.

http://localhost:20000/synapse/execute/samplePs1/12341234/part?elementPath=Actions%5B0%5D%3AResult%3AExitData&serializationType=Json&setContentType=true

Example POST

URL: http://localhost:20000/synapse/execute/samplePs1/12341234/part
Body:

{
  "Type": "Json",
  "ElementPaths": [
    "Actions[0]:Result:ExitData",
    "Result.Status"
  ]
}

Dynamic Parameters

Synapse Controller accepts dynamic Plan parameters in both GET and POST operations, as follows below.

Dynamic Parameters with GET

The general URI signature for starting a Plan via GET is:

http://host:port/synapse/execute/{planUniqueName}/start/?dryRun={true|false}&requestNumber={requestNumber}
http://host:port/synapse/execute/{planUniqueName}/start/sync/?dryRun={true|false}&requestNumber={requestNumber}

where dryRun and requestNumber are reserved by Synapse as built-in parameters. Every other key/value pair on the URL is passed-through to the Plan as a custom/dynamic parameter.

GET Example:

http://host:port/synapse/execute/{planUniqueName}/start/?dryRun=true&requestNumber=0123&key0=value0&key1=value1&key2=value2
key0, key1, and key2 will all be treated as dynamic parameters and passed through to the Plan.

Dynamic Parameters with POST

As with a GET, the URI for a POST remains:

http://host:port/synapse/execute/{planUniqueName}/start/?dryRun={true|false}&requestNumber={requestNumber}
http://host:port/synapse/execute/{planUniqueName}/start/sync/?dryRun={true|false}&requestNumber={requestNumber}

but sending dynamic parameters is accomplished in the http request via the DynamicParameters key/value pair wrapper structure.

POST Examples

Content-Type = application/json
Request Body (raw):

{
  "DynamicParameters": {
    "key0": "value0",
    "key1": "value1",
    "key2": "value2"
  }
}

Content-Type = application/xml
Request Body (raw):

<StartPlanEnvelope>
    <XmlDynamicParameters>
        <Parm Name='key0'>value0</Parm>
        <Parm Name='key1'>value1</Parm>
        <Parm Name='key2'>value2</Parm>
    </XmlDynamicParameters>
</StartPlanEnvelope>

Synapse Server Controller Web API

Executing Plans

Synchronous and Asynchronous Execution Models

Synchronous Execution

Sync Execution Options

Example GET/POST

StatusType Values

Path Syntax

SerializationType Values

Asynchronous Execution

Async Execution Options

Example GET/POST

Example Manual Poller, c-sharp

Example Manual Poller, PowerShell

Getting Plan Status with PlanInstanceId

Getting the Entire ResultPlan

Getting Subsections of the ResultPlan with the /part Interface

Example GET

Example POST

Dynamic Parameters

Dynamic Parameters with GET

GET Example:

Dynamic Parameters with POST

POST Examples

Getting Subsections of the ResultPlan with the `/part` Interface