Y# Schema reference

This document outlines a general structure and explains the default fields of the provided Variant services YAML file and the core default properties found in those types.

Schema

Implementations

This array is only found in the Startup.yaml and is used for adding global scope type dependencies. e.g. ILokiInitialisation, IAdditionalSecureSettings, IAdditionalSettings, etc.

Key	Type	Required	Description
name	string	Yes	The name of the dependency
interface	string	Yes	The full assembly name of the interface
implementation	string	Yes	The full assembly name of the implementation
values:	object	No	Any values the implmentations requires

Example

implementations:
  - name: community
    interface: Variant.Core.IAdditionalSecureSettings, Variant.Core, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
    implementation: Variant.Strategies.Azure.Vault.AzureVaultUsingClientCertificate, Variant.Strategies.Azure.Vault, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
    values:
      CacheValues: false
      ClientId: $[Workbench.Vault.ClientId]
      TenantId: $[Workbench.Vault.TenantId]
      Thumbprint: $[Workbench.Vault.Thumbprint]
      VaultUrl: $[Workbench.Vault.Url]

EndPoints

This array holds the definitions of all the endpoints the application exposes.

Key	Type	Required	Description
routeTemplate	string	Yes	The URL path for the endpoint. It can include path parameters encapsulated by `\{xxx}` (use {*xxx} to grab the following path in full). These values are accessed by the following notation: '${Request.Path.xxxx}
routeOpenApi	object	No	This allows the full OpenApi specification for this endpoint to be defined. For full details see the OpenApi specifications for the schema you have defined in the /openapi.json endpoint call
routeMethod	string	Yes	The HTTP method for the endpoint. Allowed values are `GET`, `POST`, `PUT`, `PATCH`, `HEAD`, `DELETE` & `OPTIONS`.
description	string	No	A brief description of the endpoint's purpose.
response	OpenApi response	No	Matches the OpenApi response format
queries	object	No	Defines the expected query parameters. These values are accessed by the following notation: '${Request.Query.xxxx}
headers	object	No	Defines the expected request headers. These values are accessed by the following notation: '${Request.Header.xxxx}
request	object	No	Defines the expected request body.
pipeline	array	Yes	An array of pipes which get executed in sequence. Each item in the array should correspond to a pipe defined in the `pipes` collection.

'Object' type above corresponds to properties written as:

headers:
  name: string (Required)
  mobile?: string (Optional)
  age: number (Required)

End point example

endPoints:
  - routeTemplate: api/bankholiday/{region}
    routeMethod: GET
    routeOpenApi:
      tags: [ Default ]
      summary: Get bank holidays for a region
      parameters:
        - name: region
          in: path
          required: true
          schema:
            type: string
            enum:
              - england-and-wales
              - scotland
              - northern-ireland      
      responses:
        200: ${Defaults.Ok}
    pipeline:
      - pipe: Variant.Core.Simple.HttpPushPipe
        NAMESPACE: BankHolidays
        HTTP_URL: https://www.gov.uk/bank-holidays.json
        HTTP_METHOD: GET
        CACHE_STRATEGY!: 
          strategy: Variant.Core.InMemoryCacheStrategy     
          CACHE_FOR_TIME_SPAN: 00:00:10      

      - pipe: Variant.Core.Simple.TryCatchAndReplaceScopedPipe
        EXCEPTION_PIPES: 
          - pipe: Variant.Core.ThrowNotFoundBreakPipe
            BLOCKED_WITH_ERROR_MESSAGE: Path region '${Request.Path.region}' not found!
        SCOPED_PIPES: 
          - pipe: Variant.Core.SetResponse
            RESPONSE: ${BankHolidays.${Request.Path.region}.events}

Connections

This array holds the definitions of all the connectors that runs in the application

Key	Type	Required	Description
connector	string	Yes	The name of the connector whose key is found in the connectors array.
replacements	object	No	The values that should be used to replace placeholders in the connector.
defaults	object	No	An object of default values and configurations for the connector.
pipeline	array	Yes	An array of pipes which get executed in sequence. Each item in the array should correspond to a pipe defined in the `pipes` collection.

Example

connections:
  - connector: Variant.Core.TimerConnector
    DUE_TIME: 0:0:01
    POLLING_INTERVAL: 00:00:05
    pipeline:
      - pipe: Variant.Core.LogDebugMessage
        LOG_MESSAGE: Timer ran at '{Time}'
        LOG_MESSAGE_PARAMETERS: ${DateTimeOffset.Now}

Connectors

This array holds a list of specialised templated connections that can be used in the connections section.

Key	Type	Required	Description
key	string	Yes	The unique identifier of the connector.
value	object	Yes	The details about the connector. Can be a either a specialised connector or a root connector. Root connectors are auto generated from it's underlying Dot Net object are are not editable.

The value object schema:

Core connector

Key	Type	Required	Description
type	string	Yes	Fully qualified assembly name of the connector
replacements	object	No	The values that should be used to replace placeholders in the connector.
defaults	object	No	An object of default values and configurations for the connector.
metaData	object	Yes	Contains details regarding settings, default values etc.

Example

connectors:
  - key: Variant.Core.TimerConnector
    value:
      type:  Variant.Strategies.Core.TimerConnector, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      replacements:
        IS_ENABLED: 
        DEFAULTS: 
        CONNECTOR_INSTANCE_NAME: 
        ACTIVITY_NAME: 
        DUE_TIME: "0:0:01"
        IGNORE_EVENT_IF_PROCESSING: True
        POLLING_INTERVAL: "00:00:15"
      # Properties
      DueTime: DUE_TIME
      IgnoreEventIfProcessing: IGNORE_EVENT_IF_PROCESSING
      PollingInterval: POLLING_INTERVAL
      IsEnabled: IS_ENABLED
      Defaults: DEFAULTS
      InstanceName: CONNECTOR_INSTANCE_NAME
      ActivityName: ACTIVITY_NAME
      SerializationHints: SERIALIZATION_HINTS
    metaData:
      id: Variant.Strategies.Core.TimerConnector, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      softType: connector
      description:  ""
      tags: ""
      isObsolete: False
      settings:
        - property: IS_ENABLED
          description: "Expression which determines if connector is built. Null == true"
          isRequired: False
          type: System.String
        ### Other properties removed for brevity

Specialised connector

Key	Type	Required	Description
connector	string	Yes	The name of the connector.
replacements	object	No	The values that should be used to replace placeholders in the connector.
defaults	object	No	An object of default values and configurations for the connector.

Example

connectors:
  - key: Variant.Azure.Storage.Rest.Queue.TimerConnector
    value:
      connector: Variant.Core.TimerConnector
      replacements:
        DEFAULTS: 
        ACTIVITY_NAME: 
        DUE_TIME: 0:0:01
        POLLING_INTERVAL: 00:00:15
        STORAGE_ACCOUNT_NAME: 
        QUEUE_AUTHORIZATION_PIPE:         
        QUEUE_NAME: 
        QUEUE_NUM_OF_MESSAGES: 32
        QUEUE_BATCH_SIZE: 8
        QUEUE_VISIBILITY_TIMEOUT_IN_SECONDS: 30
        QUEUE_MAX_DEQUEUE_COUNT: 2
        QUEUE_ITEM_NS: QueueItem
        QUEUE_ON_ERROR_HIDE_MESSAGE_FOR_N_SECONDS: 5
        QUEUE_DEAD_LETTER_PIPES: []
        QUEUE_PROCESS_PIPES: |2
                # Set Request header 
              - pipe: Variant.Core.Simple.ModifyMessageStrategyPipe
                NAMESPACE: Request
                VALUE: ${QueueItem.MessageText.ConvertBase64ToString().ConvertStringToJToken()} 
      defaults: 
        IGNORE_EVENT_IF_PROCESSING: True
        IS_ENABLED:
        INSTANCE_NAME: 
      pipeline:
        - pipe: Variant.Azure.Storage.Rest.Queue.ForEachAsyncPipe
          QUEUE_LOG_LEVEL: Trace

Pipes

This array holds the definitions of all the pipes used in the application. See Variant Core pipes for list of values the can be placed in the replacements or defaults properties.

Key	Type	Required	Description
key	string	Yes	The unique identifier of the pipe.
value	object	Yes	The details about the pipe. Can be a either a specialised pipe or a root pipe. Root pipes are auto generated from it's underlying Dot Net object are are not editable.

The value object schema:

Core pipe

Core pipes are auto generated directly from the their c# implementation and will always be found in extension packages and never directly in a service.

Key	Type	Required	Description
type	string	Yes	Fully qualified assembly name of the pipe
replacements	object	No	The values that should be used to replace placeholders in the pipe.
defaults	object	No	An object of default values and configurations for the pipe.
metaData	object	Yes	Contains details regarding settings, default values etc.

Example

pipes:
  - key: Variant.Core.PushMessagePipe
    value:
      type:  Variant.Strategies.Core.PushMessagePipe, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      replacements:
        PUSH_MESSAGE_STRATEGY: 
        CAN_EXECUTE_STRATEGY: 
        EXECUTION_FLOW_STRATEGY: 
        CAN_EXECUTE_EXPRESSION: 
        INSTANCE_NAME: 
        ACTIVITY_NAME: 
        IS_ENABLED: 
        CONTINUATION_POLICY: Default # [ Default | ReturnIfExecuted | ContinueOnNotExecuted | ContinueOnError | ReturnOnSuccess | ReturnIfNotExecuted ]
        CONTINUE_ON_ERROR_EXCEPTION_NS: Exception
      # Properties
      PushMessageStrategy: PUSH_MESSAGE_STRATEGY
      CanExecuteStrategy: CAN_EXECUTE_STRATEGY
      CanExecuteExpression: CAN_EXECUTE_EXPRESSION
      ContinuationPolicy: CONTINUATION_POLICY
      ExecutionFlowStrategy: EXECUTION_FLOW_STRATEGY
      ContinueOnErrorExceptionNs: CONTINUE_ON_ERROR_EXCEPTION_NS
      InstanceName: INSTANCE_NAME
      ActivityName: ACTIVITY_NAME
      IsEnabled: IS_ENABLED
      SerializationHints: SERIALIZATION_HINTS
    metaData:
      id: Variant.Strategies.Core.PushMessagePipe, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      softType: pipe
      description:  ""
      tags: ""
      isObsolete: False
      settings:
        - property: PUSH_MESSAGE_STRATEGY
          description: "Injected class for pushing a UniteMessage"
          isRequired: True
          type: Variant.Strategies.Core.IPushMessageStrategy
          defaultValue: ""
        - property: CAN_EXECUTE_STRATEGY
          description: "Allows for more complex filtering"
        #  Properties removed for brevity

Specialised pipe

Specialised pipes always derive from core pipes and can be found in both extension packages and with service files.

Key	Type	Required	Description
pipe	string	Yes	The name of the pipe.
replacements	object	No	The values that should be used to replace placeholders in the pipe.
defaults	object	No	An object of default values and configurations for the pipe.

Example

pipes:
  - key: Variant.Core.HttpPushMessageStrategyPipe
    value:
      pipe: Variant.Core.PushMessagePipe
      replacements:
        # Pipe replacements
        CAN_EXECUTE_EXPRESSION: null
        CAN_EXECUTE_STRATEGY: null
        CONTINUATION_POLICY: Default
        # Strategy replacements
        CACHE_STRATEGY: 
        RETRY_STRATEGY: 
        HTTP_BODY: 
        HTTP_DATA_HEADER: 
        HTTP_CONTENT_HEADERS: 
        HTTP_RESPONSE_ID: 
        JSON_PARSE_PATH: 
        HTTP_URL: "http://localhost:9012"
        HTTP_LOG_LEVEL: Debug # [ Trace | Debug | Information | Warning | Error | Critical | None ]
        ADD_HEADER_IF_NULL_OR_WHITESPACE: False
        HTTP_HEADERS: |2-
          Content-Type: application/json; charset=utf-8
          Accept: application/json
        HTTP_METHOD: GET
        HTTP_RESPONSE_CONTENT_HEADER:  # Response.ContentHeaders
        HTTP_RESPONSE_HEADER:  # Response.Headers
        HTTP_READ_AS: JToken # [ Stream | String | JToken | HttpResponseMessage ]
        NAMESPACE: Response
        HTTP_TIMEOUT: 60000
        SET_STATUS_CODE_HEADER: False
        HTTP_ALLOW_AUTO_DIRECTS: False
      defaults:
        LOG_ERRORS: True
        ACTIVITY_NAME: 
        EXECUTION_FLOW_STRATEGY: null
        PUSH_MESSAGE_STRATEGY:
          strategy: Variant.Core.HttpPushMessageStrategy

Strategies

This array holds the definitions of all the strategies used in the application.

Key	Type	Required	Description
key	string	Yes	The unique identifier of the strategy.
value	object	Yes	The details about the strategy. Can be a either a specialised strategy or a root strategy. Root strategies are auto generated from it's underlying Dot Net object are are not editable.

The value object schema:

Core strategy

Core strategies are auto generated directly from the their c# implementation and will always be found in extension packages and never directly in a service.

Key	Type	Required	Description
type	string	Yes	Fully qualified assembly name of the strategy
replacements	object	No	The values that should be used to replace placeholders in the strategy.
defaults	object	No	An object of default values and configurations for the strategy.
metaData	object	Yes	Contains details regarding settings, default values etc.

Example

strategies:
 - key: Variant.Core.HttpPushMessage2Strategy
    value:
      type:  Variant.Strategies.Core.HttpPushMessage2Strategy, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      replacements:
        CACHE_STRATEGY: 
        RETRY_STRATEGY: 
        HTTP_BODY: 
        HTTP_DATA_HEADER: 
        HTTP_CONTENT_HEADERS: 
        HTTP_RESPONSE_ID: 
        JSON_PARSE_PATH: 
        INSTANCE_NAME: 
        HTTP_URL: "http://localhost:9012"
        HTTP_LOG_LEVEL: Debug # [ Trace | Debug | Information | Warning | Error | Critical | None ]
        ADD_HEADER_IF_NULL_OR_WHITESPACE: False
        HTTP_HEADERS: |2-
          Content-Type: application/json; charset=utf-8
          Accept: application/json
        HTTP_METHOD: GET
        HTTP_RESPONSE_CONTENT_HEADER:  # Response.ContentHeaders
        HTTP_RESPONSE_HEADER:  # Response.Headers
        HTTP_READ_AS: JToken # [ Stream | String | JToken | HttpResponseMessage ]
        NAMESPACE: Response
        HTTP_TIMEOUT: 60000
        SET_STATUS_CODE_HEADER: False
        HTTP_ALLOW_AUTO_DIRECTS: False
        LOG_ERRORS: True
      # Properties
      CacheStrategy: CACHE_STRATEGY
      Url: HTTP_URL
      Body: HTTP_BODY
      DataHeader: HTTP_DATA_HEADER
      HttpLogLevel: HTTP_LOG_LEVEL
      AddHeaderIfNullOrWhiteSpace: ADD_HEADER_IF_NULL_OR_WHITESPACE
      Headers: HTTP_HEADERS
      ContentHeaders: HTTP_CONTENT_HEADERS
      Method: HTTP_METHOD
      RetryStrategy: RETRY_STRATEGY
      HttpResponseContentHeader: HTTP_RESPONSE_CONTENT_HEADER
      HttpResponseHeader: HTTP_RESPONSE_HEADER
      HttpResponseId: HTTP_RESPONSE_ID
      ReadAs: HTTP_READ_AS
      JsonParsePath: JSON_PARSE_PATH
      Namespace: NAMESPACE
      Timeout: HTTP_TIMEOUT
      SetStatusCodeHeader: SET_STATUS_CODE_HEADER
      AllowAutoDirects: HTTP_ALLOW_AUTO_DIRECTS
      InstanceName: INSTANCE_NAME
      LogErrors: LOG_ERRORS
      SerializationHints: SERIALIZATION_HINTS
    metaData:
      id: Variant.Strategies.Core.HttpPushMessage2Strategy, Variant.Strategies.Core, Version=1.1.0.0, Culture=neutral, PublicKeyToken=null
      softType: strategy
      description:  ""
      tags: ""
      isObsolete: False
      settings:
        - property: CACHE_STRATEGY
          description: "Cache strategy"
          isRequired: False
          type: Variant.Strategies.Core.ICacheStrategy
          defaultValue: ""
        # Additional properties removed for brevity

Specialised strategy

Specialised strategies always derive from core strategies and can be found in both extension packages and with service files.

Key	Type	Required	Description
strategy	string	Yes	The name of the strategy.
replacements	object	No	The values that should be used to replace placeholders in the strategy.
defaults	object	No	An object of default values and configurations for the strategy.

Example

As strategies need to be instantiated with a pipe we can use a simplified http pipe for calling http endpoints

strategies:
  - key: Variant.Core.Simple.HttpPushPipe
    value:
      pipe: Variant.Core.HttpPushMessage2StrategyPipe
      replacements:
        NAMESPACE: Response
        HTTP_URL: 
        HTTP_METHOD: GET
        HTTP_READ_AS: JToken
        HTTP_HEADERS: |2-

              Content-Type: application/json; charset=utf-8
              Accept: application/json
        HTTP_BODY:

Variant Core Pipes

There are 3 different pipe definitions / types:

VariantPipe: All pipes are themselves derived from this pipe
VariantConditionalPipe: Adds conditional processing to the VariantPipe
VariantScopedConditionalPipe: A pipe that has a collection of child pipes. Itself is derived from VariantConditionalPipe.

All of the keys below can be placed under the replacements or defaults property of its pipe.

Note: All pipes when executed return either: Success, NotExecuted or Failed.

Variant Pipe

Key	Type	Required	Description
INSTANCE_NAME	string	No	A description that is used when logging or throwing errors. If not present then a the name of the type will be used instead.
LOG_ERRORS	bool	Yes	When implemented and true, the pipe should not write any errors to the logging system

Variant Conditional Pipe

Derived from VariantPipe and includes includes all the properties that that exposes.

Key	Type	Required	Description
CAN_EXECUTE_EXPRESSION	string	No	The unique identifier of the strategy. e.g. "${MyValue}" == true
CAN_EXECUTE_STRATEGY	strategy	No	A strategy that is derived from the ICanExecuteStrategy interface. Allows for a more business specific run conditions.
EXECUTION_FLOW_STRATEGY	strategy	No	Provides a granular approach for return values: outcome, error message & error id dependent on the ContinuationPolicy.
CONTINUATION_POLICY	ContinuationPolicy	No	Determines execution flow dependent on pipe result

Variant Conditional Scoped Pipe

Derived from VariantConditionalPipe and includes includes all the properties that that exposes.

Key	Type	Required	Description
SCOPED_PIPES	array	Yes	A list of pipes to execute.

ContinuationPolicy

Key	Type	Description
Default	string	Execution continues unless there are errors. On an error the pipeline execution stops at that pipe line
ReturnIfExecuted	string	If the pipe runs then no other peer pipes are executed in the pipeline
ReturnIfNotExecuted	string	If the pipe is not executed then no other peer pipes are executed in the pipeline
ReturnOnSuccess	string	Stops execution of any further pipes in the pipeline if the pipe was successful. i.e. Outcome != Failed
ContinueOnNotExecuted	string	Allows continuation when pipe execution returns NotExecuted.
ContinueOnError	string	Continues onto the next pipe even if the pipe errored.

Schema​

Implementations​

Example​

EndPoints​

End point example​

Connections​

Example​

Connectors​

Core connector​

Example​

Specialised connector​

Example​

Pipes​

Core pipe​

Example​

Specialised pipe​

Example​

Strategies​

Core strategy​

Example​

Specialised strategy​

Example​

Variant Core Pipes​

Variant Pipe​

Variant Conditional Pipe​

Variant Conditional Scoped Pipe​

ContinuationPolicy​

Schema

Implementations

Example

EndPoints

End point example

Connections

Example

Connectors

Core connector

Example

Specialised connector

Example

Pipes

Core pipe

Example

Specialised pipe

Example

Strategies

Core strategy

Example

Specialised strategy

Example

Variant Core Pipes

Variant Pipe

Variant Conditional Pipe

Variant Conditional Scoped Pipe

ContinuationPolicy