In Situ Substitution Expressions

Document created by DPM Admin on Jul 21, 2017
Version 1Show Document
  • View in full screen mode

In Situ Substitution Expressions (ISSEs), are text expressions that can be entered anywhere within Message text to be sent.  The ISSEs are replaced with their corresponding value before the Message is sent.

ISSEs can be entered in either the Form or the XML side of the Message Editor.  They can appear anywhere within the Message text.  There is no relationship between ISSEs and XML (if the Message being sent is XML) – a pure text replacement is done.  Therefore, ISSEs can cause XML to be inserted into the Message.  There is currently no way to specify that the text produced by an ISSE is to be escaped for XML purposes – the user must arrange for that himself.

ISSE’s can be interspersed within partial field values to cause the results of the ISSEs to be concatenated to or inserted into partial constant values.

There are three major types of ISSEs: property references, global property references, and expressions.

References to System and Custom Properties

This form of ISSE refers to a System or Custom Property within one of the items in the Composition. The value of the specified property is substituted into the Message in place of the ISSE.

The syntax of this form of ISSE is:

{%% property-type : item-type : property-path %%}

Spaces are not significant except for cases in which the names of properties specified in the property-path contain spaces.

Property-type field

This field specifies what type of property is being referenced. It can be any of the following values to denote a Custom Property (case is not significant):

  • Empty string (e.g. “{%% : item-type : property-path %%}”)
  • prop”
  • custom-prop”
  • custom-property”

It can be any of the following values to denote a System Property (case is not significant):

  • sys-prop”
  • sys-property”
  • system-property”

Item-type field

This field specifies the type of item within the Composition that contains the property. It can be any of the following values (case is not significant):

  • Composition”
  • Band”
  • Track”
  • MessageClip” or Clip” (either one is accepted)
  • Message”
  • Delay”
  • Target”
  • Destination”

Property-path field

This field specifies which property is to be accessed.

It can be a simple as only a property name, in which case the property will be taken from the “current” item of the type specified in the property-type field. For example, the current Message, its “destination”, or its parent Message Clip, Track, or Band.

In order to refer to other properties, a “path” to the property can be given, using the names of the containers of the property, separated by slashes.

For example, for type “Message”, the following path:

Band2/Track3/Clip2/Message5/MyProperty

Refers to the property named “MyProperty” in Message “Message5”, which is contained in Message Clip “Clip2”, in Track “Track3” of Band “Band2”.

If any of the names contain spaces, they must appear at their appropriate places, for example if the names in the above example contained spaces, the path would be:

Band 2/Track 3/Clip 2/Message 5/My Property

“Left” portions of the path may be omitted to provide “relative” paths which reference “current” item(s) and parent(s) according to the context in which the ISSE is used. For example, if the following path were to be used in the above example for a Message property:

Clip 2/Message 5/My Property

The ISSE would be referencing the specified Message Clip “Clip 2” and Message “Message 5” contained within the current Band and Track (since the Band and Track portions of the path were omitted).

There is a subtle difference between types “Destination” and “Target”.

For “Destination”, the path to a Message is given, and the specified item is the Target being used by that Message. For example:

Band5/Track6/Clip2/Message27/TargetPropertyName

For “Target”, a path to any arbitrary Target (by name) in any arbitrary Message Clip is given to specify any Target in any Clip. For example:

Band5/Track6/Clip2/Target7/TargetPropertyName

Note that for Message Clips and Targets, the “local name” (as defined in the Composition or Message Clip) must be used, not the name of the Repository item that is being linked to. (Since a Message Clip or Target can be used multiple times, the Repository Name is not necessarily unique.)

References to Global Custom Properties

This form of ISSE refers to a Global Custom Property from a Global Custom Property List.  The value of the specified Global Custom Property is substituted into the Message in place of the ISSE.  Global Custom Property Lists are defined in Central and, as the name implies, are globally accessible from all Compositions.

The syntax of this form of ISSE is:

{%% property-type : property-path %%}

Spaces are not significant except for cases in which the names of lists or properties specified in the property-path contain spaces.

Property-type field

This field must be any of the following values to denote a Global Custom Property (case is not significant):

  • “global-prop”
  • “global-property”
  • “global-custom-prop”
  • “global-custom-property”

Property-path field

This field specifies which property is to be accessed.

It can be as simple as only a property name, in which case the property will be taken from the default Global Custom Property List (named “Default”).

In order to refer to properties in other lists aside from the Default, a “path” to the property can be given, using the name of the Global Custom Property List, a slash, and then the name of the Global Property in that list.

For example, the following path:

My list/Some property

Refers to the property named “Some property” in the Global Custom Property List named “My list”.

The following paths are equivalent:

Default/Property 6

Property 6

Both of the above paths refer to the property named “Property 6” in the default Global Custom Property List.

Counters

Global Custom Properties that are defined to be of type “counter” contain integer numbers that are automatically incremented every time they are referenced.  The ISSE reference syntax is the same regardless of whether the property being referenced is a counter.

Message-Level Counters

Global Custom Properties that are defined to be of type “Message-level counter” behave the same as regular “counters”, except that they are incremented only the first time they are referenced within each Message.  Thus if there is more than one ISSE in the same Message referencing the same Global Custom Property of type “Message-level counter”, that property will only be incremented once for that Message and all of those ISSE substitutions within that Message will have the same value substituted.


Encoding in ISSE substitution

In some cases, it may be necessary to use encoding in order to POST items in a test.

There is currently only one parameter type supported, “encoding”.  It can only have the following values:  “urlencode”, “urldecode” or “base64”. Any number of encoding parameters can be included, and they are executed in order

For single encoding cases where only one form of encoding is required create an ISSE with the base64 encode option shown below:

{%%Custom-Property, encoding=base64: message: Prop 1%%}

In more complicated cases, multiple forms of encoding can be used. For example, some environments may require an XML string to base64 encoded, but also may require the XML string to be URL encoded it before conducting a POST.

Multiple encodings, which are order-dependent, can be applied using the following ISSE syntax:

{%% Custom-Property, encoding=base64, encoding=urlencode : message : Prop 1 %%}

Execution of an Expression In A Script

This form of ISSE causes a scripting expression to be executed.  The value of the expression is substituted into the Message in place of the ISSE.

The syntax of this form of ISSE is:

{%% expression-indicator: expression-text %%}

Spaces are not significant.  There is currently no provision for allowing the sequence “%%}” to appear in the script.  (This should not be a problem, since that sequence has no meaning in JavaScript.  If it were desired to use that value in a string within the script, something like “’%%’ + ‘}’” could be used within the script.)

Expression-indicator field

This field must be one of the following values (case is not significant):

  • “expr”
  • “expression”

Expression-text field

This is the expression to be executed.

It can be a simple expression, such as 10 + 20”.  The reserved variable name result” is the result of the expression, thus result = 10 + 20;” would have the same effect.

The script can be a complete program if desired.  For example, the following would yield the same result as the prior examples:

var a=10; var b=20; result=a+b;

 

The script has full access to any of the capabilities of a Transition.  It can even modify properties or other portions of the Composition, as allowed in a Transition.  Obviously this has the potential to be confusing if taken too far.

The result of the expression that is substituted is the value of either the variable named result” or the last expression (without a left side) or function call executed.

See the separate document on scripting for a full description of what can be done within a script.

 

Some examples

{%% prop : composition : CompositionProp1 %%}

{%%Prop:Band:BandProp2%%}

{%% Custom-prop: Track: TrackProp2 %%}

{%% custom-property: Clip: ClipProp1 %%}

{%% custom-property: MessageClip: ClipProp1 %%}

{%%Custom-property:destination:TargetProp1%%}

{%%Custom-property:desTination:TargetProp2%%}

{%%Custom-Property:message:Message1Prop1%%}

{%% sys-prop : destination : HostName %%}

{%%sys-Prop:Destination:ServicePath%%}

{%% Sys-property: desTination: Port %%}

{%% sys-property : destination : UseSSL %%}

{%%sys-Property:Destination:UserName%%}

{%% system-property : destination : URL %%}

{%% system-property : clip : Delay 5/Duration %%}

{%% eXpr: "Hello, world!" %%}

{%% eXpression: 10 + 20 + 30 %%}

{%%prop:composition:Band 1/BandProp2%%}

{%%prop:band:../Band 2/Band2Prop1%%}

{%%prop:band:Track 1/TrackProp2%%}

{%%prop:track:Clip 021/ClipProp2%%}

{%%prop:track:../../Band 1/Track 1/TrackProp1%%}

{%%prop:track:../Track 2/Track2Prop2%%}

{%%prop:clip:Message 2/Message2Prop2%%}

{%%prop:clip:../Track 1/Clip 021/ClipProp2%%}

{%%prop:clip:../../../Band 1/Track 1/Clip 021/ClipProp1%%}

{%%prop:message:../Message 2/Message2Prop2%%}

{%%prop:message:../../Clip 021/Message 2/Message2Prop2%%}

{%%prop:message:../../../Track 1/Clip 021/Message 2/Message2Prop2%%}

{%%prop:destination:../Message 2/TargetProp2%%}

{%%prop:destination:../../Clip 021/Message 2/TargetProp2%%}

{%%prop:destination:../../../Track 1/Clip 021/Message 2/TargetProp2%%}

{%%prop:clip:Target 021 local name/TargetProp2%%}

{%%prop:track:Clip 021/Target 021-2 local name/TargetProp2%%}

{%%prop:band:Track 1/Clip 021/Target 021 local name/TargetProp2%%}

{%%prop:composition:Band 1/Track 1/Clip 021/Target 021 local name/TargetProp1%%}

{%% global-prop: Property A %%}

{%%global-property: Default/Counter 1%%}

{%%global-system-property: My list 3/My Counter 2%%}

Attachments

    Outcomes