Service Consumer Builder

Service Consumer Builder

In this topic ...

How Do I...
Specifying Inputs
Objects this Builder Creates

Related Topics ...

Overview: Working with Data Services

This builder works in conjunction with the service definition and service operation builders and is used to provide access to a public service created by those builders in a service provider model. The operations from the service are available through the WebApp Data Service object created by this builder.
This builder generates the code required to support the following two operating modes:

Single Operation Mode In this mode we can select an individual operation made available by a Service Provider model. To invoke the service from this Builder you select by name a Provider model and an operation contained in that model.
Select Mutiple Operation Mode In this mode we can select mutiple operations made available by the Service Provider model. By selecting the operation and selecting the enable operation checkbox for each operation, that operation will be exposed in the service consumer.
All Operations Mode In this mode we can select all operations available in a Service Provider model and call any operation. To invoke the service from a Service Consumer model, reference the Data Service created by the Service Provider.

Once a service is available, to build out a presentation of inputs or results from the service, use builders such as the View & Form builder. That builder lets you specify a Data Service Operation and it automatically finds the input and results variables and creates pages for them. We can also use the Variables and Methods created by Service Consumer with other builders such as Data Page and Action List builders.
For an example of a Service Consumer model, see: samples/gettingstarted/SimpleServiceConsumer.model in the "Tutorials and Samples Applications" Feature Set.

How Do I...

Expose an operation in a Service Provider model and use it in a Service Consumer model?

Create a model that provides functionality that you want to expose as a service. An example might be a method that returns a list of records from a back end database, such as SAP or PeopleSoft. The model should provide a method (that may or may not take arguments) that returns the desired data. The returned data can be directly returned from the method, or placed in a known schema-typed variable.
Add a Service Definition builder to your model and a Service Operation builder for each method you wish to expose. Save and close the Service Provider model.
Next create or open an existing model that you want to have consume the service. In this Service Consumer model add a Service Consumer builder and select the provider model and, optionally, the operation. The Service Consumer builder will add a Data Service and local methods to your model that can be used to invoke the service. The service inputs and outputs will be exposed as Variables.
Finally, add builders to your model to invoke the service operation and process the output. Use a high-level builder, such as the View & Form builder, to invoke a service operation, and display its data. In the View & Form builder, use the "View Method" input to select the Data Service operation DataService/<consumer builder name>/<operation name> (e.g. DataServices/orders/getOrders).

Provide runtime input values to a service operation?

We can provide inputs to a service operation in three ways:
Use the "Inputs" XML variable created in the WebApp - Use this variable with the Data Page builder (or with a higher-level builder such as View & Form) to present the inputs in a web page. This variable is named <builderName><operationName>InputsFor example: contactsUpdateContactInputs
Use the "Input Overrides" option in Service Consumer builder - This is often the most convenient way to "wire" inputs to other runtime values, or to supply predefined input values. For example, if you are presenting a list of results from a service and have another Service Operation that gets detailed information related to one row, we can wire inputs for the "get details" operation to the selected row data of the list results. Any values specified as Input Overrides will take precedence over values from the inputs XML variable.
Call the "WithArgs" method that is generated for the operation - The name of this method is <builderName><operationName>WithArgs For Example: contactsUpdateContactWithArgs. This method has an argument for each of the members of the input structure. When you use this method, your values take precedence over both the inputs variable values and Input Override values.

More How do I... Topics

Specifying Inputs

This builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties input group, see "Using the builder Call Editor."

Input Name Description
Name Enter a name for this builder call. The designer tool displays this name in the builder call list.
This entry is used as the local name of service. If this input is blank or if "Add All Target Methods" is enabled, the target method name will be used.
Provider Model Select a provider model that contains a Service Definition builder you want to use.
Example: samples/gettingstarted/OrdersServiceProvider
Add All Provider Operations Enable to add all the exposed operations from the provider model and make them available to the consumer.
Note that If this input is disabled, select individual operations using the Operation Name input below.
Operation Name This input is available when "Add All Provider Operations" above is disabled. Use this input to select one or more operations from the provider model.
Enable Operation Check this option for each operation listed in the Operations table that should be availabe for this consumer model.
Override Inputs Enable to override one or more input values for any of the service operations.
Note that You must set override values in the "Overridden Inputs" input below.
Overridden Inputs This input table is available when "Override Inputs" is enabled. Use this input table to set override values for service operation inputs. Input values you set here will automatically populate the specified input variable prior to the service operation being invoked.
Note that Values passed to the <buildername><target operation name>WithArgs method will take priority over these overridden inputs.
Rich Data Definition File Use this input to select a rich data definition XML file. This file is optional and, if specified, is applied to all of the schemas picked up from the provider model.
This input allows you to avoid adding a separate Rich Data Definition builder to your model. Use this input to specify an existing XML-based Data Definition File to apply to the Service Consumer schemas.
Using this input is equivalent to adding one or more Rich Data Definition builders to the mode,l and applying them to the schemas related to the service operations.
See the Rich Data Definition builder help for additional information.
Context Variables
Context Variable Values Context Variables are variables in a service model, published by operations using an ID (allowing common/shared types.) A service consumer model looks for these published context variables, and allows values to be set for them.
Select an operation, and then provide a context variable ID and value.
Note that You might want to use context variables if the provider model defines context variables in its Service Operation builder, and you want to supply alternate values for those variables. Assigning values here provides a way for the consumer model to pass information to the provider model without exposing extra parameters to the operation.
Mapping Parameters
Mapping Parameters Use this input to control the behavior of the service mapping registry.
For example in a service mapping registry file you may have a "role" parameter defined, which is used to select the service to use. We can use the mapping parameters to set the role value from data in your model or from a profiled value.
Example:
<!-- Use a mapping parameter named "role" to select implementation for a given service. -| <ForService name="Service1"> <IfParameterEquals name="role" value="manager"> <UseService name="Service1_manager" /> </IfParameterEquals> .....
Advanced
Profile Name Use this input to specify an optional profile name to apply to the provider model selected above. This is useful if the provider model is profiled, and you want to override the default profile selection by specifying another profile.
You specify this value as <profile set name>:<profile name>. We can specify more than one profile by using a comma separator.

Objects Created by the this builder

A variety of WebApp artifacts are created by this builder. These artifacts include the following LJOs, variables, methods and Data Services:

Linked Java objects

<buildername> - LJO that includes helper methods that are used by the generated method to invoke the service operations

Schemas

<buildername><schema from provider> - XSD schema will be created for each of the schema defined by the provider model

Variables

<buildername><target operation name>Inputs - Schema-type input variable used to provide input values to the specified operation

<buildername><target operation name>Results - Schema-type results variable used to hold the result values of the specified operation

Methods

<buildername><target operation name> - Method used to invoke the service without passing arguments.
Note that The <buildername><target operation name>Inputs WebApp Variable should be populated prior to invoking this method.

<buildername><target operation name>WithArgs - Method used to invoke the service, operation passing any required arguments

Data Service

<buildername > - Data Service metadata that provides the name of the operation(s) provided by this builder, and the input/output Variables used by each operation. Relevant property information is also provided.

Input Name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list. This entry is used as the local name of service. If this input is blank or if "Add All Target Methods" is enabled, the target method name will be used.
Provider Model	Select a provider model that contains a Service Definition builder you want to use. Example: `samples/gettingstarted/OrdersServiceProvider`
Add All Provider Operations	Enable to add all the exposed operations from the provider model and make them available to the consumer. Note that If this input is disabled, select individual operations using the Operation Name input below.
Operation Name	This input is available when "Add All Provider Operations" above is disabled. Use this input to select one or more operations from the provider model.
Enable Operation	Check this option for each operation listed in the Operations table that should be availabe for this consumer model.
Override Inputs	Enable to override one or more input values for any of the service operations. Note that You must set override values in the "Overridden Inputs" input below.
Overridden Inputs	This input table is available when "Override Inputs" is enabled. Use this input table to set override values for service operation inputs. Input values you set here will automatically populate the specified input variable prior to the service operation being invoked. Note that Values passed to the <buildername><target operation name>WithArgs method will take priority over these overridden inputs.
Rich Data Definition File	Use this input to select a rich data definition XML file. This file is optional and, if specified, is applied to all of the schemas picked up from the provider model. This input allows you to avoid adding a separate Rich Data Definition builder to your model. Use this input to specify an existing XML-based Data Definition File to apply to the Service Consumer schemas. Using this input is equivalent to adding one or more Rich Data Definition builders to the mode,l and applying them to the schemas related to the service operations. See the Rich Data Definition builder help for additional information.
Context Variables
Context Variable Values	Context Variables are variables in a service model, published by operations using an ID (allowing common/shared types.) A service consumer model looks for these published context variables, and allows values to be set for them. Select an operation, and then provide a context variable ID and value. Note that You might want to use context variables if the provider model defines context variables in its Service Operation builder, and you want to supply alternate values for those variables. Assigning values here provides a way for the consumer model to pass information to the provider model without exposing extra parameters to the operation.
Mapping Parameters
Mapping Parameters	Use this input to control the behavior of the service mapping registry. For example in a service mapping registry file you may have a "role" parameter defined, which is used to select the service to use. We can use the mapping parameters to set the role value from data in your model or from a profiled value. Example: <!-- Use a mapping parameter named "role" to select implementation for a given service. -\| <ForService name="Service1"> <IfParameterEquals name="role" value="manager"> <UseService name="Service1_manager" /> </IfParameterEquals> .....
Advanced
Profile Name	Use this input to specify an optional profile name to apply to the provider model selected above. This is useful if the provider model is profiled, and you want to override the default profile selection by specifying another profile. You specify this value as `<profile set name>:<profile name>`. We can specify more than one profile by using a comma separator.