Creating distributed mappings

The information in this topic is applicable only for on-premises deployments.

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.

The mapping used in a distributed operation is selected according to the order of precedence, as defined in the following table. A field or combination of fields takes precedence as long as no field of higher precedence contains a value.

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. 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. 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. 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 in the topic Distributed-transfers. 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 in the topic Distributed-transfers. 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.) 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 the topic Managing-request-IDs-in-distributed-environments). 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 form definitions 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 Monitoring-and-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 the sections that follow.
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 the sections that follow.
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.

To set up automatic mapping

Automatic mapping is typically used to map transfers between identical forms.

1. Open the distributed mapping in the Distributed Mapping editor.
2. Ensure that the information in the Basic and Options panels of the Distributed Mapping editor is correctly specified.
3. In the  Transfer to Target  or  Return   from Target  panel, click  Auto Map .
4. In the Auto Map dialog box, select an automatic mapping method:
   • Match IDs—Maps fields on the source form to fields on the target form that have the same field IDs. If you later add fields with matching IDs to both forms, BMC Remedy AR System automatically maps them to each other.
   • Match Names—Maps fields on the source form to fields on the target form that have the same field names. If you later add fields with matching names to both forms, BMC Remedy AR System automatically maps them to each other.
5. To prevent BMC Remedy AR System from mapping certain fields, select the fields in the Auto Map table's Field column, and click Remove.

6. Click OK.
   The mapped fields appear in the table on the Transfer or Return panel.

   If you are not creating mapping between identical forms, ensure that no unwanted unmapped fields exist on the forms.

7. To customize any of the mappings listed in the table or to add custom mappings, see the procedure below.

To add a field in the excluded fields list

For the Like Field IDs or Like Field Names mapping type, you can select a list of fields that you want to exclude from mapping. DSO avoids mapping these fields for the DSO transfer or return action. After the mapping is configured, if a new field gets added, it gets mapped automatically, unless it is present in the excluded fields list.

You can use the excluded fields list for both DSO transfer and DSO return actions.

1. Open the distributed mapping in the Distributed Mapping editor.
2. Ensure that the information in the Basic and Options panels of the Distributed Mapping editor is correctly specified.
3. In the Transfer to Target or Return from Target panel, select Like Field IDs or Like Field Names, and click Add.
4. In the Object Selector, select the fields that you want to exclude from mapping, and click OK.
   The excluded fields appear in the table on the Transfer to Target or Return from Target panel.

To create custom mapping

Use custom mapping in these situations:

• The source and target forms contain fields whose IDs and names do not match.
• You want to use keywords, static values, arithmetic operations, functions, or processes based on the values of one or more fields in the source form to populate a field in the target form.

1. Open the distributed mapping in the Distributed Mapping editor.
2. Ensure that the information in the Basic and Options panels of the Distributed Mapping editor is correctly specified.
3. Open the Transfer to Target or Return from Target panel.
4. Perform one of these actions:
   • To add a custom mapping, click the first empty Field cell, and then click the cell's ellipsis button.
   • To customize an existing mapping, click the mapping's Field cell, and then click the cell's ellipsis button.
5. In the Field Selector dialog box, select a field in the To (target) form, then click OK.
6. In the same table row, click the Value cell, and then click the cell's ellipsis button.
7. In the Expression Editor, specify one of the following items from which to derive a value in the source form to pass to the target field specified in step 4:
   • Field in the From (source) form
   • Keyword
   • Static value
   • Arithmetic operation
   • Function
   • Process

   • Distributed logical mapping

     This option shows the logical strings that can be used for custom mapping. For more information, see Distributed-logical-mapping.

     When specifying field mappings in the Expression Editor, ensure that the values you enclose in dollar signs ($) do not match strings used as keywords (unless you want to map a keyword value). For example, if you have a field named OS (short for "Operating System") and specify the field mapping as $OS$, map the value for the keyword OS (in this case, your operating system) instead of the preferred field value. For more information, see Keywords.
     

     Important

     Always map the source and target Request ID fields to each other. If you do not, the system creates a new ID on the target server for the transferred request. If you use matching qualifications, you must also map the fields used in the qualification to uniquely match one request with another.

8. Repeat steps 3 through 6 for each field that you want to map.
9. To delete a mapping from the table, select the Field value, press Delete, then s.
10. Save your changes.