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.

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>

Sync sets

A sync set ties together one type map and one project map, and optionally adds filters, sync conditions, and calculated values.

Note: For now, dynamic filters are not supported, and you cannot create them through Pulumi. Connections that have such filters will be rejected from import and refresh.

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

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>

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, FreeFormFilterArgs,
    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",
        ],
        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=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:
            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

Importing existing connections

To bring existing connections under Pulumi state management, temporarily add this script to __main__.py to generate a pulumi-import-all.json file. Remove it after the import is complete.

Copy code 
import json
from pulumi_mfcpulumiprovider import get_all_connections

result = get_all_connections()
resources = []

for conn in result.connections:
    resource_name = f"imported-connection-{conn.connect_name}".replace(" ", "-").lower()

    resources.append({
        "type": "mfcpulumiprovider:index:ConnectionResource",
        "name": resource_name,
        "id": conn.connect_id
    })

with open("pulumi-import-all.json", "w") as f:
    json.dump({"resources": resources}, f, indent=2)

print(f"Generated import file with {len(resources)} resources")
print("Run: pulumi import -f pulumi-import-all.json")

Then run: pulumi import -f pulumi-import-all.json

Limitations and general considerations

Note the following limitations:

  • For source/target types, source/target fields, and source/target values, specify the underlying values, not the display values.
  • After each deployment of the configuration please run Update labels for all affected connections in order to see correct configuration in Connect UI.
  • Named filters are not yet supported in Pulumi.
  • Common projects are not supported in Pulumi.

See also