Creating distributed mappings

This section contains information about:

• Setting up automatic mapping
• Using the excluded fields option
• Creating custom mapping

For each server involved in ownership transfers and returns, you must define a separate, compatible distributed mapping. That is, to transfer requests with ownership from server 1 to server 2 and to return them with ownership from server 2 to server 1, you must have a distributed mapping on both servers.

To create a distributed mapping

1. In Developer Studio, select File > New > Distributed Mapping.
2. Select the server on which to create the mapping, and click Finish.

3. In the Basic panel of the Distributed Mapping editor, enter the following information, then select File > Save.

   Field	Description
   State	Specifies the availability of the mapping: Enabled (default) — Can be used. Disabled — Cannot be used.
   Default Mapping	When selected, specifies that the mapping is the default mapping. When the DSO action in a filter or escalation does not specify a mapping, the default mapping is used. See Creating workflow to perform DSO operations. For any pair of From and To servers and forms, only one distributed mapping should be specified as the default. If two or more are specified as defaults, the system selects the mapping that was created first when a mapping is not specified in a DSO action.
   From
   Server Name	Specifies the name of the server from which the distributed operation is initiated (the source server). You can enter or select any server on which you are a valid user. You can also select a logical server name that has already been defined. To create or edit a logical mapping, see Enabling logical mappings. Note You can specify a server name other than the default server name for distributed operations. For example, your operating environment might require you to use the fully qualified domain name (FQDN) for your server. See Specifying a DSO host name. Warning This field is limited to 64 characters. If the server name exceeds that limit, it is truncated, and the distributed operation fails. This is most likely to occur when you select the following Allow Any Server in Server Group option. In that case, this field must contain the server name alias, which is specified in the Server-Name option of the AR System server configuration file.
   Allow Any Server in Server Group	Specifies that the mapping can use any server in the group as the From server. See Configuring DSO for a server group. Available only when the server is in a server group. Note When you select this option, the From Server Name field must contain the server name alias, which is specified in the Server-Name option of the AR System server configuration file.
   Form Name	Specifies the name of the form from which the distributed operation is initiated (the source form). Enter the form name, or click the ellipsis button to use the Form Selector.
   To
   Server Name	Specifies the name of the server to which the transfer is mapped and from which update and return operations occur (the target server). You can enter or select any server on which you are a valid user. You can also select a logical server name that has already been defined. To create or edit a logical mapping, see Enabling logical mappings. Note This field is limited to 64 characters. If the server name exceeds that limit, it is truncated, and the distributed operation fails.
   Form Name	Specifies the name of the form to which the distributed operation is mapped (the target form). Enter the form name, or click the ellipsis button to use the Form Selector.

4. In the Save Distributed Mapping As dialog box, enter a name for the mapping.
   Distributed mapping names can include up to 80 characters, including spaces. In the Options panel of the Distributed Mapping editor, enter the following information, then save your changes.

   Field	Description
   When to Update	Specifies the update frequency for the original request if a copy transferred with ownership is updated: Daily — At two minutes past midnight. Hourly — At two minutes past the hour. Immediately — Right after the copy is changed. No Update — Never. On Return — Only when ownership is returned.
   Transfer Mode	Specifies the type of transfer to perform: Copy + Delete — Transfers an independent copy of the request with ownership. If successful, deletes the original in the source form. Data + Ownership — Transfers a copy with ownership inside the ownership chain. The transferred copy becomes the master copy and can be modified in the target form. The original becomes a data-only copy. See Request ownership chains. Data Only — Transfers a data-only copy. The original copy in the source form retains ownership. Independent Copy — Transfers an independent copy with ownership. It is outside the ownership chain of the original copy. See Types of distributed transfers. Note At a minimum, to transfer ownership, the form must have the basic distributed fields.
   Duplicate Request ID Action	Specifies the action that occurs if you transfer a request and the target form already contains a request with the same request ID: Create New — A new request is created on the target server for the transfer. Error — The transfer fails. Overwrite — The transferred request overwrites only the mapped fields on the request on the target server that has the same request ID. (To overwrite all fields, see Overwriting all fields in duplicate requests.) Note If you do not map the Request ID field, the system always creates a new Request ID on the To server for the transferred request.
   Enforce Pattern Matching	Specifies whether to enforce patterns defined in fields on the target form: Yes — The target system pattern checks data sent to the target form. Data transferred to fields on the target form must follow pattern attributes defined in mapped fields on the target form. No — The target system does not pattern check data sent to the target form. For example, suppose you map two character fields. On the target form, the mapped field's Pattern property is set to $LOWER$. On the source form, a user enters uppercase letters in the mapped field. When the system attempts a distributed transfer, the operation succeeds or fails depending on whether you enforce pattern matching. Other field properties are also subject to pattern matching. See the definition for "Pattern" in Field Properties.
   Require Required Fields	Specifies whether to require values in fields defined as required fields on the target form: Yes — The target system does not allow NULL entries in required fields on the target form. Optional fields on the source form must contain data if they are mapped to required fields on the target form. No — The target system allows NULL entries in required fields on the target form except in core fields. For example, suppose you map an optional field on the source form to a required field on the target form. A user enters no data in the optional field on the source form. When the system attempts a distributed transfer, the operation succeeds or fails depending on whether you allow NULL entries in required fields on the target form.
   Match by Request ID	Specifies whether to use request IDs or another qualification to find the correct request in the target form: Selected — Distributed transfers are performed when the request ID in the target form matches the request ID in the source form. Cleared — Target and source data are matched according to the qualification entered in the following Matching Qualification field. For example, if you do not want to use server-specific request ID prefixes to distinguish the requests from one another, you can use this method (see Preventing duplicate request IDs). In this case, use a different data field that uniquely identifies each request to match a target request with a source request.
   Matching Qualification	When the Match by Request ID check box is not selected, specifies the qualification to use to find the correct entry in the target form. If you match by qualification, all formdefinitions used in the qualification should be on the From (source) server. A unique index should be created on the field used to distinguish requests. For more information about qualifications, see Building qualifications and expressions.
   Retries	Specifies the maximum number of times a pending item is retried before the system cancels the item: Forever — The item is retried until its operation succeeds. Only Once — The item is tried one time. If its operation does not succeed, it is not retried. Try for Maximum of — The item is retried throughout the period of time that you specify. See Managing pending distributed operations.

5. In the Transfer to Target panel of the editor, specify how the data in a source form is mapped to a target form for a transfer.
   See these sections:
   • Setting up automatic mapping
   • Using the excluded fields option
   • Creating custom mapping
6. In the Return from Target panel of the editor, specify how the data in a target form is mapped to a source form for an update or a return.
   See these sections:
   • Setting up automatic mapping
   • Using the excluded fields option
   • Creating custom mapping
7. To view, add, and edit Help text for the distributed mapping, use the Help Text property in the Properties tab.
   In most cases, the Help text is simply a description of the mapping. Only AR System administrators and subadministrators who have the mapping open in the Distributed Mapping editor can view and edit the Help.
   See the definition for "Help Text" in Field Properties.
8. To view, add, and edit change history for the distributed mapping, use the Change History properties in the Properties tab, then save your changes.
   For each distributed mapping, AR System automatically records information about the owner, the user who last modified the mapping, and the date of the modification. You can view and modify this information at any time by opening the mapping in the Distributed Mapping editor.
   See the definition for "Change History" in Field Properties.