<assign property="propertyname" value="expression" />
|Attribute or Element||Description||Value|
|property attribute||Required. The target of this assignment. This must be a property in an execution context object, usually context, request, response, callrequest, or callresponse. For details, see the table in the Description topic, below.||A string of one or more characters.|
|value attribute||Required. Value of the property.||A literal value, or an expression that returns a valid value for the property. If this is an expression, it must use the scripting language specified by the containing <process> element.|
|action attribute||Optional. If property is a collection (list or array), use action to specify the type of assignment to perform on the collection. If not specified, a “set” is performed.||A literal string, either “append”, “ set”, “clear”, “insert”, or “remove” as described below.|
|key attribute||Optional, except in some cases when property is a collection (list or array). If so, you must use this key to specify the member of the collection that is the target of this assignment.||An expression that evaluates to a key.|
|name, disabled, xpos, ypos, xend, yend attributes||See “Common Attributes and Elements.”|
This topic describes the importance of the execution context to BPL business processes, and explains how to use the <assign> element to set values in the business process execution context.
A business process must have certain state information saved to disk and restored from disk, whenever it suspends or resumes execution. This feature is especially important for long-running business processes, which may take days or weeks to complete. To address this need, InterSystems IRIS provides every BPL business process with a group of objects and variables called the execution context. The variables in the execution context are automatically saved and restored each time the BPL business process suspends and resumes execution. The correct operation of a BPL business process depends on the appropriate use of these variables.
Every variable in the execution context has a specific name and purpose, and can have its value set using the <assign> element. The following table lists the variables in the execution context.
|callrequest||The callrequest object contains any properties that are required to build the request message object to be sent by a <call>. Within the corresponding <request> activity, use a sequence of <assign> elements to set the property values in callrequest.|
|callresponse||Upon completion of a <call> activity, the callresponse object contains the properties of the response message object that was returned to the <call>. Within the corresponding <response> activity, use a sequence of <assign> elements to copy the returned values from properties on callresponse into properties on context or response.|
|context||The context object is a general-purpose data container for the business process. context has no automatic definition. To define properties of this object, use the <context> element. That done, you may refer to these properties anywhere inside the <process> element using dot syntax, as in: context.Balance|
|request||The request object contains any properties of the original request message object that caused this business process to be instantiated. You may refer to request properties anywhere inside the <process> element using dot syntax, as in: request.UserID|
|response||The response object contains any properties that are required to build the final response message object to be returned by the business process. You may refer to response properties anywhere inside the <process> element using dot syntax, as in: response.IsApproved. Use the <assign> element to assign values to these properties.|
|status||status is a value of type %Status that indicates success or failure. As the BPL business process runs, if at any time status acquires a failure value, InterSystems IRIS immediately terminates the business process and writes a text message to the Event Log indicating the reason for failure. In general, this happens automatically, when unsuccessful values are returned from <call> activities. However, BPL business process code can initiate a sudden, but graceful exit by setting the status value using <assign> or <code>. See the description at the end of this topic.|
|syncresponses||syncresponses is a collection of response objects, keyed by the names of the <call> activities being synchronized. Only completed calls are represented. You can retrieve a response from syncresponses only after a <sync> and before the end of the current <sequence>. Do so using the syntax syncresponses.GetAt("MyName") where the relevant call was defined as <call name="MyName">|
The synctimedout value is an integer. synctimedout indicates the outcome of a <sync> activity after several calls. You can test the value of synctimedout after the <sync> and before the end of the <sequence> that contains the calls and <sync>. synctimedout has one of three values:
Generally you will test synctimedout for status and then retrieve the responses from completed calls out of the syncresponses collection.
Like all other execution context variable names, status is a reserved word in BPL. Do not use it with <assign> except as described above.
The BPL <assign> element specifies a target and an expression that will be assigned to it. The target may be a property in one of the objects in the business process execution context, or it may be one of the single-valued variables such as status. The properties involved in an <assign> element can be data types, objects, or collections of either. Collection properties are declared by setting the collection attribute to “array” or “list” in the corresponding <property> element.
As described in the above table, the object called context serves as a general-purpose context object for the business process. Properties in the context object are defined using the <context> and <property> elements at the beginning of the <process> environment. For example:
<process request="Demo.Loan.Msg.Application" response="Demo.Loan.Msg.Approval"> <context> <property name="CreditRating" type="%Integer"/> <property name="PrimeRate" type="%Numeric"/> </context> ... </process>
The above BPL excerpt defines two context properties for this business process — context.CreditRating and context.PrimeRate — but does not assign values to them. An <assign> element anywhere below this <context> element and within the <process> environment can assign a value to any of these properties as needed. For example:
<process request="Demo.Loan.Msg.Application" response="Demo.Loan.Msg.Approval"> <context> <property name="CreditRating" type="%Integer"/> <property name="PrimeRate" type="%Numeric"/> </context> <sequence> <call name="PrimeRate" target="Demo.Loan.WebOperations" async="0"> <request type="Demo.Loan.Msg.PrimeRateRequest"> </request> <response type="Demo.Loan.Msg.PrimeRateResponse"> <assign property="context.PrimeRate" value="callresponse.PrimeRate"/> </response> </call> ... </sequence> ... </process>
The above BPL excerpt continues the first one. Note that the <call> element in this example is synchronous, and has both a <request> and a <response> element.
The <response> in this case contains an <assign> operation that references two properties on objects inside the execution context: context.PrimeRate (from the general-purpose context object) and callresponse.PrimeRate (from the response object associated with the current <call> element, in this case Demo.Loan.Msg.PrimeRateResponse as you can see above). The <assign> operation receives the value of the PrimeRate property returned from the <call> and places it in the general-purpose context object.
Inside the <sequence> element shown above, and continuing from the <call> element just discussed, the example continues as follows:
<call name="CreditRating" target="Demo.Loan.WebOperations" async="0"> <request type="Demo.Loan.Msg.CreditRatingRequest"> <assign property="callrequest.SSN" value='request.SSN'/> </request> <response type="Demo.Loan.Msg.CreditRatingResponse"> <assign property="context.CreditRating" value="callresponse.CreditRating"/> </response> </call>
The above statements assign the SSN property from the primary request (request.SSN) to the SSN property in the request being made by the current <call> element (callrequest.SSN). After this assignment is made, the <call> element issues the request. It is a synchronous call of type Demo.Loan.WebOperations. When a response returns, the <call> element gets the value of the CreditRating property returned from the <call> (callresponse.CreditRating) and places it in a property on the general-purpose context object (context.CreditRating).
The following statement assigns the integer value 1 to the IsApproved property in the primary response object for the business process (response.IsApproved). In this example, IsApproved is a Boolean value (true or false) according to InterSystems IRIS conventions. That is, an integer value of 1 means true (the applicant was approved), and 0 means false (the applicant was not approved).
<assign name='IsApproved' property="response.IsApproved" value="1"> <annotation> <![CDATA[Copy IsApproved into the response object.]]> </annotation> </assign>
The following statement assigns a calculated value — the result of an expression involving two properties in the general-purpose context object — to the InterestRate property in the primary response object for the business process (response.InterestRate):
<assign name='InterestRate' property="response.InterestRate" value="context.PrimeRate+1+(2*(1-(context.CreditRating/100)))"> <annotation> <![CDATA[Copy InterestRate into the response object.]]> </annotation> </assign>
Types of <assign> Operation
The syntax for the BPL <assign> element works as follows:
The property attribute identifies an object and property that is the target of the assignment operation.
The value attribute provides the value for the target property. This may be an expression that is evaluated at runtime to provide a value for the assignment. Expressions within an <assign> element must use the language specified by the <process> element for the business process.
There are several types of BPL <assign> operation, as specified by the optional action attribute. The allowable values for the action attribute are:
Value Description “append” Add the target element to the end of the list. “set” (Default) Set the target element to a new value. “insert” Insert a new value into the collection. “remove” Remove the target element from the collection. “clear” Clear the contents of the target collection.
Aside from the default value “set”, most of these variations are intended to handle assignments involving collection properties. The various assignment types are summarized in the following table.
|Property Type||action Attribute Value||key Attribute Required||Result|
|Non-collection||“set”||No||Property is set to new value|
|Array||“clear”||No||Array is cleared|
|Array||“remove”||Yes||Element at key is removed|
|Array||“set”||Yes||Element at key is set to new value|
|List||“append”||No||Element is added to the end of the list|
|List||“clear”||No||List is cleared|
|List||“insert”||Yes||Element is inserted at position determined by key|
|List||“remove”||Yes||Element at key is removed|
|List||“set”||Yes||Element at key is replaced|
Details about each type of BPL <assign> operation follow.
The append Operation
The “append” operation adds the target element to the end of a list property.
The set Operation
The “set” operation sets the value of the specified property to the value of the value attribute. Note that the value attribute contains an expression and can itself refer to an object or property of an object within the execution context:
<assign name='CopyResult' property='context.SSN' value='callresponse.SSN' />
If the target property is an array collection, then the value of the key attribute specifies an item in the array, otherwise the key attribute is ignored.
If the target property is a collection and the value attribute specifies a collection of the same type, then the collection contents are copied into the target collection:
<assign name='CopyResults' property='context.List' value='callresponse.List' />
The default action for the assign element is the set operation; if action is not specified, then the assign specifies a set operation.
The clear Operation
This operation applies to collection properties only. The “clear” operation clears the contents of the specified collection property. The value and key attributes are ignored, but since the BPL schema for the <assign> element requires it, a value attribute must be present in the statement.
For example, the following will clear the contents of the collection property List:
<assign name='ClearResults' property='context.List' action='clear' value='' />
The insert Operation
This applies to list collection properties only. The “insert” operation inserts a value into the specified collection property. If the key attribute is present the new value is inserted after the position (an integer) specified by key otherwise the new item is inserted at the end.
For example, the following will insert a value into the array collection property Array using the key “primary”:
<assign name='Ins' property='context.Array' action='insert' key='primary' value='request.Primary' />
The remove Operation
This applies to collection properties only. The “remove” operation removes an item from the specified collection property. The value attribute is ignored, but since the BPL schema for the <assign> element requires it, a value attribute must be present in the statement.
If the target property is an array collection, then the value of the key attribute specifies an item in the array, otherwise the key attribute is ignored.
For example, the following will remove the element with key “abc” from the array property Array:
<assign name='Remove' property='context.Array' action='remove' key='abc' value='' />
Using <assign> to Set the status Variable
status is a business process execution context variable of type %Status that indicates success or failure.
Error handling for a BPL business process happens automatically, without your ever needing to test or set the status value in the BPL source code. The status value is documented here in case you need to trigger a BPL business process to exit under certain special conditions.
When a BPL business process starts up, status is automatically assigned a value indicating success. To test that status has a success value, you can use the macro $$$ISOK(status) in ObjectScript. If the test returns a True value, status has a success value.
As the BPL business process runs, if at any time status acquires a failure value, InterSystems IRIS immediately terminates the business process and writes the corresponding text message to the Event Log. This happens regardless of how status acquired the failure value. Thus, the best way to cause a BPL business process to exit suddenly, but gracefully is to set status to a failure value.
You can use an <assign> element to set status to a failure value. The usual convention for doing this is to use an <if> element to test the result of some prior activity, and then within the <true> or <false> element, use <assign> to set status to a failure value when failure conditions exist.