Configure the TeleStaff Business Structure Export Integration

This topic describes how to configure this integration.

Dimensions is the system of record for business structure.

This integration exports a business structure — locations, and generic and assigned jobs — and maps it to organization structure levels and ranks in TeleStaff, directly by way of APIs and not with flat files.

A business structure defines the organizational hierarchy of locations and jobs that people work.

Note: Normally, this is the first integration to run because other integrations require that the business structure be in place before they can be run.

Before you start, Configure Access to TeleStaff Integrations.

Configure the integration

  1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

    Note: If prompted, enter your Username and Password. Click Tap Log in.

  2. Select the Manage tab > Atom Management.
  3. Select your environment.
  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  3. Scroll to and select the integration pack: TeleStaff Business Structure Export > WFTSBusinessStructureExport-v1.
  1. Select Process Properties.

    Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

  2. From the Process Property dropdown list, select BusinessStructureExport-v1_CRTConfig to define headers in cross-reference tables.

    Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.

    For the column headers, see Configure cross-reference tables.

    For each of the tables:

    1. Clear Use Default. 
    2. In Value, enter the header column names, separated by commas (,) but no spaces, exactly as shown below the Value field. You can select and copy the headers from the screen, then paste them in the Value field.
    3. Repeat for the other tables.

  3. From the Process Property dropdown list, select WFTSBusinessStructureExport-v1_ProcessProperties to set process properties that must be configured before the integration can run.

    Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

    Process Properties
    Property Required Actions
    StartDate Required

    Sets the start date of the period for which to export the business structure.

    To change the date:

    1. Clear Use Default. 
    2. Enter the date; use the format YYYY-MM-DD.

      If no date is specified, the default start date is the Beginning of Time which is defined as 1900-01-01.
    EndDate Required

    Sets the end date of the period for which to export the business structure.

    To change the date:

    1. Clear Use Default. 
    2. Enter the date; use the format YYYY-MM-DD.

      If no date is specified, the default start date is the End of Time which is defined as 3000-01-01.
    LocationType Required

    Sets the top-level location in the organization for which to export the business structure.

    To change the top-level location:

    1. Clear Use Default. 
    2. Enter the full path to and name of the location.

      Example: To export Location 3 at level 3, enter location1/location2/location3.

    _DefaultTimeZone

    		Not required

    The default time zone applies to all locations and is defined in Main Menu  > Administration > Application Setup > System Configuration > Time Zones.

    Only if the organization does not use Institution Focus, or it does but operates in only one time zone, should you change the default time zone:

    Caution: Settings in the BusinessStructureExport-v1_TimeZone cross-reference table override values in the _DefaultTimeZone process property; see Cross-reference tables.

    1. Clear Use Default. 
    2. Enter the Java Time Zone reference. These references account for daylight saving time changes.

      Example time zones in the United States:

      • Pacific Time: America/Los_Angeles
      • Mountain Time: America/Denver
      • Central Time: America/Chicago
      • Eastern Time: America/New_York
      • Arizona: America/Phoenix
    _TargetSystem Not required

    Sets the destination (or target) system for the integration.

    Default = TeleStaff

    To change the system:

    1. Clear Use Default. 
    2. Enter the full path to and name of the system.
    EnableInstitutionFilter Not required

    Sets which locations in the business structure to export.

    Default = Export all locations.

    To export only the locations in the business structures that are defined in the LocationFilter cross-reference table:

    1. Clear Use Default.
    2. Select EnableInstitutionFilter.

      Caution: If the EnableInstitutionFilter process property is enabled but the LocationFilter cross-reference table is blank, the integration exports no records.
    _jobSelectionMode Not required

    The job selection mode defines whether job data can be exported only within the direct hierarchy or from anywhere in an institution.

    Default = STRICT

    To change the job selection mode:

    1. Clear Use Default. 
    2. Select one of the following:

      STRICT = The only jobs that are available are jobs that are direct descendents of the selected locations.

      LOOSE = Jobs are available from any descendent of the selected institution. At this setting, the export can synchronize the organization with unlimited access to jobs.
  4. (Optional) From the Process Property dropdown list, select WFTSAPIErrorHandlerProperties to define how to handle errors if integration runs exceed the limitations of an API.

    InitialTimeToWait: If an API limit is exceeded, this property defines how long to wait before sending the API call again.

    Default = 60000 ms (1 minute)

    This property sets only the first retry. If the API call has to be sent again, each repetition adds 60,000 ms to the wait time.

    Example:

    • 1st TimetoWait = 60,000 ms (InitialTimeToWait)
    • 2nd TimetoWait = 60,000 ms + 60,000 ms = 120,000 ms
    • 3rd TimetoWait = 60,000 ms + (2 * 60,000 ms) = 180,000 ms

    To change the initial wait time:

    • Clear Use Default.
    • Enter the wait time in milliseconds (ms) up to a maximum of 180000 ms.

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

A cross-reference table (CRT) translates parameter values in an integration as follows:

  • Organizes data values into rows and columns:
    • Maximums = 20 columns, 10,000 rows.
  • Can combine values from multiple columns to determine a single output value.
  • If more than one row matches a reference value, the first match is the output value.
  • If no match is found, the output value can be null, or the integration can produce errors.

  1. Caution: For the cross-reference tables that you are customizing, make sure that Use Default is not selected in Process Properties > {ProcessName}_CRTConfig, and that the headers are defined.

  2. Select Cross Reference.
  3. From the Cross Reference dropdown list, select any of the following tables:

    Caution: Cross-reference tables are not case-sensitive. However, APIs can be case-sensitive, so a best practice is to use the same capitalization in the cross-reference tables as in the APIs.

    Note: You cannot change the names of the tables.

    BusinessStructureExport-v1_LocationTypes

    Maps location types between the systems.

    Column headers:

    WFTS Type,WFD Type

    1. Select Override.
    2. Enter the location types for TeleStaff and Dimensions.
      Example LocationTypes cross-reference table
      WFTS TypeWFD Type
      InstitutionRegion
      AgencyLocation
      RegionDepartment
      StationArea
      UnitUnit

    BusinessStructureExport-vx_LocationFilter

    Filters location types so that only the specified business structure hierarchies are exported.

    Note: Only WFD Types that are mapped to Institutions in the _LocationTypes cross-reference table are used as filters.

    Column headers:

    WFD Type,WFDLocationQualifier

    1. Select Override.
    2. Enter the location types and location qualifiers.
      Example LocationFilter cross-reference table
      WFD TypeWFDLocationQualifier
      RegionOrganization/Australia
      RegionOrganization/Denmark
      RegionOrganization/United States

      In this example, only Organization/Australia, Organization/Denmark, and Organization/United States are included; other locations such as Organization/China, Organization/India, Organization/Japan, or Organization/Spain are excluded.

      Caution:

      The WFDLocationQualifier:

      • Must match exactly the path to and the name of the location in the business structure.
      • Is not case sensitive.
      • Does not support wildcards.
      • Cannot start with a leading slash (/).
      • If the EnableInstitutionFilter process property is enabled but the LocationFilter cross-reference table is blank, the integration exports no records.

    BusinessStructureExport-v1_TimeZone

    Only if the organization operates across multiple time zones and uses Institution Focus, should you configure the BusinessStructureExport-v1_TimeZone cross-reference table to map time zones between the systems. The settings in this cross-reference table override values in the _DefaultTimeZone process property.

    Column headers:

    WFD TimeZone,WFTS TimeZone

    1. Display the Time Zone selector in the business structure; see Configure Time Zones for Business Structure Export.
    2. Set the time zones for the locations in the business structure; see Locations.
    3. Return to the Integration Template Designer for this integration.
    4. Do not set the _DefaultTimeZone process property.
    5. For this cross-reference table, select Override.
    6. Enter the time zones to map from Dimensions to TeleStaff Institutions.

(Optional)

A data map translates a data structure from the source format to the destination format. Examples: Map "PersonID" in the source to "Person ID" in the destination or "LastName" to "Last Name".

Each integration pack has a default data map. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

  1. Select Data Maps.

  2. From the Data Maps dropdown list, select one of the following:

    WFTSBusinessStructureExport-v1_WFDBusinessStructure – WFTSBusinessStructureExport-v1_WFTSOrganizationStructure

    Data Map — Export Business Structure to TeleStaff Organization Structure

    WFTSBusinessStructureExport-v1_WFDGenericJobs – WFTSBusinessStructureExport-v1_WFTSJobTitle

    Data Map — Export Business Structure to TeleStaff Job Titles

    WFTSBusinessStructureExport-v1_WFDJobs – WFTSBusinessStructureExport-v1_WFTSJobs

    Data Map — Export Business Structure to TeleStaff Jobs

  3. Select Expand to expand or Collapse to collapse levels.

    To expand all levels, right-click the green boxes icon Map level options. Select Expand AllExpand all map levels.

    The lines show the links between fields in the source (left side), any intermediate functions, and the destination (right side).

  4. (Optional)

    Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.

    • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

      You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

    • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.

      Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.

      1. In Function, click tap the plus button Add map function to add an intermediate function.
      2. From Category, select a category of functions:

        String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

        Caution: Do not use special characters such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

        Numeric — Perform mathematical calculations on the data.

        Date — Change the format or get the current date.

        Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

        Connector — Call a value from a connector to an application or data source.

        Custom Scripting — Transform data by way of Groovy or JavaScript code.

        Properties — Get or set process or document properties.

      3. Select the function from the list in the selected category.
      4. Click Tap OK.
      5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
      6. Select and drag from a source field to an input of the function.
      7. Select and drag from the output of the function to a destination field.
      8. Repeat to add another function.
  5. When you finish, click tap OK.