Migration

Use the Gateway Migration Utility to help facilitate migration.

The migration APIs allow you to move entities, including folders, services and policies from one Gateway to another.

The following is an overview of the migration workflow:

Export a bundle from the source Gateway.
Map entities as required.
Import the bundle into the target Gateway.

Exporting a Bundle

Send the following request to export a bundle.

Bundle Export Example

Request
Uri	$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle?[[folder\|service\|policy]={id} \| all=true]
Http Method	GET
Response
Http Status	200
Message Body	<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management"> <l7:Name>Bundle</l7:Name> <l7:Type>BUNDLE</l7:Type> <l7:TimeStamp>2014-01-13T11:43:01.482-08:00</l7:TimeStamp> <l7:Link/> <!-- This will contain the link used to generate this bundle. --> ... <l7:Resource> <l7:Bundle> <!-- The bundle object --> <l7:References> <!-- This is the list of entities that are in the bundle. <l7:Item /> ... </l7:References> <l7:Mappings> <!-- This is the list of mappings. It describes how to create the entity on import. The must be one mapping for every entity. A mapping may not reference a resource in the bundle if it will not be migrated. They are in the order they should be created in so to avoid any dependency issues.--> <l7:Mapping /> ... </l7:Mappings> </l7:Bundle> </l7:Resource> </l7:Item>

The request URI contains query parameters of the folders, services or policies to export, specified by their ids. You can also specify all=true to export all the entities on the Gateway.

For example:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle?folder=97cd0afb295cd2d823d0fdd43e720bbc&service=08890dfa5e893770ac234e5d5a43000b&service=0ef0d5dd06fe67ab15b6a1b16517e0f5

The above URI will bundle folder with ID 97cd0afb295cd2d823d0fdd43e720bbc, and services with ID 08890dfa5e893770ac234e5d5a43000b and 0ef0d5dd06fe67ab15b6a1b16517e0f5.

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle?all=true

The above URI will bundle all the entities in the Gateway.

Importing a Bundle

To import a bundle send a PUT request with the same bundle XML to $#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle

Import Bundle Example

Request
Uri	$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle
Http Method	PUT
Content-Type	application/xml
Message Body	<l7:Bundle xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management"> <!-- The bundle object --> <l7:References> <!-- This is the list of entities that are in the bundle. <l7:Item /> ... </l7:References> <l7:Mappings> <!-- This is the list of mappings. It describes how to create the entity on import. The must be one mapping for every entity. A mapping may not reference a resource in the bundle if it will not be migrated. They are in the order they should be created in so to avoid any dependency issues.--> <l7:Mapping /> ... </l7:Mappings> </l7:Bundle>
Response
Http Status	200
Message Body	<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <l7:Item xmlns:l7="http://ns.l7tech.com/2010/04/gateway-management"> <l7:Name>Bundle mappings</l7:Name> <l7:Type>BUNDLE MAPPINGS</l7:Type> <l7:TimeStamp>2014-04-01T15:20:04.222-07:00</l7:TimeStamp> <l7:Link rel="self" uri="$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/bundle"/> <l7:Resource> <l7:Mappings> <l7:Mapping /> ... </l7:Mappings> </l7:Resource> </l7:Item>

The response will contain a list of mappings describing the actions that were performed during the bundle import. If bundle import failed for any reason, the mappings will describe the errors.

Mapping the Entities

Mapping Attributes

The mapping section in a bundle describes how to import the entities listed in the resource section when the bundle is imported. Default mappings are automatically created when the bundle is exported. The mapping section has the following attributes:

type

Type of entity being mapped

scrId

Source ID of the service being mapping; this normally references an entity in the bundle resources section

srcUri

Source URI to retrieve the entity from the Gateway

targetId

During bundle import, this ID instructs the importer to map this entity with the given target ID. The bundle importer will return a list of the mappings that were made (i.e., ID of the entity that was mapped or created on the target Gateway during import).

targetUri

Target uri of the entity that was mapped or created.

action

The possible mapping actions are as follows:

NewOrExisting	If an existing entity is found on the target Gateway, map to this existing entity (no update occurs). If an existing entity is not found, then create a new one on the target Gateway.
NewOrUpdate	If an existing entity is found on the target Gateway, map to this existing entity and update it using information from the bundle. If an existing entity is not found, then create a new one on the target Gateway.
AlwaysCreateNew	If an existing entity is found on the target Gateway, then create a new one with a different ID. If an existing entity is not found, then create a new one with the source ID.
Delete	If an existing entity is found on the target Gateway it will be removed. If an existing entity is not found, then nothing will happen and bundle import will continue (this will not fail bundle import)
Ignore	Ignore this entity and do not import it.

actionTaken

This is the action that was taken during the import. This attribute is only returned by the bundle import results. The possible actions are as follows:

UsedExisting	The entity was mapped to an existing entity on the target Gateway. The target entity was not updated.
UpdatedExisting	The entity was mapped to an existing entity on the target Gateway and the target entity was updated.
CreatedNew	A new entity was created on the target Gateway.
Deleted	The entity was deleted on the target Gateway.
Ignored	The entity was ignored and not imported. If the action was Delete and the action taken was Ignored that means that a target entity could not be found to be deleted.

errorType

This is set if there was an error attempting to import the entity. The possible errors are as follows:

TargetExists	A new entity was supposed to be created but an entity already exists on the target Gateway. See the FailOnExisting property.
TargetNotFound	An existing entity should exist on the target Gateway but it cannot be found. See the FailOnNew property.
TargetReadOnly	Target entity is read-only: Not possible to perform action.
UniqueKeyConflict	There is an entity on the target Gateway with a conflicting unique key (usually name) as the one that is being created or updated.
CannotReplaceDependency	An error occurred when replacing an entity's dependencies.
InvalidResource	A problem occurred when updating an entity.

Simple Mapping Examples

NewOrExisting

This will create a new entity or reuse an existing one:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting" />

Possible Responses

An entity with the same ID exists on the target Gateway and this existing entity was used:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    actionTaken="UsedExisting"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

An entity with the same ID does NOT exist on the target Gateway and a new entity with the specified ID was created:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

An entity with the same ID does NOT exist on the target Gateway but one with a conflicting unique key was present instead, resulting in a 409 error response:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    errorType="UniqueKeyConflict" >
        <l7:Properties>
            <l7:Property key="ErrorMessage">
                <l7:StringValue>(name)  must be unique</l7:StringValue>
            </l7:Property>
        </l7:Properties>
</l7:Mapping>

NewOrUpdate

This will create a new entity or update an existing one:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate" />

Possible Responses

An entity with the same ID exists on the target Gateway. This entity has been updated using the entity in the import bundle:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate"
    actionTaken="UpdatedExisting"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

An entity with the same ID does NOT exist on the target Gateway and a new entity with the ID specified was created:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate"
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

An entity with the same ID does NOT exist on the target Gateway, but an entity with a conflicting unique key is present instead. Alternatively, an entity with the same ID exists, but unique key errors occurred when updating it, resulting in a 409 error response:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate"
    errorType="UniqueKeyConflict" >
        <l7:Properties>
            <l7:Property key="ErrorMessage">
                <l7:StringValue>(name)  must be unique</l7:StringValue>
            </l7:Property>
        </l7:Properties>
</l7:Mapping>

A read-only entity with the same ID exist on the target Gateway:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate"
    errorType="TargetReadOnly" >
        <l7:Properties>
            <l7:Property key="ErrorMessage">
                <l7:StringValue>Target entity is read-only: Not possible to update...</l7:StringValue>
            </l7:Property>
        </l7:Properties>
</l7:Mapping>

AlwaysCreateNew

This will create a new entity:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="AlwaysCreateNew" />

Possible Responses

An entity with the same ID exists on the target Gateway, resulting in a new entity with a new ID being created on the target Gateway.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="AlwaysCreateNew"
    actionTaken="CreatedNew"
    targetId="8756846868e6eb676bf4ed8a9bfba04b"
    targetUri="https://ssgtarget/restman/1.0/policies/8756846868e6eb676bf4ed8a9bfba04b" />

An entity with the same ID does NOT exist on the target Gateway, resulting in a new entity being created with the specified ID.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="AlwaysCreateNew"
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

The entity created has unique key conflicts with an entity on the Gateway, resulting in a 409 error response:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="AlwaysCreateNew"
    errorType="UniqueKeyConflict" >
        <l7:Properties>
            <l7:Property key="ErrorMessage">
                <l7:StringValue>(name)  must be unique</l7:StringValue>
            </l7:Property>
        </l7:Properties>
</l7:Mapping>

Delete

This will delete an entity:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="Delete" />

Possible Responses

An entity with the same ID exists on the target Gateway, resulting in the entity being deleted on the target Gateway.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="Delete"
    actionTaken="Deleted"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" />

An entity with the same ID does NOT exist on the target Gateway, resulting in no entity being deleted.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="Delete"
    actionTaken="Ignored" />

A read-only entity with the same ID exist on the target Gateway:

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate"
    errorType="TargetReadOnly" >
        <l7:Properties>
            <l7:Property key="ErrorMessage">
                <l7:StringValue>Target entity is read-only: Not possible to delete...</l7:StringValue>
            </l7:Property>
        </l7:Properties>
</l7:Mapping>

Ignore

This will ignore the entity. No attempt will be made to import the entity.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="Ignore" />

Possible Responses

There is only one possible response.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    actionTaken="Ignored" />

Mapping Properties

A mapping can also have properties specified. Properties are specified as a key value map. The currently supported properties are:

NewOrExistingFailOnExisting	This is a boolean property that can be applied to any mapping type. If true it will fail with a 409 if an entity with the same ID exists on the target. The possible values are 'true' or 'false'. If this is not specified false is assumed. Example Failure response: <l7:mapping type="POLICY" srcId="97cd0afb295cd2d823d0fdd43e720bbc" srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" errorType="TargetExists" />
FailOnNewFailOnNew	This is a boolean property that can be applied to any mapping type. If true it will fail with a 409 if an entity with the same ID DOES NOT EXIST on the target. The possible values are 'true' or 'false'. If this is not specified false is assumed. Example Failure response: <l7:mapping type="POLICY" srcId="97cd0afb295cd2d823d0fdd43e720bbc" srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" errorType="TargetNotFound" />
MapBy	This can specify the unique key to map the target by. The possible values are: name The name of the entity. guid The guid of the entity. This property is only applicable for services and encapsulated assertions. mapByRoleEntity 'mapByRoleEntity' is used to map an auto created role to an auto created role on the target Gateway. This property is automatically set when performing a full Gateway export. moduleSha256 'moduleSha256' is used to map a ServerModuleFile using its content digest on the target Gateway. This is the default property when exporting ServerModuleFile(s). routingUri 'routingUri' is the routing uri for a service entity. This property is only applicable for services. The usage of this property is best suited for cases where there are duplicate entity names, or when the ids of entities from the source and target gateway are different. path 'path' is the folder path of the entity. This property is only applicable for services, policies, folders, and aliases. The usage of this property is best suited for cases where there are duplicate entity names, or when the ids of entities from the source and target gateway are different.
MapTo	This is an optional property that allows for mapping to a different entity and can only used when the 'MapBy' property is specified. If 'MapTo' is not specified, the mapping target is assumed to be the same as the source Gateway.

Complex Mapping Examples

Mapping by Name

Map a policy to a policy on the target Gateway with the same name.

<l7:mapping
     type="POLICY"
     srcId="97cd0afb295cd2d823d0fdd43e720bbc"
     srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
     action="NewOrUpdate" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Possible Responses

If an entity with the same name DOES NOT exist on the target Gateway this will create a new entity with the ID specified.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate" >
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name exist on the target Gateway this will update the entity.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate" >
    actionTaken="UpdatedExisting"
    targetId="8756846868e6eb676bf4ed8a9bfba04b"
    targetUri="https://ssgtarget/restman/1.0/policies/8756846868e6eb676bf4ed8a9bfba04b" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name DOES NOT exist on the target Gateway but one with the same ID does, this will fail.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrUpdate" >
    errorType="UniqueKeyConflict"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="ErrorMessage">
            <l7:StringValue>Other entity exists with the given id: 97cd0afb295cd2d823d0fdd43e720bbc</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:Mapping>

Mapping by Name to a Specific Entity

Map a service to a service on the target Gateway with a specific name.

<l7:mapping
     type="POLICY"
     srcId="97cd0afb295cd2d823d0fdd43e720bbc"
     srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
     action="NewOrExisting" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Possible Responses

If an entity with the target name DOES NOT exist on the target Gateway this will create a new entity with the ID specified, and the mapTo name ("MyTargetService").

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the target name exist on the target Gateway this will do nothing, used the existing service.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    actionTaken="UsedExisting"
    targetId="8756846868e6eb676bf4ed8a9bfba04b"
    targetUri="https://ssgtarget/restman/1.0/policies/8756846868e6eb676bf4ed8a9bfba04b" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the target name DOES NOT exist on the target Gateway but one with the same ID does, this will fail.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    errorType="UniqueKeyConflict"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="ErrorMessage">
            <l7:StringValue>Other entity exists with the given id: 7d428d5529fece370bc3cb5b44027ba0</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Mapping by ID where Entity Must Exist on the Target

Map a service to a service on the target Gateway. The service must exist on the target Gateway.

<l7:mapping
     type="POLICY"
     srcId="97cd0afb295cd2d823d0fdd43e720bbc"
     srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
     action="NewOrExisting" >
    <l7:Properties>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Possible Responses

If an entity with the same ID DOES NOT exist on the target Gateway this will fail.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    errorType="TargetNotFound" >
    <l7:Properties>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same ID exist on the target Gateway this will do nothing, used the existing service.

<l7:mapping
    type="POLICY"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc"
    action="NewOrExisting"
    actionTaken="UsedExisting"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/policies/97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Mapping by Name to Specific Entity Do Not Fail on ID Clash

Map a service to a service on the target Gateway with a specific name. Do not fail if a service with the same ID exists on the target Gateway.

<l7:mapping
     type="SERVICE"
     srcId="97cd0afb295cd2d823d0fdd43e720bbc"
     srcUri="https://ssgsource/restman/1.0/services/97cd0afb295cd2d823d0fdd43e720bbc"
     action="AlwaysCreateNew" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Possible Responses

If an entity with the same name DOES NOT exist on the target Gateway this will create a new entity with the ID specified, and the mapTo name ("MyTargetService").

<l7:mapping
    type="SERVICE"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/services/97cd0afb295cd2d823d0fdd43e720bbc"
    actionTaken="CreatedNew"
    targetId="97cd0afb295cd2d823d0fdd43e720bbc"
    targetUri="https://ssgtarget/restman/1.0/services/97cd0afb295cd2d823d0fdd43e720bbc" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name exists on the target Gateway this will fail with unique key conflict.

<l7:mapping
    type="SERVICE"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/services/97cd0afb295cd2d823d0fdd43e720bbc"
    errorType="UniqueKeyConflict"
    targetId="8756846868e6eb676bf4ed8a9bfba04b"
    targetUri="https://ssgtarget/restman/1.0/services/8756846868e6eb676bf4ed8a9bfba04b" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name DOES NOT exist on the target Gateway but one with the same ID does, this will create a new entity with a new ID, and the mapTo name ("MyTargetService").

<l7:mapping
    type="SERVICE"
    srcId="97cd0afb295cd2d823d0fdd43e720bbc"
    srcUri="https://ssgsource/restman/1.0/services/97cd0afb295cd2d823d0fdd43e720bbc"
    actionTaken="CreatedNew"
    targetId="8756846868e6eb676bf4ed8a9bfba04b"
    targetUri="https://ssgtarget/restman/1.0/services/8756846868e6eb676bf4ed8a9bfba04b" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
    <l7:Properties>
</l7:mapping>

Delete by Name a Specific Entity Fail if Entity Does Not Exist

Delete a service on the target Gateway with the name 'MyTargetService'. If the service does not exist fail the bundle import.

<l7:mapping
     type="SERVICE"
     action="Delete" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

Possible Responses

If an entity with the same name exists on the target Gateway this will delete the entity.

<l7:mapping
     type="SERVICE"
     action="Delete"
     actionTaken="Deleted"
     targetId="8756846868e6eb676bf4ed8a9bfba04b"
     targetUri="https://ssgtarget/restman/1.0/services/8756846868e6eb676bf4ed8a9bfba04b" >
    <l7:Properties>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name DOES NOT exist on the target Gateway this will fail.

<l7:mapping
     type="SERVICE"
     action="Delete" >
    <l7:Properties>
        <l7:Property key="ErrorMessage">
            <l7:StringValue>Could not locate entity: Fail on new specified and could not locate existing target. Source Entity: EntityHeader. Name=MyTargetService, id=null, description=null, type = SERVICE</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapBy">
            <l7:StringValue>name</l7:StringValue>
        </l7:Property>
        <l7:Property key="MapTo">
            <l7:StringValue>MyTargetService</l7:StringValue>
        </l7:Property>
        <l7:Property key="FailOnNew">
            <l7:BooleanValue>true</l7:BooleanValue>
        </l7:Property>
    </l7:Properties>
</l7:mapping>

If an entity with the same name exist on the target Gateway this will fail with unique key conflict.

Mapping by routingUri

    <l7:Mapping action="NewOrUpdate" srcId="7a20dc65166addef9088427e9c65f89f" srcUri="https://localhost:8443/restman/1.0/services/7a20dc65166addef9088427e9c65f89f" type="SERVICE">
        <l7:Properties>
            <l7:Property key="MapBy">
                <l7:StringValue>routingURI</l7:StringValue>
            </l7:Property>
            <l7:Property key="MapTo">
                <l7:StringValue>/newTarget</l7:StringValue>
            </l7:Property>
        </l7:Properties>
    </l7:Mapping>

Possible Responses

If no services have the routingUri='/newTarget', the service will be created using details from the bundle.

A UniqueKeyConflict error may arise if the service with the routingUri '/newTarget' has the same id as another service on the target gateway.

If there is a service with the routingUri='/newTarget', the service will be updated using details from the bundle.
If there are multiple services with routingUri='/newTarget', the bundle import will fail with an error: 'Incorrect mapping instructions: Found multiple possible target entities found with routing URI:...'

Mapping by path

Map service to a service on the target Gateway with a specific path.

    <l7:Mapping action="NewOrUpdate" srcId="7a20dc65166addef9088427e9c65f89f" srcUri="https://localhost:8443/restman/1.0/services/7a20dc65166addef9088427e9c65f89f" type="SERVICE">
        <l7:Properties>
            <l7:Property key="MapBy">
                <l7:StringValue>path</l7:StringValue>
            </l7:Property>
            <l7:Property key="MapTo">
                <l7:StringValue>/a/b/newService</l7:StringValue>
            </l7:Property>
        </l7:Properties>
    </l7:Mapping>

Possible Responses

If no services have the path='/a/b/newService', the service will be created using details from the bundle. Any folder along the path that does not currently exist will be created as well.

A UniqueKeyConflict error may arise if the service with the path '/a/b/newService' has the same id as another service on the target gateway.

If there is a service with the path='/a/b/newService', the service will be updated using details from the bundle.
If there are multiple services with the path='/a/b/newService', the bundle import will fail with an error: 'Incorrect mapping instructions: Found multiple possible target entities found with path:...'
A mapping error message which resembles:

Cannot add or update a child row: a foreign key constraint fails (`ssg`.`folder`, CONSTRAINT `folder_parent_folder` FOREIGN KEY (`parent_folder_goid`) REFERENCES `folder` (`goid`) ON DELETE NO ACTION ON UPDATE NO ACTION)

Map folder to another folder on the target Gateway. The folder on the target gateway contains special characters and in this case is called 'Folder/WithSlash'. Use '\' to escape special characters.

    <l7:Mapping action="NewOrUpdate" srcId="7a20dc65166addef9088427e9c65f89f" srcUri="https://localhost:8443/restman/1.0/folders/7a20dc65166addef9088427e9c65f89f" type="FOLDER">
        <l7:Properties>
            <l7:Property key="MapBy">
                <l7:StringValue>path</l7:StringValue>
            </l7:Property>
            <l7:Property key="MapTo">
                <l7:StringValue>/a/Folder\/WithSlash</l7:StringValue>
            </l7:Property>
        </l7:Properties>
    </l7:Mapping>

Possible Responses

If no folders have the path='/a/Folder\/WithSlash', the folder will be created using details from the bundle. Any folder along the path that does not currently exist will be created as well.

A UniqueKeyConflict error may arise if the folder with the path '/a/Folder\/WithSlash' has the same id as another folder on the target gateway.

If there is a folder with the path='/a/Folder\/WithSlash', the folder will be updated using details from the bundle.
A mapping error message which resembles:

Cannot add or update a child row: a foreign key constraint fails (`ssg`.`folder`, CONSTRAINT `folder_parent_folder` FOREIGN KEY (`parent_folder_goid`) REFERENCES `folder` (`goid`) ON DELETE NO ACTION ON UPDATE NO ACTION)

Supporting Large Migrations

By default the REST Management Service accepts requests up to 50MB in size. If you need to increase the maximum message size that the REST Management Service can accept edit the restman.request.message.maxSize cluster property.

Migration Example

For an example migration work-flow see:

$#{scheme}://$#{host}:$#{port}/$#{service-url}/1.0/doc/migration-example.html