Composited Add

In this Lesson

You will

  • Learn how multiple agents can be composited into a single add operation
  • Observe how the composited agents acts as a single unit
  • Learn how the scheme is used to communicate with the Pump
  • Perform an add operation that involves 2 agents


Multiple agents may participate in an add mode operation. Add mode processing proceeds as follows

  1. All agents are asked to validate their data. If any errors are produced then add processing stops and the errors are returned to the client.
  2. If there are no validation errors then each agent is asked to perform their add operation.
  3. If an agent is missing a key for their data they will wait around until all the other agents have completed their add operations.
    [ I hope someone brought my key to the party or else I think I’m going to be sick ]
  4. When an agent provides a key that is needed by some other agent the Pump will push the key to the waiting agents.
    The waiting agents are then re-invited to perform their add operation.
  5. If all agents complete their add operation successfully then a database commit is performed.
  6. If any of the agents fails to complete their add operation then a database rollback is performed.

Agent Add Mode Processing

Each agent that performs an add mode operates like this

Agents are more like event handlers than actual programs.
  1. The agent collects the information into it’s scheme. This can be accomplished in three ways
    • Binding nodes to elements in a scene so the customer can enter the information.
    • Subscribing to a context value in the conversation.
      The agent can then move the value from the subscription channel into the scheme node.
    • Keys can be pushed to an agent.
      The agent can then move the pushed value into the scheme node.
  2. Validation is performed on the values in the scheme.
  3. Values are moved from the scheme to the datasource.
  4. The datasource is asked to insert the values into the table.

Agents that do not use a datasource would simply have alternate ways to store information in the last two steps.

Agents are not in control
The agent does not control when these actions occur. The Pump tells the agent when to validate, when to insert the row, etc. The agent simply responds to requests from the Pump.
Commit Free Zone
Agents should generally not ask the database to commit or rollback. Why? Because they don’t know if some other agent may also be participating in the unit of work.

Consider the PartyTheme Agent

The PartyTheme agent that you created will be used to add the party’s theme to the ACME PartyTheme table.

This agent has two nodes for which it must obtain values in order to perform an add operation.

  • The partyTheme node will be bound to a scene element so the customer may enter the party theme.
  • The partyId node is an interesting case
    • It will not be bound to a scene element because the customer does not enter a party ID. A party ID is a system generated identifier.
    • This agent cannot generate the party ID because it is not responsible for creating new parties. This agent simply collects information about an existing party.

How does the agent get the Party ID?
The partyId is the unique key for the values in the ACME PartyTheme table. For this reason the partyId is also marked as a key in the agent.

Because partyId is a key the Pump will give this agent a partyId if some other agent in the conversation creates one.

So, this agent simply needs to take partyId it receives and store it in the partyId scheme node.

[ wait just a minute … the agent has the party_id designated as ‘Create’ but you said it does not generate the party Id! ]
The ‘Create’ column in the context section seems to indicate the agent creates a partyId. It would be more precise to say the agent is responsible for the partyId. This agent creates, or owns, the key that is placed into the ACME PartyTheme table – from an ACME perspective.

How the Pump and Agent Share Information

The scheme is the agent’s public contract, or interface. It is used by the designer in the scene editor and it is also used by the Pump. Each scheme may have up to four different storage areas – three of which are used to exchange information between the agent and the Pump.

  • Nodes are used to communicate with the client and scene editor.
  • Keys are exchanged between the Agent and Pump.
    The key specifies what the agent is currently focused on. In this example the agent focuses on a specific party.
  • Subscribed values
    The Pump provides the current context as subscribed values before running an agent.
  • Published values
    The agent may request a change in context. The topic does not change immediately: the pump will process the requests at the right time.

Prepare the Agent for a composited add

  1. Open the file

  2. Open the Override/Implement Methods dialog

  3. Expand the Agent class node and select provideDefaultKeyValueForAdd

  4. Add this syntax to the end of the provideDefaultKeyValueForAdd method
    //get the key (passed to the agent's scheme by the pump )
    //store the value on the partyId scheme node
  5. The file should now look like this

  6. Save the file.
Matching Names
The customization you did in the provideDefaultKeyValueForAdd method is not really required in most cases. If the name of the context key matches the name of the scheme node then the generated code will move the key to the scheme for you. The names do match in this agent so you could remove this customization and the agent will still work. We simply wanted you to be aware of this method and how it is used.

Prepare the scene for a composited add

  1. Open the PartyDefinition scene
  2. Select the add layer
  3. Make the Create a Party container taller by dragging the top edge up.
  4. Select all the elements below the location.
    Right click and drag a selection area around the elements.

  5. Move the selected elements down to make room for a theme field under the location.

  6. Add a label and text field for the party theme

  7. Bind the PartyTheme agent to the layer

  8. Save the scene

Test the Scene

  1. Start the solution
  2. Advance to the add layer
  3. Provide all the required values except for the party theme and then press OK
    Notice how the error coming from the PartyTheme agent causes processing to stop for all agents.
    [ wow! they really do act like they are a single service. are you sure the agents cannot see each other? ]

  4. Provide a theme and then press OK.

  5. The party has been added by the Party agent

  6. Use DBeaver to confirm everything worked properly

The design change required for the ACME tenant is nearly complete. We extended the data model to meet their needs without changing the core agents or data model.

What remains is to have the theme input field appear only when the ACME tenant is using the product. That piece of work will be accomplished in a future lesson.

That’s all for this lesson.