Manage connections

Available from version 26.3: This topic describes how to manage connections with the Connect Pulumi plugin with Python and YAML.

Note: This feature is technical preview. We welcome your feedback as we continue to improve its functionality and address any issues or limitations.

The ConnectionResource resource

The ConnectionResource manages a synchronization between two datasources, defining how items flow, which types and projects are paired, and how fields map between them.

Resource type: mfcpulumiprovider:index:ConnectionResource

Required Properties

Property Type Description
connectName string Display name of the connection.
masterDatasourceId string ID of the source datasource.
targetDatasourceId string ID of the target datasource.
logicalGroupId string ID of the logical group this connection belongs to.
defaultDirection string fromSource, fromTarget, or both.
cacheItemsBetweenIterations boolean Whether to cache items between sync iterations.

Optional Properties

Property Type Description
description string A description of the connection.
syncFrequency integer Sync interval in minutes.
emailFrequency integer Email notification interval in minutes.
sendEmailTo string[] Email addresses to notify.
typeMaps list Links source/target item types and their field mappings.
projectMaps list Links source/target projects.
syncSets list Pairs a type map + project map and adds filters, conditions, and calculated values.
projectFallbackUsers list Fallback users configured per project mapping, or connection-wide.
typeFallbackUsers list Fallback users configured per project map, type map, and optional field.

Type maps

A type map links an item type from the source to one in the target (for example, Bug to Issue) and defines which fields sync between them.

typeMaps is a list. You can define multiple type maps per connection. Each has a tag (we recommend using a UUID) and a typeMapConfiguration.

Inside each type map, fieldMappings is a list of fields to sync. Each field mapping can optionally include valueMappings, which contains a mappings list of source-to-target value pairs.

Copy code 
typeMaps:
  - tag: <unique-uuid>
    typeMapConfiguration:
      sourceType: <source-item-type>
      targetType: <target-item-type>
      direction: both
      enabled: true
      fieldMappings:
        - sourceField: <source-field-name>
          targetField: <target-field-name>
        - sourceField: <source-field-name>
          targetField: <target-field-name>
          direction: fromTarget
          conversionType: applyUserMap
        - sourceField: <source-field-name>
          targetField: <target-field-name>
          valueMappings:
            defaultSource: <fallback-value-when-no-match-on-source-side>
            defaultTarget: <fallback-value-when-no-match-on-target-side>
            mappings:
              - sourceValue: <source-value-1>
                targetValue: <target-value-1>
              - sourceValue: <source-value-2>
                targetValue: <target-value-2>
  - tag: <another-unique-uuid>
    typeMapConfiguration:
      sourceType: <another-source-type>
      targetType: <another-target-type>
      fieldMappings:
        - sourceField: <source-field-name>
          targetField: <target-field-name>

Project maps

A project map links a project (or folder path) in the source to one in the target.

Copy code 
projectMaps:
  - tag: <unique-tag>
    enabled: true
    projectMapConfiguration:
      sourceProject: <source-project-name>
      targetProject: <target-project-name>
      sourcePath: <optional-sub-path>
      targetPath: <optional-sub-path>

Syncsets

A syncset joins one type map and one project map, and optionally adds filters, sync conditions, and calculated values.

Copy code 
syncSets:
  - typeMapTag: <type-map-tag>
    projectMapTag: <project-map-tag>
    sourceFilter:
      filterId: <saved-query-id>
    targetFilter:
      filterContent: <filter-expression>
    sourceSyncCriteria: <group-condition>
    targetSyncCriteria: <group-condition>
    sourceCalculatedValues: <list>
    targetCalculatedValues: <list>

Filters

sourceFilter and targetFilter each accept either a named filter or a free-form filter, but not both.

Filter type Type Description
Named filter DynamicFilter References a saved query (named filter) in the source or target datasource. Re-evaluated on every sync run.
Free-form filter FreeFormFilter A static filter expression, useful for pinning synchronization to a fixed set of items by ID.

DynamicFilter fields:

Field Type Description
filterId string Required. ID of the saved query (named filter) in the source or target system (for example, a shared query GUID in Azure DevOps).
filterName string Output only. Display name of the filter, typically the saved query path. Cannot be set from Pulumi.
filterContent string Output only. The full query string executed at sync time. Cannot be set from Pulumi.
Copy code 
syncSets:
  - typeMapTag: <type-map-tag>
    projectMapTag: <project-map-tag>
    sourceFilter:
      filterId: <saved-query-id>            # named filter (DynamicFilter)
    targetFilter:
      filterContent: <filter-expression>    # free-form filter

Conditions

Conditions are used in sourceSyncCriteria, targetSyncCriteria, and the when / from fields of calculated values. They come in two forms that can be freely mixed and nested.

GroupCondition combines multiple conditions using a logical operator:

Field Type Description
operator string And, Or, or Not.
conditions list A list of SimpleCondition or nested GroupCondition items.

SimpleCondition evaluates a single field:

Field Type Description
propertyName string The field name to evaluate.
operator string See operators below.
propertyValue string The value to compare against. Omit for Is Empty, Is New, and Is Modified.

Available operators: Equals, Includes, Is Empty, Is New, Is Modified, Starts With, Ends With, Contained In String, Contained In Set, Field Contains Value, Greater Than, Less Than, Greater Than Or Equals, Less Than Or Equals, Is Descendant Of, Instance Of

Copy code 
operator: And
conditions:
  - propertyName: <field-name>
    operator: Equals
    propertyValue: <value>
  - operator: Or
    conditions:
      - propertyName: <field-name>
        operator: Includes
        propertyValue: <value>
      - propertyName: <field-name>
        operator: Is Empty

Calculated values

Calculated values let you set a field to a fixed or derived value during sync, optionally gated by a condition.

Copy code 
- fieldName: <field-to-set>
  fieldValue: <constant-or-mapped-value>
  executionOrder: 1
  from: <group-condition>
  when: <group-condition>

Fallback users

Fallback users specify which user a synchronized item is attributed to, when the usual user mapping has no match.

The properties projectFallbackUsers and typeFallbackUsers mirror the Projects and Types and Fields grids on the connection wizard's Fallback Users page.

Both properties are optional. Omitting them, or removing them from the Pulumi program and running pulumi up, clears any fallback users previously configured for the connection.

ProjectFallbackUser is one entry per project map, or one connection-wide default when projectMapTag is omitted. You can define at most one entry per project map, and at most one entry without projectMapTag.

Field Type Description
projectMapTag string Optional tag of the project map these users apply to. Omit for the connection-wide default (Any project).
sourceUser string Optional fallback user on the master (source) side.
targetUser string Optional fallback user on the target side.

TypeFallbackUser is one entry per project map, type map, and side, and can be narrowed to a single field.

Field Type Description
projectMapTag string Required. Tag of the project map this entry applies to.
typeMapTag string Required. Tag of the type map this entry applies to.
isSource boolean Required. true for the master (source) side, false for the target side.
userName string Required. The name of the user to fall back to.
fieldName string Optional field this entry is restricted to. Omit to apply to every field of the type.
Copy code 
projectFallbackUsers:
  - projectMapTag: <project-map-tag>
    sourceUser: <source-fallback-user>
    targetUser: <target-fallback-user>
  - sourceUser: <source-fallback-user>   # no projectMapTag means connection-wide default (Any project)

typeFallbackUsers:
  - projectMapTag: <project-map-tag>
    typeMapTag: <type-map-tag>
    isSource: true
    userName: <source-fallback-user>
  - projectMapTag: <project-map-tag>
    typeMapTag: <type-map-tag>
    isSource: false
    userName: <target-fallback-user>
    fieldName: <field-name>

Validation, enforced at pulumi preview and pulumi up:

  • projectMapTag and typeMapTag must reference maps declared on the same connection.
  • At most one projectFallbackUsers entry is allowed for each project map and side, and at most one entry can omit projectMapTag. Duplicates are rejected on create and update.
  • Entries that differ only by isSource are not duplicates. Each side can have its own fallback user.

Python example: Connections

This section provides a Python example for managing connections.

Copy code 
import pulumi
from pulumi_mfcpulumiprovider import (
    ConnectionResource, ConnectionResourceArgs,
    TypeMapArgs, TypeMapConfigurationArgs,
    FieldMappingArgs, ValueMappingsArgs, ValueMappingArgs,
    ProjectMapArgs, ProjectMapConfigurationArgs,
    SyncSetArgs, DynamicFilterArgs, FreeFormFilterArgs,
    ProjectFallbackUserArgs, TypeFallbackUserArgs,
    GroupConditionArgs, SimpleConditionArgs, CalculatedValueArgs,
)

connection = ConnectionResource(
    "myConnection",
    ConnectionResourceArgs(
        connect_name="<connection-display-name>",
        master_datasource_id="<master-datasource-id>",
        target_datasource_id="<target-datasource-id>",
        default_direction="both",
        cache_items_between_iterations=True,
        sync_frequency=20,
        logical_group_id="<logical-group-id>",
        send_email_to=[
            "alice@test.com",
            "bob@test.com",
            "charlie@test.com",
        ],
        project_fallback_users=[
            ProjectFallbackUserArgs(
                project_map_tag="<project-map-tag>",
                source_user="<source-fallback-user>",
                target_user="<target-fallback-user>",
            ),
        ],
        type_fallback_users=[
            TypeFallbackUserArgs(
                project_map_tag="<project-map-tag>",
                type_map_tag="<type-map-tag>",
                is_source=True,
                user_name="<source-fallback-user>",
            ),
        ],
        type_maps=[
            TypeMapArgs(
                tag="<type-map-tag>",
                type_map_configuration=TypeMapConfigurationArgs(
                    source_type="<source-item-type>",
                    target_type="<target-item-type>",
                    enabled=True,
                    direction="both",
                    field_mappings=[
                        FieldMappingArgs(source_field="<source-field>", target_field="<target-field>"),
                        FieldMappingArgs(
                            source_field="<source-status-field>",
                            target_field="<target-status-field>",
                            value_mappings=ValueMappingsArgs(
                                default_source="<default-source-value>",
                                default_target="<default-target-value>",
                                mappings=[
                                    ValueMappingArgs(source_value="<source-value-1>", target_value="<target-value-1>"),
                                    ValueMappingArgs(source_value="<source-value-2>", target_value="<target-value-2>"),
                                ],
                            ),
                        ),
                        FieldMappingArgs(
                            source_field="<owner-field>",
                            target_field="<assignee-field>",
                            conversion_type="applyUserMap",
                        ),
                    ],
                ),
            )
        ],
        project_maps=[
            ProjectMapArgs(
                tag="<project-map-tag>",
                enabled=True,
                project_map_configuration=ProjectMapConfigurationArgs(
                    source_project="<source-project-name>",
                    target_project="<target-project-name>",
                ),
            )
        ],
        sync_sets=[
            SyncSetArgs(
                type_map_tag="<type-map-tag>",
                project_map_tag="<project-map-tag>",
                source_filter=DynamicFilterArgs(
                    filter_id="<saved-query-id>",
                ),
                target_filter=FreeFormFilterArgs(
                    filter_content="<filter-expression>",
                ),
                source_sync_criteria=GroupConditionArgs(
                    operator="And",
                    conditions=[
                        SimpleConditionArgs(
                            property_name="<field-name>",
                            operator="Includes",
                            property_value="<value>",
                        ),
                    ],
                ),
                target_calculated_values=[
                    CalculatedValueArgs(
                        field_name="<field-to-set>",
                        field_value="<value>",
                        execution_order=1,
                        when=GroupConditionArgs(
                            operator="And",
                            conditions=[
                                SimpleConditionArgs(
                                    property_name="<field-name>",
                                    operator="Is Modified",
                                ),
                            ],
                        ),
                    ),
                ],
            )
        ],
    ),
)

YAML example: Connections

This section provides a YAML example for managing connections.

Copy code 
name: my-connection
runtime: yaml
resources:
    myConnection:
        type: mfcpulumiprovider:index:ConnectionResource
        properties:
            connectName: <connection-display-name>
            masterDatasourceId: ${masterDatasource.id}
            targetDatasourceId: ${targetDatasource.id}
            defaultDirection: both
            cacheItemsBetweenIterations: true
            syncFrequency: 20
            logicalGroupId: <logical-group-id>
            sendEmailTo:
                - alice@test.com
                - bob@test.com
                - charlie@test.com
            typeMaps:
                -
                    tag: <type-map-tag>
                    typeMapConfiguration:
                        sourceType: <source-item-type>
                        targetType: <target-item-type>
                        direction: both
                        enabled: true
                        fieldMappings:
                            -
                                sourceField: <source-field>
                                targetField: <target-field>
                            -
                                sourceField: <source-status-field>
                                targetField: <target-status-field>
                                valueMappings:
                                    defaultSource: <default-source-value>
                                    defaultTarget: <default-target-value>
                                    mappings:
                                        -
                                            sourceValue: <source-value-1>
                                            targetValue: <target-value-1>
                                        -
                                            sourceValue: <source-value-2>
                                            targetValue: <target-value-2>
                            -
                                sourceField: <owner-field>
                                targetField: <assignee-field>
                                conversionType: applyUserMap
            projectMaps:
                -
                    tag: <project-map-tag>
                    enabled: true
                    projectMapConfiguration:
                        sourceProject: <source-project-name>
                        targetProject: <target-project-name>
            syncSets:
                -
                    typeMapTag: <type-map-tag>
                    projectMapTag: <project-map-tag>
                    sourceFilter:
                        filterId: <saved-query-id>
                    targetFilter:
                        filterContent: <filter-expression>
                    sourceSyncCriteria:
                        operator: And
                        conditions:
                            -
                                propertyName: <field-name>
                                operator: Includes
                                propertyValue: <value>
                    targetCalculatedValues:
                        -
                            fieldName: <field-to-set>
                            fieldValue: <value>
                            executionOrder: 1
                            when:
                                operator: And
                                conditions:
                                    -
                                        propertyName: <field-name>
                                        operator: Is Modified
            projectFallbackUsers:
                -
                    projectMapTag: <project-map-tag>
                    sourceUser: <source-fallback-user>
                    targetUser: <target-fallback-user>
            typeFallbackUsers:
                -
                    projectMapTag: <project-map-tag>
                    typeMapTag: <type-map-tag>
                    isSource: true
                    userName: <source-fallback-user>

For onboarding and importing existing resources into Pulumi state, see Pulumi onboarding.

General considerations

For source/target types, source/target fields, and source/target values, specify the underlying values, not the display values.

See also