Linking steps

You can link steps in an import mapping file to reflect relationships between different types of records. For example, step 1 in a mapping file might act on a parent record, such as a work order, while step 2 might act on its children, such as costs. To link the costs to the correct work order, you can make step 2 a child of step 1.

Steps that aren’t linked to other steps are called root steps, while steps that are linked are called child steps. A child step can be linked to a root step, or to another child step. The sample below shows two work orders in an import file. Each work order has associated labor costs, represented by child <Cost> elements.

<WorkOrders>
   <WorkOrder activity="Tuneup" plannedQuantity="2">
      <LaborCosts>
         <Cost hours="5" Employee="1006" />
         <Cost hours="6" Employee="1011" />
      </LaborCosts>
   </WorkOrder>
   <WorkOrder activity="Tuneup" plannedQuantity="5">
      <LaborCosts>
         <Cost hours="4" Employee="1006" />
         <Cost hours="7" Employee="1011" />
         <Cost hours="8" Employee="1252" />
      </LaborCosts>
   </WorkOrder>
</WorkOrders>

The mapping file must import work orders and costs, so there are two business objects involved in this import: the work orders object is Hansen.WorkManagement.WorkOrder, and the labor cost object is Hansen.WorkManagement.LaborCost. The work order key is used to associate each labor cost with its parent work order.

As in the previous example, you use the RootQuery attribute of the <Steps> element to specify an XML element.

<Steps RootQuery="/WorkOrders/WorkOrder">
</Steps>

The first step in the mapping file maps the work order data to the WorkOrder object, as shown below. Again, this is similar to the first example, and again the <Step> element now has a child <Outputs> element. In this case, once the work order is created, the work order key (WorkOrderNumber) is mapped to an output called WONUMBER.

<Steps RootQuery="/WorkOrders/WorkOrder">
   <Step Id="1" 
    TargetBusinessObject="Hansen.WorkManagement.WorkOrder" 
    Action="Create, Update">
      <Outputs>
         <Output Id="WONUMBER" Source="WorkOrderNumber" />
      </Outputs>
      <Mappings>
         <Map Source="@plannedQuantity" Target="PlannedQuantity" />
         <Map Source="@activity" Target="Activity.ActivityCode" />
      </Mappings>
   </Step>
</Steps>

The second step maps the labor costs in the import file to the LaborCost object, as shown below. This time the step has a <Link> element in addition to <Inputs> element.

<Steps RootQuery="/WorkOrders/WorkOrder">
   <Step Id="1" 
    TargetBusinessObject="Hansen.WorkManagement.WorkOrder" 
    Action="Create, Update">
      <Outputs>
         <Output Id="WONUMBER" Source="WorkOrderNumber" />
      </Outputs>
      <Mappings>
         <Map Source="@plannedQuantity" Target="PlannedQuantity" />
         <Map Source="@activity" Target="Activity.ActivityCode" />
      </Mappings>
   </Step>
   <Step Id="2" 
    TargetBusinessObject="Hansen.WorkManagement.LaborCost" 
    Action="Create, Update">
      <Link StepId="1" RelativeQuery="./LaborCosts/Cost" />
      <Inputs>
         <Input VariableId="WONUMBER" Target="WorkOrder.WorkOrderNumber" />
      </Inputs>
      <Mappings>
         <Map Source="@hours" Target="HoursWorked"/>
         <Map Source="@Employee" Target="Employee"/>
      </Mappings>
   </Step>
</Steps>

In this case the <Input> element maps the WONUMBER output from the previous step to the WorkOrderNumber property.

The <Link> element identifies step 2 as a child of step 1 (identified by the StepId attribute). The RelativeQuery attribute of the <Link> element identifies the source of the labor cost data in the import file. Like the RootQuery, the RelativeQuery attribute uses XPath syntax. The child step’s query is relative to the node returned by its parent, so the full XPath query for this step would be /WorkOrders/WorkOrder/LaborCosts/Cost.

Note: The RootQuery attribute is optional. If you don’t enter a Rootquery, you can specify a root step’s XPath query by adding a <Link> element and setting the RelativeQuery attribute without entering a StepId.

During an import, the import processor will process a root step and all its children before moving to the next step.