Create a Mapping Step Using Hub Central

Before you begin

You need:

  • Security role: Hub Central Developer, Hub Central Curator, or any role that inherits any of these. Learn more: Users and Roles

Procedure

  1. Go to the Curate area of Hub Central.
    Learn how.
    1. Go to your Hub Central endpoint.
      Note: Disregard this step if you are working from an on-prem environment. See Step 1b.

      Learn more:

    2. In the icon bar, click the Curate icon ().
      Hub Central - icon bar - Curate
  2. In the list, expand the entity type you want to use.
  3. Click the Map tab, then click the Add New tile.

    Hub Central - Mapping step - Add New
  4. Configure the step's basic settings.

    Hub Central - Mapping step - properties
    Name Description
    Name The name of the step instance.
    Note: The step name is used as part of the names of related assets, as a collection name to tag processed documents, and as metadata in provenance and lineage logs. Therefore, it cannot be changed after the step is created.
    Description(Optional) A description of the step.
    Source Query The collection or CTS query that selects the source data to process.

    Learn more: CTS Query.

  5. Go to the Advanced tab.
  6. Configure the step's advanced settings.

    Hub Central - Mapping step - advanced settings
    Name Description
    Source Database The database from which to take the input data. Choose the STAGING database where you stored ingested data. The default is data-hub-STAGING.
    Target DatabaseThe FINAL database where you want to store mapped data. The default is data-hub-FINAL.
    Target Collections Comma-separated string containing additional collection tags to apply to the processed records. The Default Collections tags are automatically applied.
    Target Permissions The permissions required to access the documents created by the step.

    The string must be in the format role,capability,role,capability,..., where capability can be read, insert, update, or execute.

    Target Format The format of the processed record: Text, JSON, XML, or Binary. The default is JSON.
    Provenance Granularity The granularity of the provenance tracking information: coarse (default) to store document-level provenance information only, fine to store document-level and property-level provenance information, or off to disable provenance tracking in future job runs. Applies only to mapping, matching, merging, mastering, and custom steps. Learn more: About Provenance and Lineage.
    Entity Validation Indicates whether to validate the mapped entity instance against the schema document based on the entity model, and what action to take. Set to false to skip validation. Set to accept to write the mapped entity instance to the database regardless of the validation result. Set to reject to skip writing the mapped entity instance to the database if the validation failed. The default is false. Learn more: about-mapping.html#about-mapping__validation-of-mapped-expressions.
    Source Record Scope The scope of the source record you want to map to. Choose Instance Only to map to the source instance in your envelope. Choose Entire Record to map to any of the source fields in your envelope. The default is Instance Only. Changes to the source record scope affect existing mapping expressions. Adjust existing mapping expressions to reflect the new paths to your source fields. Options: instanceOnly, entireRecord
    Batch Size The number of documents to process per batch. A smaller batch size provides finer granularity in the jobs reporting. However, a smaller batch file also costs more because of the processing overhead. The recommended batch size for merging is 1.
    Header Content A JSON object that represents additional metadata to add to the header section of the envelope of each record.
    Interceptors An array of JSON objects specifying the custom modules that perform additional processes on a batch after the core step processes are completed and before the results are saved in the database.

    Syntax:

       [
    {
      "path": "/uri/of/custom/module/in/modules/database/a.sjs",
      "vars": {
        "myParameter": "myParameterValue"
      }
      "when": "beforeContentPersisted",
    }
  ]
    path
    The URI of the interceptor in the MODULES database.
    vars
    (Optional) A JSON object containing parameters to pass to the interceptor.
    when
    Currently, only beforeContentPersisted is supported.
    Example
    Custom Hook A step add-on that performs additional processes in its own transaction before or after the core step transaction. Results are saved within a transaction.

    Syntax:

       {
    "module" : "/uri/of/custom/module/in/modules/database/a.sjs",
    "parameters" : {
      "myParameter" : "myParameterValue"
    },
    "user" : "account-required-to-run-module",
    "runBefore" : false
  }
    module
    The URI of your custom hook module in the MODULES database.
    parameters
    (Optional) A JSON object containing parameters to pass to your custom hook module.
    user
    The user account to use to run the module. Typically, a user with the security role data-hub-operator.
    runBefore
    For a pre-step hook, set to true. For a post-step hook, set to false.

    Example

    Learn more: Creating a Custom Hook Module and Adding a Custom Hook to a Step Manually.

    Important: Custom hooks are deprecated.
    Namespaces A namespace is a URI (Uniform Resource Locator). Namespaces are necessary to distinguish between two elements with the same name. They are also important for grouping elements relating to a common idea together. If you define a namespace for an entity type, the Entity Services API uses it when generating XML envelope documents but discards it when generating JSON envelope documents or extracting an envelope document as JSON. Because XPath is used to navigate XML structures and namespaces are defined in an XML model descriptor, when the Entity Services API extracts an instance from a JSON document instead of an XML document, the namespaces are ignored and must be added manually.

What to do next

Configure the mapping.