Service Operation Builder

Service Operation Builder

In this topic ...

Creating an operation based on an integration builder
Specifying Inputs
Objects this Builder Creates

Related Topics ...

Overview: Working with Data Services
Using data services

This builder adds an operation to a service created with the service definition builder. The operation will typically invoke some data access functionality available in the Model. Data access is usually provided by back end integration builders (such as SAP function and SQL call) and can also be provided by a linked Java object or a data-returning method.
For an example of service provider and consumer models, see SimpleServiceProvider and SimpleServiceConsumer models. These models are included in the Tutorials and Samples Applications feature set. Once this feature set is installed, open the WEB-INF/models/samples/gettingstarted/ folder, to access these models.

Creating an operation based on an integration builder

In a model, place a service definition builder identifying the service that will hold the operation. Also place in the model an integration builder (SAP function call, SQL call, Web service call, or Domino view) that can successfully access back-end data.
Next add a service operation builder to the model and, for "Operation Name," enter the name you want to use for your operation. A typical name might look like: findEmployees. In the Service Operation Builder, for "Action To Call" input, look under Data Services for the back end operation. For example, for a SQL Call, this might be something like: employeeSearch/execute.
We can configure the inputs (if any) and results of your operation. To use the same input and result structure as the back end operation you are calling, select "Use Structure From Called Action" for both inputs or results, and leave the Field Mapping choices on "Automatic". See below for information on transforming to a different schema structure.
Note that You must use different techniques when working with Data Services and Methods. For example, Factory integration Builders create Data Service Operations and Methods to support their operations in the WebApp. In the "Action To Call" input, we can select either one, by picking under Data Services or Methods. However, as a general rule, you should select the Data Service Operation rather than the equivalent Method. When you select an operation from Data Services, the Service Operation Builder can access information about the input and output parameters of the operations, including the schema type information. When you select from Methods, specify the schema type for XML inputs or results.
Note that The only supported methods are those with the following types of argument:

no argument
a single IXML argument
one or more simple arguments (String, int/Integer, Double, Boolean,and the like)

So, for example, we cannot use methods that take a Bean argument or that take an IXML argument and one or more simple arguments.

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
Service Operation Properties
Data Service Select a Data Service to which to add an operation.
Note that If this input appears blank, no Data Services exist in the model. Use the Service Definition Builder to create an empty Data Service to which we can add an operation.
Operation Name Enter a name for this operation.
Example: getJanFinancials
Action to Call action that does the main execution for your operation.
Note that If you are calling an action from an integration Builder (such as SQL call or SAP function call), we can select the operation from the Data Services node in the selector.
Operation Description Enter a description of the operation. This text will be visible when using the service in a Consumer model.
Operation Inputs
Input Structure Handling Select the way you want any inputs to your operation to be handled.
We can choose:

Use structure from called action - To use action's input structure. (Available when calling a Data Service Operation (which has a known schema structure) or when calling a method that has one or more simple type arguments.)
Specify input schema - To specify a schema to use for the input
No inputs -If the operation action does not require or accept inputs

Note that Methods and data services are handled differently. See Creating an operation based on an integration builder for more information.
Input Schema This input is available when "Specify input schema" is selected as the Input Structure Handling choice above. Use the selector to select a schema to use for the input structure.
Input Description This input is available when "Specify input schema" is selected as the Input Structure Handling choice above. Enter a description of the input schema. This description will be displayed in the service consumer builder.
Input Field Mapping This input is available if the action you are calling has inputs. You can choose:

Automatic To automatically copy your operation inputs into the called action inputs
Specify input values - To specify the values for each of the called action inputs

Input Field values This table if available if you select "Specify input values" for Input Field Mapping. All input fields for the called operation are listed in the Name column. Use the Value column to assign values to inputs as desired.
Note that The Arguments node in the value selector lists all the fields from your operation's inputs.
Operation Results
Result Structure Handling Select the way you want operation results handled. You can choose:

Use structure from called action - Available only when calling a Data Service Operation. When calling a method, we need to specify the result structure.
Specify result schema - To specify a schema to use for the result
No inputs -If the operation action does not require or accept inputs

Note that Methods and Data Services are handled differently. See Creating an operation based on an integration builder for more information.
Result Schema This input is available when "Specify result schema" is selected as the Result Structure Handling choice above. Use the selector to select a schema to use for the result structure.
Result Description This input is available when "Specify result schema" is selected as the Result Structure Handling choice above. Enter a description of the result schema. This description will be displayed in Service Consumer Builder.
Result Field Mapping This input is visible only if your operation has results. We can choose:

Automatic - To automatically copy the called action results into your operation results
Specify Result Values - To specify the values for each of your operation result fields.

Result Field Values This input is available if you select "Specify result values" for Result Field Mapping. All result fields for the called operation are listed in the Name column. Use the Value column to assign values to results as desired.
Note that All fields from the results of the action you are calling are listed in the "Results" section of the value picker.
Result Caching
Enable Caching of Service Results Enable to automatically cache the operation results.
Note that This input uses the functionality provided by the Cache Control Builder. Refer to that Builder's Help page for additional information.
Refresh Interval Enter an interval (in seconds) used to refresh service results.
Additional Processing
Pre-Execute Support This input is used to call other code when your operation is executed, just before the called action is invoked. See Creating an operation based on an integration builder for more information. We can choose:

None - To disable Pre-Execute support.
Fire Event - To fire an event called: <operationname>PreExecute
Specify Method -To specify the name of a method tor Pre-Execute handling

Per-Execute Method This input is available when "Specify Method" is selected as the Pre-Execute Support choice above.
Specify the method to run that provides pre-execute support.
Post-Execute Support This input is used to call other code when your operation is executed, after the called action returns. See Creating an operation based on an integration builder for more information. We can choose:

None - To disable Post-Execute support.
Fire Event - To fire an event called: <operationname>PostExecute
Specify Method - To specify the name of a method tor Post-Execute handling.

Post-Execute Method This input is available when "Specify Method" is selected as the Post-Execute Support choice above. Specify the method to run that provides post-execute support.
Error Handler Method Specify an Error handler method to attach to the operation. This method is called when an exception is thrown during operation execution.
Note that The error handler method must take no arguments. See Error handler builder for information about including detailed exception information in your handler method.
Context Variables
Arguments We can use this optional input to publish values that can be referenced in a Consumer model (from the Service Consumer Builder). Any context values that are specified in the Consumer are then pushed into the corresponding service model instance variables just before the operation is invoked.
Context Variables are published using an ID (allowing common/shared types.) The Service Consumer Builder looks for published context variables, and allows values to be set for them.
Paging Options
Page Enable Option Select one of these options to support implementing pageable resource solutions.

Default - Uses the setting from the data source. Currently SQL Call Builder and the Domino View & Form Builder provide implementations for pageable data resources.
No Paging - If data source is set to paging, use this option to turn off the paging feature
Page Enable - Supports paging a data resource.

Objects created by the this builder

A variety of WebApp artifacts are created by this Builder. These artifacts include the following linked Java objects, variables, methods and data services:

Variables

<operationname>Inputs Schema-typed variable that contains operation's inputs

<operationname>Results Schema-typed variable that contains operation's results

Methods

<operationname>Execute Main method used to execute operation

Data Services

An Operation with the specified Operation Name is added to the specified Data Service

Input Name	Description
Service Operation Properties
Data Service	Select a Data Service to which to add an operation. Note that If this input appears blank, no Data Services exist in the model. Use the Service Definition Builder to create an empty Data Service to which we can add an operation.
Operation Name	Enter a name for this operation. Example: `getJanFinancials`
Action to Call	action that does the main execution for your operation. Note that If you are calling an action from an integration Builder (such as SQL call or SAP function call), we can select the operation from the Data Services node in the selector.
Operation Description	Enter a description of the operation. This text will be visible when using the service in a Consumer model.
Operation Inputs
Input Structure Handling	Select the way you want any inputs to your operation to be handled. We can choose: Use structure from called action - To use action's input structure. (Available when calling a Data Service Operation (which has a known schema structure) or when calling a method that has one or more simple type arguments.) Specify input schema - To specify a schema to use for the input No inputs -If the operation action does not require or accept inputs Note that Methods and data services are handled differently. See Creating an operation based on an integration builder for more information.
Input Schema	This input is available when "Specify input schema" is selected as the Input Structure Handling choice above. Use the selector to select a schema to use for the input structure.
Input Description	This input is available when "Specify input schema" is selected as the Input Structure Handling choice above. Enter a description of the input schema. This description will be displayed in the service consumer builder.
Input Field Mapping	This input is available if the action you are calling has inputs. You can choose: Automatic To automatically copy your operation inputs into the called action inputs Specify input values - To specify the values for each of the called action inputs
Input Field values	This table if available if you select "Specify input values" for Input Field Mapping. All input fields for the called operation are listed in the Name column. Use the Value column to assign values to inputs as desired. Note that The Arguments node in the value selector lists all the fields from your operation's inputs.
Operation Results
Result Structure Handling	Select the way you want operation results handled. You can choose: Use structure from called action - Available only when calling a Data Service Operation. When calling a method, we need to specify the result structure. Specify result schema - To specify a schema to use for the result No inputs -If the operation action does not require or accept inputs Note that Methods and Data Services are handled differently. See Creating an operation based on an integration builder for more information.
Result Schema	This input is available when "Specify result schema" is selected as the Result Structure Handling choice above. Use the selector to select a schema to use for the result structure.
Result Description	This input is available when "Specify result schema" is selected as the Result Structure Handling choice above. Enter a description of the result schema. This description will be displayed in Service Consumer Builder.
Result Field Mapping	This input is visible only if your operation has results. We can choose: Automatic - To automatically copy the called action results into your operation results Specify Result Values - To specify the values for each of your operation result fields.
Result Field Values	This input is available if you select "Specify result values" for Result Field Mapping. All result fields for the called operation are listed in the Name column. Use the Value column to assign values to results as desired. Note that All fields from the results of the action you are calling are listed in the "Results" section of the value picker.
Result Caching
Enable Caching of Service Results	Enable to automatically cache the operation results. Note that This input uses the functionality provided by the Cache Control Builder. Refer to that Builder's Help page for additional information.
Refresh Interval	Enter an interval (in seconds) used to refresh service results.
Additional Processing
Pre-Execute Support	This input is used to call other code when your operation is executed, just before the called action is invoked. See Creating an operation based on an integration builder for more information. We can choose: None - To disable Pre-Execute support. Fire Event - To fire an event called: `<operationname>PreExecute` Specify Method -To specify the name of a method tor Pre-Execute handling
Per-Execute Method	This input is available when "Specify Method" is selected as the Pre-Execute Support choice above. Specify the method to run that provides pre-execute support.
Post-Execute Support	This input is used to call other code when your operation is executed, after the called action returns. See Creating an operation based on an integration builder for more information. We can choose: None - To disable Post-Execute support. Fire Event - To fire an event called: `<operationname>PostExecute` Specify Method - To specify the name of a method tor Post-Execute handling.
Post-Execute Method	This input is available when "Specify Method" is selected as the Post-Execute Support choice above. Specify the method to run that provides post-execute support.
Error Handler Method	Specify an Error handler method to attach to the operation. This method is called when an exception is thrown during operation execution. Note that The error handler method must take no arguments. See Error handler builder for information about including detailed exception information in your handler method.
Context Variables
Arguments	We can use this optional input to publish values that can be referenced in a Consumer model (from the Service Consumer Builder). Any context values that are specified in the Consumer are then pushed into the corresponding service model instance variables just before the operation is invoked. Context Variables are published using an ID (allowing common/shared types.) The Service Consumer Builder looks for published context variables, and allows values to be set for them.
Paging Options
Page Enable Option	Select one of these options to support implementing pageable resource solutions. Default - Uses the setting from the data source. Currently SQL Call Builder and the Domino View & Form Builder provide implementations for pageable data resources. No Paging - If data source is set to paging, use this option to turn off the paging feature Page Enable - Supports paging a data resource.