How the Service Wizard works
Summary
The Service Wizard generates rules and data objects for services that do one of the following tasks:
- Create and manage work
- Invoke existing activity rules
- Process input or output data
The Service Wizard displays a sequence of forms that you fill out to define the service rules and the supporting data objects for a service of that type. When you are finished, the Service Wizard displays the values you specified and allows you to review and modify the values of those settings before it creates the rules.
Quick Links
Supported service types
You can use the Service Wizard to create the following types of service rules only:
- EJB
- File
- Java
- JMS
- JSR 94
- MQ
- .NET
- SOAP
- HTTP
For email services, you use the Email Accelerator. See About Email for links to articles that describe how email services work and how to set them up.
For portlet, BPEL, COM, and CORBA services, you create the rules and data objects manually. For information about creating portlet services, see About JSR 168 Portlet Services.
Service activities
Two standard service activities are available for the services generated by the Service Wizard.
- svcAddWorkObject, which creates the work object and starts the flow. It is the standard service activity for services that create new work items.
- svcPerformFlowAction, which identifies the work object and then calls the flow action. It is the standard service activity for services that perform a flow action on a work object.
A service does not have to create new work objects or perform a flow action; it can invoke any service activity that you choose. If the service activity does not already exist, the Service Wizard generates a stub activity that you can then edit as necessary.
Mapping request, response, and activity parameters
Data mapping defines the relationships between parameter-value pairs in external systems and property-value pairs on Process Commander clipboard pages. When you create a service rule manually, you specify where the incoming data is mapped to and where the outgoing data is mapped from. When you use the Service Wizard, the wizard assembles a list of input and output parameters, which includes the following:
- Request and response parameters — the external system that makes the request provides values for request parameters, and the service uses response parameters to create the reply. These parameter-value pairs are mapped to and from properties on clipboard pages or parameters on the activity parameter page: for example, a work object description for a new work object, or the work object ID of an existing work object.
- Default activity parameter values — the choices you make when you use the accelerator determine the default values of the activity parameters; for example, the name of the flow or the flow action to be invoked are set in the list of default parameter values in the service rule.
The input and output lists are different, depending on the purpose of the service – whether it creates a work item, completes a flow action on a work item, or calls an activity. You can accept the suggestions that the Service Wizard provides or clear them.
After choosing the input and output parameters for your service, you select one of two data mapping options:
- Use XML for data mapping. To choose this option, select the Use XML for Mapping Data check box, located on the Accelerator's Customize Service Data form.
- Use the default data mapping. To choose this option, leave the Use XML for Mapping Data check box blank.
If you use XML for data mapping, the Accelerator creates an XML mapping rule that maps each input and output property that you select to or from a stream of XML tags. The XML tags have the same names as the properties that they map to.
The type of mapping rule that the Accelerator creates depends upon the service type you are generating and whether the XML data is part of the request (inbound data) or the response (outbound data):
- For a SOAP service, this option creates a model rule for either the request or the response data. The model uses XML page semantics that are specific to SOAP services.
- For any other type of service, this option generates XML parse rules for request data or XML stream rules for response data.
If you use the default data mapping, each data mapped parameter appears on either the Request or the Response tab of the generated service rule.
Note: For additional information about data mapping, see also Data Mapping XML.
Create and Manage Work
When the purpose of a service package is to create and manage a work object, the Service Accelerator generates a list of possible input and output properties. This list contains:
- All properties from the Work class.
- Any properties inherited from the classes that the Work class derives from.
- Any properties referenced from the HTML, section, flow action, and validation rules.
The list does not contain any properties from the standard RuleSets, unless those properties are referenced in the HTML, section, flow action or validation rules.
The Service Accelerator selects required properties by default. You can manually select any additional values that you want to pass between Process Commander and the external system.
Create Work
When you choose to generate a service that creates a work object, the Service Accelerator generates a list of possible input properties. This list contains:
- Any properties referenced in the section or HTML rules that are included in your instance of the New harness.
- Any properties from the OnAdd or Validate validation rules.
The Service Accelerator selects required properties by default. Required properties from the flow action, section, and validation cannot be cleared.
Data Mapping for Services that Create or Manage Work
By default, the Service Accelerator maps data from the primary page. However, services that create and/or manage work objects can also map data from the newAssignPage. This allows the calling application to get a list of actions that can be performed next. The Return Process Info XML option, available on the Accelerator's Customize Service Data form, creates this list of actions.
The Return Process Info XML Checkbox
If you choose Create and Manage Work as your service purpose, the Accelerator displays the Return Process Info XML check box on the Customize Service Data form. When you select this check box, the Service Accelerator returns an XML stream of properties containing information about the work object's state after the service activity has finished processing. The properties that contain this information are part of the Code-ProcessOutput-Service class, and are written to a clipboard page named svcOutput.
The following properties provide useful information when you are creating multiple services that are to be invoked in a specific sequence:
Property Name | Property Mode | Description |
|---|---|---|
pyStatus | Single Value | The status of the action that was just performed. If the action was processed successfully, pyStatus has a value of "success". If the action could not be processed, pyStatus has a value of "fail". |
pyErrors | Embedded Page | A list of error messages describing the circumstances of the action's failure. |
pyWorkObjectHandle | Single Value | The work object's unique identifier. pyWorkObjectHandle is equivalent to pzInsKey. |
pyWorkObjectStatus | Single Value | The current status of the work object. |
pyProcessState | Embedded Page | Contains information about the process, including a list of valid actions that can be performed on the work object. |
Perform an Action on a Work Object
When the purpose of the service rule is to perform a flow action on an existing work item, the input list on the Customize Service Data form includes:
- Any properties referenced from the flow action.
- Any properties referenced from HTML or section rules that are included in the flow action.
- Properties referenced from any validation rule used by the flow action.
The Service Accelerator selects required properties by default. Required properties from flow action, section, or validation rules cannot be cleared.
In addition, the Accelerator adds the following parameters to the input list. The parameters appear in the generated service rule, but not on list of inputs on the Customize Service Data form.
- The flowName parameter from the svcPerformFlowAction service activity. The flowName parameter specifies the subscript of the flow that the flow action belongs to. Since multiple flows can be started on a single work object, this parameter identifies which flow is being processed. This value is typically contained in the response data of a previous service invocation.
- The workHandle parameter from the svcPerformFlowAction service activity. The workHandle parameter specifies the unique instance of the work object to perform the action on. This value is typically contained in the response data of a previous service invocation.
Call an Activity Rule
When the purpose of the service rule is to call an activity, the input list includes:
- All properties from the activity class.
- Any properties inherited from classes that the activity class derives from.
- Any input parameters listed on the Parameters tab of the activity. If no activity parameters are listed on theParameters tab, no parameters appear in the input list.
The list does not contain any properties from the standard standard Pega- RuleSets.
The Service Accelerator selects required parameters by default. You cannot clear required parameters, but you can select additional parameters for the generated service.
Outbound data mapping includes the activity class properties and output parameters that are listed on theParameters tab.
Process Input or Output Data
When the purpose of the service rule is to map data to or from the clipboard, the input and output lists include:
- All properties from the data class.
- Any properties inherited from classes that the data class derives from.
The list does not contain any properties from the standard Pega- RuleSets.
Use the check boxes on the Customize Service Data form to choose the data that you want to pass between the external system and Process Commander.
Unlike the other service purposes, Process Input or Output Data generates a single service rule, plus a stub service activity that you can modify after you have run the accelerator. Configure the stub service activity to use the mapped input data to perform some action, and to populate the clipboard properties that will be returned in the mapped output fields.
Results
After you have entered data in the forms, the accelerator lists the data you entered so that you can review it. For services of type .NET, and SOAP, the accelerator then generates deployment files — a.wsdl file — after you click Finish. If you created a service that creates or manages work and you chose the Use XML for Mapping Data option, the accelerator also creates an XML schema.
To make changes to the service rule or the supporting data objects immediately after you complete the Service Accelerator flow, click the Open icon next to the item that you wish to update. This opens the generated rule or data object.
To find service rules or packages at a later time, use the Integration page of the Developer portal to browse for the rule or package. If you know the name of the rule or service package, you can also use the Find field to locate it.
Previous topic Using the Service Wizard Next topic Before you run the Service Wizard